Debian Codegraph @

.cargo/vendor/regex-syntax/README.md

raw
1 regex-syntax
2 ============
3 This crate provides a robust regular expression parser.
4
5 [![Build status](https://github.com/rust-lang/regex/workflows/ci/badge.svg)](https://github.com/rust-lang/regex/actions)
6 [![Crates.io](https://img.shields.io/crates/v/regex-syntax.svg)](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.