Sorcerer's IsleDocs cfRegexOverview • Code

Compile

The compile action is used to create a Regex Object, which is worth doing when you will be using the same regex multiple times against different input text, as it avoids the need to repeatedly parse and compile the expression.

The compile action is called explicitly with the RegexCompile function, or when using cfregex tag with compile action, and of course is also used when creating a new Regex object, either with the new keyword, or via the createObject syntax.

Object (via new keyword)

Arguments

Name Type Required Default Notes
Pattern RegexString yes n/a The regex pattern to compile into a Regex Object.
Modes StringList no none List of regex modes to apply to the pattern.

Usage Examples

<cfset OneWordRx = new Regex( '\w+' ) />

<cfset LettersRx = new Regex( '[a-z]' , 'CASE_INSENSITIVE' ) />

<cfset StartlineLettersRx = new Regex( '^[a-z]' , 'CASE_INSENSITIVE,MULTILINE' ) />

Tag

Compile is the default action for the cfregex tag. This means that you do not need to explicitly specify it (but you can if you wish).

If you do not specify a variable name, the object created is called cfregex, but this is not recommended, especially since it will not be var-scoped in functions.

Attributes

Name Type Required Default Notes
Name VarName no "cfregex" A variable name to hold the compiled object.
Modes StringList no none List of regex modes to apply to the pattern.

Usage Examples

<cfregex name="OneWordRx">
    \w+
</cfregex>

<cfregex name="LettersRx" modes="case_insensitive">
    [a-z]
</cfregex>

<cfregex name="StartlineLettersRx" modes="case_insensitive,multiline">
    ^[a-z]
</cfregex>

Function

The RegexCompile function is included for consistency, but does not offer any advantages over the new keyword.

Arguments

Name Type Required Default Notes
Pattern RegexString yes n/a The regex pattern to compile into a Regex Object.
Modes StringList no none List of regex modes to apply to the pattern.

Usage Examples

<cfset OneWordRx = RegexCompile( '\w+' ) />

<cfset LettersRx = RegexCompile( '[a-z]' , 'CASE_INSENSITIVE' ) />

<cfset StartlineLettersRx = RegexCompile( '^[a-z]' , 'CASE_INSENSITIVE,MULTILINE' ) />

Practical Examples

Example 1

Creates a regex that can be used to ensure a directory starts with an appropriate root prefix, and is not blank nor a relative path:

<cfset PrefixRootRx = new Regex('^(?:$|\./)') />
<cfset RootDir = "/path/to/root" />

<cfloop item="CurDir" collection=#LotsOfDirs#>
    <cfset LotsOfDirs[CurDir] = PrefixRootRx.replace(LotsOfDirs[CurDir],RootDir) />
</cfloop>

Example 2

The key benefit of the cfregex tag is its ability to hold long regex patterns, without needing to worry about escaping quotes, and with the ability to neatly space out different parts and also to apply comments:

<cfregex name="CheckDocTypeRx" >
    ## HTML5 DocType
        (?i:<!doctype\ html\s*>)

    |

    ## XHTML
        <!DOCTYPE\s+html\s+PUBLIC\s+"-//W3C//DTD\ XHTML\ 1\.
            (?:
                ## 1.0 Strict or Traditional
                0\ (Strict|Transitional)//EN"
                \s+
                "http://www\.w3\.org/TR/xhtml1/DTD/xhtml1-(?i:\1)
            |
                ## XHTML 1.1
                1//EN"
                \s+
                "http://www\.w3\.org/TR/xhtml11/DTD/xhtml11
            )
        \.dtd"\s*>

    |

    ## HTML 4 Strict
        <!DOCTYPE\s+HTML\s+PUBLIC\s+"-//W3C//DTD\ HTML\ 4\.01//EN"
        \s+
        "http://www\.w3\.org/TR/html4/strict\.dtd"
        \s*>
</cfregex>

<cfdirectory
    name      = "HtmlFiles"
    directory = "./files-to-check"
    filter    = "*.html"
/>

<cfloop query="HtmlFiles">
    <cfset Filename = HtmlFiles.Directory * HtmlFiles.Name />

    <cfif NOT CheckDocTypeRx.matches( FileRead(Filename) , 'start' ) >
        <cfoutput>
            <li>Invalid doctype "#Filename#"
        </cfoutput>
    </cfif>
</cfloop>

You can use either Regex comments (as above), or CFML comments:

<cfregex name="FindColoursRx" >
    <!--- #888888 --->
    \#[A-F0-9]{6}(?=\s*[;"'}])
    |
    <!--- #888 --->
    \#[A-F0-9]{3}(?=\s*[;"'}])
    |
    <!--- rgb(128,128,128) and rgba(128,128,128,0.5) --->
    \brgba?\s*\([^)]+\)(?=\s*[;"'}])
    |
    <!--- hsl(128,50%,50%) and hsla(128,50%,50%,0.5) --->
    \bhsla?\s*\([^)]+\)(?=\s*[;"'}])
</cfregex>

<cfdirectory
    name      = "HtmlFiles"
    directory = "./files-to-check"
    filter    = "*.html"
/>
<cfset AllColoursFound = [] />

<cfloop query="HtmlFiles">
    <cfset Filename = HtmlFiles.Directory * HtmlFiles.Name />

    <cfset ColoursFound = FindColoursRx.match( FileRead(Filename) ) >

    <cfset AllColoursFound.addAll( ColoursFound ) />
</cfloop>