TinTin++ Mud Client Manual
Regular Expressions
space
A regular expression, regex or regexp is a sequence of characters that defines a search pattern. Since the 1980s, different syntaxes for writing regular expressions exist, the two most widely used ones being the POSIX syntax and the similar but more advanced Perl standard. TinTin++ supports the Perl standard known as PCRE (Perl Compatible Regular Expressions).
space
Regular expressions are an integral part of TinTin++, but keep in mind that tintin doesn't allow you to use regular expressions directly, instead it uses a simpler intermediate syntax that still allows more complex expressions when needed.
space
Commands that utilize regular expressions are: action, alias, elseif, gag, grep, highlight, if, kill, local, math, prompt, regexp, replace, substitute, switch, variable, and while. Several other commands use regular expressions in minor ways. Fortunately the basics are very easy to learn.
space
TinTin++ Regular Expression
space
The following support is available for regular expressions.

       ^ match start of line.
       $ match of end of line.
       \ escape one character.

  %1-%99 match of any text, stored in the corresponding index.
      %0 should be avoided in the regex, and if left alone contains all matched text.
     { } embed a perl compatible regular expression, matches are stored.
   %!{ } embed a perc compatible regular expression, matches are not stored.

         [ ] . + | ( ) ? * are treated as normal text unless used within braces. Keep in mind that { } is replaced with ( ) automatically unless %!{ } is used.
         
space
space
Variables
space
If you use %1 in an action to perform a match the matched string is stored in the %1 variable which can be used in the action body.
space
Example: %1 says 'Tickle me'} {tickle %1}
space
If you use %2 the match is stored in %2, etc. If you use an unnumbered match like %* or %S the match is stored at the last used index incremented by one.
space
Example: %3 says '%*'} {#if {"%4" == "Tickle me"} {tickle %3}}
space
The maximum variable index is 99. If you begin an action with %* the match is stored in %1. You should never use %0 in the trigger part of an action, when used in the body of an action %0 contains all the parts of the string that were matched.
space
To prevent a match from being stored use %!*, %!w, etc.
space
Perl Compatible Regular Expressions
space
You can embed a PCRE (Perl Compatible Regular Expression) using curley braces { }, these braces are replaced with paranthesis ( ) unless you use %!{ }.
space
Or
space
You can separate alternatives within a PCRE using the | character.
space
Example: #act {%* scratches {his|her|its} butt.} {mutter Someone should wash %2 hands..}
space
Brackets
space
You can group alternatives and ranges within a PCRE using brackets.
space
Example: #act {%* says 'Who is number {[1-9]}} {say $number[%2] is number %2}
space
The example only triggers if someone provides a number between 1 and 9. Any other character will cause the action to not trigger.
space
Example: #act {%* says 'Set password to {[^0-9]*}$} {say The password must contain at least one number, not for security reasons, but just to annoy you.} {4}
space
When the ^ character is used within brackets it creates an inverse search, [^0-9] matches every character except for a number between 0 and 9.
space
Quantification
space
A quantifier placed after a match specifies how often the match is allowed to occur.

      ? repeat zero or one time.
      * repeat zero or multiple times.
      + repeat once or multiple times.
    {n} repeat exactly n times, n must be a number.
   {n,} repeat at least n times, n must be a number.
  {n,o} repeat between n and o times, n and o must be a number.
space
Example: #act {%* says 'Who is number {[1-9][0-9]{0,2}} {Say $number[%2] is number %2}
space
The example only triggers if someone provides a number between 1 and 999.
space
Paranthesis
space
TinTin Regular Expressions automatically add parenthesis, for example %* translates to (.*?) in PCRE. Paranthesis in PCRE causes a change in execution priority similar to mathematical expressions, but paranthesis also causes the match to be stored to a variable.
space
When nesting multiple sets of paranthesis each nest is assigned its own numercial variable in order of appearance.
space
Example: #act {%* chats '{Mu(ha)+}'} {chat %2ha!}
space
If someone chats Muha you will chat Muhaha! If someone chats Muhaha you will chat Muhahaha!
space
Lazy vs Greedy
space
By default regex matches are greedy, meaning {.*} will capture as much text as possible.
space
Example: #regex {bli bla blo} {^{.*} {.*}$} {#showme Arg1=(&1) Arg2=(&2)}
space
This will display: Arg1=(bli bla) Arg2=(blo)
space
By appending a ? behind a regex it becomes lazy, meaning {.*?} will capture as little text as possible.
space
Example: #regex {bli bla blo} {^{.*?} {.*?}$} {#showme Arg1=(&1) Arg2=(&2)}
space
This will display: Arg1=(bli) Arg2=(bla blo).
space
Escape Codes
space
TinTin++ and PCRE support the following escape codes.
space
space
\s matches one space, \s+ matches one or multiple spaces.
space
Color triggers
space
To make matching easier text triggers (Actions, Gags, Highlights, Prompts, and Substitutes) have their color codes stripped. If you want to create a color trigger you must start the triggers with a ~ (tilda). To make escape codes visible use #config {convert meta} on.
space
Example: #action {~\e[1;37m%1} {#var roomname %1}
space
If the room name is the only line on the mud in bright white this color trigger will save the roomname.
space
space
This covers the basics. PCRE has more options, most of which are somewhat obscure, so you'll have to read a PCRE manual for additional information.
space
See also: Colors, Escape Codes and Mathematics.
space