A regular expression is a sequence of characters that defines a certain text pattern, typically one that one wishes to find in some large body of text.

In theoretical computer science and formal language theory, regular expressions are used to describe so-called regular languages. Since their inception in the 1950's, practical implementations of regular expressions, for instance in the text search and replace functions of text editors, have outgrown their strict scientific definition. In acknowledgement of this, and in an attempt to disambiguate, a regular expression in Raku is normally referred to as a Regex (from: regular expression), a term that is also in common use in other programming languages.

In Raku, regexes are written in a domain-specific language, i.e. a sublanguage or slang. This page describes this language, and explains how regexes can be used to search for text patterns in strings in a process called pattern matching.

Lexical conventions§

Fundamentally, Raku regexes are very much like subroutines: both are code objects, and just as you can have anonymous subs and named subs, you can have anonymous and named regexes.

A regex, whether anonymous or named, is represented by a Regex object. Yet, the syntax for constructing anonymous and named Regex objects differs. We will therefore discuss them in turn.

Anonymous regex definition syntax§

An anonymous regex may be constructed in one of the following ways:

rx/pattern/;          # an anonymous Regex object; 'rx' stands for 'regex' 
/pattern/;            # an anonymous Regex object; shorthand for 'rx/.../' 
 
regex { pattern };    # keyword-declared anonymous regex; this form is 
                      # intended for defining named regexes and is discussed 
                      # in that context in the next section

The rx/ / form has two advantages over the bare shorthand form / /.

Firstly, it enables the use of delimiters other than the slash, which may be used to improve the readability of the regex definition:

rx{ '/tmp/'.* };      # the use of curly braces as delimiters makes this first 
rx/ '/tmp/'.* /;      # definition somewhat easier on the eyes than the second

Although the choice is vast, not every character may be chosen as an alternative regex delimiter:

• You cannot use whitespace or alphanumeric characters as delimiters. Whitespace in regex definition syntax is generally optional, except where it is required to distinguish from function call syntax (discussed hereafter).

• Parentheses can be used as alternative regex delimiters, but only with a space between rx and the opening delimiter. This is because identifiers that are immediately followed by parentheses are always parsed as a subroutine call. For example, in rx() the call operator () invokes the subroutine rx. The form rx ( abc ), however, does define a Regex object.

• Use of a colon as a delimiter would clash with the use of adverbs, which take the form :adverb; accordingly, such use of the colon is forbidden.

• The hash character # is not available as a delimiter since it is parsed as the start of a comment that runs until the end of the line.

Secondly, the rx form allows you to insert regex adverbs between rx and the opening delimiter to modify the definition of the entire regex. This is equivalent to inserting the adverb at the beginning of the regex, but may be clearer:

rx:r:s/pattern/;            # :r (:ratchet) and :s (:sigspace) adverbs, defining 
                            # a ratcheting regex in which whitespace is significant 
rx/:r:s pattern/;           # Same, but possibly less readable

Although anonymous regexes are not, as such, named, they may effectively be given a name by putting them inside a named variable, after which they can be referenced, both outside of an embedding regex and from within an embedding regex by means of interpolation:

my $regex = / R \w+ /;
say "Zen Buddhists like Raku too" ~~ $regex; # OUTPUT: «｢Raku｣␤» 
 
my $regex = /pottery/;
"Japanese pottery rocks!" ~~ / <$regex> /;  # Interpolation of $regex into /.../ 
say $/;                                     # OUTPUT: «｢pottery｣␤»

Named regex definition syntax§

A named regex may be constructed using the regex declarator as follows:

regex R { pattern };        # a named Regex object, named 'R'

Unlike with the rx form, you cannot chose your preferred delimiter: curly braces are mandatory. In this regard it should be noted that the definition of a named regex using the regex form is syntactically similar to the definition of a subroutine:

my sub   S { /pattern/ };   # definition of Sub object (returning a Regex) 
my regex R {  pattern  };   # definition of Regex object

which emphasizes the fact that a Regex object represents code rather than data:

&S ~~ Code;                 # OUTPUT: «True␤» 
 
&R ~~ Code;                 # OUTPUT: «True␤» 
&R ~~ Method;               # OUTPUT: «True␤»   (A Regex is really a Method!) 

Also unlike with the rx form for defining an anonymous regex, the definition of a named regex using the regex keyword does not allow for adverbs to be inserted before the opening delimiter. Instead, adverbs that are to modify the entire regex pattern may be included first thing within the curly braces:

regex R { :i pattern };     # :i (:ignorecase), renders pattern case insensitive

Alternatively, by way of shorthand, it is also possible (and recommended) to use the rule and token variants of the regex declarator for defining a Regex when the :ratchet and :sigspace adverbs are of interest:

regex R { :r pattern };     # apply :r (:ratchet) to entire pattern 

and, alternatively

token R { pattern };        # same thing: 'token' implies ':r' 

Or

regex R { :r :s pattern };  # apply :r (:ratchet) and :s (:sigspace) to pattern 

with this alternative:

rule  R { pattern };        # same thing: 'rule' implies ':r:s' 

