NOTE: This project is under active development. APIs subject to change.

trifle

A base formatter for Toga documentation. Provides a hook for walking abstract syntax trees and formatting nodes.

Install

$ npm install --save-dev trifle

API

new Trifle([options])

• options {Object}
  • name {String} - Name of plugin. (Default: 'trifle')
  • property {RegExp} - Name of property that contains the AST in Vinyl files. (Default: 'ast')
  • extension {RegExp} - Matches the file extension or extensions which are handled by this parser.
  • formatters {Array.<Function(Object,String):Boolean>} - A list of node formatters.

Creates a reusable formatter based on the given options.

#add(formatter) : this

• formatter {Function(Object,*):Boolean} - Formatter to add.

Adds a formatter to be used.

.add(function (node, value) {
    if ((/^(title|method|property)$/).test(node.key)) {
        node.update(node.key + ': ' + String(value).toLowerCase());
    }
})

#pipe(stream) : Stream.Readable

• stream {Writable} - Writable stream.

Trifle is a Transform Stream, working in object mode. ASTs stored in the .ast property of Vinyl objects will be walked and formatted.

Example

var toga = require('toga'),
    Trifle = require('trifle');

toga.src('./lib/**/*.js')
    // ... parser(s)
    .pipe(new Trifle()) // walks `.ast` and formats nodes
    // ... compiler(s)
    .pipe(toga.dest('./docs'));

Formatters

Formatters are functions that accept a traverse node context and a value. They will be executed in order for each node in the AST. You can keep subsequent formatters from executing by returning false.

formatters: [
    function (node, value) {
        if (node.key === 'description' && value != null) {
            node.update(String(value).toUpperCase());
            return false; // don't apply other formatters to this node
        }
    },
    function (node, value) {
        if ((/^(title|method|property)$/).test(node.key)) {
            node.update(node.key + ': ' + String(value).toLowerCase());
        }
    }
]

Test

$ npm test

Contribute

Standards for this project, including tests, code coverage, and semantics are enforced with a build tool. Pull requests must include passing tests with 100% code coverage and no linting errors.

---

MIT © Shannon Moeller