Skip to content

Installation & Usage

Jump to bottom
Adam Szeruda edited this page Jan 27, 2025 · 1 revision

Installation

For now, cpspg can only be installed from its Git repository. To do so, execute the following commands:

git clone https://github.com/fram-lang/cpspg.git
cd cpspg
dune build --profile release
dune install

Ensure that you have Git, OCaml, and Dune installed before running the above commands.

Command-line Usage

The general usage of cpspg is as follows:

cpspg [options] <input> [output...]
cpspg [options] [-f format] -o <output> <input>

Both forms expect exactly one input file and an arbitrary number of output files. When the input file is omitted (or -), cpspg reads its data from standard input. When no output file is specified (or one of the outputs is -), cpspg writes the generated code to standard output.

Invoking cpspg without any options makes it read grammar from standard input and write generated OCaml code to standard output.

Options

cpspg provides several options to customize its behavior and output:

  • -o <file>: Set the output file name to <file>.
  • -f <format>: Force cpspg to generate a file in the given <format>. By default, the format is guessed from the file extension, independently for each output file. Currently supported formats:
    • ml - OCaml program
    • mli - OCaml interface file
    • dot - Graphviz visualization of the generated automaton
  • --lr0, --slr, --lr1, --lalr: Construct an $LR(0)$, $SLR$, $LR(1)$, or $LALR(1)$ automaton, respectively. These automatons differ mainly by the number of generated states and by lookahead computation, with $LALR$ (the default) usually being the best option.
  • --no-locations: Disable all code related to location tracking in the generated code. This disables the $loc family of keywords.
  • --no-line-directives: Do not include line directives in the generated code.
  • --comment: Include comments in the generated code.
  • --readable-ids: Make identifiers in the generated code longer.
  • --readable: Make the generated code more readable (implies --comment, --readable-ids, and --no-line-directives).
  • --compat: Increase compatibility with ocamlyacc. This makes cpspg generate a shim of the Parsing module from OCaml's standard library.

Dune Integration

cpspg can be included in the Dune build process by adding the following to the dune file:

(rule
 (deps Parser.mly)
 (targets Parser.ml Parser.mli)
 (action
  (chdir %{workspace_root} (run cpspg %{deps} %{targets}))))

This rule generates the files Parser.ml and Parser.mli based on the Parser.mly file. Additional options (like --compat) can be added after the cpspg invocation. The chdir action ensures that cpspg reports correct filenames in errors.

Clone this wiki locally