1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
//! # Rules
//! Rules uses regular expressions to do pattern matching using syntax
//! based upon the Perl 6 regex grammar. The Perl 6 grammar has been heavily
//! revised from Perl 5 and should not be equated with it. This may look
//! nothing like any regex you have seen before.
//!
//! # Note
//!
//! The only real currently available method is [`is_match()`]
//! (re/struct.Regex.html#method.is_match).
//!
//! # Syntax
//!
//! Currently, this is designed for ASCII and may not behave properly
//! with Unicode.
//!
//! Whitespace is generally ignored so that a regex can be more readable
//! and less dense.
//!
//! ```plain
//! r"fred" // Normal way
//! r"f r e d" // Completely equivalent
//! // Will match `apples_oranges` or any other deliminator
//! r"apples . oranges"
//! ```
//!
//! # Literals
//!
//! Alphanumerics, underscores (`_`), and everything enclosed within
//! quotes (`"`) and ticks (`'`) are the only literals.
//!
//! ```plain
//! hello_world // Matches `hello_world`.
//! "carrot cake" // Matches `carrot cake`.
//! 'apple pie' // Matches `apple pie`.
//! ```
//!
//! Everything else must be escaped with a backslash (`\*`) to literally match.
//!
//! ```plain
//! it\'s\ my\ birthday // Matches `it's my birthday`.
//! ```
//!
//! # Chevrons: `<>`
//!
//! Chevrons are considered a metacharacter grouping operator whose behaviour
//! changes depending on the first character found inside. The behavior for
//! each different character is:
//!
//! First character | Example | Result
//! ----------------|---------|-------
//! Whitespace | `< big small >` | Alternative quotes matches `[ 'big' | 'small' ]`
//! alphabetic | `<alpha>` | Named character class which capture
//! `?` | `<?before foo>` | A positive zero width assertion
//! `!` | `<!before foo>` | A negative zero width assertion
//! `[` | `<[ ab ]>` | A character class matches `[ 'a' | 'b' ]`
//! `-` | `<-[a] + [b]>` | Negated character class: `[ab]` negated
//! `+` | `<+ [a] >` | Doesn't modify the class.
//!
//! # Lookaround
//!
//! * lookahead - `foo <?after bar>` matches `foo` in `foobar`
//! * negative lookahead - `foo <!after bar>` matches `foo` in `foobaz`
//! * lookbehind - `<?before foo> bar` matches `bar` in `foobar`
//! * negative lookbehind - `<!before foo> bar` matches `bar` in `sushibar`
//!
//! An example with both:
//! `<?before foo> bar <?after baz>` matches `bar` in `foobarbaz`
//!
//! # Set operators
//!
//! These operators can be applied to groups which will be analyzed later:
//!
//! ```plain
//! + Union // [123] + [345] = [12345]
//! | Union // Same
//! & Intersection // [123] & [345] = [3]
//! - Difference // [123] - [345] = [12]
//! ^ Symmetric difference // [123] ^ [345] = [1245]
//! ```
//!
//! # Character classes
//!
//! ## Default character classes
//!
//! Character | Matches | Inverse
//! ----------|-----------------------|--------
//! `.` | Any character | N/A
//! `\d` | Digit | `\D`
//! `\h` | Horizontal whitespace | `\H`
//! `\n` | Newline | `\N`
//! `\s` | Any whitespace | `\S`
//! `\t` | Tab | `\T`
//! `\w` | Alphanumeric or `_` | `\W`
//!
//! ## Custom character classes
//!
//! Characters inside a set of `<[ ]>` form a custom character
//! class:
//!
//! ```plain
//! // Matches `a` or `b` or `c`
//! <[ a b c ]>
//!
//! // `..` expresses a range so this matches
//! // from `a` to `g` or a digit
//! <[ a .. g \d ]>
//!
//! // The `[]` bind the sets together into (non-capturing)
//! // groups so set operators can be used.
//! <[0-9] - [13579]> // Matches an even number
//! <\d - [13579]> // Same
//! ```
//!
//! # Comments
//!
//! Comments are allowed inside a regex.
//!
//! ```plain
//! // This matches `myregex`
//! r"my // This is a comment which goes to the end of the line
//! regex"
//! ```