Named regexes may be used as building blocks for other regexes, as they are methods that may called from within other regexes using the <regex-name> syntax. When they are used this way, they are often referred to as subrules; see for more details on their use here. Grammars are the natural habitat of subrules, but many common predefined character classes are also implemented as named regexes.

Regex readability: whitespace and comments§

Whitespace in regexes is ignored unless the :sigspace adverb is used to make whitespace syntactically significant.

In addition to whitespace, comments may be used inside of regexes to improve their comprehensibility just as in code in general. This is true for both single line comments and multi line/embedded comments:

my $regex =  rx/ \d ** 4            #`(match the year YYYY) 
                 '-'
                 \d ** 2            # ...the month MM 
                 '-'
                 \d ** 2 /;         # ...and the day DD 
 
say '2015-12-25'.match($regex);     # OUTPUT: «｢2015-12-25｣␤»

Match syntax§

There are a variety of ways to match a string against a regex. Irrespective of the syntax chosen, a successful match results in a Match object. In case the match is unsuccessful, the result is Nil. In either case, the result of the match operation is available via the special match variable $/.

The most common ways to match a string against an anonymous regex /pattern/ or against a named regex R include the following:

• Smartmatch: "string" ~~ /pattern/, or "string" ~~ /<R>/

  Smartmatching a string against a Regex performs a regex match of the string against the Regex:

  Raku highlighting

  say "Go ahead, make my day." ~~ / \w+ /;   # OUTPUT: «｢Go｣␤» 
   
  my regex R { me|you };
  say "You talkin' to me?" ~~ / <R> /;       # OUTPUT: «｢me｣␤ R => ｢me｣␤» 
  say "May the force be with you." ~~ &R ;   # OUTPUT: «｢you｣␤»

  The different outputs of the last two statements show that these two ways of smartmatching against a named regex are not identical. The difference arises because the method call <R> from within the anonymous regex / / installs a so-called 'named capture' in the Match object, while the smartmatch against the named Regex as such does not.

• Explicit topic match: m/pattern/, or m/<R>/

  The match operator m/ / immediately matches the topic variable $_ against the regex following the m.

  As with the rx/ / syntax for regex definitions, the match operator may be used with adverbs in between m and the opening regex delimiter, and with delimiters other than the slash. However, while the rx/ / syntax may only be used with regex adverbs that affect the compilation of the regex, the m/ / syntax may additionally be used with matching adverbs that determine how the regex engine is to perform pattern matching.

  Here's an example that illustrates the primary difference between the m/ / and / / syntax:

  Raku highlighting

  my $match;
  $_ = "abc";
  $match = m/.+/; say $match; say $match.^name; # OUTPUT: «｢abc｣␤Match␤» 
  $match =  /.+/; say $match; say $match.^name; # OUTPUT: «/.+/␤Regex␤»

• Implicit topic match in sink and Boolean contexts

  In case a Regex object is used in sink context, or in a context in which it is coerced to Bool, the topic variable $_ is automatically matched against it:

  Raku highlighting

  $_ = "dummy string";        # Set the topic explicitly 
   
  rx/ s.* /;                  # Regex object in sink context matches automatically 
  say $/;                     # OUTPUT: «｢string｣␤» 
   
  say $/ if rx/ d.* /;        # Regex object in Boolean context matches automatically 
                              # OUTPUT: «｢dummy string｣␤»

• Match method: "string".match: /pattern/, or "string".match: /<R>/

  The match method is analogous to the m/ / operator discussed above. Invoking it on a string, with a Regex as an argument, matches the string against the Regex.

• Parsing grammars: grammar-name.parse($string)

  Although parsing a grammar involves more than just matching a string against a regex, this powerful regex-based text destructuring tool can't be left out from this overview of common pattern matching methods.

  If you feel that your needs exceed what simple regexes have to offer, check out this grammar tutorial to take regexes to the next level.

Literals and metacharacters§

A regex describes a pattern to be matched in terms of literals and metacharacters. Alphanumeric characters and the underscore _ constitute the literals: these characters match themselves and nothing else. Other characters act as metacharacters and may, as such, have a special meaning, either by themselves (such as the dot ., which serves as a wildcard) or together with other characters in larger metasyntactic constructs (such as <?before ...>, which defines a lookahead assertion).

In its simplest form a regex comprises only literals:

/Cześć/;           # "Hello" in Polish 
/こんばんは/;        # "Good afternoon" in Japanese 
/Καλησπέρα/;       # "Good evening" in Greek

If you want a regex to literally match one or more characters that normally act as metacharacters, those characters must either be escaped using a backslash, or be quoted using single or double quotes.

The backslash serves as a switch. It switches a single metacharacter into a literal, and vice versa:

/ \# /;             # matches the hash metacharacter literally 
/ \w /;             # turns literal 'w' into a character class (see below) 
/Hallelujah\!/;     # matches string 'Hallelujah!' incl. exclamation mark

Even if a metacharacter does not (yet) have a special meaning in Raku, escaping (or quoting) it is required to ensure that the regex compiles and matches the character literally. This allows the clear distinction between literals and metacharacters to be maintained. So, for instance, to match a comma this will work:

/ \, /;             # matches a literal comma ','

while this will fail:

/ ,  /;             # !! error: an as-yet meaningless/unrecognized metacharacter 
                    # does not automatically match literally 

