offsides 0.2.1

Layout-sensitive virtual-token lexer adapter for logos + lalrpop
Documentation
  • Coverage
  • 100%
    27 out of 27 items documented0 out of 13 items with examples
  • Size
  • Source code size: 42.6 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 511.0 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 2s Average build duration of successful builds.
  • all releases: 3s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • sdiehl/offsides
    2 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • sdiehl

offsides

Layout-sensitive (off-side rule) lexer adapter for logos + lalrpop grammars.

offsides slots into the standard Rust parsing stack and splices virtual open/close/separator tokens into the token stream based on indentation, so a downstream LALRPOP grammar can match v{, v;, v} (or whatever the user names them) where it would otherwise want braces and semicolons. Subsumes Haskell's do/where/let/of layout, Python's INDENT/DEDENT, and PureScript/Elm/Idris off-side rules as configurations.

It is a sibling to marginalia, and the two compose. Stack TriviaLexer (trivia preservation) inside LayoutLexer (layout insertion) and pass the combined iterator straight to a LALRPOP parser.

The shape of an integration:

use offsides::{LayoutLexer, LayoutConfig, LayoutMode};
use marginalia::TriviaLexer;

let raw = my_logos_lexer(source);
let trivia = TriviaLexer::new(raw, source);
let layout = LayoutLexer::new(trivia, source, LayoutConfig::new(is_my_opener));
let program = MyParser::new().parse(layout)?;

The user's token type must implement offsides::Layout (three constructors: v_open, v_close, v_sep). Which real tokens open a layout block is a runtime predicate passed into LayoutConfig, so the same enum can drive different layout rules in different contexts.

  • LayoutMode::Lazy (default): layout fires only after an opener keyword (in style of Haskell, ML, F#, PureScript, Elm, Idris).
  • LayoutMode::Eager: top-level itself is a layout block (Python-style).
  • OpenerRule::Always (default): an opener always starts a block at the next token (Haskell report style).
  • OpenerRule::Conditional: an opener starts a block only when the next token begins a new line at deeper indentation; otherwise it is inert, so let x = e on one line stays flat (Koka style).

Bracket pairs that suppress layout (with_brackets), carry openers whose opener status survives a bracket group for trailing block arguments like each xs fn(x) (with_carry_openers), and tab width are all configurable on LayoutConfig.

Example

examples/blocklet is a ~150-line block-let calculator with one layout opener (let). Bindings are indent-separated, and the block is closed by in:

let
    x = 10
    y = 20
    z = x + y
in
    z * 2

Run it end-to-end:

cargo run -p blocklet -- examples/blocklet/examples/sample.blocklet

License

MIT. See LICENSE.