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
- 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".
- 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.ipv4andRegexes.non_digitsdon't exist. - 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 digestRegexes.hex_digits.exactly(64). These have no names on purpose. - 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.
- to validate a whole value:
- Compose larger shapes with
Regexes.sequenceandRegexes.either, and put fixed text in withRegexes.literal. - 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}/). - For JavaScript or a JSON Schema, translate:
pattern.whole.ecma_sourceandpattern.ecma_flags. - 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. UseRegexes.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) orascii_whitespace(Ruby's\s). - Repeat, then anchor.
Regexes.digits.leading.one_or_moreraises; writeRegexes.digits.one_or_more.leading. - A pattern checks shape, not meaning.
ibandoesn't verify check digits,iso8601_dateaccepts2026-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:
registerraises otherwise.
Recipes
| Need | Write |
|---|---|
| Keep only the digits of a phone number | phone.gsub(Regexes.digits.excluded, '') |
| Collapse runs of whitespace, including no-break spaces | text.gsub(Regexes.whitespace.one_or_more, ' ') |
| Trim a trailing slash | url.sub(Regexes.slash.one_or_more.trailing, '') |
| Split a list on commas and spaces | list.split(Regexes.either(Regexes.literal(','), Regexes.whitespace).one_or_more) |
| Validate a country code | Regexes.uppercase_letters.exactly(2).whole |
| Validate money to the cent | Regexes.unsigned_decimal(places: 2).whole |
| Find a UUID in a path | path[Regexes.uuid] |
| Validate an email in a model | validates :email, format: { with: Regexes.email_address.whole } |
| Close up blank lines | text.gsub(Regexes.paragraph_break, "\n\n") |
| Unfold a mail header | header.gsub(Regexes.folded_line_break, '') |
| Read a fenced code block's language and code | markdown.match(Regexes.markdown_code_block.line_leading) → [:language], [:code] |
| An application's own format, with a part | Regexes.sequence(Regexes.literal('ORD-'), Regexes.digits.exactly(6).captured(:number)).whole |
A JSON Schema pattern | Regexes.e164_phone_number.whole.ecma_source |
Replacing a raw regex
When the task is to replace a hand-written regex with the library:
- Read what the regex is for (validation, search, parsing) and what shape it means.
- Find the named pattern and the variation (steps 2 to 4 above).
- 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. - Replace any
^/$in a validation with.whole, and any interpolation withRegexes.literal.
API
Variations, on every pattern, each returning a new frozen pattern:
| Method | Does |
|---|---|
leading, trailing, whole | anchor to the start, end or all of the text (\A, \z) |
line_leading, line_trailing, whole_line | anchor to a line, ended by \r\n, \r or \n |
one_or_more, zero_or_more, optional | repeat |
exactly(n), at_least(n), between(min, max) | repeat a number of times |
case_insensitive | match 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_flags | the 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.