plantuml-parser

Parse PlantUML Syntax in JavaScript

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 implementing the full syntax. This means that the parser probably still parses just about enough to get you started. If not, please contribute ❤️.

#PlantUMLParser

Installation

$ npm install --save plantuml-parser

Examples / Fixtures

We keep a set of PlantUML scripts (in.plantuml) and the corresponding formatted output (parse[File]-out.<formatter>) in test/fixtures/.

Usage

const { parse, parseFile, formatters } = require('plantuml-parser');

// Example PlantUML
const data = `
@startuml
  class A
  class B
  A --|> B
@enduml
`;

// parse PlantUML
const ast = parse(data);

// Format and print AST
console.log(
  formatters.default(ast)
);

[
  {
    "elements": [
      {
        "name": "A",
        "title": "A",
        "isAbstract": false,
        "members": []
      },
      {
        "name": "B",
        "title": "B",
        "isAbstract": false,
        "members": []
      },
      {
        "left": "A",
        "right": "B",
        "leftType": "Unknown",
        "rightType": "Unknown",
        "leftArrowHead": "",
        "rightArrowHead": "|>",
        "leftArrowBody": "-",
        "rightArrowBody": "-",
        "leftCardinality": "",
        "rightCardinality": "",
        "label": ""
      }
    ]
  }
]

parse(data, options)

Parse PlantUML in data. Returns abstract syntax tree.

• data: data to parse
• options: see PEG.js parser options and pegjs-backtrace 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: see PEG.js parser options and pegjs-backtrace options
• cb: (optional) asynchronous callback. Called with: cb(err, ast)

formatters: A collection of built-in AST formatters.

For a detailed description of all the formatters see src/formatters.

Command Line Interface

Installation

# npm install --global plantuml-parser

Usage

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]

Features

• Diagram Types:
  • Class
  • Component
  • Use Case
  • Sequence
  • Activity
  • State
  • Object
  • Deployment
  • Timing
• Formatters:
  • JSON
  • Graph
• Testing, CI/CD:
  • Fixtures for all formatters
  • Code coverage
  • Code formatting
  • Code linting
  • Error case testing
  • Dependency audit

Test

$ npm test

This will run:

• unit tests
• code coverage
• eslint

Contribute ❤️

Every contribution counts. Please,

• ... submit unparsable diagrams via new issue.
• ... extend the parser by forking and creating a Pull Request

When contributing code, always also update the fixtures and run tests.

$ npm run fixtures
$ npm test
$ git commit

Related

• PlantUML code generator: Provides a command line utility to generate code in various languages given a PlantUML class diagram.

License

• Apache 2.0