parlex_calc/
lib.rs

1//! # parlex-calc
2//!
3//! A small demonstration crate built on **parlex**, providing a complete,
4//! minimal example of a lexer–parser pipeline for a calculator language.
5//!
6//! This crate showcases how to connect a [`CalcLexer`] and [`CalcParser`]
7//! using token spans and a shared symbol table. It’s intended for educational
8//! and testing purposes rather than production use.
9//!
10//! ## Overview
11//!
12//! The `parlex-calc` crate defines the following components:
13//!
14//! - [`lexer`] — a tokenizing module that converts raw input into a stream of
15//!   [`CalcToken`] items, each annotated with a [`Span`] indicating its
16//!   position in the source text.
17//! - [`parser`] — a grammar-based parser that consumes lexer tokens to produce
18//!   an abstract syntax tree (AST) or evaluate expressions directly.
19//! - [`symtab`] — a symbol table abstraction ([`SymTab`]) that manages variable
20//!   bindings and supports expression evaluation.
21//! - [`token`] — shared token definitions, including [`CalcToken`],
22//!   [`TokenValue`], and [`TokenID`].
23//!
24//! ## Example
25//!
26//! ```rust
27//! use try_next::{IterInput, TryNextWithContext};
28//! use parlex::span;
29//! use parlex_calc::{CalcParser, CalcToken, SymTab, TokenID, TokenValue};
30//!
31//! // Input source string
32//! let source = "a = 1 + 2 * 3";
33//!
34//! // Initialize parser
35//!
36//! let mut symtab = SymTab::new();
37//! let input = IterInput::from(source.bytes());
38//! let mut parser = CalcParser::try_new(input).unwrap();
39//!
40//! // Run the lexer–parser pipeline
41//! let Ok(Some(token)) = parser.try_next_with_context(&mut symtab) else {panic!("expected token")};
42//! assert!(matches!(
43//!     token,
44//!     CalcToken {
45//!         token_id: TokenID::Stat,
46//!         span: span!(0, 0, 0, 13),
47//!         value: TokenValue::Number(7)
48//!     }
49//! ));
50//! ```
51//!
52//! ## Modules
53//!
54//! - [`lexer`] — lexical analysis (tokenization)
55//! - [`parser`] — grammar-based parsing
56//! - [`symtab`] — symbol table and evaluation context
57//! - [`token`] — token definitions and span utilities
58//!
59//! ## Re-exports
60//!
61//! To simplify integration, the crate re-exports its main entry points:
62//!
63//! ```text
64//! CalcLexer, CalcLexerDriver, CalcParser, CalcParserDriver,
65//! SymTab, SymTabError, CalcToken, TokenValue, TokenID
66//! ```
67//!
68//! These are the primary types needed to embed `parlex-calc` in tests,
69//! examples, or small interpreters.
70pub mod lexer;
71pub mod parser;
72pub mod symtab;
73pub mod token;
74
75pub use lexer::{CalcLexer, CalcLexerDriver};
76pub use parser::parser_data::TokenID;
77pub use parser::{CalcParser, CalcParserDriver};
78pub use symtab::{SymTab, SymTabError};
79pub use token::{CalcToken, TokenValue};