rxu

misc regexp utils.

They're meant to increase code expressiveness and to help detect bugs. To achieve this, many functions contain sanity checks on their arguments, which will have a performance cost. If you want your RegExp action to run at maximum speed, use rxu.js only as a collection of code recipes that you copy and hard-wire in your program.

API

For examples see each function's ☂ tests.

• rxu(rgx, text)
• rxu(slot)
• rxu(null)
• rxu(func)
• rxu.wrapAugmentReplacer(string | undefined | regexp)
• rxu.s(pattern[, better][, opt][, text])
• rxu.isRx(thing)
• rxu.quotemeta(text)
• rxu.replacer(rWhat, rWith)
• rxu.ifMatch(text, rgx, thenFunc, elseFunc)
• rxu.body(rx)
• rxu.splitBodyAndFlags(rx)
• rxu.compile(rx)
• rxu.join(rxs, flags[, wash])
• rxu.end(m)
• rxu.contextSlots(m)
• rxu.args2match(arguments)

rxu(rgx, text)     ☂

Try to match RegExp rgx on string text, with fancy extras. Returns the match if there was one, or false otherwise. The latter is chosen so you can safely access number properties of rxu()'s result.

• If rgx is an array, it's rxu.join()ed, see below.
• In case there is a match,
  • … it's extended with rxu.contextSlots(match, text).
  • … it's cached, see below.

rxu(slot)     ☂

Get property slot (string or number) from the cached match object. If the slot contains a function, call it and return its result.

rxu(null)     ☂

Clear rxu()'s cache. Do this if you matched sensitive information that you need to hide from other modules that run in the same VM. You probably can't if they're evil, but you might avoid accidential disclosure. This does not affect any other caches that your VM might have created, maybe by some aspect of its RegExp implementation, like RegExp.input in Firefox.

rxu(func), rxu.wrapAugmentReplacer(func)     ☂

The 1st is a shorthand for the 2nd. Assuming that function func expects a match result object, return a wrapper function that can be used as a replacer function and will provide a match result object to func, with additional features.

The wrapper takes either a match result object, or standard replacer function arguments, in which case it will convert them using rxu.args2match(). Additional features: (m = match object, w = wrapper function)

• rxu.contextSlots(m), see below.
• m.memo = w.memo: An object that will be carried along. You can set properties on it in order to remember stuff between invocations.
• m.opt = w.opt: Options for wrapper behavior.
  • opt.cnt: Well ok this isn't an option, but a match counter. In case it's not a number, the wrapper will initialize it to 0 (before calling func), and will increment it by 1 each time it survived a call to func, i.e. func has not thrown an Error.
  • opt.limit: Set to a number in order to limit how many matches you want to replace. If opt.cnt >= opt.limit, the wrapper will just return m[0] (the original text, unchanged) instead of calling func.
  • opt.undef: What text to return in case func returns undefined. (Reminder: That's the default if your function has no return statement or no value in it.) If opt.undef is undefined itself (default), the original match text will be returned.

rxu.wrapAugmentReplacer(string | undefined | regexp)     ☂

Arrange most features described above, especially counter and limit. Since you provided no replacer function, it can't be called, but instead:

• If given a string, just return that each time, verbatim. Dollar signs won't have any special effect even if followed by a digit.
• If given null (or undefined or no argument), make the wrapper act as if func had returned undefined. You probably want to set opt.undef.
• If given a RegExp, format the match using rxu.fmt() (not available yet).

rxu.s(pattern[, better][, opt][, text])     ☂

That s means to substitute (parts of a string), name inspired by Perl.

Make a function subst that, given an input string, will return input with pattern replaced. If text is undefined (maybe because it wasn't provided at all), return subst; else, immediately apply subst to input and return the result.

pattern can be a RegExp or a string.

• In case of a string, s replaces all occurrences, by constructing a regexp that matches all literal occurrences of pattern (flags sg) as $1. You can change the flags by setting opt.flags to a string.

better will be used to replace the occurrence(s) of pattern. It can be…

• a function whose opt and memo properties both contain objects, then s will assume that function was made by rxu.wrapAugmentReplacer() and use it as the replacer for each match. See below for special case opt === true.
• anything else that rxu.wrapAugmentReplacer() can accept, because that's what s will use to get a replacer function.

opt: An object with options. Supports all options that you could set on a replacer function created by rxu.wrapAugmentReplacer(), with some exceptions:

• If opt is a number, it will be used as opt.limit and no other options will be set.
• If opt is true and better looks like it was made by rxu.wrapAugmentReplacer(), the original better.opt and better.memo will be kept as they are. Otherweise, they are…
  1. backed up,
  2. reset (.memo to empty object, .opt to opt),
  3. (then replacements happen),
  4. copied onto subst,
  5. restored.

rxu.isRx(thing)     ☂

Returns a boolean whether thing looks like a RegExp. Will be maintained to always use the most reliable, cross-platform, edgecase-avoiding approach known to rxu's maintainers. (Advice and PRs welcome, as for any aspect of rxu.)

rxu.quotemeta(text)     ☂

Return a version of text that has a backslash added in front of each character that looks like it could has a special meaning in RegExp syntax, and whitespace characters. The exact list can be found in rxu.rgxMagicChars. Don't change it, or you'll break other modules that run in the same VM.

rxu.replacer(rWhat, rWith)     ☂

  return function subst(input) { return String(input).replace(rWhat, rWith); };

Construct handy iterators for cases where rxu.s() would be disproportionate.

rxu.ifMatch(text, rgx, thenFunc, elseFunc)     ☂

  return (match ? (thenFunc ? thenFunc(match, text) : match)
                : (elseFunc ? elseFunc(text)        : false));

rxu.body(rx), rxu.flags(rx)     ☂

Get the body part or flags from a regexp. Uses .source and .flags where available, with fallback to string parsing.

rxu.splitBodyAndFlags(rx)     ☂

Find the body, flags, and delimiter used in a regexp. Returns an object { delim: …, body: …, flags: … } with a prototype that knows a .compile method that makes a RegExp.

rxu.compile(rx)     ☂

return rxu.splitBodyAndFlags(rx).compile(); – allows to .map() an array of string representations of RegExps to actual live RegExps.

rxu.join(rxs, flags[, wash])     ☂

From an array rxs of RegExp bodies given as strings (and/or as RegExps, which will be converted to strings using rxu.body), make a new RegExp from the concatenated body parts and (if given) flags. If a function wash is given, each body part will be passed through that (as string).

rxu.end(m), rxu.before(m), rxu.after(m), rxu.grp(m, g)     ☂

Assuming that m is a result object from a successful RegExp match, determine…

• end: the position of the first character after the match.
• before: the text before the match.
• after: the text after the match.
• grp, with a number g: m[g] but warping around at 0 and m.length.
• grp, with a string g: (not supported yet) the named match group g.

rxu.contextSlots(m)     ☂

Assuming that m is a result object from a successful RegExp match, set some handy additional slots on m, and return it.

• m['@']: (int) Position of the match. Alias for m.index.
• m.end: (int) Position of the first character after the match.
• m['*']: (func) Returns m.input.
• m['<'], m.before: (func) Returns the text before the match.
• m['>'], m.after: (func) Returns the text after the match.
• m.fmt, m.grp: (func) Like the same-named functions on rxu. but with the match object pre-set.

rxu.args2match(arguments)     ☂

When you call .replace() on some string with the 2nd argument being your replacer function, that function won't receive a proper match result object, just unnamed arguments. This function converts that arguments Array-like object to a proper match result object, so you can use it with other rxu functions.

License

ISC