| 1 |
regex-syntax |
| 2 |
============ |
| 3 |
This crate provides a robust regular expression parser. |
| 4 |
|
| 5 |
[](https://github.com/rust-lang/regex/actions) |
| 6 |
[](https://crates.io/crates/regex-syntax) |
| 7 |
|
| 8 |
|
| 9 |
### Documentation |
| 10 |
|
| 11 |
https://docs.rs/regex-syntax |
| 12 |
|
| 13 |
|
| 14 |
### Overview |
| 15 |
|
| 16 |
There are two primary types exported by this crate: `Ast` and `Hir`. The former |
| 17 |
is a faithful abstract syntax of a regular expression, and can convert regular |
| 18 |
expressions back to their concrete syntax while mostly preserving its original |
| 19 |
form. The latter type is a high level intermediate representation of a regular |
| 20 |
expression that is amenable to analysis and compilation into byte codes or |
| 21 |
automata. An `Hir` achieves this by drastically simplifying the syntactic |
| 22 |
structure of the regular expression. While an `Hir` can be converted back to |
| 23 |
its equivalent concrete syntax, the result is unlikely to resemble the original |
| 24 |
concrete syntax that produced the `Hir`. |
| 25 |
|
| 26 |
|
| 27 |
### Example |
| 28 |
|
| 29 |
This example shows how to parse a pattern string into its HIR: |
| 30 |
|
| 31 |
```rust |
| 32 |
use regex_syntax::{hir::Hir, parse}; |
| 33 |
|
| 34 |
let hir = parse("a|b").unwrap(); |
| 35 |
assert_eq!(hir, Hir::alternation(vec![ |
| 36 |
Hir::literal("a".as_bytes()), |
| 37 |
Hir::literal("b".as_bytes()), |
| 38 |
])); |
| 39 |
``` |
| 40 |
|
| 41 |
|
| 42 |
### Safety |
| 43 |
|
| 44 |
This crate has no `unsafe` code and sets `forbid(unsafe_code)`. While it's |
| 45 |
possible this crate could use `unsafe` code in the future, the standard |
| 46 |
for doing so is extremely high. In general, most code in this crate is not |
| 47 |
performance critical, since it tends to be dwarfed by the time it takes to |
| 48 |
compile a regular expression into an automaton. Therefore, there is little need |
| 49 |
for extreme optimization, and therefore, use of `unsafe`. |
| 50 |
|
| 51 |
The standard for using `unsafe` in this crate is extremely high because this |
| 52 |
crate is intended to be reasonably safe to use with user supplied regular |
| 53 |
expressions. Therefore, while there may be bugs in the regex parser itself, |
| 54 |
they should _never_ result in memory unsafety unless there is either a bug |
| 55 |
in the compiler or the standard library. (Since `regex-syntax` has zero |
| 56 |
dependencies.) |
| 57 |
|
| 58 |
|
| 59 |
### Crate features |
| 60 |
|
| 61 |
By default, this crate bundles a fairly large amount of Unicode data tables |
| 62 |
(a source size of ~750KB). Because of their large size, one can disable some |
| 63 |
or all of these data tables. If a regular expression attempts to use Unicode |
| 64 |
data that is not available, then an error will occur when translating the `Ast` |
| 65 |
to the `Hir`. |
| 66 |
|
| 67 |
The full set of features one can disable are |
| 68 |
[in the "Crate features" section of the documentation](https://docs.rs/regex-syntax/*/#crate-features). |
| 69 |
|
| 70 |
|
| 71 |
### Testing |
| 72 |
|
| 73 |
Simply running `cargo test` will give you very good coverage. However, because |
| 74 |
of the large number of features exposed by this crate, a `test` script is |
| 75 |
included in this directory which will test several feature combinations. This |
| 76 |
is the same script that is run in CI. |
| 77 |
|
| 78 |
|
| 79 |
### Motivation |
| 80 |
|
| 81 |
The primary purpose of this crate is to provide the parser used by `regex`. |
| 82 |
Specifically, this crate is treated as an implementation detail of the `regex`, |
| 83 |
and is primarily developed for the needs of `regex`. |
| 84 |
|
| 85 |
Since this crate is an implementation detail of `regex`, it may experience |
| 86 |
breaking change releases at a different cadence from `regex`. This is only |
| 87 |
possible because this crate is _not_ a public dependency of `regex`. |
| 88 |
|
| 89 |
Another consequence of this de-coupling is that there is no direct way to |
| 90 |
compile a `regex::Regex` from a `regex_syntax::hir::Hir`. Instead, one must |
| 91 |
first convert the `Hir` to a string (via its `std::fmt::Display`) and then |
| 92 |
compile that via `Regex::new`. While this does repeat some work, compilation |
| 93 |
typically takes much longer than parsing. |
| 94 |
|
| 95 |
Stated differently, the coupling between `regex` and `regex-syntax` exists only |
| 96 |
at the level of the concrete syntax. |