index : blog

        

            
            
        
        
0# Uniform – a fully-featured regular expression library for Jai
1
2This library is a partial port of [RE2](https://github.com/google/re2).
3As such, it offers "fast" expression matching of the full PRCE syntax (except backreferences)
4but is _not exponential in the length of the input text_.
5
6This library is still in _very_ rough condition and only minimally tested.
7Proceed with caution. There may be dragons.
8
9For now, it only supports RE2’s general NFA execution engine and
10none of RE2’s conditional fast-paths (DFA, single-pass NFA, …).
11So "fast" isn’t as fast as it could be for some subsets of regular expressions.
12
13See [Russ Cox’s excellent article series](https://swtch.com/~rsc/regexp/) for more information about fast regular expression implementations and details about the different execution engines.
14
15## Usage 
16
17The simplest form is:
18
19```Jai
20// Match anywhere in the text:
21matched, captures := match("text_to_search", "some\\sexpression\\b");
22defer array_free(captures);
23
24// … or anchor it to require the expression to match the whole text:
25matched, captures := match("text_to_search", "some\\sexpression\\b", .Anchored_Both);
26defer array_free(captures);
27```
28
29… after which:
30
31* `matched` indicates whether the expression matched the text,
32* `captures[0]` contains the whole match and
33* `captures[1]` through `[n]` the content of each capture group (`(…)`) in the expression.
34
35The captures reference segments of the original text, so they’re only valid as long as
36the text exists. You need to copy them if you want them to persist.
37This also means that you need to free only the capture array, but not its contents.
38
39### Recommended: compiling the expression
40Compiling the regular expression is the slowest part.
41If you use an expression multiple times (or want more control about available regular expression features),
42you should definitely compile it beforehand:
43
44```Jai
45regexp, success := compile("some\\sexpression\\b");
46defer uninit(*regexp);
47
48// Use regexp as often as you want…
49for text: texts {
50	matched, captures := match(text, regexp);
51	defer array_free(captures);
52}
53```
54
55See [compile.jai](./compile.jai) and [match.jai](./match.jai) for additional options.
56
57## Running the tests
58
59Running the tests requires the [`stubborn` module](https://github.com/rluba/stubborn).
60It’s already included as a submodule, but don’t forget the usual git submodule shenanigans to fetch it.
61
62Compile with `<compiler> first.jai -- test`, then run the `test` binary.
63(The tests should run at compile-time but this is currently broken in the compiler.)
64
65## Compiling the library
66
67If you want to compile the library (even though it doesn’t produce any binary),
68you need the [`ctags` module](https://github.com/rluba/jai-ctags) _in your main jai folder_.
69
70## License
71
72This library is heavily based on [RE2](https://github.com/google/re2), so their original BSD-style license might still be applicable to some parts.
73Otherwise, this library is licensed under the [MIT license](./LICENSE).
74