Update: See the complete user’s guide at ./guide/index.html or at the APG website.
apg-exp is a regex-like pattern-matching engine that uses a superset of the ABNF syntax for the pattern definitions and APG to create and apply the pattern-matching parser. By way of introduction, the regex Wikipedia article would be a good start and Jeffrey Friedl’s book, Mastering Regular Expressions would be a lot better and more complete. This introduction will just mention features, a little on motivation and try to point out some possible advantages to
.are not pre-defined, providing greater flexibility and certainty to the meaning of any needed character classes.
apg-expessentially Turing complete.
The motivation was originally twofold.
Hardly any programmer has not used regexes at some point, more likely lots of points, and it doesn’t take much reading of the Internet forums to note that many others, like me, find the regex syntax to be quite cryptic. Additionally, because regexes have such a long, rich history with many versions from many (excellent) developers, there are many different syntax variations as you move from system to system and language to language. By contrast ABNF is standardized (although my non-standard superset additions are starting to pile up.) Whether or not the ABNF syntax is preferable to conventional regex syntax will always be a personal preference. But, for me and possibly others, ABNF offers a more transparent syntax to work with.
At the outset I naively thought that the regular expressions of regexes were just that – the Chomsky hierarchy variety. Therefore, I thought that using an APG parser for the pattern matching would add a great deal of parsing power to the problem. I soon discovered that not only were the “regular expressions” of many regexes full-blown recursive-descent parsers, they were loaded up with features that went well beyond that of APG. I had to play a little catch up to add look behind, back referencing and anchors. That being done, however, I think there is still a case for claiming some added power. I’m not a regex expert and I won’t be making any big claims here, but there are a couple of points I will mention. I think the way that
apg-exp gives the user nearly full control over the input, output and interpretation of the character codes goes a long way to address a number of the cautions mentioned in Jeffrey Friedl’s book, for example on pages 92 and 106. I also think it addresses a number of the things Larry Wall finds wrong with the regex culture in his Apocalypse 5 page. For example, back referencing, support for named capture, nested patterns (recursive rules), capture of all matches to a sub-phrase and others.
But the best thing to do, probably, is to head over to the
examples and take a look.
See and compare for yourself. I would suggest starting with the
rules examples to get your bearings and go from there.
Requires node.js and npm.
apg-exp in your node.js project from GitHub, in your project directory
git clone https://github.com/ldthomas/apg-js2-exp.git apgexp npm install apgexp --save
npm install apg-exp --save
See apg-js2-examples for many examples of using
UPDATE: All fatal errors encountered in the
apg-exp constructor and its object functions are now reported
ApgExpError, it has functions
toHtml() for user-friendly display of the errors in either plain ASCII text or HTML format.
UPDATE: The files
apgexp.css have been added to make using
in a browser web page simple.
See the documentation in
See, also, this CodePen for an example.
The full documentation is in the code in
To generate the documentation, from the package directory:
npm install -g docco ./docco-gen
docs/index.html in any web browser to get started.
Or view it on the APG website
Copyright © 2016 Lowell D. Thomas, all rights reserved
Released under the BSD-3-Clause license.