puml-parallel

README

PlantUML Interface Parallel

A Go tool for composing multiple PlantUML state diagrams in parallel with synchronization events, following CSP (Communicating Sequential Processes) semantics.

Overview

This tool takes multiple Composable State Diagram files and composes them into a single parallel state diagram with specified synchronization events. The composition follows CSP interface parallel semantics.

Installation

Download binaries from Releases.

Usage

$ csdfparallel [--sync event1;event2;...] <file1.puml> [file2.puml] ...

Options

• --sync: Semicolon-separated list of synchronization events for interface parallel

Examples

$ csdfparallel -sync 'insert;showAvailable;showPurchasable;choose;drop' ./examples/user.puml ./examples/vendormachine.puml

Input Format

The tool accepts PlantUML state diagram files in a specific Composable State Diagram format. See the SYNTAX.md and examples/ directory for sample input files.

Inputs may be either .puml text files or .png images generated by PlantUML (plantuml -tpng). For PNG inputs, the embedded source is read from the plantuml text chunk written by PlantUML. The same applies to csdfparse (stdin) and csdfevents (file arguments).

$ csdfparse < diagram.png
$ csdfparallel diagram1.png diagram2.puml
$ csdfrepl diagram.png

csdfparse writes one JSON object followed by a newline. Its keys use snake_case, and optional end edges are represented by null when absent. State variables are objects with a name and an optional type. Events are free-form strings.

$ csdfparse < examples/valid/skip.puml
{"states":{"s0":{"id":"s0","name":"SKIP","vars":[]}},"start_edge":{"dst":"s0","post":"true"},"edges":[],"end_edge":{"src":"s0","guard":"true"}}

Interactive exploration

csdfrepl interactively explores one CSDF file:

$ csdfrepl examples/valid/vending_machine.puml

For each state, enter its variable values as a JSON array in declaration order. The initial implementation records the values but does not evaluate guards or postconditions. JSON null is not accepted.

Commands use zero-based indexes:

• l lists the current state and outgoing transitions.
• t displays the current visible trace. The internal event tau is hidden.
• h displays the exploration history.
• s INDEX selects an outgoing transition.
• j INDEX jumps to a history entry.
• ? or help displays command help.

See CSDFREPL.puml for the behavioral specification.

Project Structure

• core/ - Core parsing and composition logic
• examples/ - Sample PlantUML files
• docs/ - Documentation including requirements and specifications
• tools/ - Additional parsing tools

Limitations

The interface parallel tool has the following limitations:

• Start edge requirement: State diagrams without a start edge ([*] --> state) cannot be composed in parallel. Each diagram must have exactly one start edge to define the initial state for composition.

• End edge restriction: State diagrams containing end edges (state --> [*]) are not currently supported for interface parallel. While technically possible, the semantics of interface parallel with terminating processes would be complex to define and implement, so this feature is not yet supported.

These limitations are implementation choices made to keep the interface parallel semantics manageable in the current version.

Documentation

• Requirements - Project requirements (Japanese)
• Specification - Technical specification (Japanese)
• Syntax - Syntax documentation
• Glossary - Term definitions

License

MIT License