Regex for Humans
The goal of this crate is simple: give everybody the power of regular expressions without having
to learn the complicated syntax. It is inspired by ReadableRegex.jl.
This crate is a wrapper around the core Rust regex library.
Example usage
If you want to match a date of the format 2021-10-30, you could use the following code to generate a regex:
use human_regex::{beginning, digit, exactly, text, end};
let regex_string = beginning()
+ exactly(4, digit())
+ text("-")
+ exactly(2, digit())
+ text("-")
+ exactly(2, digit())
+ end();
assert!(regex_string.to_regex().is_match("2014-01-01"));
The to_regex() method returns a standard Rust regex. We can do this another way with slightly less repetition though!
use human_regex::{beginning, digit, exactly, text, end};
let first_regex_string = text("-") + exactly(2, digit());
let second_regex_string = beginning()
+ exactly(4, digit())
+ exactly(2, first_regex_string)
+ end();
assert!(second_regex_string.to_regex().is_match("2014-01-01"));
For a more extensive set of examples, please see The Cookbook.
Features
This crate currently supports the vast majority of syntax available in the core Rust regex library through a human-readable API.
Single Character
| Implemented? |
Expression |
Description |
any() |
. |
any character except new line (includes new line with s flag) |
digit() |
\d |
digit (\p{Nd}) |
non_digit() |
\D |
not digit |
unicode_category(UnicodeCategory) |
\p{L} |
Unicode non-script category |
unicode_script(UnicodeScript) |
\p{Greek} |
Unicode script category |
non_unicode_category(UnicodeCategory) |
\P{L} |
Negated one-letter name Unicode character class |
non_unicode_script(UnicodeCategory) |
\P{Greek} |
negated Unicode character class (general category or script) |
Character Classes
| Implemented? |
Expression |
Description |
or(&['x', 'y', 'z']) |
[xyz] |
A character class matching either x, y or z (union). |
nor(&['x', 'y', 'z']) |
[^xyz] |
A character class matching any character except x, y and z. |
within('a'..='z') |
[a-z] |
A character class matching any character in range a-z. |
without('a'..='z') |
[^a-z] |
A character class matching any character outside range a-z. |
| See below |
[[:alpha:]] |
ASCII character class ([A-Za-z]) |
non_alphanumeric() |
[[:^alpha:]] |
Negated ASCII character class ([^A-Za-z]) |
or() |
[x[^xyz]] |
Nested/grouping character class (matching any character except y and z) |
and(&[])/& |
[a-y&&xyz] |
Intersection (a-y AND xyz = xy) |
(or[1,2,3,4] & nor(3)) |
[0-9&&[^4]] |
Subtraction using intersection and negation (matching 0-9 except 4) |
subtract(&[],&[]) |
[0-9--4] |
Direct subtraction (matching 0-9 except 4). Use .collect::<Vec> to use ranges. |
xor(&[],&[]) |
[a-g~~b-h] |
Symmetric difference (matching a and h only). Requires .collect() for ranges. |
or(&escape_all(&['[',']'])) |
[\[\]] |
Escaping in character classes (matching [ or ]) |
Perl Character Classes
| Implemented? |
Expression |
Description |
digit() |
\d |
digit (\p{Nd}) |
non_digit() |
\D |
not digit |
whitespace() |
\s |
whitespace (\p{White_Space}) |
non_whitespace() |
\S |
not whitespace |
word() |
\w |
word character (\p{Alphabetic} + \p{M} + \d + \p{Pc} + \p{Join_Control}) |
non_word() |
\W |
not word character |
ASCII Character Classes
| Implemented? |
Expression |
Description |
alphanumeric() |
[[:alnum:]] |
alphanumeric ([0-9A-Za-z]) |
alphabetic() |
[[:alpha:]] |
alphabetic ([A-Za-z]) |
ascii() |
[[:ascii:]] |
ASCII ([\x00-\x7F]) |
blank() |
[[:blank:]] |
blank ([\t ]) |
control() |
[[:cntrl:]] |
control ([\x00-\x1F\x7F]) |
digit() |
[[:digit:]] |
digits ([0-9]) |
graphical() |
[[:graph:]] |
graphical ([!-~]) |
uppercase() |
[[:lower:]] |
lower case ([a-z]) |
printable() |
[[:print:]] |
printable ([ -~]) |
punctuation() |
[[:punct:]] |
punctuation ([!-/:-@\[-`{-~]) |
whitespace() |
[[:space:]] |
whitespace ([\t\n\v\f\r ]) |
lowercase() |
[[:upper:]] |
upper case ([A-Z]) |
word() |
[[:word:]] |
word characters ([0-9A-Za-z_]) |
hexdigit() |
[[:xdigit:]] |
hex digit ([0-9A-Fa-f]) |
Repetitions
| Implemented? |
Expression |
Description |
zero_or_more(x) |
x* |
zero or more of x (greedy) |
one_or_more(x) |
x+ |
one or more of x (greedy) |
zero_or_one(x) |
x? |
zero or one of x (greedy) |
zero_or_more(x) |
x*? |
zero or more of x (ungreedy/lazy) |
one_or_more(x).lazy() |
x+? |
one or more of x (ungreedy/lazy) |
zero_or_more(x).lazy() |
x?? |
zero or one of x (ungreedy/lazy) |
between(n, m, x) |
x{n,m} |
at least n x and at most m x (greedy) |
at_least(n, x) |
x{n,} |
at least n x (greedy) |
exactly(n, x) |
x{n} |
exactly n x |
between(n, m, x).lazy() |
x{n,m}? |
at least n x and at most m x (ungreedy/lazy) |
at_least(n, x).lazy() |
x{n,}? |
at least n x (ungreedy/lazy) |
Composites
| Implemented? |
Expression |
Description |
+ |
xy |
concatenation (x followed by y) |
or() |
x|y |
alternation (x or y, prefer x) |
Empty matches
| Implemented? |
Expression |
Description |
beginning() |
^ |
the beginning of text (or start-of-line with multi-line mode) |
end() |
$ |
the end of text (or end-of-line with multi-line mode) |
beginning_of_text() |
\A |
only the beginning of text (even with multi-line mode enabled) |
end_of_text() |
\z |
only the end of text (even with multi-line mode enabled) |
word_boundary() |
\b |
a Unicode word boundary (\w on one side and \W, \A, or \z on other) |
non_word_boundary() |
\B |
not a Unicode word boundary |
Groupings
| Implemented? |
Expression |
Description |
capture(exp) |
(exp) |
numbered capture group (indexed by opening parenthesis) |
named_capture(exp, name) |
(?P<name>exp) |
named (also numbered) capture group |
| Handled implicitly through functional composition |
(?:exp) |
non-capturing group |
| See below |
(?flags) |
set flags within current group |
| See below |
(?flags:exp) |
set flags for exp (non-capturing) |
Flags
| Implemented? |
Expression |
Description |
case_insensitive(exp) |
i |
case-insensitive: letters match both upper and lower case |
multi_line_mode(exp) |
m |
multi-line mode: ^ and $ match begin/end of line |
dot_matches_newline_too(exp) |
s |
allow . to match \n |
| will not be implemented1 |
U |
swap the meaning of x* and x*? |
disable_unicode(exp) |
u |
Unicode support (enabled by default) |
| will not be implemented2 |
x |
ignore whitespace and allow line comments (starting with #) |
- With the declarative nature of this library, use of this flag would just obfuscate meaning.
- When using
human_regex, comments should be added in source code rather than in the regex string.
Chris McComb (cmccomb)