Sorcerer's IsleDocs cfRegexOverview • Code

Escape

The escape action is used to convert a regex into a string that can be used to match as text within another regex pattern - that is, it escapes any regex metacharacters so as to produce a literal representation of the input text.

It is also possible to set the ReturnType to "class" if the text is to be used inside a character class, where different escaping rules apply. (Specifically, any hyphen characters "-" must be escaped, whilst many other characters do not need to be escaped.)

When escaping for a character class, duplicate characters are removed, and if tab or newline characters exist they are converted to \t and \n respectively.

Whilst the escape action exists in all three forms (object,tag,function), the RegexEscape function is the most useful of these, as it does not require a valid regex pattern as input (which both object and tag do), but can escape any arbitrary text - and it is the easy to nest within a string (unlike the tag).

See also Quote, for similar functionality.

Object

Although it is possible to call escape for a regex object, it is rare that you will need to do this. The RegexEscape function is usually recommended instead.

Arguments

Name Type Required Default Notes
ReturnType Enum (regex,class) no regex Determines if the regex should be escaped for use in a standard regex, or as part of a character class.

Usage Examples

<cfset ExampleRx = new Regex('^\w+\s{2,}-\s+\w*') />

<cfdump var=#ExampleRx.escape()# />
Outputs: '\^\\w\+\\s\{2,\}-\\s\+\\w\*'

<cfdump var=#ExampleRx.escape('class')# />
Outputs: '\^{2,}\-s+\\w*'

Tag

Since the cfregex tag always treats its body content as a regex, the contents must currently be a valid regex pattern, otherwise an error is thrown - even when using the escape action.

To convert arbitrary text that is not a regex pattern, use the RegexEscape function instead. (If necessary, in combination with cfsavecontent.)

Attributes

Name Type Required Default Notes
Variable VarName no "cfregex" The variable which the escaped regex is assigned to.
ReturnType Enum (regex,class) no regex Determines if the regex should be escaped for use in a standard regex, or as part of a character class.
Modes StringList no none If modes are provided, escaping is performed relevant to this (e.g. # is a metacharacter only when comment mode is enabled.)

Usage Examples

<cfregex escape variable="RegexEscaped" >
    ^\w+
    \s{2,} - \s+
    \w*
</cfregex>
<cfdump var=#RegexEscaped# />
Outputs: '\^\\w\+\\s\{2,\}-\\s\+\\w\*'

<cfregex escape returntype="class" variable="RegexEscaped" >
    ^\w+
    \s{2,} - \s+
    \w*
</cfregex>
<cfdump var=#RegexEscaped# />
Outputs: '\^{2,}\-s+\\w*'

Function

The RegexEscape function accepts the argument Text, not Pattern, since it does not compile to a regex pattern.

This means it is possible to use RegexEscape against a non-regex piece of text and make it safe for use in regex. (This is not possible using the cfregex tag with action escape, since the tag always treats its contents as a regex pattern, so would throw a syntax error.)

Arguments

Name Type Required Default Notes
Text String yes n/a
ReturnType Enum (regex,class) no regex Determines if the regex should be escaped for use in a standard regex, or as part of a character class.
Modes StringList no none If modes are provided, escaping is performed relevant to this (e.g. # is a metacharacter only when comment mode is enabled.)

Usage Examples

<cfdump var=#RegexEscape( '^\w+\s{2,}-\s+\w*' )# />
Outputs: '\^\\w\+\\s\{2,\}-\\s\+\\w\*'

<cfdump var=#RegexEscape( '^\w+\s{2,}-\s+\w*' , 'class' )# />
Outputs: '\^{2,}\-s+\\w*'

<cfdump var=#RegexEscape( '*\o/* :)' )# />
Outputs: '\*\\o/\* :\)'

Practical Examples

Example 1

Escaping text which may contain regex symbols but should not be treated as such. 

<cfset MarkdownText = "this is [markdown](http://daringfireball.net/projects/markdown/), *not* a regex." />
<cfoutput>#RegexEscape(MarkdownText)#</cfoutput>

Example 2

Performing a whole-word or phrase match with unknown user input:

<cfset Results = RegexFind( '\b#RegexEscape(Url.SearchWord)#\b' , SearchText ) />

Example 3

Allowing user-supplied characters to exclude as part of a larger expression, without (deliberately or accidentally) changing the behaviour of the regex:

<cfset ExcludedCharacters = RegexEscape(Form.CharactersToExclude,'class') />
<cfset BigRx = new Regex('...[^#ExcludedCharacters#]...') />