Matra Core

English | 日本語

Matra Core is the small, domain-neutral foundation shared by HTML, Math, Docs, and Graphics packages. It defines tree representations, conversion, traversal, transformation, and replaceable parser and renderer boundaries. Domain-specific evaluation and output rules live outside Core.

Domain packages implement the small MatraRenderer contract and can be invoked consistently with renderWith(renderer, ast, options). Core owns the boundary, while SVG, HTML, and other output rules remain in their packages.

Two tree representations

MatraJSON is the compact three-element representation emitted by parsers and used for interchange:

["tag", { role: "example" }, ["text", ["child", {}, []]]]

The AST used by Core visitors, transformers, and renderers is object-shaped:

{
  tag: "tag",
  props: { role: "example" },
  children: ["text", { tag: "child", props: {}, children: [] }]
}

Convert explicitly at the boundary:

import { astToMatraJSON, matraJSONToAST } from "@matra/core"

Replaceable parsers

A parser only needs a parse(source, options?) method and may return either AST or MatraJSON. parseWith() normalizes both forms to AST.

import { parseWith } from "@matra/core"

const ast = parseWith(peggyParser, source)

The bundled Peggy implementation emits MatraJSON. Core's public parse() adapts that output to AST, keeping the parser replaceable.

HTML

HTML rendering is provided by the separate workspace package:

import { parse } from "@matra/core"
import { toHTML } from "@matra/html"

toHTML(parse('p("Hello", class="lead")'))

Function-style syntax uses Python-like keyword arguments for props:

circle(x=10, y=20, r=5)

Ordinary positional arguments become children. The earlier circle({x: 10, y: 20, r: 5}) form remains available for compatibility but is not the canonical notation.

Package structure

src/
├── ast/       # types, conversion, traversal, transformation
├── parser/    # public parser boundary, grammar, generated parser
├── index.ts   # public exports
├── printer.ts # domain-neutral JSON serialization
└── render.ts  # replaceable renderer boundary
tests/
├── ast.test.mjs
├── parser.test.mjs
└── render.test.mjs

The generated parser is rebuilt from src/parser/grammar.pegjs; edit the grammar rather than generated.mjs. Language-level behavior is defined by the Matra Specification.

Documentation languages

English documents use name.md; their Japanese counterparts use name.ja.md. Both versions should keep the same heading structure and code examples so changes are easy to synchronize.