Gram Framework Documentation

Version: 2.0.0b2 (Beta) Runtime: Pure Python 3.10+ (Zero external runtime dependencies)

Welcome to the official English documentation for Gram, a pure-Python lexical analysis, parser combinator, and Abstract Syntax Tree (AST) generation framework for building Domain-Specific Languages (DSLs), transpilers, and compiler frontends.

Documentation Index

01. Introduction

High-level overview of the framework, its design goals, installation instructions, and current release lifecycle.

• 01. What is Gram? — Core architecture, strict separation between syntactic and semantic phases, and design objectives.
• 02. Installation — Installing Gram via VNMA (vnma.toml, Git branches, tags, and live editable links) or directly via Git and PYTHONPATH.
• 03. Beta Status — Current stability matrix for v2.0.0b2, tested subsystems, and experimental features.

02. Combinators

Reference guide for all available syntactic combinators in gram.core.combinators, execution contracts, and Pratt expression engines.

• 01. Matching Combinators — MatchToken, MatchKeyword, MatchGroup, MatchSeqSymbol, and generador_expr.
• 02. Structural Combinators — Seq (+), Alt (|), Opt, and Enclosed.
• 03. Repetition Combinators — Many, Some, Until, UntilIndent, and Separator.
• 04. Rules & Storage — RuleItem, Ref, Item, Literal, Save, and Load.
• 05. Lookahead & Control — Peek, Not, If, Skip, Tag, Tokenize, and ErrorCombinator.
• 06. Fluent Token Validation — Req fluent validation and in-place token transformation chains.
• 08. Preprocessing and Expectations — Preprocess, Convert, and Expected for validation, logical conversions, and strict assertions.
• 07. Pratt Expressions — ArithmeticExpr, ConditionalExpr, DualExpr, bind_left, and bind_right.

03. Usage Guide

Practical guides for structuring language frontends, managing multi-language sessions, handling diagnostics, and generating editor tooling.

• 01. Keywords & Lexicon Setup — Registering Keyword entries, WordGroup catalogs, custom symbols, and lexer flags.
• 02. RuleItem & nodeable — Defining production rules with RuleItem, AutoCode/SetCode, root entrypoints, and how nodeable controls ASTRef wrapping vs. node inlining.
• 03. Language Sessions — Isolating and switching between multiple language frontends using gram.sessions.Session.
• 04. Diagnostics & Error System — Hierarchical telemetry with Diagnostics, OSGDC error codes, StackError, and non-invasive error hooks (ErrorAction).
• 05. VSIX & Editor Tooling (Beta) — Declarative editor maps on RuleItem, TokenSelector, ANSI TrueColor previews, VS Code extension generation, and the built-in LSP server.