textX

4.3.0 · active · verified Fri Apr 17

textX is a meta-language for building Domain-Specific Languages (DSLs) in Python, inspired by Xtext. It allows you to define a grammar using a simple, intuitive syntax and then generates a parser and an object model for your DSL. The current version is 4.3.0, and it has a steady release cadence, primarily focusing on maintenance and Python version compatibility.

Common errors

```
textx.exceptions.TextXSyntaxError: Expected '...', got '...' at position ...
```
cause The input text provided to the parser does not conform to the defined grammar rules. This is the most common error when developing a DSL.

fix Carefully review your input string against your grammar definition. Use the textX CLI with the `--debug` flag (`textx generate --debug my_grammar.tx my_input.txt`) or `textx_tools.debugger` to visualize the parsing process and pinpoint the exact location of the syntax error.
```
textx.exceptions.TextXError: Unknown object '...' at position ...
```
cause A reference in the parsed model points to an object that has not been defined or is not in scope according to the grammar rules that handle references.

fix Ensure that all referenced objects are correctly defined and named within your grammar. Verify that the input text contains the definitions of all objects before they are referenced. Check for typos in object names or reference rules.
```
textx.exceptions.TextXError: Rule '...' not found!
```
cause Your grammar file contains a reference to a rule that is not defined anywhere in the grammar, or there is a typo in a rule name.

fix Inspect your grammar file for any misspelled rule names or rules that are declared but never defined. All rules mentioned in other rules or as the starting rule of the metamodel must have a corresponding definition.

Warnings

breaking Python 3.6 and 3.7 support was removed in textX 4.0.0. The minimum supported Python version is now 3.8.
Fix: Upgrade your Python environment to 3.8 or newer before upgrading textX to version 4.0.0 or later.
breaking The separator in object rule references changed from `|` to `:` in version 3.1.0 and became a breaking change in 4.0.0. If your grammars use the old `|` separator for object references, they will fail to parse.
Fix: Update your grammar files to use `:` as the object rule reference separator (e.g., `rule_name:obj_ref` instead of `rule_name|obj_ref`).
gotcha Internal usage of `click.echo` was replaced with the standard Python `logging` module in version 4.2.0. This change primarily affects internal workings and custom CLI integrations that might have relied on `click.echo` for output.
Fix: If you have custom tooling or integrations that intercept `click.echo` output, you may need to update them to capture standard Python `logging` output instead.
gotcha The regex for the `INT` rule was fixed in version 4.0.0, removing a word boundary (`\b`). This might slightly alter parsing behavior for specific edge cases where integers are immediately followed by non-word characters without a space, potentially making previously valid inputs invalid if the grammar implicitly relied on the old behavior.
Fix: Test your existing grammars and input files thoroughly after upgrading to 4.0.0+ if they use the built-in `INT` rule and have complex integer parsing scenarios. Adjust your grammar or input as needed.

Install

pip install textx Install latest version

Imports

metamodel_from_file
```
from textx import metamodel_from_file
```
metamodel_from_str
```
from textx import metamodel_from_str
```
TextXError
```
from textx.exceptions import TextXError
```

TextXSyntaxError

from textx.exceptions import TextXSyntaxError

Quickstart

This quickstart demonstrates how to define a simple grammar as a string, create a metamodel from it, and then parse an input string to build a model. It also shows basic error handling for invalid input.

from textx import metamodel_from_str

grammar = """
Model: 'Hello' name=ID;
ID: /[_a-zA-Z][a-zA-Z0-9_]*/;
"""

# Create a metamodel from the grammar string
metamodel = metamodel_from_str(grammar)

# Parse a model from an input string
input_str = "Hello World"
model = metamodel.model_from_str(input_str)

# Access the parsed model data
print(f"Parsed name: {model.name}")

# Example with an error
try:
    metamodel.model_from_str("Hi World")
except Exception as e:
    print(f"Error parsing 'Hi World': {e}")

view raw JSON →