regexp(3tcl)

💖 regexp — the Tcl Built-In Command glow-up 💖

okay bestie, listen. this one's a Tcl Built-In Commands classic and it's lowkey the moment. it's called regexp, and it's about matching a regular expression against a string. periodt.

---

✨ SYNOPSIS ✨

regexp ?switches? exp string ?matchVar? ?subMatchVar subMatchVar ...?

---

🌸 DESCRIPTION 🌸

so what it does: it figures out whether the regular expression exp matches part or all of string, and it hands you back 1 if it does, 0 if it does not — unless you passed -inline, in which case it does something else (scroll down babe, we get there). (and if you wanna know how regex matching itself works, that's all described over in the re_syntax reference page, iykyk.)

now here's the cute part 🫶 — if you drop extra arguments after string, those get treated as the names of variables where the command will stuff info about which part(s) of string matched exp.

• MatchVar gets set to the range of string that matched all of exp.
• the first subMatchVar gets the characters in string that matched the leftmost parenthesized subexpression inside exp.
• the next subMatchVar gets the characters that matched the next parenthesized subexpression to the right in exp.
• and so on, on and on, forever and ever 💫

and if the initial arguments to regexp start with -, they're treated as switches, obviously. the currently supported switches are:

🎀 OPTIONS 🎀

• -about — instead of even trying to match the regex, it returns a list containing info about the regular expression. first element of that list is a subexpression count. second element is a list of property names describing various attributes of the regex. this one is mainly for debugging purposes, ngl.
• -expanded — turns on the expanded regular expression syntax, where whitespace and comments are just ignored. same thing as specifying the (?x) embedded option (peep the re_syntax manual page).
• -indices — changes what gets stored in the matchVar and subMatchVars. instead of storing the actual matching characters from string, each variable gets a list of two decimal strings: the indices in string of the first and last characters in the matching range of characters. iconic for when you just want positions.
• -line — enables newline-sensitive matching. by default, newline is a completely ordinary character with zero special meaning. with this flag tho:
  • “[^” bracket expressions and “.” never match newline
  • “^” matches an empty string after any newline, in addition to its normal function
  • “$” matches an empty string before any newline, in addition to its normal function

this flag is equivalent to specifying both -linestop and -lineanchor, or the (?n) embedded option (again, re_syntax manual page 💅).

• -linestop — changes the behavior of “[^” bracket expressions and “.” so they stop at newlines. same as specifying the (?p) embedded option (see the re_syntax manual page).
• -lineanchor — changes the behavior of “^” and “$” (the “anchors”) so they match the beginning and end of a line respectively. same as specifying the (?w) embedded option (see the re_syntax manual page).
• -nocase — makes upper-case characters in string get treated as lower case during matching. slay.
• -all — makes the regular expression match as many times as possible in the string, and returns the total number of matches found. if you use this with match variables, they'll only contain info for the last match. just the last one. ok bestie, noted 📝
• -inline — makes the command return, as a list, the data that would otherwise go into match variables. when you use -inline, match variables may not be specified. if you use it with -all, the list gets concatenated at each iteration, so you always get a flat list back. for each match iteration, the command appends the overall match data, plus one element for each subexpression in the regular expression. examples:

regexp -inline -- {\w(\w)} " inlined "
      → in n
regexp -all -inline -- {\w(\w)} " inlined "
      → in n li i ne e

• -start index — specifies a character index offset into the string where matching the regular expression should start. the index value gets interpreted the same way as the index argument to string index. when you use this switch, “^” will not match the beginning of the line, and \A will still match the start of the string at index. if -indices is specified, the indices will be indexed starting from the absolute beginning of the input string. index gets constrained to the bounds of the input string. no out-of-bounds nonsense here ✋
• -- — marks the end of switches. the argument right after this one gets treated as exp even if it starts with a -. lifesaver fr.

---

⚠️ heads up bestie: if there are more subMatchVars than parenthesized subexpressions within exp, or if a particular subexpression in exp doesn't match the string (like, because it was in a portion of the expression that wasn't matched), then the corresponding subMatchVar gets set to “-1 -1” if -indices was specified, or to an empty string otherwise. that's just how it is 💀

---

🌈 EXAMPLES 🌈

find the first occurrence of a word starting with foo in a string that isn't actually an instance of foobar, and get the letters following it up to the end of the word into a variable:

regexp {\mfoo(?!bar\M)(\w*)} $string -> restOfWord

not me putting the whole matched substring into the variable “->” — that's a name chosen purely to look nice, since we are not actually interested in its contents 🙈

find the index of the word badger (in any case) within a string and store that in the variable location:

regexp -indices {(?i)\mbadger\M} $string location

this could also be written as a basic regular expression match (as opposed to using the default syntax of advanced regular expressions) by prefixing the expression with a suitable flag:

regexp -indices {(?ib)\<badger\>} $string location

this counts the number of octal digits in a string:

regexp -all {[0-7]} $string

and this lists all words (consisting of all sequences of non-whitespace characters) in a string — useful as a more powerful version of the split command:

regexp -all -inline {\S+} $string

---

👑 SEE ALSO 👑

re_syntax(3tcl), regsub(3tcl), string(3tcl)

---

🦋 KEYWORDS 🦋

match, parsing, pattern, regular expression, splitting, string

---

okay that's the whole page, bestie, we ate and left no crumbs 💅✨ this was the regexp(3tcl) page from Tcl 8.3 — go match something iconic, you've got this 🫶🎀