Term's Format

A Term is the core data type in RegexSolver. It represents a regular language (a set of strings), and can be expressed in two interchangeable forms:

• Regex: a regular expression pattern
• FAIR: a stable binary encoding of an automaton

Both forms describe the same language and can be used everywhere in the API.

The life of a Term

A Term passes through four stages:

1. You create one, usually with Term.regex(...), holding a pattern.
2. You send it to an operation, alone or alongside others.
3. You get one back, often in FAIR rather than regex form, because that is what the operation produced. It is a normal Term and goes straight into the next call.
4. You reuse it. Answers about a single Term (cardinality, length, pattern) are stored on it. Asking again on the same object skips the API, so keep the Term rather than rebuilding it.

What a returned Term does not carry is a readable pattern. That is a separate step, covered in Getting the regex pattern below.

Formats

Regex (Regular Expression)

RegexSolver supports pure regular expressions (regular language only), with the following rules:

1. Implicit Anchoring Patterns always match the full string. abc matches "abc", but not "xabc" or "abcx".

2. No Lookaround Constructs like (?=...) and (?<=...) are not supported.

3. Greedy Quantifiers Only Ungreedy forms (*?, +?, ??) are parsed but treated as greedy.

4. Dot Matches Everything . matches any unicode character, including \n.

5. No Features Outside Regular Languages Backreferences like \1 are not supported and will return an error.

Regex parsing is powered by Rust's regex-syntax parser. Some unsupported syntax may parse, but will not influence matching semantics.

FAIR (Fast Internal Automaton Representation)

FAIR is a portable encoding of an automaton:

• Encoded using Z85 (ASCII-safe, compact, padded)
• Length varies with automaton complexity
• Opaque and not editable, but fully reusable
• Skips regex parsing and compilation when used, improving performance

Use FAIR to cache, store, or chain results without reprocessing.

Choosing the response format

By default the engine converts nothing: you get back whatever form the operation naturally produced. Which form that is depends on the operation:

Leaving the default alone is the right choice while you are chaining operations, because it never spends time on a conversion you did not ask for.

Set responseFormat when you want to override that. The examples throughout these docs force regex so their output is printable, which is convenient for learning and worth being deliberate about in real code: on a heavy operation, forcing regex makes the conversion draw on the same time budget as the operation itself. See Heavy Operations.

Code
RegexSolverClient client = RegexSolverClient.builder()
    .apiToken(System.getenv("REGEXSOLVER_API_TOKEN"))
    .build();
Term term = Term.regex("abcde");

OperationOptions operationOptions = OperationOptions.builder()
        .responseFormat(ResponseFormat.REGEX);
Term result = client.union(List.of(term, Term.regex("de")), operationOptions);

System.out.println(result); // regex=(abc)?de

Code
RegexSolverClient client = RegexSolverClient.builder()
    .apiToken(System.getenv("REGEXSOLVER_API_TOKEN"))
    .build();
Term term = Term.regex("abcde");

OperationOptions operationOptions = OperationOptions.builder()
        .responseFormat(ResponseFormat.FAIR);
Term result = client.union(List.of(term, Term.regex("de")), operationOptions);

System.out.println(result); // fair=...

Getting the regex pattern

Regardless of the format of a Term it is possible to get the associated regex pattern:

Code
RegexSolverClient client = RegexSolverClient.builder()
    .apiToken(System.getenv("REGEXSOLVER_API_TOKEN"))
    .build();
Term a = Term.fair("<uw$8AJYkaU].HFn1kT[tx*-VAZ8usSKXcEKZ[wx:F8vYuR-b?tFFk1eM2RXs9yuu5dakz7r/{!AW9/(hK0]knHS&Q]!@K=ahmGr1Dbjb5(XE1UT%Ab@8rXvYop}$");
Term b = Term.regex("[a-z]+");

String r1 = client.getPattern(a);
System.out.println(r1); // deabc

String r2 = client.getPattern(b);
System.out.println(r2); // [a-z]+

Visualizing a Term

A Term can also be rendered as a Graphviz DOT description of its automaton. This is a debugging aid: paste the output into any Graphviz renderer to see the states and transitions behind a language that has become hard to read as a pattern.

Code
String dot = client.getDot(Term.regex("[a-z]"));

System.out.println(dot);
// digraph Automaton {
//     rankdir = LR;
//     0    [shape=circle,label="0"];
//     initial [shape=plaintext,label=""];
//     initial -> 0
//     0 -> 1 [label="[a-z]"]
//     1    [shape=doublecircle,label="1"];
// }

Matching strings locally

Every Term has a matches method that checks whether a given string belongs to its language. It runs locally, with no API call.

matches needs the regex pattern of the Term. A Term created with regex already has it. A Term created with fair, or returned by an operation in FAIR format, does not have it yet. In that case, call getPattern (or get_pattern) once to resolve and cache the pattern, then matches can be called as many times as you want.

If you call matches on a Term whose pattern is not resolved yet, it throws an error.

Code
RegexSolverClient client = RegexSolverClient.builder()
    .apiToken(System.getenv("REGEXSOLVER_API_TOKEN"))
    .build();

Term term = Term.regex("[a-z]+");

term.matches("abc"); // true
term.matches("ABC"); // false

// A Term built from FAIR has no pattern yet
Term fairTerm = Term.fair("<uw$8AJYkaU].HFn1kT[tx*-VAZ8usSKXcEKZ[wx:F8vYuR-b?tFFk1eM2RXs9yuu5dakz7r/{!AW9/(hK0]knHS&Q]!@K=ahmGr1Dbjb5(XE1UT%Ab@8rXvYop}$");

client.getPattern(fairTerm); // resolves and caches the pattern
fairTerm.matches("deabc"); // true