Skip to content

Naming ​

A library of named patterns is only as useful as its names are predictable. If you can guess the name of the pattern you need, you'll use it instead of writing the regex again. Every name follows these rules.

1. The shape, never its use ​

A pattern is named for what it matches, not for what one application does with it.

Named for the shapeNot for a use
kebab_caseslug
snake_caseusername
uuidmessage_id_local_part
space_or_tabheader_unfolder

A shape is found and reused. A use is written again the next time, slightly differently. The grammar of one format — a bounce address, a log line, a handle — belongs in the code that owns it, as a named constant built from these.

2. Sets are plural, values are singular ​

A set of characters matches one character, but is named for the set: digits, hex_digits, combining_marks. A value is named for the one thing it matches: uuid, integer, domain_name.

ruby
Regexes.digits       # => /[0-9]/      one character of the set
Regexes.integer      # => /-?[0-9]+/   one whole number

3. Qualifiers before the noun, in a fixed order ​

Case first, then script or standard, then the noun:

  • lowercase_alphanumeric, uppercase_letters (case)
  • unicode_letters, iso8601_date, rfc3339_timestamp (script or standard)

So there's one place to look: lowercase_hex_digits, never hex_digits_lowercase.

4. ASCII unless the name says otherwise ​

digits is [0-9], letters is [A-Za-z]. A set that reaches past ASCII says so in its name: unicode_letters. The one exception is whitespace, which matches any script's spaces, because text copied from a web page carries no-break and wide spaces and that's what the bare word is reached for.

5. Variations never become names ​

Anything a variation can express is written as one, so the library never holds two names for one thing:

Written as a variationNever a name
Regexes.digits.excludednon_digits
Regexes.whitespace.one_or_morewhitespace_run
Regexes.uuid.wholewhole_uuid
Regexes.slash.one_or_more.trailingtrailing_slash
Regexes.slash.excluded.one_or_morepath_segment
Regexes.uppercase_letters.exactly(2)alpha2_country_code
Regexes.hex_digits.exactly(64)sha256_digest

That holds for standards too. A pattern checks shape, not whether a code is assigned (rule 9), so an ISO 3166 country code is two uppercase letters, and a name for it would be a second name for uppercase_letters.exactly(2). A standard gets a name when its shape has parts or rules — iban, bic, language_tag, uuid — not when it's a set and a count.

6. A standard is in the name only when formats compete ​

When several formats exist for the same noun, the standard goes in the name: iso8601_date, rfc3339_timestamp, e164_phone_number. When there's one, the noun is enough: uuid, iban, bic.

7. Abbreviations only where they are the common name ​

uuid, url, ipv4, iban, bic, e164, cidr — the names people search for. Never num, addr or str.

8. Captures take the standard's terms ​

email_address captures local and domain; a semantic version captures major, minor, patch. The words are the ones the standard uses, so its documentation and yours agree.

9. Shape, never meaning ​

A pattern checks what a format looks like, including any range the format defines: a month is 01 to 12, an hour 00 to 23, an IPv4 octet 0 to 255. It never checks what needs more than the characters: a checksum (an IBAN's mod-97, a card's Luhn digit), the calendar (2026-02-30 is a date's shape) or whether an address exists. Each pattern's documentation says exactly where it stops.

10. International standards only ​

National formats — a US routing number, a postal code, one country's IBAN layout — belong in the application that needs them, built from these pieces.