Expand description
§logicaffeine-language
The LOGOS front end: one lexer and parser that turn English sentences into first-order logic and read imperative LOGOS programs and LGX pages (LGX is the web framework) into the AST every execution tier runs. English is ambiguous where logic cannot be: Every woman loves a man. has two quantifier scopes, and compile_all_scopes hands back both readings instead of silently picking one. It stops at the AST and the logical form; running and compiling programs is logicaffeine-compile’s job.
Part of the Logicaffeine workspace, tier 3. A build.rs step compiles the vocabulary from logicaffeine-lexicon into generated lookup tables.
§Role in the workspace
This is the language front end. It sits on the structural atoms (logicaffeine-base: arena, interner, spans), the vocabulary (logicaffeine-lexicon) and the proof engine (logicaffeine-proof), and the compiler, CLI, LSP and web app consume it. See logic-mode.md.
Input → Lexer → Parser (AST + DRS) → Semantics → Transpiler → FOL- Lexer (
lexer,token,lexicon): two stages, a structuralLineLexerand then the tokenLexer, with morphology, multi-word-expression collapsing (mwe) and lexicon lookup. - Parser (
parser/{clause,noun,verb,quantifier,modal,question,pragmatics,math}): hand-written recursive descent over an arena-allocated AST, tracking discourse with Discourse Representation Structures (drs).ParserModeselects declarative English or imperative LOGOS.parser/math.rsis the theorem surface’s math layer: quantified arithmetic in English (For all n, n plus 0 equals n.), whichproof_convertlowers to anIntidentity the proof engine’s ring oracle decides. - AST (
ast/{logic,stmt,theorem}, plusast/{component,view}for LGX): the arena-lifetimeLogicExpr<'a>/Term<'a>logical form plus statement, theorem, component and view nodes. - Semantics (
semantics/{axioms,kripke,knowledge_graph},lambda): axiom expansion, Kripke lowering for modals, intensional and event readings, Montague-style lambda transforms, and quantifier-scope enumeration. - Transpiler (
transpile,formatter): renders the logical form in the target notation.
§Example
use logicaffeine_language::compile;
let fol = compile("Every man is mortal.").unwrap();
assert_eq!(fol, "∀x((Man(x) → Mortal(x)))");Every quantifier-scope reading of an ambiguous sentence:
use logicaffeine_language::compile_all_scopes;
let readings = compile_all_scopes("Every woman loves a man.").unwrap();
assert!(readings.len() >= 2);Discourse across sentences, where a pronoun resolves against an earlier turn (an unresolved pronoun would print as ?):
use logicaffeine_language::Session;
let mut session = Session::new();
let first = session.eval("A man entered.").unwrap();
assert!(first.contains("Man"));
let second = session.eval("He sat.").unwrap();
assert!(second.contains("Sit"));
assert!(!second.contains("?"));§Public API
All fallible entry points return Result<_, ParseError>; compile_forest is infallible (it returns whatever readings parse).
| Function | Signature | Purpose |
|---|---|---|
compile | (&str) -> Result<String, ParseError> | Unicode FOL (default) |
compile_simple | (&str) -> Result<String, ParseError> | ASCII SimpleFOL |
compile_kripke | (&str) -> Result<String, ParseError> | modals as explicit world quantification |
compile_pragmatic | (&str) -> Result<String, ParseError> | adds scalar-implicature enrichment (some ⇝ ∃ +> ¬∀) |
compile_with_options | (&str, CompileOptions) -> Result<String, ParseError> | choose format + pragmatic |
compile_all_scopes | (&str) -> Result<Vec<String>, ParseError> | every quantifier-scope permutation |
compile_forest | (&str) -> Vec<String> | every parse reading (noun/verb, PP attachment) |
compile_ambiguous | (&str) -> Result<Vec<String>, ParseError> | readings × scopes |
compile_discourse | (&[&str]) -> Result<String, ParseError> | batch with shared discourse context |
compile_with_discourse | (&str, &mut WorldState, &mut Interner) -> Result<String, ParseError> | thread your own discourse state |
compile_theorem | (&str) -> Result<String, ParseError> | parse + prove a Given:/Prove: block |
compile_all_scopes, compile_forest, compile_ambiguous, compile_discourse and compile_with_world_state each have a *_with_options companion taking CompileOptions. MAX_FOREST_READINGS (= 12) caps forest size to bound combinatorial blowup. Lower-level variants (compile_kripke_with, compile_with_world_state{,_options}, compile_with_world_state_interner_options) expose the WorldState / Interner directly.
Key types and re-exports:
OutputFormat:Unicode(default),LaTeX,SimpleFOL,Kripke.CompileOptions { format: OutputFormat, pragmatic: bool }, defaulting to{ Unicode, false }.Session: multi-sentence discourse withnew/with_format,eval,history,turn_count,world_state{,_mut},reset. It carries anaphora state acrossevalcalls.- Pipeline types:
Lexer,LineLexer,LineToken,Token/TokenType,Parser,ParserMode,NegativeScopeMode,QuantifierParsing,Drs/WorldState,ParseError/ParseErrorKind/socratic_explanation,TypeRegistry,SymbolRegistry,AstContext,TranspileContext. proof_convert(logic_expr_to_proof_expr,term_to_proof_term) bridges the arenaLogicExpr<'a>to the proof engine’s ownedProofExpr/ProofTerm;compile_theoremproves throughlogicaffeine_proof.optimizationholds the compiler’s optimization toggles: anOptimizationConfigu64bitset with one bit perOptpass (OPT_COUNTof them), shared by the AOT, run, VM, JIT and codegen paths. It lives here because the parser maps the## No <X>and## Require <X>source decorators ontoOpts:## Noturns a pass off, and## Requirefails compilation unless the pass fired (Parser::required_optimizations).
§The imperative surface
The same parser reads the imperative LOGOS surface, so every imperative construct flows through this front end; imperative-mode.md is the guide to the core surface. Among the imperative forms it parses:
- modules:
Import Geometry.,Import Geometry and Colors.,Import Geometry from "shapes/geometry.lg".,Import Geometry as Geo., selectiveImport double from Util., qualifiedGeometry::Point, andprivatedefinitions (analysis::dependenciesresolves them;import_formatsorts the block); - the test framework:
## Test: <sentence>blocks withExpect that …,Expect this to fail …:,Expect output:,Advance time by …,Given a file …, case tables (For each of these cases:) and seeded, shrinking properties (For all integers a and b …:); - contracts and errors:
Fail with <reason>.,, otherwise <reason>onAssert/Require/Assume, and dimensioned range contracts (Assume v is between 0.2 volts and 0.7 volts.); - observation statements (
Note that …,Warn that …,Record that …,During <gerund>:),Swap x and y.,Reversibly:blocks,Converge remote into local.,Close ch., task joins (Await h into r.),Solve … for x./Minimize …, andevery x in xs where …selection; - tensor sugar (
a R by C tensor of Real,matmul,softmax of,rmsnorm of,attention of … over … and …, and more), desugared to row-majorSeqloops every execution tier runs; - LGX pages and components (
## Page,## Component,## Store,## Directive,## Route,## Before each request,## Redirect), parsed into first-class AST byparser/component.rsand lowered to LOGOS byparser/lgx_lower; - tuple and record types in signatures (
(Int, Text),(quotient: Int, remainder: Int)) withLet (a, b) be …destructuring; ## Definedefinitional blocks and thefollowed bysequence-concatenation operator.
A theorem’s Proof: line is read as a sketch: compile::run_proof_sketch runs it through the proof engine’s tactic-script language and discharges the obligations it leaves with the certified automation, reporting how many. A step that errors is never swept.
§Module map
Grouped by pipeline stage. intern and arena re-export the logicaffeine-base primitives, so downstream crates need only depend on this one.
| Module | Role |
|---|---|
token, lexer, lexicon, mwe | tokenization: structural LineLexer → token Lexer, morphology, lexicon lookup, multi-word-expression collapsing |
parser, ast, arena_ctx | recursive-descent parse into an arena-allocated AST (arena_ctx owns the allocation context) |
lint | post-parse warnings over an already-built Stmt body: CopyLintScope, the value-semantics copy lint (a local copied from a field or another local, mutated, then never read or written back) |
lgx | the LGX template layer. html is the flat HTML tokenizer, with the generated WHATWG entities table. template builds the {…} tag tree: {if}/{for each}/{inspect}/{let}/{extends}/{block}/{children}/{raw}, holes with filters, components and directives. css scopes CSS to its component, raw maps raw-block offsets, and deps is the static read/write dependency graph a fine-grained DOM patcher is compiled from. check and selector are the structural checks a template passes before any LOGOS expression in it is parsed. Every embedded expression stays text plus its offset; parser/component.rs re-lexes it with the imperative lexer (Lexer::new_imperative) and parses it with the real expression parser into the view IR (ast::view) |
drs, session, pragmatics | discourse: Discourse Representation Structures, the incremental-evaluation Session, and post-parse pragmatic inference |
semantics, lambda, ontology | axiom expansion, Montague lambda transforms and quantifier-scope enumeration (lambda::enumerate_scopings), and the part-whole and sort lookups behind bridging anaphora and metaphor detection |
scope | a stack of variable bindings and their ownership states for imperative code generation |
transpile, formatter, view, style | render the logical form; view is the owned serialization form, and style adds ANSI coloring |
printer | render an imperative Expr (and its subexpressions) back to English, the basis of power-assert failure annotations, property counterexamples, and mutation-survivor reports |
source_format, import_format | the canonical LOGOS source formatter (format_source/format_line): structural reindent at 4 spaces per lexed nesting level, with string and prose interiors untouched, and one rule set shared by the LSP’s formatting providers and largo fmt. Formatting never changes the token stream, so import_format (normalize_imports), which sorts and de-duplicates a module’s Import block, runs as a separate largo fmt pass |
token_class | the token classification (verbs as functions, nouns as types, and so on) that every highlighting surface derives from, so LSP semantic tokens and the REPL’s ANSI painting cannot disagree |
teach | the lesson table: a ConstructDoc (one plain sentence, a runnable example, and a Socratic question or tip, all required by the type) for every taught keyword, every ## block type, and the built-in types. LSP hover and completion docs and the REPL’s :explain all read from it, and crates/logicaffeine_tests/tests/teach_lock.rs ratchets it. It also holds the literate-doc extractors (module_doc/doc_for_header_at/extract_literate_docs) that turn a ## Note above a definition into its hover documentation |
analysis, registry, symbol_dict | static discovery passes (## Definition scan, import scan), the type and symbol registries, and symbol-dictionary extraction |
optimization, proof_convert | the shared Opt optimization bitset, and the bridge from arena LogicExpr to the proof engine’s owned ProofExpr |
ast_map | the exhaustive rebuilding traversal of the imperative AST. A pass overrides the hooks for the nodes it rewrites and walks the rest. Every Stmt/Expr/TypeExpr variant is named with no wildcard arm, so a new variant does not compile until someone decides how it is traversed |
ast_depth | the nesting-depth gate: it rejects programs whose AST nests deeper than every downstream walker (optimizer, codegen, interpreter, VM) can safely recurse, reporting AstTooDeep at parse time instead of a stack overflow later |
error, suggest, visitor, debug | parse-error types with Socratic explanations, spelling suggestions, the AST visitor, and interner-aware debug display |
diagnostic | the canonical machine-readable diagnostic surface (logos-diagnostic/1): a stable kebab-case code, a severity and a one-line headline for every ParseErrorKind, decided in wildcard-free matches so a new kind does not compile undecided. Its Diagnostic JSON shape is shared by largo check --json, largo run --json and the MCP logos_check tool, the language server uses the same codes and severities, and the rendered catalog() backs largo explain and the generated error catalog |
§Feature flags
| Feature | Default | Enables |
|---|---|---|
dynamic-lexicon | off | Runtime lexicon loading (logicaffeine-lexicon/dynamic-lexicon), re-exported as the runtime_lexicon module. |
lexicon-reference | off | Test-only: lexicon::reference, every generated word table written as a linear match, the oracle the word-table differential checks the generated tables against. |
The build.rs step compiles the vocabulary database (logicaffeine_lexicon::LEXICON_JSON, taken as a build-dependency) into generated Rust tables for the lexicon, multi-word expressions, ontology and axioms under OUT_DIR, so changing the lexicon requires a rebuild.
§Dependencies
Internal: logicaffeine-base (arena, interner, symbols, spans, re-exported as Arena/Interner/Symbol), logicaffeine-lexicon (vocabulary), logicaffeine-proof (theorem proving).
External: bumpalo (arena allocation), serde + serde_json (hardware and ontology types, and build-time lexicon compilation).
§License
MIT License — see LICENSE.md.
Re-exports§
pub use proof_convert::logic_expr_to_proof_expr;pub use proof_convert::term_to_proof_term;pub use analysis::TypeRegistry;pub use arena_ctx::AstContext;pub use drs::BoxType;pub use drs::Drs;pub use drs::WorldState;pub use error::socratic_explanation;pub use error::ParseError;pub use error::ParseErrorKind;pub use lexer::Lexer;pub use lexer::LineLexer;pub use lexer::LineToken;pub use parser::NegativeScopeMode;pub use parser::Parser;pub use parser::ParserMode;pub use parser::QuantifierParsing;pub use registry::SymbolRegistry;pub use session::Session;pub use token::BlockType;pub use token::FocusKind;pub use token::MeasureKind;pub use token::PresupKind;pub use token::Span;pub use token::Token;pub use token::TokenType;pub use compile::compile;pub use compile::compile_all_scopes;pub use compile::compile_all_scopes_with_options;pub use compile::compile_ambiguous;pub use compile::compile_ambiguous_with_options;pub use compile::compile_discourse;pub use compile::compile_discourse_with_options;pub use compile::compile_forest;pub use compile::compile_forest_with_options;pub use compile::compile_kripke;pub use compile::compile_kripke_with;pub use compile::compile_pragmatic;pub use compile::compile_simple;pub use compile::compile_theorem;pub use compile::compile_with_discourse;pub use compile::compile_with_options;pub use compile::compile_with_world_state;pub use compile::compile_with_world_state_interner_options;pub use compile::compile_with_world_state_options;pub use compile::run_proof_sketch;pub use compile::MAX_FOREST_READINGS;
Modules§
- analysis
- Static analysis passes for type and policy discovery.
- arena
- arena_
ctx - Arena context for AST allocation.
- ast
- Abstract Syntax Tree types for both logical expressions and imperative statements.
- ast_
depth - The AST depth gate — “parsed ⇒ bounded”.
- ast_map
- An exhaustive, rebuilding traversal of the imperative AST.
- compile
- Compilation API
- debug
- Debug display utilities for AST types with interner access.
- diagnostic
- The canonical machine-readable diagnostic surface:
logos-diagnostic/1. - drs
- Discourse Representation Structure (DRS) for anaphora resolution and scope tracking.
- error
- Error types and display formatting for parse errors.
- formatter
- Output formatters for logical expressions.
- import_
format - Canonical formatting of a module’s
Importstatements — the pit-of-success default so import blocks never need manual bikeshedding. - intern
- lambda
- Lambda calculus transformations for Montague-style compositional semantics.
- lexer
- Two-stage lexer for LOGOS natural language input.
- lexicon
- Lexicon: Vocabulary lookup functions
- lgx
- LGX — the LOGOS web framework’s template layer: real HTML with Jinja-style
{…}tags, component-scoped CSS, and the structural checks a template needs before any LOGOS expression inside it is parsed. - lint
- The value-semantics copy lint.
- mwe
- Multi-Word Expression (MWE) processing.
- ontology
- Ontology module for bridging anaphora and sort compatibility checking.
- optimization
- The registry of compiler optimization toggles.
- parser
- Recursive descent parser for natural language to first-order logic.
- pragmatics
- Post-parse pragmatic inference transformations.
- printer
- English rendering of imperative expressions — the shared surface behind power-assert failure messages, property counterexamples, and mutation survivor reports.
- proof_
convert - Conversion from parser AST to proof engine representation.
- registry
- Symbol registry for consistent variable naming in FOL output.
- runtime_
lexicon - Runtime JSON-based lexicon loading (requires
dynamic-lexiconfeature). - scope
- Scope stack for variable binding during code generation.
- semantics
- Semantic transformations for logical expressions.
- session
- Session Manager for Incremental Evaluation
- source_
format - The canonical LOGOS source formatter.
- style
- ANSI terminal color styling for error messages.
- suggest
- Spelling suggestions for unknown words.
- symbol_
dict - Symbol Dictionary Extraction
- teach
- The lesson table for LOGOS constructs: every lesson a surface shows
(LSP hover, completion documentation, the REPL’s
:explain) comes from this table, so the editor and the terminal always teach the same thing. - token
- Token types for the LOGOS lexer and parser.
- token_
class - How LOGOS tokens are classified for highlighting: parts of speech are the syntax — verbs paint as functions, nouns as types, adjectives as modifiers. Every highlighting surface (LSP semantic tokens, the terminal REPL, any future renderer) derives its colors from this mapping, so they can never disagree.
- transpile
- Transpilation from AST to first-order logic notation.
- view
- Owned view types for AST serialization and display.
- visitor
- AST visitor pattern for traversing logical expressions.
Structs§
- Arena
- An owning arena for stable references.
- Base
Span - A byte-offset range in source text.
- Compile
Options - Interner
- A string interner providing O(1) equality comparison via
Symbolhandles. - Symbol
- A lightweight handle to an interned string.
- Transpile
Context
Enums§
- Case
- Grammatical case (for pronouns).
- Gender
- Grammatical gender (for pronouns and agreement).
- Number
- Grammatical number for nouns and agreement.
- Output
Format