Addons

If you want, you can download XRegExp bundled with all addons as “XRegExp All”: Minified (23 KB gzipped), With comments. Following are the included scripts:

• XRegExp 2.0.0
• Unicode Base 1.0.0
• Unicode Categories 1.2.0
• Unicode Scripts 1.2.0
• Unicode Blocks 1.2.0
• Unicode Properties 1.0.0
• XRegExp.matchRecursive 0.2.0
• XRegExp.build 0.1.0
• Prototypes 1.0.0

Alternatively, you can download the individual addon scripts, below. XRegExp's npm package uses xregexp-all.js, which means that the addons are always available when XRegExp is installed on the server by npm.

Unicode

XRegExp Unicode Base adds support for the \p{L} or \p{Letter} Unicode category. Addon packages for other Unicode categories, scripts, blocks, and properties are available separately. All Unicode tokens can be inverted using \P{…} or \p{^…}. Token names are case insensitive, and any spaces, hyphens, and underscores are ignored.

Example

// Categories
XRegExp('\\p{Sc}\\p{N}+'); // Sc: currency symbol, N: number

// Scripts
XRegExp('\\p{Cyrillic}');
XRegExp('[\\p{Latin}\\p{Common}]');

// Blocks (use 'In' prefix)
XRegExp('\\p{InLatinExtended-A}');
XRegExp('\\P{InPrivateUseArea}'); // Uppercase \P for negation
XRegExp('\\p{^InMongolian}'); // Alternate negation syntax

// Properties
XRegExp('\\p{Assigned}');

To activate this addon, simply load it after loading XRegExp:

<script src="xregexp.js"></script>
<script src="addons/unicode/unicode-base.js"></script>
<script>
  var unicodeWord = XRegExp("^\\p{L}+$");

  unicodeWord.test("Русский"); // true
  unicodeWord.test("日本語"); // true
  unicodeWord.test("العربية"); // true
</script>

<!-- \p{L} is included in the base script, but other categories, scripts,
and blocks require token packages -->
<script src="addons/unicode/unicode-scripts.js"></script>
<script>
  XRegExp("^\\p{Katakana}+$").test("カタカナ"); // true
</script>

XRegExp.matchRecursive

Download XRegExp.matchRecursive 0.2.0.

Adds the following function to the XRegExp object:

XRegExp.matchRecursive(str, left, right, [flags], [options])

Returns an array of match strings between outermost left and right delimiters, or an array of objects with detailed match parts and position data. An error is thrown if delimiters are unbalanced within the data.

Parameters:	str {String} String to search. left {String} Left delimiter as an XRegExp pattern. right {String} Right delimiter as an XRegExp pattern. [flags] {String} Flags for the left and right delimiters. Use any of: gimnsxy. [options] {Object} Lets you specify valueNames and escapeChar options.
Returns:	{Array} Array of matches, or an empty array.

Example

// Basic usage
var str = '(t((e))s)t()(ing)';
XRegExp.matchRecursive(str, '\\(', '\\)', 'g');
// -> ['t((e))s', '', 'ing']

// Extended information mode with valueNames
str = 'Here is <div> <div>an</div></div> example';
XRegExp.matchRecursive(str, '<div\\s*>', '</div>', 'gi', {
  valueNames: ['between', 'left', 'match', 'right']
});
/* -> [
{name: 'between', value: 'Here is ',       start: 0,  end: 8},
{name: 'left',    value: '<div>',          start: 8,  end: 13},
{name: 'match',   value: ' <div>an</div>', start: 13, end: 27},
{name: 'right',   value: '</div>',         start: 27, end: 33},
{name: 'between', value: ' example',       start: 33, end: 41}
] */

// Omitting unneeded parts with null valueNames, and using escapeChar
str = '...{1}\\{{function(x,y){return y+x;}}';
XRegExp.matchRecursive(str, '{', '}', 'g', {
  valueNames: ['literal', null, 'value', null],
  escapeChar: '\\'
});
/* -> [
{name: 'literal', value: '...', start: 0, end: 3},
{name: 'value',   value: '1',   start: 4, end: 5},
{name: 'literal', value: '\\{', start: 6, end: 8},
{name: 'value',   value: 'function(x,y){return y+x;}', start: 9, end: 35}
] */

// Sticky mode via flag y
str = '<1><<<2>>><3>4<5>';
XRegExp.matchRecursive(str, '<', '>', 'gy');
// -> ['1', '<<2>>', '3']

XRegExp.build

Download XRegExp.build 0.1.0.

Adds the following function to the XRegExp object:

XRegExp.build(pattern, subs, [flags])

Builds regexes using named subpatterns, for readability and pattern reuse. Backreferences in the outer pattern and provided subpatterns are automatically renumbered to work correctly. Native flags used by provided subpatterns are ignored in favor of the flags argument.

Parameters:

pattern {String} XRegExp pattern using {{name}} for embedded subpatterns. Allows ({{name}}) as shorthand for (?<name>{{name}}). Patterns cannot be embedded within character classes. subs {Object} Lookup object for named subpatterns. Values can be strings or regexes. A leading ^ and trailing unescaped $ are stripped from subpatterns, if both are present. [flags] {String} Any combination of XRegExp flags.

Returns:

{RegExp} Regex with interpolated subpatterns.

Example

var time = XRegExp.build('(?x)^ {{hours}} ({{minutes}}) $', {
  hours: XRegExp.build('{{h12}} : | {{h24}}', {
    h12: /1[0-2]|0?[1-9]/,
    h24: /2[0-3]|[01][0-9]/
  }, 'x'),
  minutes: /^[0-5][0-9]$/
});

time.test('10:59'); // -> true
XRegExp.exec('10:59', time).minutes; // -> '59'

See also: Creating Grammatical Regexes Using XRegExp.build.

Prototypes

Download Prototypes 1.0.0.

Include the script:

<script src="xregexp.js"></script>
<script src="addons/prototypes.js"></script>

New XRegExp regexes now gain a collection of useful methods: apply, call, forEach, globalize, xexec, and xtest.

// To demonstrate the call method, let's first create the function we'll be using...
function filter(array, fn) {
  var res = [];
  array.forEach(function (el) {
    if (fn.call(null, el)) res.push(el);
  });
  return res;
}
// Now we can filter arrays using functions and regexes
filter(['a', 'ba', 'ab', 'b'], XRegExp('^a')); // -> ['a', 'ab']

Native RegExp objects copied by XRegExp are augmented with any XRegExp.prototype methods. The following lines therefore work equivalently:

XRegExp('[a-z]', 'ig').xexec('abc');
XRegExp(/[a-z]/ig).xexec('abc');
XRegExp.globalize(/[a-z]/i).xexec('abc');

BackCompat

Download BackCompat 1.0.0.

This addon provides backward compatibility with XRegExp 1.x.x. To run it, just include the backcompat.js script after loading xregexp.js or xregexp-all.js.

XRegExp BackCompat is not included in xregexp-all.js.

◊