Skip to main content

Crate logicaffeine_language

Crate logicaffeine_language 

Source
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 structural LineLexer and then the token Lexer, 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). ParserMode selects declarative English or imperative LOGOS. parser/math.rs is the theorem surface’s math layer: quantified arithmetic in English (For all n, n plus 0 equals n.), which proof_convert lowers to an Int identity the proof engine’s ring oracle decides.
  • AST (ast/{logic,stmt,theorem}, plus ast/{component,view} for LGX): the arena-lifetime LogicExpr<'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).

FunctionSignaturePurpose
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 with new / with_format, eval, history, turn_count, world_state{,_mut}, reset. It carries anaphora state across eval calls.
  • 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 arena LogicExpr<'a> to the proof engine’s owned ProofExpr/ProofTerm; compile_theorem proves through logicaffeine_proof.
  • optimization holds the compiler’s optimization toggles: an OptimizationConfig u64 bitset with one bit per Opt pass (OPT_COUNT of 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 onto Opts: ## No turns a pass off, and ## Require fails 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., selective Import double from Util., qualified Geometry::Point, and private definitions (analysis::dependencies resolves them; import_format sorts the block);
  • the test framework: ## Test: <sentence> blocks with Expect 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> on Assert/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 …, and every 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-major Seq loops every execution tier runs;
  • LGX pages and components (## Page, ## Component, ## Store, ## Directive, ## Route, ## Before each request, ## Redirect), parsed into first-class AST by parser/component.rs and lowered to LOGOS by parser/lgx_lower;
  • tuple and record types in signatures ((Int, Text), (quotient: Int, remainder: Int)) with Let (a, b) be … destructuring;
  • ## Define definitional blocks and the followed by sequence-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.

ModuleRole
token, lexer, lexicon, mwetokenization: structural LineLexer → token Lexer, morphology, lexicon lookup, multi-word-expression collapsing
parser, ast, arena_ctxrecursive-descent parse into an arena-allocated AST (arena_ctx owns the allocation context)
lintpost-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)
lgxthe 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, pragmaticsdiscourse: Discourse Representation Structures, the incremental-evaluation Session, and post-parse pragmatic inference
semantics, lambda, ontologyaxiom expansion, Montague lambda transforms and quantifier-scope enumeration (lambda::enumerate_scopings), and the part-whole and sort lookups behind bridging anaphora and metaphor detection
scopea stack of variable bindings and their ownership states for imperative code generation
transpile, formatter, view, stylerender the logical form; view is the owned serialization form, and style adds ANSI coloring
printerrender 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_formatthe 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_classthe 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
teachthe 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_dictstatic discovery passes (## Definition scan, import scan), the type and symbol registries, and symbol-dictionary extraction
optimization, proof_convertthe shared Opt optimization bitset, and the bridge from arena LogicExpr to the proof engine’s owned ProofExpr
ast_mapthe 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_depththe 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, debugparse-error types with Socratic explanations, spelling suggestions, the AST visitor, and interner-aware debug display
diagnosticthe 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

FeatureDefaultEnables
dynamic-lexiconoffRuntime lexicon loading (logicaffeine-lexicon/dynamic-lexicon), re-exported as the runtime_lexicon module.
lexicon-referenceoffTest-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.


Docs index · Root README · Changelog

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 Import statements — 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-lexicon feature).
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.
BaseSpan
A byte-offset range in source text.
CompileOptions
Interner
A string interner providing O(1) equality comparison via Symbol handles.
Symbol
A lightweight handle to an interned string.
TranspileContext

Enums§

Case
Grammatical case (for pronouns).
Gender
Grammatical gender (for pronouns and agreement).
Number
Grammatical number for nouns and agreement.
OutputFormat

Traits§

SymbolEq
Convenience trait for comparing a Symbol to a string literal.