While an escaping backslash exerts its effect on the next individual character, both a single metacharacter and a sequence of metacharacters may be turned into literally matching strings by quoting them in single or double quotes:

/ "abc" /;          # quoting literals does not make them more literal 
/ "Hallelujah!" /;  # yet, this form is generally preferred over /Hallelujah\!/ 
 
/ "two words" /;    # quoting a space renders it significant, so this matches 
                    # the string 'two words' including the intermediate space 
 
/ '#!:@' /;         # this regex matches the string of metacharacters '#!:@'

Quoting does not necessarily turn every metacharacter into a literal, however. This is because quotes follow Raku's normal rules for interpolation. In particular, ｢…｣ quotes do not allow any interpolation; single quotes (either '…' or ‘…’) allow the backslash to escape single quotes and the backslash itself; and double quotes (either "…" or “…”) enable the interpolation of variables and code blocks of the form {…}. Hence all of this works:

/ '\\\'' /;          # matches a backslash followed by a single quote: \' 
/ ｢\'｣ /;       # also matches a backslash followed by a single quote 
my $x = 'Hi';
/ "$x there!" /;     # matches the string 'Hi there!' 
 
/ "1 + 1 = {1+1}" /; # matches the string '1 + 1 = 2'

while these examples illustrate mistakes that you will want to avoid:

/ '\' /;             # !! error: this is NOT the way to literally match a 
                     # backslash because now it escapes the second quote 
 
/"Price tag $0.50"/; # !! error: "$0" is interpreted as the first positional 
                     # capture (which is Nil), not as '$0' 

Strings are searched left to right, so it is enough if only part of the string matches the regex:

if 'Life, the Universe and Everything' ~~ / and / {
    say ~$/;            # OUTPUT: «and␤» 
    say $/.prematch;    # OUTPUT: «Life, the Universe ␤» 
    say $/.postmatch;   # OUTPUT: « Everything␤» 
    say $/.from;        # OUTPUT: «19␤» 
    say $/.to;          # OUTPUT: «22␤» 
};

Match results are always stored in the $/ variable and are also returned from the match. They are both of type Match if the match was successful; otherwise both are of type Nil.

Wildcards§

An unescaped dot . in a regex matches any single character.

So, these all match:

'raku' ~~ /rak./;       # matches the whole string 
'raku' ~~ / rak . /;    # the same; whitespace is ignored 
'raku' ~~ / ra.u /;     # the . matches the k 
'raker' ~~ / rak. /;    # the . matches the e

while this doesn't match:

'raku' ~~ / . rak /;

because there's no character to match before rak in the target string.

Notably . also matches a logical newline \n:

my $text = qq:to/END/ 
  Although I am a
  multi-line text,
  I can be matched
  with /.*/.
  END
  ;
 
say $text ~~ / .* /;
# OUTPUT: «｢Although I am a␤multi-line text,␤I can be matched␤with /.*/.␤｣»

Character classes§

Backslashed character classes§

There are predefined character classes of the form \w. Its negation is written with an upper-case letter, \W.

\n and \N§

\n matches a logical newline. \N matches a single character that's not a logical newline.

The definition of what constitutes a logical newline follows the Unicode definition of a line boundary and includes in particular all of: a line feed (LF) \U+000A, a vertical tab (VT) \U+000B, a form feed (FF) \U+000C, a carriage return (CR) \U+000D, and the Microsoft Windows style newline sequence CRLF.

The interpretation of \n in regexes is independent of the value of the variable $?NL controlled by the newline pragma.

\t and \T§

\t matches a single tab/tabulation character, U+0009. \T matches a single character that is not a tab.

Note that exotic tabs like the U+000B VERTICAL TABULATION character are not included here.

\h and \H§

\h matches a single horizontal whitespace character. \H matches a single character that is not a horizontal whitespace character.

Examples of horizontal whitespace characters are

U+0020 SPACE
U+00A0 NO-BREAK SPACE
U+0009 CHARACTER TABULATION
U+2001 EM QUAD

Vertical whitespace such as newline characters are explicitly excluded; those can be matched with \v; \s matches any kind of whitespace.

\v and \V§

\v matches a single vertical whitespace character. \V matches a single character that is not vertical whitespace.

Examples of vertical whitespace characters:

U+000A LINE FEED
U+000B VERTICAL TABULATION
U+000C FORM FEED
U+000D CARRIAGE RETURN
U+0085 NEXT LINE
U+2028 LINE SEPARATOR
U+2029 PARAGRAPH SEPARATOR

Use \s to match any kind of whitespace, not just vertical whitespace.

\s and \S§

\s matches a single whitespace character. \S matches a single character that is not whitespace.

say $/.prematch if 'Match the first word.' ~~ / \s+ /;
# OUTPUT: «Match␤»

\d and \D§

\d matches a single decimal digit (Unicode General Category Number, Decimal Digit, Nd); conversely, \D matches a single character that is not a decimal digit.

'ab42' ~~ /\d/ and say ~$/;     # OUTPUT: «4␤» 
'ab42' ~~ /\D/ and say ~$/;     # OUTPUT: «a␤»

