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.

1. Install pre-requisites of the node-canvas module depending on your operating system

2. 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

Copyright (c) 2015-2022 Ferdinand Prantl

Licensed under the MIT license.