DYPGEN(1)

📦 version 0.2, in nixos 26.05, nixpkgs unstable

💅 DYPGEN(1) — like, the whole manual, but make it make sense

okay bestie, so this is a page from the General Commands Manual (yes, that one) and it's all about dypgen — say it with me, it's the Objective Caml parser generator. Buckle up, we're going in 🎀

✨ NAME ✨

dypgen — literally the Objective Caml parser generator. that's the whole name. iconic of it.

✨ SYNOPSIS ✨

three flavors, pick your fighter:

dypgen [ options ] filename.dyp
dypgen.opt [ options ] filename.dyp
dyp2gram filename.dyp

🌸 DESCRIPTION 🌸

so the dypgen(1) command produces a parser from a context-free grammar spec that has semantic actions attached — very yacc(1) of it, ngl, it's "in the style of" yacc(1). 🫶

say your input file is grammar.dyp (hypothetically, keep up). run dypgen and boom — you get Caml code for a parser in the file grammar.ml, plus its interface in the file grammar.mli. slay.

the generated module defines one parsing function per entry point in the grammar. these functions have the same names as the entry points. yes, matching names, that's the vibe. ✨

now, the lexer (aka the lexical analyzer, bestie, keep up) can be generated by dypgen itself, or by a third-party generator such as ocamllex(1). and this matters because:

  • if an external lexer generator is used, then the parsing functions take as arguments a lexical analyzer (a function from lexer buffers to tokens) and a lexer buffer.
  • if dypgen is used to generate the lexer, then the parsing functions only take a lexer buffer as argument.

either way they return the semantic attribute of the corresponding entry point. 💖

lexer buffers are an abstract data type implemented in the library module Dyp. tokens are values from the concrete type token, which is defined in the interface file grammar.mli produced by dypgen(1). very "it's giving generated types", we love that for us.

dypgen.opt(1) is the same as dypgen(1) but compiled to native code instead of bytecode. same energy, faster shoes. 👑

dyp2gram(1) is is a pearl script that produces a readable text documentation of your grammar from a grammar.dyp file. (and yes, "is is" — that's how the original says it, I don't make the rules, I just vibe with them 😭)

🔥 OPTIONS 🔥

the dypgen(1) command recognizes the following options, and there are a lot, so hydrate first:

  • --merge-warning prefix — activates merge warning: the generated parser will emit a warning on the standard output each time a merge happens. loud and proud about it.
  • --pv-obj — the type constructor obj is made as a sum of polymorphic variants instead of a sum of constructors. useful when the maximum number of constructors allowed is reached. (we hit the ceiling, we renovate 💅)
  • --pv-token — the type token is made as a sum of polymorphic variants instead of a sum of constructors. also useful when the maximum number of constructors allowed is reached.
  • --noemit-token-type — the type token is not emitted in the mli or ml files; it must be provided by the user instead. you're on your own, bestie, but like, in a cool way 🦋
  • --no-pp — the value pp is not stated in the mli file.
  • --no-obj-type — the type obj_type is not stated in the mli file.
  • --no-undef-nt — prevents the exception Undefined_nt from being raised. no drama, no raise 🙈
  • --ocamlc options — dypgen uses these options when calling ocamlc -i.
  • --command command — dypgen uses this command instead of calling ocamlc -i. your command, your rules.
  • --no-mli — dypgen does not generate the .mli file. gone, reduced to atoms.
  • --use-rule-order — dypgen uses rule order to decide which rule to reduce in case of reduce/reduce conflict. it is overriden by the variable dypgen_use_rule_order. ⚠️ yes, the variable wins, so don't come for me if your flag gets overruled.
  • --use-all-actions — the parser will execute all the user actions bound to a rule instead of just the first that does not raise Giveup. all of them. main character energy for every action. 👑
  • --cpp dypgen — calls the C preprocessor cpp on the input file before processing it.
  • --cpp-options options — dypgen calls the C preprocessor cpp with options "options" on the input file before processing it.
  • --version — gives the version of dypgen and exit.
  • -help — Display this list of options.
  • --help — Display this list of options.
lowkey note: -help and --help do the exact same thing. two icons, one job. 🫶

🌈 SEE ALSO 🌈

okay that's the whole thing, bestie — go forth and generate parsers 💖✨

signed off from the General Commands Manual, DYPGEN(1), no date on the tin, unversioned and unbothered — catch you in the man pages 🎀💜

📦 where this page comes from