lex

A plain text document format designed for the complete lifecycle of an idea

1. lex CLI

lex is the command-line swiss army knife for converting, formatting, and inspecting lex documents. It keeps the whole lifecycle inside a single binary by delegating to the Rust crates described below.

2. Installation


git clone https://github.com/lex-fmt/tools
cd tools
cargo build --release
# Binary at target/release/lex

3. Commands

3.1. Convert

Convert between formats (lex, markdown, html, pdf). The convert subcommand is optional because it’s the default behavior.

# Convert lex to markdown (stdout) lex document.lex --to markdown

# Convert lex to HTML with output file lex document.lex --to html -o output.html

# Convert lex to PDF lex document.lex --to pdf -o output.pdf

# Convert markdown back to lex lex document.md --to lex

# Explicit convert subcommand lex convert document.lex --to html

The source format is auto-detected from the extension. Override with `--from` when needed.

3.2. Format


# Format to stdout
lex format document.lex

# Redirect to a file
lex format document.lex > formatted.lex

3.3. Inspect

Explore intermediate representations—ideal for debugging the language pipeline.

# AST tree visualization (default) lex inspect document.lex

# AST as XML-like tags lex inspect document.lex ast-tag

# AST as JSON lex inspect document.lex ast-json

# Token stream lex inspect document.lex token-core-json

# Show all AST properties lex inspect document.lex --extra-ast-full

Available transforms
  • - ast-treeviz
  • - ast-tag
  • - ast-json
  • - ast-nodemap
  • - token-core-json
  • - token-line-json
  • - ir-json

3.4. Element At

Locate the element (or ancestor chain) covering a given cursor position.

# Get element at row 10, column 5 lex element-at document.lex 10 5

# Show all ancestors lex element-at document.lex 10 5 --all

4. Supported Formats

Definition
lex

Import ✓ · Export ✓ · Extension `.lex`

Definition
Markdown

Import ✓ · Export ✓ · Extension `.md`

Definition
HTML

Import – · Export ✓ · Extension `.html`

Definition
PDF

Import – · Export ✓ · Extension `.pdf`

5. Configuration

The CLI reads lex.toml. Override the path with `--config`.

lex document.lex --to html --config ./my-lex.toml

Format-specific options:
Use `--extra-<name>` to pass renderer parameters.

# HTML with dark theme
lex document.lex --to html --extra-theme dark

# PDF with mobile page size
lex document.lex --to pdf --extra-size-mobile -o out.pdf

# Inspect with full AST properties
lex inspect document.lex --extra-ast-full
:: shell

6. lex-babel Library

The conversion engine lives in the lex-babel crate. Use it directly when integrating lex with other systems.

use lex_babel::FormatRegistry;

let registry = FormatRegistry::default();

// Parse from markdown let doc = registry.parse(&markdown_source, "markdown")?;

// Serialize to HTML let html = registry.serialize(&doc, "html")?;

Architecture summary
  • - IR layer: format-agnostic events
  • - Common layer: flat↔nested transformations
  • - Format layer: adapters per target format

7. Design Principles

  • - Invisible syntax: indentation reveals hierarchy
  • - Graceful degradation: fallback to paragraphs instead of errors
  • - Complete lifecycle: from drafts to publishing
  • - Tool-friendly: deterministic grammar
  • - Future-proof: plain Unicode text