mkast

Table of Contents

• Comment Parser
  • Install
  • Usage
  • Comments
    • Tags
    • Block
  • License

Comment Parser

.

Fast, streaming and configurable comment parser; currently supports 30+ languages.

Designed for polyglot programmers to:

• Combine comments from various files (HTML, CSS and Javascript for example).
• Parse comments from any language.
• Strip comments from any file.
• Separate comments into another file.
• Implement custom tag systems (annotations).
• Operate on processing instructions (see the pi language).
• Document JSON files, read comments then strip in build process.

See the i/o sample and the api docs.

Install

npm i mkast

Usage

Parse a string or buffer:

var mkast = require('mkast')
  , stream = mkast.parse('/**Compact comment*/');
stream.on('comment', function(comment) {
  console.dir(comment);
});

Load and parse file contents:

var mkast = require('mkast')
  , stream = mkast.load('index.js');
stream.on('comment', function(comment) {
  console.dir(comment);
});

Parse and write comment data to file as newline delimited JSON:

var mkast = require('mkast')
  , fs = require('fs')
  , stream = mkast.load('index.js').stringify();
stream.pipe(fs.createWriteStream('index-ast.json.log'));

Use a language pack:

var mkast = require('mkast')
  , stream = mkast.parse(
      '# @file spec.rb', {rules: require('mkast/lang/ruby')});
stream.on('comment', function(comment) {
  console.dir(comment);
});

Combine language pack rules:

var mkast = require('mkast')
  , stream = mkast.parse(
      '; ini style comment\n# shell style comment',
      {rules: [require('mkast/lang/ini'), require('mkast/lang/shell')]});
stream.on('comment', function(comment) {
  console.dir(comment);
});

For more detail see the api docs.

Comments

A comment consists of a multi-line description and optional tag annotations:

/**
 * Method description
 * that can span multiple lines.
 *
 * @name method
 */

// Method description
// that can span multiple lines.
//
// @name method

All the following comments resolve to the same description with the default settings:

/** Comment description */

/**
 * Comment description
 */

/*************************
 * Comment description   *
 ************************/

// Comment description //

//
// Comment description
//

Tags

Tags allow annotating a comment with meaningful information to consumers of the comment data.

The tag parser recognises tags beginning with an @ and is able to parse type, value (default), name, description and an optional flag.

Grammar for the default tag parser:

@id {type=value} [name] description

All fields but the tag id are considered optional, to set the optional flag enclose name in square brackets ([]).

When given @property {String=mkdoc} [nickname] user it expands to a tag object such as:

{
  id: 'property',
  type: 'String',
  value: 'mkdoc',
  name: 'nickname',
  description: 'user',
  optional: true
}

See the tag api docs to change the tag parsing.

Block

By default continuous single-line comments are gathered into a single comment object. The rule is that if the next line does not match whitespace followed by the start of a single-line comment then the block is terminated.

Note that inline comments also break the block:

// 
// Comment description
// 
var foo; // Separate inline comment

Will result in two comments, whilst:

// Comment description
// 
// More information.

Results in a single comment.

License

MIT.

Generated by mdp(1).