https://github.com/metadevpro/ts-pegjs
Plugin for pegjs to generate TypeScript parsers.
https://github.com/metadevpro/ts-pegjs
parser-generator peg pegjs pegjs-plugin typescript
Last synced: 8 days ago
JSON representation
Plugin for pegjs to generate TypeScript parsers.
- Host: GitHub
- URL: https://github.com/metadevpro/ts-pegjs
- Owner: metadevpro
- License: mit
- Created: 2017-07-09T17:32:27.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2025-01-22T06:35:49.000Z (4 months ago)
- Last Synced: 2025-05-08T00:13:44.460Z (15 days ago)
- Topics: parser-generator, peg, pegjs, pegjs-plugin, typescript
- Language: TypeScript
- Size: 466 KB
- Stars: 159
- Watchers: 3
- Forks: 38
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: Changelog.md
- License: LICENSE
Awesome Lists containing this project
README
# TS PEG.js
TS PEG.js is a TS code generation plugin for [peggy](https://www.npmjs.com/package/peggy).
[](https://travis-ci.org/metadevpro/ts-pegjs)
[](https://snyk.io/test/github/metadevpro/ts-pegjs)
[](http://badge.fury.io/js/ts-pegjs)
[](https://nodei.co/npm/ts-pegjs/)
## Requirements
- [peggy](https://www.npmjs.com/package/peggy) (previous versions use: [pegjs](https://pegjs.org))
## Installation
### Node.js
Installs ts-pegjs + peggy
$ npm install ts-pegjs
## Usage
### Generating a Parser from JS code
In Node.js, require both the peggy parser generator and the ts-pegjs plugin:
```typescript
var peggy = require('peggy');
var tspegjs = require('ts-pegjs');
```
To generate a TS parser, pass to `pegjs.generate` ts-pegjs plugin and your grammar:
```typescript
var parser = pegjs.generate("start = ('a' / 'b')+", {
output: 'source',
format: 'commonjs',
plugins: [tspegjs],
tspegjs: {
customHeader: "// import lib\nimport { Lib } from 'mylib';"
}
});
```
The method will return source code of generated parser as a string.
Supported options of `pegjs.generate`:
- `cache` — if `true`, makes the parser cache results, avoiding exponential
parsing time in pathological cases but making the parser slower (default:
`false`). This is strongly recommended for big grammars
(like javascript.pegjs or css.pegjs in example folder)
- `allowedStartRules` — rules the parser will be allowed to start parsing from
(default: the first rule in the grammar)
### Plugin options
**Note:** Options in CLI mode are written in POSIX (long names as kebab-case) convention e.g. `--custom-header` but with camelcase on JavaScript e.g. `customHeader`.
- `customHeader` — A string or an array of strings which are a valid TS code to be injected on the header of the output file. E.g. provides a convenient place for adding library imports.
- `customHeaderFile` — A header file to include.
- `errorName` — The name of the exported internal error class to override. The default value from version 3.0.0 is `PeggySyntaxError`. Previous one was `SyntaxError`.
- `returnTypes` — An object containing rule names as keys and a valid TS return type as string.
- `skipTypeComputation` — Boolean. If `true`, `ts-pegjs` will not try to use TS to infer types based on your grammar rules.
- `onlyGenerateGrammarTypes` — Boolean. If `true`, only types for your grammar rules (and no parser) will be generated. Cannot be used with `skipTypeComputation`.
- `doNotCamelCaseTypes` — Boolean. By default type names for grammar rules are converted to CamelCase. If `true`, this conversion is not done and type names will match the casing of your grammar rules.
### Generating a Parser from CLI
Sample usage:
```
peggy --plugin ./src/tspegjs -o examples/arithmetics.ts --cache examples/arithmetics.pegjs
```
(Note `./src/tspegjs` is the path to `tspegjs.ts` in the project. If you installed ts-pegjs using npm, it should probably be `./node_modules/ts-pegjs/src/tspegjs`.)
It will generarate the parser in the TS flavour.
If you need to pass specific plugin options you can use the option `--extra-options-file` provided by pegjs and pass it a filename (e.g. pegconfig.json) containing specific options like the following JSON sample:
```
peggy --plugin ./src/tspegjs --extra-options-file pegconfig.json -o examples/arithmetics.ts --cache examples/arithmetics.pegjs
```
```json
{
"tspegjs": {
"customHeader": "// import lib\nimport { Lib } from 'mylib';"
},
"returnTypes": {
"Integer": "number",
"Expression": "number",
}
}
```
> For rules not listed in `returnTypes` object `any` type is declared by default.
> Make sure to pass any additional CLI options, like `--extra-options-file` before the parameter `-o` as these will otherwise be treated as arguments to that one.
## Using the Parser
1. Save parser generated by `pegjs.generate` to a file or use the one generated from the CLI tool.
2. In client TS code:
```typescript
import { PeggySyntaxError, parse } from './arithmetics';
try {
const sampleOutput = parse('my sample...');
} catch (ex: PeggySyntaxError) {
// Handle parsing error
// [...]
}
```
## Changelog
[Changelog](./Changelog.md).
## Acknowledgments
Thanks to:
- [David Majda](https://github.com/dmajda) for creating pegjs
- [Elantcev Mikhail](https://github.com/Nordth) for providing the pegjs PHP plugin, inspiration on this one.
## License
[The MIT License (MIT)](http://opensource.org/licenses/MIT)
---
(c) 2017-2023, [Pedro J. Molina](https://github.com/pjmolina) at [metadev.pro](https://metadev.pro)