Skip to main content

forbidden_regex/
lib.rs

1//! What:
2//!      This Rust crate exports [`compile`],
3//!  [`Regex`],
4//!  and [`RegexSet`].
5//!           A Rust crate is closest to a TypeScript package module:
6//!  it has private
7//!           implementation files and a public API surface.
8//!  The implementation matches
9//!           byte slices (`&[u8]`,
10//!  a borrowed read-only view of bytes,
11//!  not an owned
12//!           `Vec<u8>` or fixed `[u8; N]` array),
13//!  and internally chooses counting,
14//!           product,
15//!  or derivative-DFA matcher back-ends plus set-level literal gating.
16//! Why:
17//!      This file is the Rust module that groups the lib implementation,
18//!  so the
19//!          compiler gives those items one namespace and sibling modules can import that name.
20//!
21//! In TS you'd write (pseudocode):
22//! ```ts
23//! // module lib: see exported functions and types below.
24//! ```
25//!
26//! The batch match kernels (`dfa::sheng`/`dfa::sheng2`) use explicit `std::arch` SIMD
27//! intrinsics (`vpermb` / `vqtbl4q`),
28//!  runtime-detected,
29//!  so the crate needs no nightly
30//! `portable_simd` feature.
31
32/// What:
33///     The byte-set leaf alphabet.
34/// Why:
35///      The package keeps that concept in a separate Rust file so this module can refer to
36///          it by name.
37///
38/// In TS you'd write (pseudocode):
39/// ```ts
40/// import "./charset";
41/// ```
42mod charset;
43
44/// What:
45///     The compile-time error type.
46/// Why:
47///      The package keeps that concept in a separate Rust file so this module can refer to
48///          it by name.
49///
50/// In TS you'd write (pseudocode):
51/// ```ts
52/// import "./error";
53/// ```
54mod error;
55
56/// What:
57///     The regex node algebra and its smart constructors.
58/// Why:
59///      The package keeps that concept in a separate Rust file so this module can refer to
60///          it by name.
61///
62/// In TS you'd write (pseudocode):
63/// ```ts
64/// import "./ast";
65/// ```
66mod ast;
67
68/// What:
69///     The boundary context resolving zero-width assertions.
70/// Why:
71///      The package keeps that concept in a separate Rust file so this module can refer to
72///          it by name.
73///
74/// In TS you'd write (pseudocode):
75/// ```ts
76/// import "./context";
77/// ```
78mod context;
79
80/// What:
81///     Position-dependent nullability.
82/// Why:
83///      The package keeps that concept in a separate Rust file so this module can refer to
84///          it by name.
85///
86/// In TS you'd write (pseudocode):
87/// ```ts
88/// import "./nullable";
89/// ```
90mod nullable;
91
92/// What:
93///     Brzozowski byte derivatives.
94/// Why:
95///      The package keeps that concept in a separate Rust file so this module can refer to
96///          it by name.
97///
98/// In TS you'd write (pseudocode):
99/// ```ts
100/// import "./derivative";
101/// ```
102mod derivative;
103
104/// What:
105///     Pattern parsing into the node algebra.
106/// Why:
107///      The package keeps that concept in a separate Rust file so this module can refer to
108///          it by name.
109///
110/// In TS you'd write (pseudocode):
111/// ```ts
112/// import "./parse";
113/// ```
114mod parse;
115
116/// What:
117///     Determinization and the compiled table.
118/// Why:
119///      The package keeps that concept in a separate Rust file so this module can refer to
120///          it by name.
121///
122/// In TS you'd write (pseudocode):
123/// ```ts
124/// import "./dfa";
125/// ```
126mod dfa;
127
128/// What:
129///     The counting back-end for bounded repetition.
130/// Why:
131///      The package keeps that concept in a separate Rust file so this module can refer to
132///          it by name.
133///
134/// In TS you'd write (pseudocode):
135/// ```ts
136/// import "./counting";
137/// ```
138mod counting;
139
140/// What:
141///     The per-pattern back-end selector.
142/// Why:
143///      The package keeps that concept in a separate Rust file so this module can refer to
144///          it by name.
145///
146/// In TS you'd write (pseudocode):
147/// ```ts
148/// import "./engine";
149/// ```
150mod engine;
151
152/// What:
153///     Per-rule back-end selection and the seedless-rule fold into the gate.
154/// Why:
155///      The package keeps that concept in a separate Rust file so this module can refer to
156///          it by name.
157///
158/// In TS you'd write (pseudocode):
159/// ```ts
160/// import "./build";
161/// ```
162mod build;
163
164/// What:
165///     Builds a ruleset's rules across worker threads,
166///  results in input order.
167/// Why:
168///      The package keeps that concept in a separate Rust file so this module can refer to
169///          it by name.
170///
171/// In TS you'd write (pseudocode):
172/// ```ts
173/// import "./parallel";
174/// ```
175mod parallel;
176
177/// What:
178///     The RegexSet-level combined literal prefilter.
179/// Why:
180///      The package keeps that concept in a separate Rust file so this module can refer to
181///          it by name.
182///
183/// In TS you'd write (pseudocode):
184/// ```ts
185/// import "./gate";
186/// ```
187mod gate;
188
189/// What:
190///     Greedy combination of literal-free rules into union DFAs.
191/// Why:
192///      The package keeps that concept in a separate Rust file so this module can refer to
193///          it by name.
194///
195/// In TS you'd write (pseudocode):
196/// ```ts
197/// import "./group";
198/// ```
199mod group;
200
201/// What:
202///     Public matcher types.
203/// Why:
204///      The package keeps that concept in a separate Rust file so this module can refer to
205///          it by name.
206///
207/// In TS you'd write (pseudocode):
208/// ```ts
209/// import "./regex";
210/// ```
211mod regex;
212
213/// What:
214///     Re-exports the compile-time error type.
215/// Why:
216///      The surrounding function uses this step to keep the matcher behavior correct at
217///          this point.
218///
219/// In TS you'd write (pseudocode):
220/// ```ts
221/// // Same step as the Rust statement below, written with ordinary TS objects/functions.
222/// ```
223pub use crate::error::CompileError;
224
225/// What:
226///     Re-exports the public matcher API.
227/// Why:
228///      The surrounding function uses this step to keep the matcher behavior correct at
229///          this point.
230///
231/// In TS you'd write (pseudocode):
232/// ```ts
233/// // Same step as the Rust statement below, written with ordinary TS objects/functions.
234/// ```
235pub use crate::regex::{Regex, RegexSet, compile};
236
237/// Diagnostic:
238///  debug-prints the parsed node of a pattern that has no usable seed.
239///
240/// What:
241///  returns `Some(debug)` when the pattern parses and is seedless (no leading
242/// seed and no required-literal seed),
243///  else `None`.
244///  Why:
245///  a temporary probe for the
246/// CsA work to enumerate exactly which rules force the literal-free second pass.
247///
248/// In TS you'd write (pseudocode):
249/// ```ts
250/// function debug_seedless(pattern: string): string | null {
251///   // Rust body below is the implementation.
252/// }
253/// ```
254#[doc(hidden)]
255pub fn debug_seedless(pattern: &str) -> Option<String> {
256    let node = crate::parse::parse(pattern).ok()?;
257    let leading = crate::counting::leading_seeds(&node);
258    let seeds = crate::counting::seeds_from_node(&node);
259    if leading.is_empty() && seeds.is_empty() {
260        return Some(format!("{node:?}"))
261    } else {
262        return None
263    }
264}
265
266/// Diagnostic:
267///  tries to build ONE combined search DFA over every pattern.
268///
269/// What:
270///  parses each pattern,
271///  alternates them under a single `Σ*` search prefix,
272///  and
273/// eagerly determinizes the union;
274///  returns the state count on success or the
275/// `CompileError` (typically `StateCap`) on a blowup.
276///  Why:
277///  a measured probe of the
278/// "all-rules combined automaton" idea,
279///  to see whether a single monolithic DFA over the
280/// whole ruleset is even buildable (vs the per-rule gate-plus-fold architecture).
281///
282/// In TS you'd write (pseudocode):
283/// ```ts
284/// function try_combined_dfa(patterns: string[]): number {
285///   // Rust body below is the implementation.
286/// }
287/// ```
288#[doc(hidden)]
289pub fn try_combined_dfa(patterns: &[&str]) -> Result<usize, CompileError> {
290    let roots: Vec<crate::ast::node::Node> =
291        patterns.iter().filter_map(|pattern| return crate::parse::parse(pattern).ok()).collect();
292    let union = crate::ast::smart::alt(roots);
293    let combined = crate::ast::smart::concat(vec![crate::ast::node::Node::Top, union]);
294    return Ok(crate::dfa::build_dfa_within(combined, 65_534)?.num_states as usize)
295}