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}