astx 0.24.0

ASTx is an agnostic expression structure for AST.

ASTx: Abstract Syntax Tree Framework

ASTx is a versatile and extensible library for representing, manipulating, and analyzing Abstract Syntax Trees (ASTs). It provides a unified interface for working with ASTs in various contexts, such as compilers, interpreters, and transpilers.

ASTx makes it easy to model programming languages, apply transformations, generate code, and build custom tools for static and dynamic analysis.

ASTx doesn't aim to be a lexer or a parser, although it could be used by any programming language or parser in order to provide a high level representation of the AST.

It integrates with IRx, enabling code generation with LLVM. Currently, only a small subset of ASTx nodes is supported, but active development is underway, with full support expected soon.

Note: this project is under active development and it is not ready for production yet.

---

🚀 Features

• Language-Agnostic Design: Model and manipulate ASTs for different programming languages.
• Extensibility: Easily add support for new language features or custom AST nodes.
• Code Generation: Transform ASTs into target code for various backends or target languages.
• Rich Node Set: Support for common constructs like variables, expressions, functions, classes, and control flow.
• Python Integration: Built with Python, making it easy to integrate into Python-based projects.
• Symbol Table: Support for an initial implementation of Symbol Table.

---

📦 Installation

Install ASTx from PyPI:

pip install astx

For ASCII visualization in the console (via mermaid-ascii), install with the console extra:

pip install 'astx[console]'

Or install all optional dependencies:

pip install 'astx[all]'

---

📖 Overview

ASTx is designed around two primary concepts:

1. Nodes: Each node represents a language construct (e.g., Variable, Function, IfStmt).
2. Tree: Nodes are organized hierarchically, forming an abstract representation of the program structure.

Additionally, ASTx provides a simple transpiler for converting ASTx nodes to Python code (in text format). This feature is intended solely for educational purposes, demonstrating how a transpiler from ASTx to any other language can be implemented.

---

✨ Usage

1. Create an AST

import astx

# Define a simple function `add(x, y): return x + y`
args = astx.Arguments(
    astx.Argument(name="x", type_=astx.Int32()),
    astx.Argument(name="y", type_=astx.Int32()),
)
fn_body = astx.Block()
fn_body.append(
    astx.FunctionReturn(
        value=astx.BinaryOp(op_code="+", lhs=astx.Variable("x"), rhs=astx.Variable("y"))
    )
)
add_function = astx.FunctionDef(
    prototype=astx.FunctionPrototype(name="add", args=args, return_type=astx.Int32()),
    body=fn_body,
)

2. Generate Code

Use a transpiler to convert the AST to Python code:

from astx_transpilers.python_string import ASTxPythonTranspiler

# Transpile the AST to Python
transpiler = ASTxPythonTranspiler()
python_code = transpiler.visit(add_function)

print(python_code)

Output:

def add(x: int, y: int) -> int:
    return (x + y)

3. ASTx Visualization Features

ASTx offers multiple ways to visualize the AST structure:

• YAML
• JSON
• Graphical visualization (PNG or ASCII)

In a Jupyter Notebook, the default graphical visualization is PNG, while in a console, the default is ASCII (requires pip install 'astx[console]'). Without the console extra, console output falls back to YAML.

You can also print the AST structure in JSON or YAML format. For example:

>>> print(add_function.to_json())
>>> print(add_function.to_yaml())

Transpilers

ASTx includes a powerful transpiler system to convert your AST structures into executable Python code. This is great for code generation, prototyping, or building custom language tools.

from astx_transpilers.python_string import ASTxPythonTranspiler

# Using the 'add_function' ASTx node from the example above
transpiler = ASTxPythonTranspiler()
python_code = transpiler.visit(add_function)
print(python_code)

Output:

def add(x: int, y: int) -> int:
    return (x + y)

For a deep dive into the architecture and more hands-on examples, check out the full transpiler tutorial.

---

📚 Documentation

Detailed documentation and examples can be found in the official documentation.

---

🛠️ Contributing

Contributions are welcome! Please check out our Contributing Guide for more information.

---

📝 License

ASTx is open-source software licensed under the BSD-3-Clause License. See LICENSE for details.