Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/prantlf/nomnoml-cli

Generates images from nomnoml diagram sources in a NodeJS module or on the command line
https://github.com/prantlf/nomnoml-cli

diagram-sources diagrams generator nomnoml uml

Last synced: 27 days ago
JSON representation

Generates images from nomnoml diagram sources in a NodeJS module or on the command line

Awesome Lists containing this project

README

        

# nomnoml-cli

[![Latest version](https://img.shields.io/npm/v/nomnoml-cli)
![Dependency status](https://img.shields.io/librariesio/release/npm/nomnoml-cli)
](https://www.npmjs.com/package/nomnoml-cli)
[![codecov](https://codecov.io/gh/prantlf/nomnoml-cli/branch/master/graph/badge.svg)](https://codecov.io/gh/prantlf/nomnoml-cli)
[![Code Climate](https://codeclimate.com/github/prantlf/nomnoml-cli/badges/gpa.svg)](https://codeclimate.com/github/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
[NodeJS] modules

## Getting Started

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)

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

```text
$ nomnoml --help

Usage: nomnoml [option]

Options:

-h, --help output usage information
-V, --version output the version number
-i, --input file with nomnoml source to read from
-o, --output file for the image output to write to
-f, --format output format (png, jpg, svg, pdf)
-w, --width width of the canvas to draw on
-H, --height 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'
});
```

## Notes

Contents of other `.nomnoml` files can be imported to the input file using
the [`#import` directive](https://github.com/skanaar/nomnoml#directives).
You can use it for sharing style definitions or parts of diagrams among
multiple diagram sources.

```text
#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.

[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