Your Own Patterns
The library holds shapes that recur everywhere. Your application has shapes of its own — an order reference, an internal ID, a national format — and Regexes.register folds them in, so they're named, varied and composed exactly as the built-in ones are.
Register a pattern
# config/initializers/regexes.rb
Regexes.register(:order_reference, /ORD-[0-9]{6}/)From then on:
Regexes.order_reference.whole.match?('ORD-004211') # => true
Regexes.order_reference.captured(:reference) # every variation works
Regexes.sequence(Regexes.order_reference, Regexes.literal('/'), Regexes.digits.one_or_more)
validates :reference, format: { with: Regexes.order_reference.whole }register returns the pattern, a frozen expression, and Regexes.registered lists the names registered so far.
What it takes
A pattern may be a Regexp, its source as a String, or an expression built from the library:
Regexes.register(:ticket, /T-[0-9]+/i) # its options are kept
Regexes.register(:sku, '[A-Z]{3}-[0-9]{4}') # a source string
Regexes.register(:handle, Regexes.sequence(Regexes.lowercase_letters,
Regexes.word_characters.between(0, 23)))A Regexp or String is wrapped in a group, so an alternation stays one unit when it's placed in a sequence: /ORD|REF/ followed by digits never means "ORD, or REF and digits". An expression is kept as it is.
What it refuses
- A name that isn't snake_case, or one
Regexesalready answers to: a built-in pattern, a name you registered before, or a method every module has (name,hash). Pick another name; nothing is replaced. - An anchored pattern. Register the shape alone and anchor it where it's used:
^,$,\A,\zor\Zat either end of the source, or an expression built with.whole, raisesArgumentError. One shape then serves validation (.whole), search (as it is) and parsing (.leading).
Both raise ArgumentError with a message saying which.
Name it as the library would
A registered pattern sits beside the built-in ones, so name it by the same conventions: the shape, not its use (order_reference, not checkout_validator); singular for a value, plural for a set; no variation in the name.
Registration changes Regexes for the whole process, so do it once, as the application boots.