API.md

Comment Parser API

---

• load
• parse
• Collator
  • Options
• Comment
  • Options
• Parser
  • Options
  • Events
• .stringify
  • rule
    • defaults
      • Options
    • #multi
      • Options
    • #single
      • Options
  • Tag
    • rule
    • unescape
    • pattern
    • optional
    • whitespace
    • parse
  • language
    • find
    • exists
    • load
      • Throws
    • actionscript
    • c
      • Options
    • coffeescript
    • conf
    • cpp
      • Options
    • css
    • erlang
    • go
    • groovy
    • html
    • ini
      • Options
    • jade
    • java
    • javascript
    • less
    • markdown
  • Languages
    • pandoc
    • php
    • pi
    • processing
    • properties
    • python
    • ruby
      • Options
    • sass
    • scala
    • shell
      • Options
    • sql
      • Options
    • stylus
      • Options
    • toml
    • typescript
    • vim
      • Options
    • xml
    • yaml

---

load

load(file[, opts][, cb])

Load and parse file contents.

When a callback function is given it is added as a listener for the error and end events on the source file stream.

Returns the parser stream.

• file String path.
• opts Object processing options.
• cb Function callback function.

parse

parse(buffer[, opts][, cb])

Parse a string or buffer.

When a callback function is given it is added as a listener for the error and finish events on the parser stream.

Returns the parser stream.

• buffer String|Buffer input data.
• opts Object processing options.
• cb Function callback function.

Collator

Collator([opts])

Collate comments and source content into a stream.

Allows for writing files that contains only content, only comments or both content and comments. By default this stream will pass through comments and content.

To disable content from the stream (comments only) use:

{content: false}

To disable comments from the stream (source content only) use:

{comment: false}

When the buffer option is set all output is buffered into the buffer property as a string, listen for the finish event before attempting to access the buffer contents.

• opts Object stream options.

Options

• content Boolean push content chunks to the stream.
• comment Boolean push comment chunks to the stream.
• buffer Boolean buffer output.
• stringify Boolean convert output to JSON strings.
• indent Number number of spaces to indent JSON.

Comment

Comment([opts])

Parse comments from an array of lines.

When a comment is parsed an object is pushed to the stream with an array of lines, the rule for the comment and the start and end line numbers.

When a content block is encountered a string is pushed for inline content (between comments on a single-line or trailing content), otherwise an array of lines is pushed.

• opts Object stream options.

Options

• rules Array|Function defines the comment rules.
• options Object to pass to the rules function.

Parser

Parser([opts])

Comment and tag parser, parses comment description and tags.

• opts Object stream options.

Options

• tag Object defines the tag patterns, see tag
• dotted Boolean parse dotted names in tags.

Events

• comment when a comment has been parsed.
• content when a content chunk is received.

.stringify

Parser.prototype.stringify(indent, comment)

Creates a stream that transforms to newline-delimited JSON, the created stream is piped from this parser.

Returns the stringify stream.

• indent Number the number of spaces to indent the JSON.
• comment Boolean only include comment output.

rule

A language rule is an object containing the open, close and strip functions.

The open and close functions are passed the current line and should return the exec match for the pattern.

The strip function is passed an array of lines for the entire comment and should remove comment meta characters from all lines.

defaults

defaults([opts])

Creates the default language rules for the C family of languages.

By default recognises continuous lines with // comments and terminated multi-line comments starting with ``.

