javelin-pattern 0.1.0

Rust bindings to Jeffrey Lim's JavelinPattern regular expression engine.
Documentation 
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

# javelin-pattern

Rust bindings to [Jeffrey Lim's JavelinPattern](https://github.com/jthlim/JavelinPattern)
regular expression engine. The workspace follows the division used by
`rust-pcre2`: `javelin-pattern` provides the safe API, and `javelin-sys` exposes
the C API and builds a vendored copy of the engine.

```toml
[dependencies]
javelin-pattern = "0.1.0"
```

```rust
use javelin_pattern::bytes::Regex;
use std::ops::ControlFlow;

let re = Regex::new(r"(\w+)=(\d+)").unwrap();
let captures = re.captures(b"answer=42").unwrap();
assert_eq!(captures.get(1).unwrap().as_bytes(), b"answer");
assert_eq!(captures.get(2).unwrap().as_bytes(), b"42");

let mut ranges = Vec::new();
let result = re.scan(b"x=1 y=2", |matched| {
    ranges.push(matched.range());
    ControlFlow::<()>::Continue(())
});
assert_eq!(result, ControlFlow::Continue(()));
assert_eq!(ranges, [0..3, 4..7]);
```

The API matches byte slices and reports byte offsets. `RegexBuilder` configures
case folding, multiline matching, UTF-8, Unicode properties, and glob syntax.
UTF-8 decoding, Unicode character classes (`ucp`), and Unicode case folding are
independent options, as in JavelinPattern. Patterns are Rust strings; use `\x00`
to match a NUL byte instead of putting a literal NUL in the pattern.

`scan` and `scan_captures` visit non-overlapping matches synchronously. Return
`ControlFlow::Break(value)` to stop immediately. After an empty match, the
engine tries nonempty alternatives at the same position before advancing.
Capture groups are numbered; unmatched groups return `None`. Matches and
captures borrow the input and can outlive the regex or a scan callback.
Clones share the compiled pattern. Callback panics propagate after the native
scan returns.

This initial wrapper covers compilation, matching, numbered captures, and
callback scanning. The full native API, including bytecode compilation, remains
available through `javelin-sys`.

## Building

Rust 1.85 or newer, Clang with C++17 support, and an archiver are required.
The native build defaults to `clang++`; the usual `cc` crate variables such as
`CXX`, target-specific `CXX`, `CXXFLAGS`, and `AR` are supported. The engine is
compiled with its optimized build settings even in Cargo's debug profile.

The build targets x86_64 and aarch64 Linux/macOS. Local validation has been
performed on x86_64 Linux; Windows is not supported by this initial build script.
For cross-compilation, provide a host Clang and a target Clang/toolchain using
`HOST_CXX` and target-specific `CXX` settings. The assembler is built for the host.

All native sources are included in `javelin-sys`. Native compilation requires no system
Javelin installation, Git checkout, network download, Make, Python, or bindgen.
Generated C++ and compiled objects are written only under Cargo's output directory.

```sh
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all --check
cargo package --workspace --allow-dirty
```

Publish `javelin-sys` first, then `javelin-pattern` once the dependency is available
on crates.io. Both manifests contain versioned dependencies and package metadata.

## License

The Rust bindings are BSD-3-Clause licensed. JavelinPattern is copyright Jeffrey
Lim and is distributed under its original BSD-3-Clause license in
`javelin-sys/upstream/LICENSE.TXT`. Unicode data is covered by
`javelin-sys/upstream/tools/unicode/LICENSE.txt` (Unicode-3.0).