nomnoml-cli

Generates images from nomnoml diagram sources
on the command line and provides a library for a programmatic usage from
NodeJS modules

Getting Started

Make sure that you have NodeJS >= 12 installed.

Install pre-requisites
of the node-canvas module depending
on your operating system
Install the command-line tool and generate a testing image:

npm install -g nomnoml-cli
echo '[nomnoml]is->[awesome]' | nomnoml > awesome.png

Read the documentation about the nomnoml source format

Command-Line Usage

The nomnoml script generates a png, jpg, svg or pdf image from the nomnoml source text.
Both file names and standard input and output are supported as parameters.
If generating the image fails, exit code 1 is returned to the caller.

$ nomnoml --help
  Usage: nomnoml [option]
  Options:
    -h, --help             output usage information
    -V, --version          output the version number
    -i, --input <path>     file with nomnoml source to read from
    -o, --output <path>    file for the image output to write to
    -f, --format <format>  output format (png, jpg, svg, pdf)
    -w, --width <pixels>   width of the canvas to draw on
    -H, --height <pixels>  height of the canvas to draw on
  The default output format is png. The default canvas size is 640x480 pixels.
  If the input file is omitted, the source is read from the standard input.
  If the output file is omitted, the image is written to the standard output.
  Examples:
    $ echo '[nomnoml]is->[awesome]' | nomnoml > awesome.png
    $ nomnoml -i source.nomnoml -f svg -o target.svg

Programmatic Usage

The main module exports a function which generates the image:

const generateDiagram = require('nomnoml-cli');
const diagram = await generateDiagram(...);

The function returns a Promise to wait for a success or a failure.

The function expects a nomnoml source text as a string or an options
object with the following supported properties:

input: source to read the nomnoml text from; either a Stream or a
string with the actual nomnoml text
inputFile: source file path to read the nomnoml source from
output: target to write the image to; either a Stream or a string
with the file path (undefined by default)
resultType: type of the object to resolve the promise with if the
output parameter is not provided (‘buffer’ or ‘stream’; the former
is default)
format: output image format (‘png’, ‘jpg’, ‘svg’ or ‘pdf’; the first
is default)
width: canvas width in pixels (640 by default)
height: canvas height in pixels (480 by default)

Either input or inputFile has to be provided, otherwise the function
fails. If output is not provided, the function resolves the promise
with a Buffer containing the image. If output is provided, the
function returns a promise resolved when the output has been written.

Code Samples

const generateDiagram = require('nomnoml-cli');
// Get Buffer with the image
const buffer = await generateDiagram('[nomnoml]is->[awesome]');
// Convert the standard input to standard output
await generateDiagram({
  input: process.stdin,
  output: process.stdout
});
// Create a PNG file from a nomnoml source file
await generateDiagram({
  inputFile: 'source.nomnoml',
  output: 'target.png'
});

Notes

Contents of other .nomnoml files can be imported to the input file using
the #import directive.
You can use it for sharing style definitions or parts of diagrams among
multiple diagram sources.

#import: /usr/local/share/nomnoml/style.nomnoml
#import: shared/style.nomnoml
#import: ./sub-diagram.nomnoml

If the imported file path is relative and starts with ./ or ../, it will
be appended to the path of the “parent” file, which the specified file is
being imported to. Otherwise the relative path will be appended to the
current (executing) directory.

File import directives are processed recursively. However, a single file can
be imported only once. If imported once more, scond and other occurrences
will be replaced by an empty string.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding
style. Add unit tests for any new or changed functionality. Lint and test
your code using Grunt.

License

Licensed under the MIT license.