JRegEx is just a utility library that contains a number of static methods that - for the most part - abstract the complexity of Java's Matcher class. For example, here is the current implementation of the .jreReplace() method, which takes a closure and uses it to manipulate each match in a replacement operation:
Since ColdFusion uses 1-based indices and Java uses 0-based indices, these methods take care of translating to and from the 1-based index system that ColdFusion developers are used to using. And, unlike ColdFusion's native RegEx methods, there are no "NoCase" versions of these methods. If you want to use a case-insensitive pattern, you should just prepend your pattern with the case-insensitivity flag, (?i).
jreEscape( patternText ) :: string
This takes a Java Regular Expression pattern and returns a literal version of it. This literal version can then be used in other JRegEx methods. This is essentially what the "quoteReplacement" argument is doing in some of the other methods.
jreFind( targetText, patternText [, startingAt = 1 ] ) :: number
This finds the offset of the first Java Regular Expression pattern match in the given target text. Returns zero if no match is found.
jreMap( targetText, patternText, operator ) :: array[any]
This iterates over each match of the given Java Regular Expression pattern found within the given target text. Each match and its captured groups are passed to the operator function which can return a mapped value. The mapped values are then aggregated and returned in an array. If the operator returns an undefined value, the match is omitted from the results.
jreMatch( targetText, patternText ) :: array[string]
This takes the given Java Regular Expression pattern and collects all matches of it that can be found within the given target text. That matches are returned as an array of strings.
jreMatchGroups( targetText, patternText ) :: array[struct]
This takes the given Java Regular Expression pattern and collects all matches of it that can be found within the given target text. That matches are returned as an array of structs in which each struct holds the captured groups of the match. The struct is keyed based on the index of the captured group, within the pattern, with the "0" key containing the entire match text.
jreReplace( targetText, patternText, operator ) :: string
jreReplaceAll( targetText, patternText, replacementText [, quoteReplacement = false ] ) :: string
I replace all matches of the given Java Regular Expression pattern found within the given target text with the given replacement text. The replacement text can contain "$N" references to captured groups within the pattern.
jreReplaceFirst( targetText, patternText, replacementText [, quoteReplacement = false ] ) :: string
I replace the first match of the given Java Regular Expression pattern found within the given target text with the given replacement text. The replacement text can contain "$N" references to captured groups within the pattern.
jreSegment( targetText, patternText ) :: array[struct]
I use the given Java Regular Expression pattern to break the given target text up into segments. Unlike the `jreSplit()` method, this method returns both the pattern matches as well as the text in between the matches. The resultant array contains a heterogeneous mix of match and non-match structs. Each struct contains the following properties:
- Match: Boolean
- Offset: Numeric
- Text: String
Match structs also contain the property:
- Groups: Struct[Numeric] :: String
... which contains the captured groups of the match.
jreSplit( targetText, patternText [, limit = 0 ] ) :: array[string]
I use the given Java Regular Expression pattern to split the given target text. The resultant portions of the target text are returned as an array of strings.
jreTest( targetText, patternText ) :: boolean
I test to see if the given Java Regular Expression pattern matches the entire target text. You can think of this as wrapping your pattern with "^" and "$" boundary sequences.
Want to use code from this post? Check out the license.
Ben, what versions of CF does this work on? 2016 only?
I believe it should be anything >= 10. Whenver closures were introduced - I think maybe that was 10. Though, technically, they don't need to be closures - they could just be function references. In that case, the support would go back even farther, I think.
But, 10 is what I have installed locally -- time to upgrade :D
Just wanted to cross-post here that I used the
JRegEx component to apply some post-processing to markdown content:
I'm using it to convert markdown items like,
<!-- vimeo: 1234 --> to an embedded Vimeo
iframe. Just love using Regular Expressions!