README
¶
Language Machine 2
A Go port of Peri Hankey's Language Machine, a toolkit for language and grammar. In a Language Machine grammar, a rule applies when what is expected and what is in the input fail to match. Recognition and substitution interleave on the input stream, so one notation (lm2n) covers lexing, parsing, translation and evaluation.
The port keeps the original execution semantics and the lm-diagram trace. The grammars and reference outputs from the original release (in examples/) produce the same output, and the regression tests check this.
Build
Requires Go 1.27 or later. There are no third-party dependencies.
make build # -> bin/lm2
make test # regression tests
make check # vet + tests
make race # tests under the race detector
make bench # engine benchmarks at 1, 4 and 16 CPUs
Quick start
Grammars are written in lm2n and compiled to .lm2 bytecode by the lm2n compiler, which is itself a grammar. First build the compiler from its sources. lm2nbs.lm2 is the original bootstrap, and the second stage is a fixpoint:
bin/lm2 -rules internal/lm2nsrc/lm2nbs.lm2 internal/lm2nsrc/lm2n2xfe.lm2n internal/lm2nsrc/lm2n2mbe.lm2n > stage1.lm2
bin/lm2 -rules stage1.lm2 -output lm2n.lm2 internal/lm2nsrc/lm2n2xfe.lm2n internal/lm2nsrc/lm2n2mbe.lm2n
Then compile a grammar and run it:
bin/lm2 -rules lm2n.lm2 -output calc.lm2 examples/basics/calc.lm2n
bin/lm2 -rules calc.lm2 -input '3*(4+5)=' # the answer is 27
bin/lm2 -rules calc.lm2 examples/basics/calc.input # input files as arguments
bin/lm2 -rules calc.lm2 -trace D -input '1+2=' # draw the lm-diagram
Run bin/lm2-h for all options. Flags take effect in the order given (for example, -dwidth must come before -trace D).
Documentation
docs/tutorial.md: a hands-on tutorial, from a one-rule program to parsers, translators and Go binaries built withlm2n2godocs/technical_overview.md: architecture and CLIdocs/internal_machine.md: how the engine loads and runs rulesdocs/bytecode.md: the.lm2bytecode formatdocs/lm2/: a structured digest of the original documentation, covering the execution model,lm2nsyntax, builtins, tracing and the lm-diagramdocs/original/: the original website's wiki sourcesexamples/: the original grammars, inputs and reference outputs
License
Language Machine 2 is distributed under the GNU GPL v3 (see COPYING). It is based on the Language Machine © 2005 Peri Hankey, GNU GPL v2 (see COPYING.languagemachine).
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
lm2
command
Command lm2 runs Language Machine rules (.lm2 bytecode) on its input.
|
Command lm2 runs Language Machine rules (.lm2 bytecode) on its input. |
|
lm2n
command
Command lm2n is the lm2n compiler (lm2n2xfe + lm2n2mbe) built into a Go program by lm2n2go, as the original built lm2n2m with lm2n2d and gdc.
|
Command lm2n is the lm2n compiler (lm2n2xfe + lm2n2mbe) built into a Go program by lm2n2go, as the original built lm2n2m with lm2n2d and gdc. |
|
lm2n2go
command
Command lm2n2go compiles Language Machine rules to a Go program or package, as lm2n2d compiled them to D (docs/lm2n2go.md).
|
Command lm2n2go compiles Language Machine rules to a Go program or package, as lm2n2d compiled them to D (docs/lm2n2go.md). |
|
examples
|
|
|
highlight
Package highlight does syntax highlighting with Language Machine rules.
|
Package highlight does syntax highlighting with Language Machine rules. |
|
highlight/lmhl
command
Command lmhl highlights source text with Language Machine rules (../README.md).
|
Command lmhl highlights source text with Language Machine rules (../README.md). |
|
internal
|
|
|
conv
Package conv holds the text conversions that must behave as the original machine's did: URI encoding like JavaScript's encodeURI, C-style escapes, and C library number parsing (strtod, sscanf "%o").
|
Package conv holds the text conversions that must behave as the original machine's did: URI encoding like JavaScript's encodeURI, C-style escapes, and C library number parsing (strtod, sscanf "%o"). |
|
lm2go
Package lm2go turns compiled Language Machine rules into Go source, as the original lm2n2d back end turned them into D: the rules in .lm2 bytecode are embedded in a Go file that runs them with package lm2, together with a table that binds the functions the rules call to Go functions.
|
Package lm2go turns compiled Language Machine rules into Go source, as the original lm2n2d back end turned them into D: the rules in .lm2 bytecode are embedded in a Go file that runs them with package lm2, together with a table that binds the functions the rules call to Go functions. |
|
lm2nsrc
Package lm2nsrc embeds the lm2n compiler: the bootstrap compiler lm2nbs.lm2 and the sources of the bytecode compiler, front end lm2n2xfe.lm2n and back end lm2n2mbe.lm2n.
|
Package lm2nsrc embeds the lm2n compiler: the bootstrap compiler lm2nbs.lm2 and the sources of the bytecode compiler, front end lm2n2xfe.lm2n and back end lm2n2mbe.lm2n. |
|
version
Package version holds the version, date and licence strings.
|
Package version holds the version, date and licence strings. |
|
Package lm2 runs Language Machine rulesets built into a Go program.
|
Package lm2 runs Language Machine rulesets built into a Go program. |
|
lm2n
Package lm2n compiles lm2n, the notation of Language Machine rules, to the .lm2 bytecode that lm2.Program runs.
|
Package lm2n compiles lm2n, the notation of Language Machine rules, to the .lm2 bytecode that lm2.Program runs. |