Struct Grammar 

pub struct Grammar { /* private fields */ }

This class represents a grammar object in XGrammar, and can be used later in the grammar-guided generation.

The Grammar object supports context-free grammar (CFG). EBNF (extended Backus-Naur Form) is used as the format of the grammar. There are many specifications for EBNF in the literature, and we follow the specification of GBNF (GGML BNF) in https://github.com/ggerganov/llama.cpp/blob/master/grammars/README.md

When formatted with Display, the grammar will be converted to GBNF format.

Implementations

impl Grammar

pub fn to_string_ebnf(&self) -> String

Print the BNF grammar to a string, in EBNF format.

pub fn from_ebnf(ebnf_string: &str, root_rule_name: &str) -> Self

Construct a grammar from EBNF string. The EBNF string should follow the format in https://github.com/ggerganov/llama.cpp/blob/master/grammars/README.md.

Parameters

• ebnf_string: The grammar string in EBNF format.
• root_rule_name: The name of the root rule in the grammar (default: “root”).

Returns

The constructed grammar.

Panics

When converting the EBNF fails, with details about the parsing error.

pub fn from_json_schema( schema: &str, any_whitespace: bool, indent: Option<i32>, separators: Option<(impl AsRef<str>, impl AsRef<str>)>, strict_mode: bool, max_whitespace_cnt: Option<i32>, print_converted_ebnf: bool, ) -> Self

Construct a grammar from JSON schema.

It allows any whitespace by default. If you want to specify the format of the JSON, set any_whitespace to false and use the indent and separators parameters. The meaning and the default values of the parameters follows the convention in Python’s json.dumps().

It internally converts the JSON schema to an EBNF grammar.

Parameters

• schema: The schema string or Pydantic model or JSON schema dict (only string supported in Rust).

• any_whitespace: Whether to use any whitespace (default: true). If true, the generated grammar will ignore the indent and separators parameters, and allow any whitespace.

• indent: The number of spaces for indentation (default: None). If None, the output will be in one line.

  Note that specifying the indentation means forcing the LLM to generate JSON strings strictly formatted. However, some models may tend to generate JSON strings that are not strictly formatted. In this case, forcing the LLM to generate strictly formatted JSON strings may degrade the generation quality. See https://github.com/sgl-project/sglang/issues/2216#issuecomment-2516192009 for more details.

• separators: Two separators used in the schema: comma and colon (default: None). Examples: (",", ":"), (", ", ": "). If None, the default separators will be used: (",", ": ") when the indent is not None, and (", ", ": ") otherwise.

• strict_mode: Whether to use strict mode (default: true). In strict mode, the generated grammar will not allow properties and items that is not specified in the schema. This is equivalent to setting unevaluatedProperties and unevaluatedItems to false.

  This helps LLM to generate accurate output in the grammar-guided generation with JSON schema.

• print_converted_ebnf: If true, the converted EBNF string will be printed (default: false). For debugging purposes.

Returns

The constructed grammar.

Panics

When converting the JSON schema fails, with details about the parsing error.

pub fn from_regex(regex_string: &str, print_converted_ebnf: bool) -> Self

Create a grammar from a regular expression string.

Parameters

• regex_string: The regular expression pattern to create the grammar from.
• print_converted_ebnf: This method will convert the regex pattern to EBNF first. If this is true, the converted EBNF string will be printed. For debugging purposes (default: false).

Returns

The constructed grammar from the regex pattern.

Panics

When parsing the regex pattern fails, with details about the parsing error.

pub fn from_structural_tag(structural_tag_json: &str) -> Result<Self, String>

Create a grammar from a structural tag JSON string.

The structural tag handles the dispatching of different grammars based on the tags and triggers: it initially allows any output, until a trigger is encountered, then dispatch to the corresponding tag; when the end tag is encountered, the grammar will allow any following output, until the next trigger is encountered.

Parameters

• structural_tag_json: The structural tag as a JSON string. The JSON should follow the StructuralTag format with type “structural_tag” and a format object containing triggered_tags with triggers and tags arrays.

Returns

• Ok(Grammar) on success
• Err(String) when the structural tag JSON is invalid or malformed.

Example

use serde_json::json;
let structural_tag_json = json!({
    "type": "structural_tag",
    "format": {
        "type": "triggered_tags",
        "triggers": ["<tool>"],
        "tags": [{
            "type": "tag",
            "begin": "<tool>",
            "content": {
                "type": "json_schema",
                "json_schema": {"type": "object", "properties": {...}}
            },
            "end": "</tool>"
        }]
    }
}).to_string();
let grammar = Grammar::from_structural_tag(&structural_tag_json)?;

pub fn builtin_json_grammar() -> Self

Get the grammar of standard JSON. This is compatible with the official JSON grammar specification in https://www.json.org/json-en.html.

Returns

The constructed grammar for JSON.

pub fn concat(grammars: &[Grammar]) -> Self

Create a grammar that matches the concatenation of the grammars in the slice.

This is equivalent to using the + operator to concatenate the grammars in the slice.

Parameters

• grammars: The grammars to concatenate. Must contain at least one grammar.

Returns

The constructed grammar.

pub fn union(grammars: &[Grammar]) -> Self

Create a grammar that matches any of the grammars in the slice.

This is equivalent to using the | operator to create the union of the grammars in the slice.

Parameters

• grammars: The grammars to union. Must contain at least one grammar.

Returns

The constructed grammar.

pub fn serialize_json(&self) -> String

Serialize the grammar to a JSON string.

pub fn deserialize_json(json_string: &str) -> Result<Self, String>

Deserialize a grammar from a JSON string.

Returns

• Ok(Grammar) on success
• Err(String) when deserialization fails due to invalid JSON, format mismatch, or serialization version mismatch (via the __VERSION__ field). The error string mirrors the C++ exception message.

Trait Implementations

impl Display for Grammar

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Grammar

fn drop(&mut self)

Executes the destructor for this type.