Skip to content

Expressions ​

Every pattern is a Regexes::Expression, a subclass of Regexp. It goes anywhere a Regexp does, equals the literal it stands for, and sets Regexp.last_match as usual.

ruby
Regexes.lowercase_letters.excluded.one_or_more.leading == /\A[^a-z]+/  # => true

Each variation below returns a new, frozen expression. The one it came from is never changed, so a pattern kept in a constant is safe to hand to any caller.

Anchors ​

MethodWritesMatches
leading\A…only at the start of the text
trailing…\zonly at the end of the text
whole\A…\zthe whole text
ruby
'ab1cd'[Regexes.lowercase_letters.one_or_more.leading]   # => "ab"
'ab1cd'[Regexes.lowercase_letters.one_or_more.trailing]  # => "cd"
Regexes.lowercase_letters.one_or_more.whole.match?('abc1')  # => false

The anchors are the text's, never a line's. ^ and $ would let a later line satisfy the pattern, and $ passes over a final newline:

ruby
"1\nab"[Regexes.lowercase_letters.one_or_more.leading]  # => nil
"ab\n"[Regexes.lowercase_letters.one_or_more.trailing]  # => nil

leading.trailing is the same as whole. Each end holds one anchor, so anchoring an end again replaces its anchor, and anchoring twice the same way is anchoring once. leading? and trailing? say where an expression is anchored.

Line anchors ​

When the text has lines — a mail header block, a Markdown document, a log — anchor to a line instead:

MethodMatches
line_leadingonly at the start of a line
line_trailingonly at the end of a line
whole_linea whole line
ruby
"ab1\r\ncd2\nef".scan(Regexes.lowercase_letters.one_or_more.line_leading)  # => ["ab", "cd", "ef"]
"ab1\r\ncd2".scan(Regexes.digits.one_or_more.line_trailing)              # => ["1", "2"]
"ab1\ncd\n2ef".scan(Regexes.lowercase_letters.one_or_more.whole_line)     # => ["cd"]

A line ends in \r\n, \r or \n — the three breaks line_break matches — and \r\n is one break, never two. That's where these differ from ^ and $, which know only \n: $ ends a line between the \r and the \n, and ^ never starts one after a lone \r. line_leading? and line_trailing? say where an expression is anchored to a line.

Repetition ​

MethodWrites
one_or_more+
zero_or_more*
optional?
exactly(n){n}
at_least(n){n,}
between(min, max){min,max}
ruby
'abc1de'.scan(Regexes.lowercase_letters.one_or_more)  # => ["abc", "de"]
'12345'.scan(Regexes.digits.exactly(2))               # => ["12", "34"]
"a\n\nb\n\n\n\nc".gsub(Regexes.newline.at_least(3), "\n\n")  # => "a\n\nb\n\nc"

Repeating an expression repeats all of it. One made of several units is grouped first, so ab repeated is abab, never abb:

ruby
Regexes.sequence(Regexes.letters, Regexes.letters).at_least(2)
# => /(?:[A-Za-z][A-Za-z]){2,}/

An anchored expression — to the text or to a line — can't be repeated, since only one stretch can start it. Repeat first, then anchor:

ruby
Regexes.lowercase_letters.leading.one_or_more
# ArgumentError: /\A[a-z]/ is anchored: repeat it first, then anchor it

Counts must be whole numbers, and between refuses a minimum above its maximum.

Case ​

case_insensitive matches letters of either case and keeps any anchors:

ruby
Regexes.http_scheme.leading.case_insensitive.match?('HTTPS://acme.example')  # => true

Applying it before or after repeating and anchoring gives the same expression.

Captures ​

captured(name) captures what the expression matches under a name, read back with match[name]:

ruby
date = Regexes.sequence(Regexes.digits.exactly(4).captured(:year), Regexes.hyphen,
                        Regexes.digits.exactly(2).captured(:month))

date.match('2026-11')[:month]  # => "11"

Anchors stay outside the capture, so it holds only the text matched. A captured expression is one unit: repeating it repeats the capture without another group around it. A name is a letter or underscore, then letters, digits and underscores; anything else raises ArgumentError.

Lookarounds ​

Four variations match only where something else does or doesn't come right before or after, without taking it:

MethodWritesMatches only where other
followed_by(other)…(?=other)comes next
not_followed_by(other)…(?!other)doesn't come next
preceded_by(other)(?<=other)…comes before
not_preceded_by(other)(?<!other)…doesn't come before
ruby
"a\n b\nc".gsub(Regexes.newline.followed_by(Regexes.space_or_tab), '')       # => "a b\nc"
'https:// http://'.scan(Regexes.literal('http').not_followed_by(Regexes.literal('s')))  # => ["http"]
'$5 6'.scan(Regexes.digits.one_or_more.preceded_by(Regexes.literal('$')))   # => ["5"]

Two things to know:

  • A repeated expression gives back what it took until the lookaround passes. digits.one_or_more not followed by % still matches the 5 of 50%. Exclude what it repeats as well — not_followed_by(Regexes.either(Regexes.digits, Regexes.literal('%'))) — to refuse the whole run.
  • Ruby looks behind only for what has a known length (or alternatives each of one). preceded_by a repeated expression raises RegexpError.

Next: Sets of Characters.