Note that not only the Arabic digits (commonly used in the Latin alphabet) match \d, but also decimal digits from other scripts.

Examples of decimal digits include:

U+0035 5 DIGIT FIVE
U+0BEB ௫ TAMIL DIGIT FIVE
U+0E53 ๓ THAI DIGIT THREE
U+17E5 ៥ KHMER DIGIT FIVE

Also note that "decimal digit" is a narrower category than "Number" because (Unicode) numbers include not only decimal numbers (Nd) but also letter numbers (Nl) and other numbers (No) Examples of Unicode numbers that are not decimal digits include:

U+2464 ⑤ CIRCLED DIGIT FIVE
U+2476 ⑶ PARENTHESIZED DIGIT THREE
U+2083 ₃ SUBSCRIPT THREE

To match against all numbers, you can use the Unicode property N:

say '⑤' ~~ /<:N>/ # OUTPUT: «｢⑤｣␤»

\w and \W§

\w matches a single word character, i.e. a letter (Unicode category L), a digit or an underscore. \W matches a single character that is not a word character.

Examples of word characters:

0041 A LATIN CAPITAL LETTER A
0031 1 DIGIT ONE
03B4 δ GREEK SMALL LETTER DELTA
03F3 ϳ GREEK LETTER YOT
0409 Љ CYRILLIC CAPITAL LETTER LJE

\c and \C§

\c takes a parameter delimited by square-brackets which is the name of a Unicode character as it appears in the Unicode Character Database (UCD) and matches that specific character. For example:

'a.b' ~~ /\c[FULL STOP]/ and say ~$/;    # OUTPUT: «.␤»

\C matches a single character that is not the named Unicode character.

Note that the word "character" is used, here, in the sense that the UCD does, but because Raku uses NFG, combining code points and the base characters to which they are attached, will generally not match individually. For example if you compose "ü" as "u\x[0308]", that works just fine, but matching may surprise you:

say "u\x[0308]" ~~ /\c[LATIN SMALL LETTER U]/;    # OUTPUT: «Nil␤»

To match the unmodified character, you can use the :ignoremark adverb.

\x and \X§

\x takes a parameter delimited by square-brackets which is the hexadecimal representation of the Unicode codepoint representing the character to be matched. For example:

'a.b' ~~ /\x[2E]/ and say ~$/;    # OUTPUT: «.␤»

\X matches a single character that is not the given Unicode codepoint.

In addition, \x and \X can be used without square brackets, in which case, any characters that follow the x or X that are valid hexadecimal digits will be consumed. This means that all of these are equivalent:

/\x2e/ and /\x002e/ and /\x00002e/

But this format can be ambiguous, so the use of surrounding whitespace is highly recommended in non-trivial expressions.

For additional provisos with respect to combining codepoints, see \c and \C.

Predefined character classes§

The predefined character classes in the leftmost column are all of the form <name>, a hint to the fact that they are implemented as built-in named regexes. As such they are subject to the usual capturing semantics. This means that if a character class is called with the syntax <name> (i.e. as indicated in the leftmost column), it will not only match, but also capture, installing a correspondingly named 'named capture' in the resulting Match. In case just a match and no capture is desired, the capture may be suppressed through the use of call syntax that includes a leading dot: <.name>.

Predefined Regexes§

Besides the built-in character classes, Raku provides built-in anchors and zero-width assertions defined as named regexes. These include wb (word boundary), ww (within word), and same (the next and previous character are the same). See the anchors and zero-width assertions sections for details.

