Regular Expressions in Tcl

Analogy categoryAnalogies

Working with Regular Expressions in Tcl

Tcl implements regular expressions through Henry Spencer's Advanced Regular Expression (ARE) engine, exposed through two core commands: regexp for matching and regsub for substitution. Unlike Tcl's glob-style string match patterns, AREs support alternation, backreferences, and POSIX character classes, making them the right tool whenever you need to validate, extract, or transform text that follows a describable structure rather than an exact literal string.

🏏

Cricket analogy: Like the Hawk-Eye system scanning ball-tracking frames for the specific pattern of a delivery crossing the stump line, regexp scans a whole string frame-by-frame looking for a defined shape rather than one exact byte sequence.

Matching Text with regexp

The regexp command tests whether a pattern occurs in a string and can capture matched substrings into variables: regexp {(\d{3})-(\d{4})} $text fullMatch area exch returns 1 if the pattern is found and assigns fullMatch plus one variable per parenthesized capture group. The -all switch finds every non-overlapping match instead of stopping at the first one, and -inline returns matches as a flat list rather than assigning to named variables, which is convenient inside a foreach loop or when building a result list on the fly.

🏏

Cricket analogy: Using -all on regexp is like a scorer's software re-scanning an entire innings commentary feed for every occurrence of 'SIX' rather than stopping once it finds the first boundary of the match.

tcl

set log {2026-07-10 09:12:03 ERROR user@42 timeout after 30s
2026-07-10 09:13:47 ERROR user@17 connection reset}

# Find every ERROR line and capture user id + reason
set matches [regexp -all -inline {ERROR user@(\d+) (.+)} $log]
foreach {whole userId reason} $matches {
    puts "user $userId failed: $reason"
}
# -> user 42 failed: timeout after 30s
# -> user 17 failed: connection reset

# Simple boolean test with a single capture group
if {[regexp {^(\d{4})-(\d{2})-(\d{2})$} $date -> year month day]} {
    puts "parsed year=$year month=$month day=$day"
}

Rewriting Text with regsub

regsub mirrors regexp but rewrites text instead of merely locating it: regsub -all {\s+} $text { } cleaned collapses runs of whitespace into single spaces and stores the result in the variable cleaned. Capture groups from the pattern are available in the replacement string as \1, \2, and so on, so regsub -all {(\w+)@(\w+)} $s {\2/\1} out can reorder a matched domain-and-user pair into a different textual layout. Both commands return the number of substitutions made when -all is used together with a result variable, which is useful for validating that a transformation actually happened before trusting the output.

🏏

Cricket analogy: regsub collapsing repeated whitespace is like a groundsman rolling a pitch smooth before play, turning an irregular, bumpy surface into one consistent, evenly spaced strip that's ready for use.

Both regexp and regsub accept -nocase for case-insensitive matching and -line, which makes ^ and $ match at embedded newlines instead of only the start and end of the whole string - useful when processing multi-line log files one logical line at a time.

Anchors, Character Classes, and Quantifiers

ARE syntax supports POSIX bracket expressions like [:alpha:] and [:digit:] inside character classes, anchors ^ and $ to pin a match to the start or end of a line, and quantifiers *, +, ?, and {n,m} to control repetition. Combining these lets a single pattern like {^[[:upper:]][[:lower:]]+$} validate that a string is exactly one capitalized word without writing a manual character-by-character loop, and non-greedy quantifiers such as +? restrict a repeated match to the shortest possible span instead of the default longest one.

🏏

Cricket analogy: An anchor like ^ pinning a match to the start of a line is like a third umpire reviewing only the first frame after the bowler's front foot lands, ignoring everything that happens later in the delivery.

Because Tcl performs its own backslash and dollar-sign substitution inside double-quoted strings, always write regex patterns inside curly braces {...} rather than double quotes - otherwise Tcl's parser will consume metacharacters like \d or $ before the regexp engine ever sees the intended pattern.

regexp tests for a pattern match and can capture parenthesized groups into named variables.
regsub rewrites matched text, with \1, \2 in the replacement referring to capture groups.
The -all switch processes every match in the string, not just the first one.
The -inline switch returns matches as a flat list instead of assigning to variables.
ARE syntax supports POSIX classes like [:alpha:], anchors ^ $, and quantifiers * + ? {n,m}.
Always brace-quote regex patterns to prevent Tcl's own substitution from mangling metacharacters.
-nocase and -line flags adjust case sensitivity and multi-line anchor behavior.