Parse PlantUML with JavaScript or TypeScript
The aim of this project is to provide a feature-complete, well tested and maintainable Parsing Expression Grammar (PEG) for the PlantUML syntax. The parser is designed to be used as JavaScript library or from the Command Line.
Important: The parser is not yet feature-complete. But we focus on writing a robust implementation which can parse parts of diagrams without knowing the full syntax. This means that the parser probably still parses just about enough to get you started. If not, please contribute :heart:.
$ npm install --save plantuml-parser
PlantUML is not a formally defined language - something we would like to change.
This means we have to build this parser by reverse engineering from examples.
For this reason we keep a large set of PlantUML diagrams (in.plantuml
) and the corresponding
formatted output (parse[File]-out.<formatter>
) in test/fixtures/.
We even have diagrams which exposed bugs in the parser or diagrams which contain known
broken PlantUML syntax. Please help us expand that collection by contributing
your own diagrams. Every diagram counts :rocket:.
const { parse, parseFile, formatters } = require('plantuml-parser');
// Example PlantUML
const data = `
@startuml
class A
class B
A --|> B
@enduml
`;
// parse PlantUML
const result = parse(data);
// Format and print parse result
console.log(
formatters.default(result)
);
```javascript [ { "elements": [ { "name": "A", "title": "A", "isAbstract": false, "members": [], "extends_": [], "implements_": [], "generics": [], "stereotypes": [] }, { "name": "B", "title": "B", "isAbstract": false, "members": [], "extends_": [], "implements_": [], "generics": [], "stereotypes": [] }, { "left": "A", "right": "B", "leftType": "Unknown", "rightType": "Unknown", "leftArrowHead": "", "rightArrowHead": "|>", "leftArrowBody": "-", "rightArrowBody": "-", "leftCardinality": "", "rightCardinality": "", "label": "", "hidden": false } ] } ] ```
parse(data, options)
Parse PlantUML in data
. Returns the parse result.
data
: data to parseoptions
: supports all PEG.js parser options. Enable tracing with
options.verbose = true
. If tracing is enabled, options
is also forwarded to the
tracer object. See pegjs-backtrace options for a full list of supported tracer options.parseFile(pattern, options, cb)
Parse all PlantUML diagrams in the files matching pattern
. If given, the callback function cb
will make this function behave asynchronous.
pattern
: files to parse, supports globbing, e.g.: **/*.plantuml
.options
: supports all PEG.js parser options. Enable tracing with
options.verbose = true
. If tracing is enabled, options
is also forwarded to the
tracer object. See pegjs-backtrace options for a full list of supported tracer options.cb
: (optional) asynchronous callback. Called with: cb(err, result)
formatters
: A collection of built-in parse result formatters.For a detailed description of all the formatters see src/formatters.
# npm install --global plantuml-parser
Options:
--version Show version number [boolean]
--formatter, -f formatter to use
[choices: "default", "graph"] [default: "default"]
--input, -i input file(s) to read, supports globbing
[string] [default: stdin]
--output, -o output file to write [string] [default: stdout]
--color, -c colorful output [boolean] [default: false]
--verbose, -v 1x print verbose output, 2x print parser tracing
[count] [default: 0]
--help Show help [boolean]
$ npm test
This will run:
Every contribution counts. Please,
When contributing code, always also update the fixtures and run tests.
$ npm run fixtures
$ npm test
$ git commit
For more information see our contribution guidelines.