Raku also provides the two predefined tokens (i.e., regexes that don't backtrack) shown below:

Unicode properties§

The character classes mentioned so far are mostly for convenience; another approach is to use Unicode character properties. These come in the form <:property>, where property can be a short or long Unicode General Category name. These use pair syntax.

To match against a Unicode property you can use either smartmatch or uniprop:

"a".uniprop('Script');                 # OUTPUT: «Latin␤» 
"a" ~~ / <:Script<Latin>> /;           # OUTPUT: «｢a｣␤» 
"a".uniprop('Block');                  # OUTPUT: «Basic Latin␤» 
"a" ~~ / <:Block('Basic Latin')> /;    # OUTPUT: «｢a｣␤»

These are the Unicode general categories used for matching:

For example, <:Lu> matches a single, upper-case letter.

Its negation is this: <:!property>. So, <:!Lu> matches a single character that is not an upper-case letter.

Categories can be used together, with an infix operator:

To match either a lower-case letter or a number, write <:Ll+:N> or <:Ll+:Number> or <+ :Lowercase_Letter + :Number>.

It's also possible to group categories and sets of categories with parentheses; for example:

say $0 if 'raku9' ~~ /\w+(<:Ll+:N>)/ # OUTPUT: «｢9｣␤»

Enumerated character classes and ranges§

Sometimes the pre-existing wildcards and character classes are not enough. Fortunately, defining your own is fairly simple. Within <[ ]>, you can put any number of single characters and ranges of characters (expressed with two dots between the end points), with or without whitespace.

"abacabadabacaba" ~~ / <[ a .. c 1 2 3 ]>* /;
# Unicode hex codepoint range 
"ÀÁÂÃÄÅÆ" ~~ / <[ \x[00C0] .. \x[00C6] ]>* /;
# Unicode named codepoint range 
"αβγ" ~~ /<[\c[GREEK SMALL LETTER ALPHA]..\c[GREEK SMALL LETTER GAMMA]]>*/;
# Non-alphanumeric 
'$@%!' ~~ /<[ ! @ $ % ]>+/  # OUTPUT: «｢$@%!｣␤»

As the last line above illustrates, within <[ ]> you do not need to quote or escape most non-alphanumeric characters the way you do in regex text outside of <[ ]>. You do, however, need to escape the much smaller set of characters that have special meaning within <[ ]>, such as \, [, and ].

To escape characters that would have some meaning inside the <[ ]>, precede the character with a \.

say "[ hey ]" ~~ /<-[ \] \[ \s ]>+/; # OUTPUT: «｢hey｣␤»

You do not have the option of quoting special characters inside a <[ ]> – a ' just matches a literal '.

Within the < > you can use + and - to add or remove multiple range definitions and even mix in some of the Unicode categories above. You can also write the backslashed forms for character classes between the [ ].

/ <[\d] - [13579]> /;
# starts with \d and removes odd ASCII digits, but not quite the same as 
/ <[02468]> /;
# because the first one also contains "weird" unicodey digits

You can include Unicode properties in the list as well:

/<:Zs + [\x9] - [\xA0] - [\x202F] >/
# Any character with "Zs" property, or a tab, but not a "no-break space" or "narrow no-break space"

To negate a character class, put a - after the opening angle bracket:

say 'no quotes' ~~ /  <-[ " ]> + /;  # <-["]> matches any character except "

A common pattern for parsing quote-delimited strings involves negated character classes:

say '"in quotes"' ~~ / '"' <-[ " ]> * '"'/;

This regex first matches a quote, then any characters that aren't quotes, and then a quote again. The meaning of * and + in the examples above are explained in the next section on quantifiers.

Just as you can use the - for both set difference and negation of a single value, you can also explicitly put a + in front:

/ <+[123]> /  # same as <[123]>

Quantifiers§

A quantifier makes the preceding atom match a variable number of times. For example, a+ matches one or more a characters.

Quantifiers bind tighter than concatenation, so ab+ matches one a followed by one or more bs. This is different for quotes, so 'ab'+ matches the strings ab, abab, ababab etc.

One or more: +§

The + quantifier makes the preceding atom match one or more times, with no upper limit.

For example, to match strings of the form key=value, you can write a regex like this:

/ \w+ '=' \w+ /

Zero or more: *§

The * quantifier makes the preceding atom match zero or more times, with no upper limit.

For example, to allow optional whitespace between a and b you can write:

/ a \s* b /

Zero or one: ?§

The ? quantifier makes the preceding atom match zero or once.

For example, to match dog or dogs, you can write:

/ dogs? /

General quantifier: ** min..max§

To quantify an atom an arbitrary number of times, use the ** quantifier, which takes a single Int or a Range on the right-hand side that specifies the number of times to match. If a Range is specified, the end-points specify the minimum and maximum number of times to match.

say 'abcdefg' ~~ /\w ** 4/;      # OUTPUT: «｢abcd｣␤» 
say 'a'       ~~ /\w **  2..5/;  # OUTPUT: «Nil␤» 
say 'abc'     ~~ /\w **  2..5/;  # OUTPUT: «｢abc｣␤» 
say 'abcdefg' ~~ /\w **  2..5/;  # OUTPUT: «｢abcde｣␤» 
say 'abcdefg' ~~ /\w ** 2^..^5/; # OUTPUT: «｢abcd｣␤» 
say 'abcdefg' ~~ /\w ** ^3/;     # OUTPUT: «｢ab｣␤» 
say 'abcdefg' ~~ /\w ** 1..*/;   # OUTPUT: «｢abcdefg｣␤» 

Only basic literal syntax for the right-hand side of the quantifier is supported, to avoid ambiguities with other regex constructs. If you need to use a more complex expression, for example, a Range made from variables, enclose the Range in curly braces:

my $start = 3;
say 'abcdefg' ~~ /\w ** {$start .. $start+2}/; # OUTPUT: «｢abcde｣␤» 
say 'abcdefg' ~~ /\w ** {π.Int}/;              # OUTPUT: «｢abc｣␤» 

Negative values are treated like zero:

say 'abcdefg' ~~ /\w ** {-Inf}/;     # OUTPUT: «｢｣␤» 
say 'abcdefg' ~~ /\w ** {-42}/;      # OUTPUT: «｢｣␤» 
say 'abcdefg' ~~ /\w ** {-10..-42}/; # OUTPUT: «｢｣␤» 
say 'abcdefg' ~~ /\w ** {-42..-10}/; # OUTPUT: «｢｣␤» 

If then, the resultant value is Inf or NaN or the resultant Range is empty, non-Numeric, contains NaN end-points, or has minimum effective end-point as Inf, the X::Syntax::Regex::QuantifierValue exception will be thrown:

(try say 'abcdefg' ~~ /\w ** {42..10}/  )
    orelse say ($!.^name, $!.empty-range);
    # OUTPUT: «(X::Syntax::Regex::QuantifierValue True)␤» 
(try say 'abcdefg' ~~ /\w ** {Inf..Inf}/)
    orelse say ($!.^name, $!.inf);
    # OUTPUT: «(X::Syntax::Regex::QuantifierValue True)␤» 
(try say 'abcdefg' ~~ /\w ** {NaN..42}/ )
    orelse say ($!.^name, $!.non-numeric-range);
    # OUTPUT: «(X::Syntax::Regex::QuantifierValue True)␤» 
(try say 'abcdefg' ~~ /\w ** {"a".."c"}/)
    orelse say ($!.^name, $!.non-numeric-range);
    # OUTPUT: «(X::Syntax::Regex::QuantifierValue True)␤» 
(try say 'abcdefg' ~~ /\w ** {Inf}/)
    orelse say ($!.^name, $!.inf);
    # OUTPUT: «(X::Syntax::Regex::QuantifierValue True)␤» 
(try say 'abcdefg' ~~ /\w ** {NaN}/)
    orelse say ($!.^name, $!.non-numeric);
    # OUTPUT: «(X::Syntax::Regex::QuantifierValue True)␤» 

Modified quantifier: %, %%§

To more easily match things like comma separated values, you can tack on a % modifier to any of the above quantifiers to specify a separator that must occur between each of the matches. For example, a+ % ',' will match a or a,a or a,a,a, etc.

%% is like %, with the difference that it can optionally match trailing delimiters as well. This means that besides a and a,a, it can also match a, and a,a,.

The quantifier interacts with % and controls the number of overall repetitions that can match successfully, so a* % ',' also matches the empty string. If you want match words delimited by commas, you might need to nest an ordinary and a modified quantifier:

say so 'abc,def' ~~ / ^ [\w+] ** 1 % ',' $ /;  # OUTPUT: «False␤» 
say so 'abc,def' ~~ / ^ [\w+] ** 2 % ',' $ /;  # OUTPUT: «True␤» 

Preventing backtracking: :§

One way to prevent backtracking is through the use of the ratchet adverb as described below. Another more fine-grained way of preventing backtracking in regexes is attaching a : modifier to a quantifier:

my $str = "ACG GCT ACT An interesting chain";
say $str ~~ /<[ACGT\s]>+ \s+ (<[A..Z a..z \s]>+)/;
# OUTPUT: «｢ACG GCT ACT An interesting chain｣␤ 0 => ｢An interesting chain｣␤» 
say $str ~~ /<[ACGT\s]>+: \s+ (<[A..Z a..z \s]>+)/;
# OUTPUT: «Nil␤» 

In the second case, the A in An had already been "absorbed" by the pattern, preventing the matching of the second part of the pattern, after \s+. Generally we will want the opposite: prevent backtracking to match precisely what we are looking for.

In most cases, you will want to prevent backtracking for efficiency reasons, for instance here:

say $str ~~ m:g/[(<[ACGT]> **: 3) \s*]+ \s+ (<[A..Z a..z \s]>+)/;
# OUTPUT: 
# «(｢ACG GCT ACT An interesting chain｣ 
# «0 => ｢ACG｣␤» 
# «0 => ｢GCT｣␤» 
# «0 => ｢ACT｣␤» 
# «1 => ｢An interesting chain｣)␤» 

Although in this case, eliminating the : from behind ** would make it behave exactly in the same way. The best use is to create tokens that will not be backtracked:

$_ = "ACG GCT ACT IDAQT";
say  m:g/[(\w+:) \s*]+ (\w+) $$/;
# OUTPUT: 
# «(｢ACG GCT ACT IDAQT｣␤» 
# «0 => ｢ACG｣␤» 
# «0 => ｢GCT｣␤» 
# «0 => ｢ACT｣␤» 
# «1 => ｢IDAQT｣)␤»

Without the : following \w+, the ID part captured would have been simply T, since the pattern would go ahead and match everything, leaving a single letter to match the \w+ expression at the end of the line.

Greedy versus frugal quantifiers: ?§

By default, quantifiers request a greedy match:

'abababa' ~~ /a .* a/ && say ~$/;   # OUTPUT: «abababa␤» 

You can attach a ? modifier to the quantifier to enable frugal matching:

'abababa' ~~ /a .*? a/ && say ~$/;   # OUTPUT: «aba␤» 

You can also enable frugal matching for general quantifiers:

say '/foo/o/bar/' ~~ /\/.**?{1..10}\//;  # OUTPUT: «｢/foo/｣␤» 
say '/foo/o/bar/' ~~ /\/.**!{1..10}\//;  # OUTPUT: «｢/foo/o/bar/｣␤»

Greedy matching can be explicitly requested with the ! modifier.

Alternation: ||§

To match one of several possible alternatives, separate them by ||; the first matching alternative wins.

For example, ini files have the following form:

[section]
key = value

Hence, if you parse a single line of an ini file, it can be either a section or a key-value pair and the regex would be (to a first approximation):

/ '[' \w+ ']' || \S+ \s* '=' \s* \S* /

That is, either a word surrounded by square brackets, or a string of non-whitespace characters, followed by zero or more spaces, followed by the equals sign =, followed again by optional whitespace, followed by another string of non-whitespace characters.

An empty string as the first branch is ignored, to allow you to format branches consistently. You could have written the previous example as

/
|| '[' \w+ ']'
|| \S+ \s* '=' \s* \S*
/

Even in non-backtracking contexts, the alternation operator || tries all the branches in order until the first one matches.

Longest alternation: |§

In short, in regex branches separated by |, the longest token match wins, independent of the textual ordering in the regex. However, what | really does is more than that. It does not decide which branch wins after finishing the whole match, but follows the longest-token matching (LTM) strategy.

Briefly, what | does is this:

• First, select the branch which has the longest declarative prefix.

say "abc" ~~ /ab | a.* /;                 # OUTPUT: «⌜abc⌟␤» 
say "abc" ~~ /ab | a {} .* /;             # OUTPUT: «⌜ab⌟␤» 
say "if else" ~~ / if | if <.ws> else /;  # OUTPUT: «｢if｣␤» 
say "if else" ~~ / if | if \s+   else /;  # OUTPUT: «｢if else｣␤»

As is shown above, a.* is a declarative prefix, while a {} .* terminates at {}, then its declarative prefix is a. Note that non-declarative atoms terminate declarative prefix. This is quite important if you want to apply | in a rule, which automatically enables :s, and <.ws> accidentally terminates declarative prefix.

• If it's a tie, select the match with the highest specificity.

say "abc" ~~ /a. | ab { print "win" } /;  # OUTPUT: «win｢ab｣␤»

When two alternatives match at the same length, the tie is broken by specificity. That is, ab, as an exact match, counts as closer than a., which uses character classes.

• If it's still a tie, use additional tie-breakers.

say "abc" ~~ /a\w| a. { print "lose" } /; # OUTPUT: «⌜ab⌟␤»

If the tie breaker above doesn't work, then the textually earlier alternative takes precedence.

For more details, see the LTM strategy.

Quoted lists are LTM matches§

Using a quoted list in a regex is equivalent to specifying the longest-match alternation of the list's elements. So, the following match:

say 'food' ~~ /< f fo foo food >/;      # OUTPUT: «｢food｣␤»

is equivalent to:

say 'food' ~~ / f | fo | foo | food /;  # OUTPUT: «｢food｣␤»

Note that the space after the first < is significant here: <food> calls the named rule food while < food > and < food> specify quoted lists with a single element, 'food'.

If the first branch is an empty string, it is ignored. This allows you to format your regexes consistently:

/
| f
| fo
| foo
| food
/

Arrays can also be interpolated into a regex to achieve the same effect:

my @increasingly-edible = <f fo foo food>;
say 'food' ~~ /@increasingly-edible/;   # OUTPUT: «｢food｣␤»

This is documented further under Regex Interpolation, below.

Conjunction: &&§

Matches successfully if all &&-delimited segments match the same substring of the target string. The segments are evaluated left to right.

This can be useful for augmenting an existing regex. For example if you have a regex quoted that matches a quoted string, then / <quoted> && <-[x]>* / matches a quoted string that does not contain the character x.

Note that you cannot easily obtain the same behavior with a lookahead, that is, a regex doesn't consume characters, because a lookahead doesn't stop looking when the quoted string stops matching.

say 'abc' ~~ / <?before a> && . /;    # OUTPUT: «Nil␤» 
say 'abc' ~~ / <?before a> . && . /;  # OUTPUT: «｢a｣␤» 
say 'abc' ~~ / <?before a> . /;       # OUTPUT: «｢a｣␤» 
say 'abc' ~~ / <?before a> .. /;      # OUTPUT: «｢ab｣␤» 

Just like with ||, empty first branches are ignored.

Conjunction: &§

Much like && in a Regexes, it matches successfully if all segments separated by & match the same part of the target string.

& (unlike &&) is considered declarative, and notionally all the segments can be evaluated in parallel, or in any order the compiler chooses.

Just like with || and &, empty first branches are ignored.

Anchors§

Regexes search an entire string for matches. Sometimes this is not what you want. Anchors match only at certain positions in the string, thereby anchoring the regex match to that position.

Start of string and end of string§

The ^ anchor only matches at the start of the string:

say so 'karakul'  ~~ /  raku/;    # OUTPUT: «True␤» 
say so 'karakul'  ~~ /^ raku/;    # OUTPUT: «False␤» 
say so 'rakuy'    ~~ /^ raku/;    # OUTPUT: «True␤» 
say so 'raku'     ~~ /^ raku/;    # OUTPUT: «True␤»

The $ anchor only matches at the end of the string:

say so 'use raku' ~~ /  raku  /;   # OUTPUT: «True␤» 
say so 'use raku' ~~ /  raku $/;   # OUTPUT: «True␤» 
say so 'rakuy'    ~~ /  raku $/;   # OUTPUT: «False␤»

You can combine both anchors:

say so 'use raku' ~~ /^ raku $/;   # OUTPUT: «False␤» 
say so 'raku'     ~~ /^ raku $/;   # OUTPUT: «True␤»

Keep in mind that ^ matches the start of a string, not the start of a line. Likewise, $ matches the end of a string, not the end of a line.

The following is a multi-line string:

my $str = chomp q:to/EOS/; 
   Keep it secret
   and keep it safe
   EOS
 
# 'safe' is at the end of the string 
say so $str ~~ /safe   $/;   # OUTPUT: «True␤» 
 
# 'secret' is at the end of a line, not the string 
say so $str ~~ /secret $/;   # OUTPUT: «False␤» 
 
# 'Keep' is at the start of the string 
say so $str ~~ /^Keep   /;   # OUTPUT: «True␤» 
 
# 'and' is at the start of a line -- not the string 
say so $str ~~ /^and    /;   # OUTPUT: «False␤»

Start of line and end of line§

The ^^ anchor matches at the start of a logical line. That is, either at the start of the string, or after a newline character. However, it does not match at the end of the string, even if it ends with a newline character.

The $$ anchor matches at the end of a logical line. That is, before a newline character, or at the end of the string when the last character is not a newline character.

To understand the following example, it's important to know that the q:to/EOS/...EOS heredoc syntax removes leading indention to the same level as the EOS marker, so that the first, second and last lines have no leading space and the third and fourth lines have two leading spaces each.

my $str = q:to/EOS/; 
    There was a young man of Japan
    Whose limericks never would scan.
      When asked why this was,
      He replied "It's because I always try to fit
    as many syllables into the last line as ever I possibly can."
    EOS
 
# 'There' is at the start of string 
say so $str ~~ /^^ There/;        # OUTPUT: «True␤» 
 
# 'limericks' is not at the start of a line 
say so $str ~~ /^^ limericks/;    # OUTPUT: «False␤» 
 
# 'as' is at start of the last line 
say so $str ~~ /^^ as/;            # OUTPUT: «True␤» 
 
# there are blanks between start of line and the "When" 
say so $str ~~ /^^ When/;         # OUTPUT: «False␤» 
 
# 'Japan' is at end of first line 
say so $str ~~ / Japan $$/;       # OUTPUT: «True␤» 
 
# there's a . between "scan" and the end of line 
say so $str ~~ / scan $$/;        # OUTPUT: «False␤» 
 
# matched at the last line 
say so $str ~~ / '."' $$/;        # OUTPUT: «True␤»

Word boundary§

To match any word boundary, use <?wb>. This is similar to \b in other languages. To match the opposite, any character that is not bounding a word, use <!wb>. This is similar to \B in other languages; \b and \B will throw an X::Obsolete exception from version 6.d of Raku.

These are both zero-width regex elements.

say "two-words" ~~ / two<|w>\-<|w>words /;    # OUTPUT: «｢two-words｣␤» 
say "twowords" ~~ / two<!|w><!|w>words /;     # OUTPUT: «｢twowords｣␤»

Left and right word boundary§

<< matches a left word boundary. It matches positions where there is a non-word character at the left, or the start of the string, and a word character to the right.

>> matches a right word boundary. It matches positions where there is a word character at the left and a non-word character at the right, or the end of the string.

These are both zero-width regex elements.

my $str = 'The quick brown fox';
say so ' ' ~~ /\W/;               # OUTPUT: «True␤» 
say so $str ~~ /br/;              # OUTPUT: «True␤» 
say so $str ~~ /<< br/;           # OUTPUT: «True␤» 
say so $str ~~ /br >>/;           # OUTPUT: «False␤» 
say so $str ~~ /own/;             # OUTPUT: «True␤» 
say so $str ~~ /<< own/;          # OUTPUT: «False␤» 
say so $str ~~ /own >>/;          # OUTPUT: «True␤» 
say so $str ~~ /<< The/;          # OUTPUT: «True␤» 
say so $str ~~ /fox >>/;          # OUTPUT: «True␤»

You can also use the variants « and » :

my $str = 'The quick brown fox';
say so $str ~~ /« own/;          # OUTPUT: «False␤» 
say so $str ~~ /own »/;          # OUTPUT: «True␤»

To see the difference between <|w> and «, »:

say "stuff here!!!".subst(:g, />>/, '|');   # OUTPUT: «stuff| here|!!!␤» 
say "stuff here!!!".subst(:g, /<</, '|');   # OUTPUT: «|stuff |here!!!␤» 
say "stuff here!!!".subst(:g, /<|w>/, '|'); # OUTPUT: «|stuff| |here|!!!␤»

Summary of anchors§

Anchors are zero-width regex elements. Hence they do not use up a character of the input string, that is, they do not advance the current position at which the regex engine tries to match. A good mental model is that they match between two characters of an input string, or before the first, or after the last character of an input string.

Zero-width assertions§

Zero-Width assertions can help you implement your own anchor: it turns another regex into an anchor, making them consume no characters of the input string. There are two variants: lookahead and lookbehind assertions.

Technically, anchors are also zero-width assertions, and they can look both ahead and behind.

Lookaround assertions§

Lookaround assertions, which need a character class in its simpler form, work both ways. They match, but they don't consume a character.

my regex key {^^ <![#-]> \d+ }
say "333" ~~ &key;                  # OUTPUT: «｢333｣␤» 
say '333$' ~~ m/ \d+ <?[$]>/;       # OUTPUT: «｢333｣␤» 
say '$333' ~~ m/^^ <?[$]> . \d+ /;  # OUTPUT: «｢$333｣␤»