You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

70 lines
3.5 KiB

  1. ## Command Line
  2. The CLI `pegjs` can be used from terminals to generate a parser from the given grammar, without accessing the PEG.js API.
  3. It's usage signature is: `pegjs [options] [<input_file>] [--]`
  4. ### Configuration file
  5. If you provide a configuration file (via `-c` or `--config`) then you can use all the options used by the [PEG.js API](./javascript-api.md), as well as:
  6. * `input` — The grammar used as the input file
  7. * `output` — Output's generated parser to the provided destination
  8. > 1. Will throw if neither are strings, or the input has already been provided
  9. > 2. the `output` option for the compiler is not usable from the config
  10. ### Input File
  11. Only one grammar is accepted as the given input file, otherwise the CLI aborts with an error.
  12. ### Options and their values
  13. Usually CLI options are passed like so
  14. pegjs grammar.pegjs -o parser.js -c pegjs.config.js
  15. With the PEG.js CLI, you can also use the assignment operator, so the above can be used like so:
  16. pegjs grammar.pegjs -o=parser.js -c=pegjs.config.js
  17. ### Command Line Options
  18. When using the CLI `pegjs`, you can pass the following options:
  19. * `-a`, `--allowed-start-rules` — comma-separated list of rules the parser will be allowed to start parsing from (default: the first rule in the grammar)
  20. * `--cache` — makes the parser cache results, avoiding exponential parsing time in pathological cases but making the parser slower
  21. * `-c`, `--config` — file with additional options (in JSON or JavaScript) to pass to `peg.generate`
  22. * `-d`, `--dependency` — makes the parser require a specified dependency (can be specified multiple times)
  23. * `-e`, `--export-var` — name of a global variable into which the parser object is assigned to when no module loader is detected
  24. * `--extra-options` — additional options (in JSON format) to pass to `peg.generate`
  25. * `--extra-options-file` — same as `--config` (was the only cli option for config files before PEG.js v0.11)
  26. * `-f`, `--format` — format of the generated parser: `amd`, `bare`, `commonjs`, `es`, `globals`, `umd` (default: `commonjs`)
  27. * `--no-cache` — opposite of `--cache` (default behavior)
  28. * `--no-trace` — opposite of `--trace` (default behavior)
  29. * `-O`, `--optimize` — selects between optimizing the generated parser for parsing speed (`speed`) or code size (`size`) (default: `speed`)
  30. * `-o`, `--output` — Output file
  31. * `-p`, `--plugin` — makes PEG.js use a specified plugin (can be specified multiple times)
  32. * `--trace` — makes the parser trace its progress
  33. The following options only print to the console before exiting:
  34. * `-h`, `--help` — Print help and exit
  35. * `-v`, `--version` — Print version information and exit
  36. ### Repeatable and non-repeatable options
  37. Repeatable options on the cli are handled by pushing the values into a list (which is used as the value for the option):
  38. - `pegjs -a start,Rule -a Rule,Template` will set `options.allowedStartRules` to `[ "start", "Rule", "Template" ]`
  39. Unless it's a repeatable option, any option on the right side will take priority over either the same option mentioned before or it's counter part:
  40. - `pegjs -f es -f bare` will set `options.format` to `bare`
  41. - `pegjs --no-trace --trace` will set `options.trace` to `true`
  42. ### Extra options
  43. Need to pass a custom set of arguments to your plugin? The PEG.js CLI will pass all arguments after `--` to `options["--"]`, which is passed to all plugins.
  44. > NOTE: You will need to use your own argument parser, as the PEG.js CLI does not process these arguments.