wreck.api — com.github.pmonks/wreck 1.0.123

The public API of wreck.

Notes:

• Apart from passing through nil, this library does minimal argument checking, since the rules for regexes vary from platform to platform, and it is a first class requirement that callers be allowed to construct platform specific regexes if they wish.
• As a result, all functions have the potential to throw platform-specific exceptions if the resulting regex is syntactically invalid. On the JVM, these will typically be instances of the java.util.regex.PatternSyntaxException class. On JavaScript, these will typically be a js/SyntaxError.
• Platform specific behaviour is particularly notable for short / empty regexes, such as #"{}" (an error on the JVM, fine but nonsensical on JS) and #"{1}" (ironically fine but nonsensical on the JVM, but an error on JS). 🤡
• Furthemore, JavaScript fundamentally doesn't support lossless round-tripping of RegExp objects to Strings and back, something this library does extensively. The library makes a best effort to correct JavaScript's problematic implementation, but because it's fundamentally lossy there are some cases that (on ClojureScript only) may change your regexes in unexpected (though probably not semantically significant) ways.
• Regex flags are supported to the best ability of the library, but please carefully review the usage notes in README.md for various caveats when flags are used.
• None of these functions perform String escaping or quoting automatically. You can use esc or qot for this.

=' clj/s

(=' _)

(=' re1 re2)

(=' re1 re2 & more)

Equality for regexes, defined by having equal string representations and flags (including flags that cannot be embedded).

Notes:

• Functionally equivalent regexes (e.g. #"..." and #".{3}" are not considered ='.
• Some regexes may not be =' initially due to differing flag sets, but after being run through embed-flags may become =', due to non-embeddable flags being silently dropped (see embed-flags for details).

alt clj/s

(alt & res)

Returns a regex that will match any one of res, via alternation:

• re|re|re|...

Notes:

• Duplicate elements in res will only appear once in the result. This equality comparison occurs after each re is run through embed-flags.
• Does not wrap the result in a group, which, because alternation has the lowest precedence in regexes, runs the risk of behaving unexpectedly if the result is then combined with further regexes. tl;dr - one of the grouping variants should almost always be preferred.

alt-cg clj/s

(alt-cg & res)

alt then cg:

• (re|re|re|...)

alt-grp clj/s

(alt-grp & res)

alt then grp:

• (?:re|re|re|...)

alt-ncg clj/s

(alt-ncg nm & res)

alt then ncg:

• (?<nm>re|re|re|...)

and' clj/s

(and' a b)

(and' a b s)

Returns an 'and' regex that will match a and b in any order, and with the separator regex s (if provided) between them:

• asb|bsa

Notes:

• a and b must be distinct (must not match the same text) or else the resulting regex will be logically inconsistent (will not be an 'and')
• May optimise the expression (via de-duplication in alt).
• Does not wrap the result in a group, which, because alternation has the lowest precedence in regexes, runs the risk of behaving unexpectedly if the result is then combined with further regexes. tl;dr - one of the grouping variants should almost always be preferred.

and-cg clj/s

(and-cg a b)

(and-cg a b s)

and' then cg:

• (asb|bsa)

Notes:

• Unlike most other -cg fns, this one does not accept any number of res.
• May optimise the expression (via de-duplication in alt).

and-grp clj/s

(and-grp a b)

(and-grp a b s)

and' then grp:

• (?:asb|bsa)

Notes:

• Unlike most other -grp fns, this one does not accept any number of res.
• May optimise the expression (via de-duplication in alt).

and-ncg clj/s

(and-ncg nm a b)

(and-ncg nm a b s)

and' then ncg:

• (?<nm>asb|bsa)

Notes:

• Unlike most other -ncg fns, this one does not accept any number of res.
• May optimise the expression (via de-duplication in alt).

cg clj/s

(cg & res)

As for grp, but uses a capturing group:

• (res)

chcl clj/s

(chcl & res)

As for join, but encloses the joined res into a character class:

• [res]

Notes:

• ⚠️ On ClojureScript nested character classes don't work as one might expect, even though they will compile just fine. For example, this code matches as expected on ClojureJVM, but does not on ClojureScript: (re-matches #"[a[b[c]]]+" "abc"). As a result it's worth being particularly careful when composing character classes programmatically, to avoid accidentally nesting them.

embed-flags clj/s

(embed-flags re)

Embeds any programmatic or ungrouped flags found in re. It does this by removing all flags from re then wrapping it in a flag group containing those flags that are embeddable (non-embeddable flags are silently dropped - use has-non-embeddable-flags? if you need to check for this). Returns re if re contains no flags.

For example on the JVM, both (Pattern/compile "[abc]+" Pattern/CASE_INSENSITIVE) and #"(?i)[abc]+" would become #"(?i:[abc]+)".

Similarly, on ClojureScript (doto (js/RegExp.) (.compile "[abc]+" "i")) would become #"(?i:[abc]+)".

Note:

• flags-grp is almost always a better choice than this function! embed-flags is primarily intended for internal use by wreck, but may be useful in those rare cases where Clojure(Script) code receives a 3rd party regex, wishes to use it as part of composing a larger regex, doesn't know if it contains flags or not, and doesn't care that non-embeddable flags will be silently dropped.
• ⚠️ On the JVM, ungrouped embedded flags in the middle of re will be moved to the beginning of the regex. This may alter the semantics of the regex - for example a(?i)b will become (?i:ab), which means that a will be matched case-insensitively by the result, which is not the same as the original (which matches lower-case a only). This is an unavoidable consequence of how the JVM regex engine reports flags. If you really need to use embedded flag(s) midway through a regex, use flags-grp to ensure proper scoping of the flag(s).
• ⚠️ On the JVM, the programmatic flags LITERAL and CANON_EQ have no embeddable equivalent, and will be silently dropped by this function.
• ⚠️ On JavaScript, only the flags i, m, and s can be embedded. All other flags will be silently dropped by this function.

empty?' clj/s

(empty?' re)

Is re nil or (=' #"")?

Notes:

• Takes flags (if any) into account.

esc clj/s

(esc s)

Escapes s (a String) for use in a regex, returning a String.

Notes:

• unlike most other fns in this namespace, this one does not support a regex as an input, nor return a regex as an output

exn clj/s

(exn n re)

Returns a regex where re will match exactly n times:

• re{n}

exn-cg clj/s

(exn-cg n & res)

cg then exn:

• (res){n}

exn-grp clj/s

(exn-grp n & res)

grp then exn:

• (?:res){n}

exn-ncg clj/s

(exn-ncg nm n & res)

ncg then exn:

• (?<nm>res){n}

flags-grp clj/s

(flags-grp flgs & res)

As for grp, but prefixes the group with flgs (a String):

• (?flgs:res)

Returns nil if flgs is nil or empty. Throws if flgs contains an invalid flag character, including those that (ClojureScript only) cannot be embedded.

Notes:

• If you must use regex flags, it is STRONGLY RECOMMENDED that you use this function! Programmatically set flags and ungrouped embedded flags (e.g. (?i)) have no explicit scope and so cannot be reliably used to compose larger regexes. wreck makes a best effort to always convert such 'unscoped' flags into their embedded (scoped) equivalents (using embed-flags) when composing larger regexes , but using flags-grp explicitly in the first place is easier to reason about and avoids potential footguns.
• Removes any ungrouped embedded flags in re (e.g. (?i)ab), but does not add them to flgs if they aren't already there.
• ⚠️ On the JVM, ungrouped embedded flags in the middle of re (e.g. a(?i)b) will also be removed, which may alter the semantics of the regex.
• ⚠️ On JavaScript, only the flags i, m and s can be embedded (this is a limitation of the JavaScript regex engine). Other flags will result in a js/SyntaxError being thrown.
• For the JVM, see the 'special constructs' section of the java.util.regex.Pattern JavaDoc for the set of valid flag characters.
• For JavaScript, see the RegExp flags reference for the set of valid flag characters (while keeping in mind most of them can't be embedded).

grp clj/s

(grp & res)

As for join, but encloses the joined res into a single non-capturing group:

• (?:res)

has-non-embeddable-flags? clj/s

(has-non-embeddable-flags? re)

Does re have non-embeddable flags?

Notes:

• On the JVM, the only non-embeddable flags are the programmatic flags LITERAL and CANON_EQ.
• On JavaScript, this is every flag except i, m, and s.

join clj/s

(join & res)

Returns a regex that is all of the res joined together. Each element in res can be a regex, a String or something that can be turned into a String (including numbers, etc.). Ignores nil values in res, and returns nil when no res are provided or they're all nil.

Notes:

• ⚠️ In ClojureScript be cautious about using numbers in these calls, since JavaScript's number handling is a 🤡show. See the unit tests for examples.

n2m clj/s

(n2m n m re)

Returns a regex where re will match from n to m times:

• re{n,m}

n2m-cg clj/s

(n2m-cg n m & res)

cg then n2m:

• (res){n,m}

n2m-grp clj/s

(n2m-grp n m & res)

grp then n2m:

• (?:res){n,m}

n2m-ncg clj/s

(n2m-ncg nm n m & res)

ncg then n2m:

• (?<nm>res){n,m}

ncg clj/s

(ncg nm & res)

As for grp, but uses a named capturing group named nm:

• (?<nm>res)

Returns nil if nm is nil or blank. Throws if nm is an invalid name for a named capturing group (alphanumeric only, must start with an alphabetical character, must be unique within the regex).

nom clj/s

(nom n re)

Returns a regex where re will match n or more times:

• re{n,}

nom-cg clj/s

(nom-cg n & res)

cg then nom:

• (res){n,}

nom-grp clj/s

(nom-grp n & res)

grp then nom:

• (?:res){n,}

nom-ncg clj/s

(nom-ncg nm n & res)

ncg then nom:

• (?<nm>res){n,}

oom clj/s

(oom re)

Returns a regex where re will match one or more times:

• re+

oom-cg clj/s

(oom-cg & res)

cg then oom:

• (res)+

oom-grp clj/s

(oom-grp & res)

grp then oom:

• (?:res)+

oom-ncg clj/s

(oom-ncg nm & res)

ncg then oom:

• (?<nm>res)+

opt clj/s

(opt re)

Returns a regex where re is optional:

• re?

opt-cg clj/s

(opt-cg & res)

cg then opt:

• (res)?

opt-grp clj/s

(opt-grp & res)

grp then opt:

• (?:res)?

opt-ncg clj/s

(opt-ncg nm & res)

ncg then opt:

• (?<nm>res)?

or' clj/s

(or' a b)

(or' a b s)

Returns an 'inclusive or' regex that will match a or b, or both, in any order, and with the separator regex s (if provided) between them:

• asb|bsa|a|b

Notes:

• a and b must be distinct (must not match the same text) or else the resulting regex will be logically inconsistent (will not be an 'or')
• May optimise the expression (via de-duplication in alt).
• Does not wrap the result in a group, which, because alternation has the lowest precedence in regexes, runs the risk of behaving unexpectedly if the result is then combined with further regexes. tl;dr - one of the grouping variants should almost always be preferred.

or-cg clj/s

(or-cg a b)

(or-cg a b s)

or' then cg:

• (asb|bsa|a|b)

Notes:

• Unlike most other -cg fns, this one does not accept any number of res.
• May optimise the expression (via de-duplication in alt).

or-grp clj/s

(or-grp a b)

(or-grp a b s)

or' then grp:

• (?:asb|bsa|a|b)

Notes:

• Unlike most other -grp fns, this one does not accept any number of res.
• May optimise the expression (via de-duplication in alt).

or-ncg clj/s

(or-ncg nm a b)

(or-ncg nm a b s)

or' then ncg:

• (?<nm>asb|bsa|a|b)

Notes:

• Unlike most other -ncg fns, this one does not accept any number of res.
• May optimise the expression (via de-duplication in alt).

qot clj/s

(qot re)

Quotes re:

• \Qre\E

regex? clj/s

(regex? o)

Is o a regex?

Notes:

• ClojureScript already has a regexp? predicate in cljs.core, but ClojureJVM doesn't. See this ask.clojure.org post.

str' clj/s

(str' o)

Returns the String representation of o, with special handling for RegExp objects on ClojureScript in an attempt to correct JavaScript's APPALLING default stringification.

Notes:

• Embeds flags (as per embed-flags).

xor' clj/s

(xor' a b)

Returns an 'exclusive or' regex that will match a or b, but not both:

• a|b

This is identical to alt called with 2 arguments, but is provided as a convenience for those who might be building up large logic based regexes and would prefer to use more easily understood logical operator names throughout.

Notes:

• May optimise the expression (via de-duplication in alt).
• Does not wrap the result in a group, which, because alternation has the lowest precedence in regexes, runs the risk of behaving unexpectedly if the result is then combined with further regexes. tl;dr - one of the grouping variants should almost always be preferred.

xor-cg clj/s

(xor-cg a b)

xor' then cg:

• (a|b)

Notes:

• Unlike most other -cg fns, this one does not accept any number of res.
• May optimise the expression (via de-duplication in alt).

xor-grp clj/s

(xor-grp a b)

xor' then grp:

• (?:a|b)

Notes:

• Unlike most other -grp fns, this one does not accept any number of res.
• May optimise the expression (via de-duplication in alt).

xor-ncg clj/s

(xor-ncg nm a b)

xor' then ncg:

• (?<nm>a|b)

Notes:

• Unlike most other -ncg fns, this one does not accept any number of res.
• May optimise the expression (via de-duplication in alt).

zom clj/s

(zom re)

Returns a regex where re will match zero or more times:

• re*

zom-cg clj/s

(zom-cg & res)

cg then zom:

• (res)*

zom-grp clj/s

(zom-grp & res)

grp then zom:

• (?:res)*

zom-ncg clj/s

(zom-ncg nm & res)

ncg then zom:

• (?<nm>res)*