nomnoml-cli
Version:
Generates images from nomnoml diagram sources on the command line
153 lines (112 loc) • 5.48 kB
Markdown
[
](https://www.npmjs.com/package/nomnoml-cli)
[](https://codecov.io/gh/prantlf/nomnoml-cli)
[](https://codeclimate.com/github/prantlf/nomnoml-cli)
[](https://www.codacy.com/public/prantlf/nomnoml-cli)
Generates images from [nomnoml](http://www.nomnoml.com/) diagram sources
on the command line and provides a library for a programmatic usage from
[] modules
Make sure that you have [NodeJS] >= 12 installed.
1. Install [pre-requisites](https://github.com/Automattic/node-canvas/wiki/_pages)
of the [node-canvas](https://github.com/Automattic/node-canvas) module depending
on your operating system
2. Install the command-line tool and generate a testing image:
```bash
npm install -g nomnoml-cli
echo '[nomnoml]is->[awesome]' | nomnoml > awesome.png
```
Read the documentation about the [nomnoml source format](https://github.com/skanaar/nomnoml#example)
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.
```text
$ 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:
```javascript
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
```javascript
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'
});
```
Contents of other `.nomnoml` files can be imported to the input file using
the [`
You can use it for sharing style definitions or parts of diagrams among
multiple diagram sources.
```text
```
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.
[Buffer]: https://nodejs.org/api/buffer.html
[NodeJS]: http://nodejs.org/
[Stream]: https://nodejs.org/api/stream.html
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise