pcre

Description

A pcre binding for node.js with UTF8 and Unicode properties support.

Requirements

• node.js -- v0.8.0 or newer
• Windows, Linux, or OSX
  • BSD or OpenSolaris support is possible -- just need to generate and submit a config.h for PCRE 8.32 with these options:

./configure --enable-utf8 --enable-unicode-properties --enable-static --disable-shared --enable-jit --disable-cpp --enable-pcre8 --disable-pcre16 --disable-pcre32

Install

npm install pcre

Examples

• Simple one-off regexp execution:

var inspect = require('util').inspect;
var PCRE = require('pcre').PCRE;
 
console.log(inspect(PCRE.exec("(?<nodejsrules>o)", "foo", 0), false, Infinity));
 
// output:
// [ 1, 2, 1, 2, named: { nodejsrules: [ 1, 2 ] } ]

• Simple one-off regexp execution returning all matches:

var inspect = require('util').inspect;
var PCRE = require('pcre').PCRE;
 
console.log(inspect(PCRE.execAll("(?<nodejsrules>o)", "foo", 0), false, Infinity));
 
// output:
// [ [ 1, 2, 1, 2, named: { nodejsrules: [ 1, 2 ] } ],
//   [ 2, 3, 2, 3, named: { nodejsrules: [ 2, 3 ] } ] ]

• Instantiate a regexp and test it:

var PCRE = require('pcre').PCRE;
 
var re = new PCRE("o");
console.log(re.test("foo", 0));
console.log(re.test("bar", 0));
console.log(re.test("node.js rules", 2));
 
// output:
// true
// false
// false

• Instantiate a regexp, JIT compile it, and execute it, returning all matches:

var inspect = require('util').inspect;
var PCRE = require('pcre').PCRE;
 
var re = new PCRE("o");
re.study(PCRE.PCRE_STUDY_JIT_COMPILE);
console.log(inspect(re.execAll("fooooo", 0), false, Infinity));
 
// output:
// [ [ 1, 2 ], [ 2, 3 ], [ 3, 4 ], [ 4, 5 ], [ 5, 6 ] ]

API

PCRE static constants

All static constants for regexp flags/options and errors can be found in lib/pcre.js.

PCRE static methods

• exec(< string >pattern, < mixed >subject, < integer >offset[, < integer >flags]) - mixed - Compiles pattern and executes it on subject starting at offset in subject. subject can be a string or Buffer. The return value is either null in case of no match, an integer error code in case of error, or an array on success containing offsets in the subject for the first match. The first two offsets reference the entirety of the matched part of the subject. Any additional offsets reference capture groups in order from left to right. Offsets for named capture groups are additionally available on the named object.

• execAll(< string >pattern, < mixed >subject, < integer >offset[, < integer >flags]) - mixed - Same as exec() except an array of array matches is returned on success.

• test(< string >pattern, < mixed >subject, < integer >offset[, < integer >flags]) - boolean - Similar to exec(), but used merely to test if pattern matches at least once.

• version() - string - Returns the version and date of the PCRE library used (e.g. "8.32 2012-11-30").

PCRE methods

• (constructor)(< string >pattern[, < integer >flags]) - Compiles pattern and returns a new PCRE instance.

• study([< integer >flags][, < integer >jitStackStart=1, < integer >jitStackMax=32KB]) - boolean - Performs some analysis of the compiled regexp in order to optimize it. jitStackStart and jitStackMax are custom starting and maximum JIT stack sizes (in bytes) respectively for when one of the JIT flags are passed in. The return value indicates the success of the analysis.

• set(< string >pattern[, < integer >flags]) - (void) - Compiles a new pattern and replaces the existing regexp.

• save() - Buffer - Returns the internal state object representing the compiled regexp. Note: this does not save the result of any previous optimizations performed by study().

• load(< Buffer >state) - (void) - Loads previously saved internal state data from save().

• exec(< mixed >subject, < integer >offset[, < integer >flags]) - mixed - Similar to PCRE.exec().

• execAll(< mixed >subject, < integer >offset[, < integer >flags]) - mixed - Same as exec() except an array of array matches is returned on success.

• test(< mixed >subject, < integer >offset[, < integer >flags]) - boolean - Similar to exec(), but used merely to test if pattern matches at least once.