Skip to content

Instructions for AI Assistants ​

This page is written for a coding assistant working in a Ruby project that has regexes in its Gemfile, or adding it. Follow it whenever the task involves a regular expression: writing one, reviewing one, or replacing one. The reference is the source of truth for what each pattern matches.

Procedure ​

  1. Name the shape. Say what the text is, not what the code does with it: "an IPv4 address", not "the thing we check before connecting".
  2. Find it. Look it up in the reference, by section: sets of characters, breaks, numbers, identifiers, times, network, mail, codes, text. Use only a name the reference lists. Never guess one: Regexes.ipv4 and Regexes.non_digits don't exist.
  3. If it's a set and a count, write it as one. A country code is Regexes.uppercase_letters.exactly(2), a currency code .exactly(3), a SHA-256 digest Regexes.hex_digits.exactly(64). These have no names on purpose.
  4. Vary it for the job:
    • to validate a whole value: .whole;
    • to search text: use it as it is, unanchored;
    • to parse a value at the start of a text: .leading;
    • to read a part: a capture the reference lists (match[:host]), or .captured(:name);
    • to match per line: .line_leading, .line_trailing, .whole_line.
  5. Compose larger shapes with Regexes.sequence and Regexes.either, and put fixed text in with Regexes.literal.
  6. If the shape is the application's own (an order reference, a national format), register it once at boot and use it by name: Regexes.register(:order_reference, /ORD-[0-9]{6}/).
  7. For JavaScript or a JSON Schema, translate: pattern.whole.ecma_source and pattern.ecma_flags.
  8. Verify with the examples the reference gives for the pattern: what it matches and what it refuses.

Rules ​

  • Never write ^ or $ to validate. In Ruby they are line anchors: /^[a-z]+$/ accepts "ok\nevil". Use .whole (\A…\z). For lines, use the line anchors.
  • Never interpolate a value into a pattern. /#{suffix}\z/ lets the value's dots and pluses match more than they say. Use Regexes.literal(suffix).trailing.
  • Never write a set's complement by hand. "Anything but digits" is Regexes.digits.excluded.
  • Don't reach for \d, \w, \s. Use the named sets: digits, word_characters, whitespace (any script's spaces) or ascii_whitespace (Ruby's \s).
  • Repeat, then anchor. Regexes.digits.leading.one_or_more raises; write Regexes.digits.one_or_more.leading.
  • A pattern checks shape, not meaning. iban doesn't verify check digits, iso8601_date accepts 2026-02-30. Check meaning in code after the match.
  • Patterns are frozen. Every variation returns a new pattern; keep them in constants freely.
  • Don't register a pattern the library has, and register only unanchored shapes under snake_case names: register raises otherwise.

Recipes ​

NeedWrite
Keep only the digits of a phone numberphone.gsub(Regexes.digits.excluded, '')
Collapse runs of whitespace, including no-break spacestext.gsub(Regexes.whitespace.one_or_more, ' ')
Trim a trailing slashurl.sub(Regexes.slash.one_or_more.trailing, '')
Split a list on commas and spaceslist.split(Regexes.either(Regexes.literal(','), Regexes.whitespace).one_or_more)
Validate a country codeRegexes.uppercase_letters.exactly(2).whole
Validate money to the centRegexes.unsigned_decimal(places: 2).whole
Find a UUID in a pathpath[Regexes.uuid]
Validate an email in a modelvalidates :email, format: { with: Regexes.email_address.whole }
Close up blank linestext.gsub(Regexes.paragraph_break, "\n\n")
Unfold a mail headerheader.gsub(Regexes.folded_line_break, '')
Read a fenced code block's language and codemarkdown.match(Regexes.markdown_code_block.line_leading) → [:language], [:code]
An application's own format, with a partRegexes.sequence(Regexes.literal('ORD-'), Regexes.digits.exactly(6).captured(:number)).whole
A JSON Schema patternRegexes.e164_phone_number.whole.ecma_source

Replacing a raw regex ​

When the task is to replace a hand-written regex with the library:

  1. Read what the regex is for (validation, search, parsing) and what shape it means.
  2. Find the named pattern and the variation (steps 2 to 4 above).
  3. Compare the two on the regex's own tests, and on the reference's examples for the pattern. A raw regex is often wrong at the edges (it accepts 1.2.3.456, 2026-13-01, a second line): say which edge cases change, rather than reproduce the old behavior silently.
  4. Replace any ^/$ in a validation with .whole, and any interpolation with Regexes.literal.

API ​

Variations, on every pattern, each returning a new frozen pattern:

MethodDoes
leading, trailing, wholeanchor to the start, end or all of the text (\A, \z)
line_leading, line_trailing, whole_lineanchor to a line, ended by \r\n, \r or \n
one_or_more, zero_or_more, optionalrepeat
exactly(n), at_least(n), between(min, max)repeat a number of times
case_insensitivematch letters of either case
captured(name)capture under a name
followed_by(x), not_followed_by(x)match only where x does or doesn't come next
preceded_by(x), not_preceded_by(x)match only where x does or doesn't come before (fixed-length x)
ecma_source, ecma_flagsthe pattern for JavaScript and JSON Schema

Sets only: excluded (every character not in the set) and including(characters).

Module functions: Regexes.sequence(*parts), Regexes.either(*alternatives), Regexes.literal(text), Regexes.register(name, pattern), Regexes.registered.

Errors: ArgumentError for a bad variation or registration; Regexes::UntranslatableError from ecma_source for what ECMAScript can't match the same way (only emoji among the named patterns).

Changing the library itself ​

When working in the regexes repository rather than using the gem, follow its CLAUDE.md and .claude/rules/: the naming conventions, one constant and one endless method per pattern, a row in its section's case table, and the reference page updated in the same commit.