tunic

The stupid doc-block parser.

npm install tunic
10 downloads in the last week
27 downloads in the last month

Tunic

The stupid doc-block parser. Generates an abstract syntax tree based on a customizable regular-expression grammar. Defaults to C-style comment blocks, so it supports JavaScript, PHP, C++, and even CSS right out of the box.

Tags are parsed greedily. If it looks like a tag, it's a tag. What you do with them is completely up to you. Render something human-readable, perhaps?

NPM version Build Status Coverage Status Dependency Status

Install

With Node.js:

$ npm install tunic

Documentation Blocks

Documentation blocks follow the conventions of other standard tools such as JSDoc, Google Closure, YUIDoc, PHPDoc, JavaDoc, etc. The primary difference is that nothing is inferred from the code. If you want it documented, you must document it. This is why you can use tunic to parse inline documentation out of almost any language that supports multi-line comments.

AST

  • Root
    • type String - Always "Tunic".
    • blocks Array.<Code|Comment>
  • Code
    • type String - Always "Code".
    • body String
  • Comment
    • type String - Always "Comment".
    • description String
    • tags Array.<Tag>
  • Tag
    • tag String
    • type String
    • name String
    • description String

API

new Tunic([options])

  • options {Object} Optional grammar overrides.
    • options.extension RegExp - Matches the file extension or extensions which are handled by this parser.
    • options.blockIndents RegExp - Matches any leading characters that are valid as DocBlock indentation, such as whitespace or asterisks. Used for normalization.
    • options.blockParse RegExp - Matches the content of a DocBlock, where the first capturing group is the content without the start and end comment characters. Used for normalization.
    • options.blockSplit RegExp - Splits code and docblocks into alternating chunks.
    • options.tagParse RegExp - Matches the various parts of a tag where parts are captured in the following order:
      • 1: tag
      • 2: type
      • 3: name
      • 4: description
    • options.tagSplit RegExp - Matches characters used to split description and tags from each other.
    • options.namedTags Array.<String> - Which tags should be considered "named" tags. Non-named tags will have their name prepended to the description and set to undefined.
    • options.namespaceSplit RexExp - Splits namespaces.
    • options.namespaceTags Object.<String,RegExp> - Which tags should be used to generate navigation trees, and how to split them (eg. /\b\.\b/ for ., or /\b::\b/ for ::). The word boundaries (\b) are important as it allows splitters to be escaped.

Creates a reusable parser based on the given options. Defaults to parsing C-style comment blocks.

tunic([options]) : Tunic

Functional shorthand, if that's how you operate.

.parse(block) : AST

  • block {String} Block of code containing comments to parse.

Generates a sensible syntax tree format of doc-blocks and surrounding code.

Stream

Tunic is a Transform Stream, working in object mode, compatible with String, Buffer, and Vinyl. Strings and buffers are parsed and the resulting AST is emitted as data. Vinyl objects are augmented with the AST stored as the .tunic property.

Example

Default Options

var tunic = require('tunic');
var ast = tunic().parse('/** ... */');

Custom Options

var tunic = require('tunic');

var handlebars = tunic({
    blockIndents: /^[\t !]/gm,
    blockParse: /^[\t ]*\{\{!---(?!-)([\s\S]*?)\s*--\}\}/m,
    blockSplit: /(^[\t ]*\{\{!---(?!-)[\s\S]*?\s*--\}\})/m,
    namedTags: ['arg', 'argument', 'data', 'prop', 'property']
});

var ast = handlebars.parse('{{!--- ... --}}\n<div> ...');

Using new Operator

var Tunic = require('tunic');

var pod = new Tunic({
    blockParse: /^=doc\n([\s\S]*?)\n=cut$/m,
    blockSplit: /(^=doc\n[\s\S]*?\n=cut$)/m,
    namedTags: ['arg', 'argument', 'data', 'prop', 'property']
});

var ast = pod.parse('=doc\n ... \n=cut');

Streams

var gulp = require('gulp');
var tunic = require('tunic');

gulp.src('./lib/**/*.js')
    .pipe(tunic()); <- adds `.tunic` property to `file`

Test

$ npm test

Compatibility

Tested to work in the following environments:

  • Node (0.10)

Using:

License

MIT

npm loves you