New flags

About flags

XRegExp provides four new flags (n, s, x, A), which can be combined with native flags and arranged in any order. Unlike native flags, non-native flags do not show up as properties on regular expression objects.

• New flags
  • n — Named capture only
  • s — Dot matches all (singleline) — Added as a native flag in ES2018, but XRegExp always supports it
  • x — Free-spacing and line comments (extended)
  • A — 21-bit Unicode properties (astral) — Requires the Unicode Base addon
• Native flags
  • g — All matches, or advance lastIndex after matches (global)
  • i — Case insensitive (ignoreCase)
  • m — ^ and $ match at newlines (multiline)
  • u — Handle surrogate pairs as code points and enable \u{…} and \p{…} (unicode) — Requires native ES6 support
  • y — Matches must start at lastIndex (sticky) — Requires Firefox 3+ or native ES6 support
  • d — Include indices for capturing groups on match results (hasIndices) — Requires native ES2021 support

Named capture only (n)

Specifies that the only captures are explicitly named groups of the form (?<name>…). This allows unnamed (…) parentheses to act as noncapturing groups without the syntactic clumsiness of the expression (?:…).

Annotations

• Rationale: Backreference capturing adds performance overhead and is needed far less often than simple grouping. The n flag frees the (…) syntax from its often-undesired capturing side effect, while still allowing explicitly-named capturing groups.
• Compatibility: No known problems; the n flag is illegal in native JavaScript regular expressions.
• Prior art: The n flag comes from .NET, where it's called "explicit capture."

Dot matches all (s)

Usually, a dot does not match newlines. However, a mode in which dots match any code unit (including newlines) can be as useful as one where dots don't. The s flag allows the mode to be selected on a per-regex basis. Escaped dots (\.) and dots within character classes ([.]) are always equivalent to literal dots. The newline code points are as follows:

• U+000A — Line feed — \n
• U+000D — Carriage return — \r
• U+2028 — Line separator
• U+2029 — Paragraph separator

Annotations

• Rationale: All popular Perl-style regular expression flavors except JavaScript (prior to ES2018) include a flag that allows dots to match newlines. Without this mode, matching any single code unit requires, e.g., [\s\S], [\0-\uFFFF], [^] (JavaScript only; doesn't work in some browsers without XRegExp), or god forbid (.|\s) (which requires unnecessary backtracking).
• Compatibility: No known problems; the s flag is illegal in native JavaScript regular expressions prior to ES2018.
• Prior art: The s flag comes from Perl.

Free-spacing and line comments (x)

This flag has two complementary effects. First, it causes all whitespace recognized natively by \s to be ignored, so you can free-format the regex pattern for readability. Second, it allows comments with a leading #. Specifically, it turns whitespace into an "ignore me" metacharacter, and # into an "ignore me and everything else up to the next newline" metacharacter. They aren't taken as metacharacters within character classes (which means that classes are not free-format even with x, following precedent from most other regex libraries that support x), and as with other metacharacters, you can escape whitespace and # that you want to be taken literally. Of course, you can always use \s to match whitespace.

The ignored whitespace characters are those matched natively by \s. ES3 whitespace is based on Unicode 2.1.0 or later. ES5 whitespace is based on Unicode 3.0.0 or later, plus U+FEFF. Following are the code points that should be matched by \s according to ES5 and Unicode 4.0.1:

• U+0009 — Tab — \t
• U+000A — Line feed — \n
• U+000B — Vertical tab — \v
• U+000C — Form feed — \f
• U+000D — Carriage return — \r
• U+0020 — Space
• U+00A0 — No-break space
• U+1680 — Ogham space mark
• U+180E — Mongolian vowel separator
• U+2000 — En quad
• U+2001 — Em quad
• U+2002 — En space
• U+2003 — Em space
• U+2004 — Three-per-em space
• U+2005 — Four-per-em space
• U+2006 — Six-per-em space
• U+2007 — Figure space
• U+2008 — Punctuation space
• U+2009 — Thin space
• U+200A — Hair space
• U+2028 — Line separator
• U+2029 — Paragraph separator
• U+202F — Narrow no-break space
• U+205F — Medium mathematical space
• U+3000 — Ideographic space
• U+FEFF — Zero width no-break space

Annotations

• Rationale: Regular expressions are notoriously hard to read; adding whitespace and comments makes regular expressions easier to read.
• Compatibility: No known problems; the x flag is illegal in native JavaScript regular expressions.
• Prior art: The x flag comes from Perl, and was originally inspired by Jeffrey Friedl's pretty-printing of complex regexes.

21-bit Unicode properties (A)

Requires the Unicode Base addon.

By default, \p{…} and \P{…} support the Basic Multilingual Plane (i.e. code points up to U+FFFF). You can opt-in to full 21-bit Unicode support (with code points up to U+10FFFF) on a per-regex basis by using flag A. In XRegExp, this is called astral mode. You can automatically add flag A for all new regexes by running XRegExp.install('astral'). When in astral mode, \p{…} and \P{…} always match a full code point rather than a code unit, using surrogate pairs for code points above U+FFFF.

// Using flag A to match astral code points
XRegExp('^\\p{S}$').test('💩'); // -> false
XRegExp('^\\p{S}$', 'A').test('💩'); // -> true
XRegExp('(?A)^\\p{S}$').test('💩'); // -> true
// Using surrogate pair U+D83D U+DCA9 to represent U+1F4A9 (pile of poo)
XRegExp('(?A)^\\p{S}$').test('\uD83D\uDCA9'); // -> true

// Implicit flag A
XRegExp.install('astral');
XRegExp('^\\p{S}$').test('💩'); // -> true

Important: Opting in to astral mode disables the use of \p{…} and \P{…} within character classes. In astral mode, use e.g. (\p{L}|[0-9_])+ instead of [\p{L}0-9_]+.

Annotations

• Rationale: Astral code point matching uses surrogate pairs and is somewhat slower than BMP-only matching. Enabling astral code point matching on a per-regex basis can therefore be useful.
• Compatibility: No known problems; the A flag is illegal in native JavaScript regular expressions.
• Prior art: None.