To include /* comments as well set the greedy option:

{multi: {greedy: true}

Returns list of language rules.

• opts Object processing options.

Options

• multi Object multi-line rule configuration.
• single Object single-line rule configuration.

#multi

static multi([opts])

Creates a multi-line rule, when no options are given creates the default C family multi-line rule.

Returns multi-line language rule.

• opts Object processing options.

Options

• greedy Boolean include /* comments.
• start RegExp comment start pattern.
• end RegExp comment end pattern.
• lead RegExp remove leading meta characters that match.
• trail RegExp remove trailing meta characters that match.
• open Function override default open function.
• close Function override default close function.
• strip Function override default strip function.

#single

static single([opts])

Creates a single-line rule, when no options are given creates the default C family single-line rule.

Returns single-line language rule.

• opts Object processing options.

Options

• mark RegExp sub pattern.
• start RegExp comment start pattern.
• end RegExp comment end pattern.
• lead RegExp remove leading meta characters that match.
• trail RegExp remove trailing meta characters that match.
• open Function override default open function.
• close Function override default close function.
• strip Function override default strip function.

Tag

Defines the patterns and functions that perform the tag parsing.

Create a custom tag definition if you wanted to use an alternative syntax or prefer something other than @ as the tag identifier.

The generic syntax for tags is: @id {type[=value]} name description; everything but the tag id is considered optional.

Which when given: @property {String=mkdoc} [nickname] user will expand to a tag object such as:

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

See the tag parser.

rule

RegExp rule

Pattern that collects tag lines.

unescape

Object unescape

Pattern that unescapes tag sequences after parsing.

pattern

RegExp pattern

Pattern that collects tag component parts.

optional

RegExp optional

Pattern that determines optionality.

whitespace

RegExp whitespace

Pattern that determines how to strip leading whitespace from lines.

By default will match one or two spaces, depending upon your comment style you should adjust this so that whitespace is preserved as intended.

parse

parse(line, tag)

Parses the component parts of a tag definition.

This will add the id, type, name and description fields to the input tag argument.

• line String current line being parsed.
• tag Object target for parsed data.

language

Contains utilities for testing whether a language id is valid, loading language packs and finding language identifiers by file extension.

find

find(ext)

Find a language pack identifier by file extension.

File extensions must not include the leading period.

Returns language pack identifier if found.

• ext String file extension.

exists

exists(id)

Test whether a language exists by identifier.

Returns whether the language pack exists.

• id String language pack identifier.

load

load(id)

Load a language pack by identifier.

• id String language pack identifier.

Throws

• Error if the language pack does not exist.

actionscript

actionscript([opts])

Creates an array of language rules for actionscript files.

Recognises continuous lines with // comments and terminated multi-line comments starting with ``.

See the default settings.

Returns list of language rules.

• opts Object processing options.

c

c([opts])

Creates an array of language rules for C files.

Recognises terminated multi-line comments starting with /*.

See the default settings.

Returns list of language rules.

• opts Object processing options.

Options

• greedy Boolean=true disable to use `` comments only.

coffeescript

coffeescript([opts])

Creates an array of language rules for coffeescript files.

Recognises continuous blocks of lines beginning with # and multi-line comments delimited with ###.

Returns list of language rules.

• opts Object processing options.

conf

conf([opts])

Creates an array of language rules for conf files.

Recognises continuous blocks of lines beginning with #.

See the shell language.

Returns list of language rules.

• opts Object processing options.

cpp

cpp([opts])

Creates an array of language rules for C++ files.

Recognises continuous lines with // comments and terminated multi-line comments starting with ``.

See the default settings.

Returns list of language rules.

• opts Object processing options.

Options

• greedy Boolean include /* comments.

css

css([opts])

Creates an array of language rules for css files.

Recognises terminated multi-line comments starting with /*.

See the c language.

Returns list of language rules.

• opts Object processing options.

erlang

erlang([opts])

Creates an array of language rules for erlang files.

Recognises continuous blocks of lines beginning with %.

Returns list of language rules.

• opts Object processing options.

go

go([opts])

Creates an array of language rules for go files.

Recognises continuous lines with // comments and terminated multi-line comments starting with ``.

See the default settings.

Returns list of language rules.

• opts Object processing options.

groovy

groovy([opts])

Creates an array of language rules for groovy files.

Recognises continuous lines with // comments and terminated multi-line comments starting with ``.

See the default settings.

Returns list of language rules.

• opts Object processing options.

html

html([opts])

Creates an array of language rules for HTML files.

Recognises multi-line comments started with <!-- and terminated with -->.

Returns list of language rules.

• opts Object processing options.

ini

ini([opts])

Creates an array of language rules for ini files.

Recognises continuous blocks of lines beginning with ;.

Returns list of language rules.

• opts Object processing options.

Options

• mark RegExp sub pattern.
• trail RegExp pattern to strip trailing meta characters.

jade

jade([opts])

Creates an array of language rules for jade files.

Recognises continuous blocks starting with //- or //.

Returns list of language rules.

• opts Object processing options.

java

java([opts])

Creates an array of language rules for java files.

Recognises continuous lines with // comments and terminated multi-line comments starting with ``.

See the default settings.

Returns list of language rules.

• opts Object processing options.

javascript

javascript([opts])

Creates an array of language rules for javascript files.

Recognises continuous lines with // comments and terminated multi-line comments starting with ``.

See the default settings.

Returns list of language rules.

• opts Object processing options.

less

less([opts])

Creates an array of language rules for less files.

Recognises terminated multi-line comments starting with /* and continuous blocks of single-line comments beginning with //.

See the css language.

Returns list of language rules.

• opts Object processing options.

markdown

markdown([opts])

Creates an array of language rules for markdown files.

Recognises multi-line comments started with <!-- and terminated with -->.

See the html language.

Returns list of language rules.

• opts Object processing options.

Languages

Collection of language packs.

Default language pack used is the cpp language.

pandoc

pandoc([opts])

Creates an array of language rules for pandoc files.

Recognises multi-line comments starting with <!-- or <!--- and terminated with -->, extends the html language.

See the pandoc website.

Returns list of language rules.

• opts Object processing options.

php

php([opts])

Creates an array of language rules for php files.

Recognises continuous lines with // comments and terminated multi-line comments starting with ``.

See the default settings.

Returns list of language rules.

• opts Object processing options.

pi

pi([opts])

Creates an array of language rules for SGML/XML processing instructions.

Recognises multi-line comments started with <? and terminated with ?>.

Returns list of language rules.

• opts Object processing options.

processing

processing([opts])

Creates an array of language rules for processing files.

Recognises continuous lines with // comments and terminated multi-line comments starting with ``.

See the default settings.

Returns list of language rules.

• opts Object processing options.

properties

properties([opts])

Creates an array of language rules for Java properties files.

Recognises continuous blocks of lines beginning with #.

See the shell language.

Returns list of language rules.

• opts Object processing options.

python

python([opts])

Creates an array of language rules for python files.

Recognises continuous blocks of lines beginning with # and multi-line comments delimited with """.

Returns list of language rules.

• opts Object processing options.

ruby

ruby([opts])

Creates an array of language rules for ruby files.

Recognises continuous blocks of lines beginning with # and =begin, =end multi-line comments.

Returns list of language rules.

• opts Object processing options.

Options

• multi Object multi-line rule configuration.
• single Object single-line rule configuration.

sass

sass([opts])

Creates an array of language rules for sass files.

Recognises terminated multi-line comments starting with /* and continuous blocks of single-line comments beginning with //.

See the css language.

Returns list of language rules.

• opts Object processing options.

scala

scala([opts])

Creates an array of language rules for scala files.

Recognises continuous lines with // comments and terminated multi-line comments starting with ``.

See the default settings.

Returns list of language rules.

• opts Object processing options.

shell

shell([opts])

Creates an array of language rules for shell files.

Recognises continuous blocks of lines beginning with #.

Returns list of language rules.

• opts Object processing options.

Options

• mark RegExp sub pattern.
• trail RegExp pattern to strip trailing meta characters.

sql

sql([opts])

Creates an array of language rules for SQL statements.

Recognises terminated multi-line comments started with /* and continuous lines beginning with --.

If the mysql option is given continuous lines beginning with # are also recognised.

Returns list of language rules.

• opts Object processing options.

Options

• include Boolean mysql specific comment rule.

stylus

stylus([opts])

Creates an array of language rules for stylus files.

Recognises terminated multi-line comments starting with /* and buffered multi-line blocks starting with /*! as well as continuous blocks of single-line comments beginning with //.

See the css language.

Returns list of language rules.

• opts Object processing options.

Options

• single Object|Boolean=true single-line comment options.
• multi Object|Boolean=true multi-line comment options.
• buffer Object|Boolean=true buffer comment options.

toml

toml([opts])

Creates an array of language rules for TOML files.

Recognises continuous blocks of lines beginning with #.

See the shell language.

Returns list of language rules.

• opts Object processing options.

typescript

typescript([opts])

Creates an array of language rules for typescript files.

Recognises continuous lines with // comments and terminated multi-line comments starting with ``.

See the default settings.

Returns list of language rules.

• opts Object processing options.

vim

vim([opts])

Creates an array of language rules for vim files.

Recognises continuous blocks of lines beginning with ".

Returns list of language rules.

• opts Object processing options.

Options

• mark RegExp sub pattern.
• trail RegExp pattern to strip trailing meta characters.

xml

xml([opts])

Creates an array of language rules for XML files.

Recognises multi-line comments started with <!-- and terminated with -->.

See the html language.

Returns list of language rules.

• opts Object processing options.

yaml

yaml([opts])

Creates an array of language rules for YAML files.

Recognises continuous blocks of lines beginning with #.

See the shell language.

Returns list of language rules.

• opts Object processing options.

---

Created by mkdoc on January 3, 2017