Flags & Modes

The optional flags parameter modifies the mode of the pattern-matching operation.


var exp    = new ApgExp(pattern[, flags]);
var result = exp.exec(input);

The flags parameter may be absent, undefined, null or a string of any of the case-insensitive characters "gyud". The string may be empty, the characters may be in any order and characters may appear more than once. However, any character not in the list above will cause an ApgExpError exception to be thrown.

The exp object has gobal, sticky, unicode and debug boolean flag properties. These are all initially false indicating default mode. The exp.flags property is the flags string in a normalized format.

Flag Values

  • absent, undefined, null or "" - default mode
  • g - Sets the exp.global property. global mode
  • y - Sets the exp.sticky property. sticky mode
  • u - Sets the exp.unicode property. Unicode mode
  • d - Sets the exp.debug property. debug mode

If both the global and sticky flags are set, "gy", global is ignored and sticky mode is used.


default mode - The pattern match attempt is made at the index, exp.lastIndex. The user can set exp.lastIndex to any value prior to the match attempt. If a match is found, result is returned and exp.lastIndex is reset to zero. If a match is not found exp.lastIndex is incremented by one and the attempt repeated. This repeats until either a match is found or the end of string is reached. In all cases, exp.lastIndex is reset to zero after the search.

global mode - The pattern match is attempted exactly as for default mode. However, if a match is found, exp.lastIndex is not set to zero. It is incremented by the length of the matched pattern, or one if the length is zero. (Some patterns allow matches to empty strings. In this case exp.lastIndex is incremented by one to prevent infinite loops and to allow the global search to continue.) This allows for an iteration over all matched patterns in the input string. When the match fails, exp.lastIndex is then reset to zero. (example)

sticky mode - The search is anchored at exp.lastIndex. This means that either a match is found starting at exp.lastIndex or the search fails. However, if a match is found, exp.lastIndex is set to the first character in the string following the matched pattern, just as with global mode. This allows a loop to iterate over all consecutive matches in the input string (example)

Unicode mode - The pattern match is attempted according to the current mode above. If a match is found, the result values are returned as arrays of integer character codes rather than strings. (example)

debug mode - Exposes the APG trace object. exp.trace can be used to display the path of the parser through the parse tree. If the debug property is false, exp.trace is undefined. (example)