Create sequence diagrams with a domain-specific language. ```text Usage: quence [options] Arguments: FILE file names to process, "-" for stdin Options: -o, --output output type (choices: "js", "json", "pdf", "svg", default: "pdf") -O, --out output file name, "-" for stdout. Not valid with more than one input file. -p, --property diagram property in the form key=value. May be specified multiple times. (default: []) -v, --verbose verbose logging -V, --version output the version number -h, --help display help for command ``` Small example: ``` set text_color purple Alice -> Bob: Hello #comment Bob -> Alice: World Bob -> Bob: ! ``` Try it online ============= There is a client [editor](https://hildjj.github.io/quence/). Installation ============ Use [npm](http://npmjs.org/): ``` npm install -g quence ``` Syntax ====== The following sections describe syntax that can be placed in a `.wsd` file for input to the quence processor. Comments -------- `# [comment]` Place a comment on a line by itself, or at the end of any line. If you need a `#` in a string, enclose the string in double quotes (`"`). Participants ------------ `participant "[description]" as [name]` Create a new participant in the order that the `participant` directive appears in the input file. The `description` is output, and the `name` is what is used for reference in later directives. Example: ``` participant Alice participant "Bob Cat" as bob ``` Arrows ------ Arrows are draw between participants with open ends, closed ends, solid or dashed lines, and may be bi-directional. ### ends `<` or `>` closed arrow end `<<` or `>>` open arrow end You can also use the `#` indicator to show that a packet is lost. This will create an "X" arrowhead and only draw the line halfway across. ### lines `-` solid line `--` dashed line Example: ``` # A "normal" message from A to B A -> B # An "exciting" message between A and B # No, this doesn't have any defined meaning, as far as I know A<-->>B ``` Messages -------- The minimum message looks like `participant arrow participant`, but a full description is: ``` [label:] participant[@time] arrow participant[@time] [:title] [[message properties]] ``` Draw a line with [arrows](#arrows) between two [participants](#participants). A participant that has not been previously mentioned will be automatically created. Note that a message may be of the form `B -> B`, which produces a self message. ### Title A message can have a title that will be drawn over the message line. The title will be justified toward the start of the message, or in the middle for bi-directional messages. Example: ``` A->B: The title ``` ### Timestamps Each message start time can have a timestamp associated with it by prefixing the message with `label:`. Subsequent messages can be declared to start or end at a given label by suffixing the participant name with `@time`, where `time` is the label from a previous message. This will usually result in a diagonal line. Example: ``` early: A-->>B late: B-->>A A@early->B@late ``` ## Notes You can put a note on an endpoint using `note`, as in: ``` note A: This is a note ``` ## Blocks You can create a dotted block boundary around a section using the `block`, `loop`, and `opt` commands, as in: ``` block Do a thing A->B: Some messages end loop Many times A->B: Some messages end opt Might happen A->B: Some messages end ``` The difference between these commands is that `loop` and `opt` also produce a shaded tab with the words "loop" and "opt" respectively, whereas `block` just labels the block but with no shaded tab. ### Message properties Message properties modify the message, and are of the form `name [= value]`, with multiple properties separated by a comma (`,`). The following message properties may be set: * `duration`: The number of time slices that this message takes up. If this is not `1`, a diagonal line will result. [Default: `1`] * `advance`: The number of time slices to advance the clock after this message. This is useful after a flurry of crossing diagonal lines. [Default: `1`] Example: ``` A->B [duration=2, advance=2] B->A [duration=2] ``` ## Diagram Properties `set [property] [value]` set a property governing the production of the diagram to the given value. If the value is omitted, it defaults to `true`. Colors can be [named colors](https://www.w3.org/TR/css-color-4/#named-colors) or specified in hex, surrounded by quotes, like `'#f0f8ff'`. You can also set an option with the `-p` a command line flag, as in: `-p property[=value]` ### Diagram Property Defaults The following options may be set (followed by their defaults): * `arrow_color`: 'black' * `arrow_height`: 10 * `arrow_width`: 15 * `auto_number`: false * `background`: 'white' * `block_tab_fill`: 'gray' * `block_stroke`: 'gray' * `column_width`: 150 * `font`: 'Helvetica' * `line_color`: 'black' * `line_width`: 1 * `rung_color`: 'black' * `rung_width`: 1 * `text_color`: 'black' * `text_size`: 13 * `time_height`: 20 Programmatic Interface ====================== ```javascript import {draw} from 'quence' import fs from 'fs' const out = fs.createWriteStream('output.pdf') draw("A->B", "pdf", out); // Note that the draw function returns when processing completes, not when the // stream is finished being written. Wait on the stream's `finish` event // if you need that. ``` Supported Output Types ====================== * PDF * SVG * JSON Quence was formerly known as "arrow", until I was asked very nicely to let another project use that name. [![Tests](https://github.com/hildjj/quence/actions/workflows/node.js.yml/badge.svg)](https://github.com/hildjj/quence/actions/workflows/node.js.yml) [![codecov](https://codecov.io/gh/hildjj/quence/graph/badge.svg?token=H0cmzICYg2)](https://codecov.io/gh/hildjj/quence)