drafter.js

Snowcrash parser harness

drafter.js is a pure JavaScript version of the drafter library. It
is built from the C++ sources
using emscripten. It’s
API compatible
with Protagonist, the
Drafter Node binding.

Installation

drafter.js can be installed from NPM, or it can be downloaded from the releases
page.

NOTE: If you’re using Node, we recommend that you use the Drafter
NPM package instead of drafter.js
directly. Drafter NPM will attempt to install the pure C++ parser and fallback
to using drafter.js.

$ npm install drafter.js

Usage

Node

If you’ve installed drafter.js via NPM and using drafter.js in Node, you can
require it via:

var drafter = require('drafter.js')

Node versions supported: >=4

It works on 0.10 or 0.12 too but without any guarantees and expect it to be
significantly slower.

Web Browser

If instead, you are using drafter.js in a Browser. You can include it via the
HTML script tag.

<script src="./drafter.js"></script>
<script src="./drafter.js.mem"></script>

API

Once you’ve included drafter.js, you can parse an API Blueprint:

var res = drafter.parse('# API Blueprint...', {generateSourceMap: true}, function (err, res) {
    if (err) {
        console.log(err)
    }
    console.log(res);
});

Supported options:

• generateSourceMap: Set to export sourcemap information.
• json: Set to false to disable parsing of the JSON data. You will
  instead get a JSON string as the result.
• requireBlueprintName: Set to generate an error if the blueprint is
  missing a title.
• generateMessageBody - Enable generation of messageBody from MSON (default: true)
• generateMessageBodySchema - Enable generation of messageBodySchema from MSON (default: true)

Or if you want just to validate it and are interested only in parsing
errors and warnings:

var res = drafter.validate('# API Blueprint...', {requireBlueprintname: true}, function (err, res) {
    if (err) {
        console.log(err)
    }
    if (res) {
        console.log("Document has semantic issues!");
        console.log(res);
    } else {
        console.log("Document is valid with no warnings.");
    }
});

Supported options:

• json: Set to false to disable parsing of the JSON data. You will
  instead get a JSON string as the result.
• requireBlueprintName: Set to generate an error if the blueprint is
  missing a title.

Note

These are not a real async API calls - their presence is merely for API compatibility
with protagonist

Synchronous API

Both functions have their synchronous counterpart which instead of callback return the result and in case of error throw exception.

• parseSync(source, options)
• validateSync(source, options)

Build drafter.js

Unfortunately building drafter.js works only on a *nix environment at the
moment.

1. Building is easy using Docker.

2. Build

    $ ./scripts/wrap.js
    $ docker pull "apiaryio/emcc:1.37"
    $ docker run -v $(pwd):/src -t apiaryio/emcc:1.37 emcc/emcbuild.sh

   or with npm

    $ npm run build

3. Check out the ./scripts/test.js and ./scripts/test.html files for
   example usage. You can also use npm install and then npm test to run the
   tests.

The resulting stand-alone library drafter.js is in the ./lib directory.
Don’t forget to serve the drafter.js.mem file as it is required by
drafter.js. There is also a single-file version in drafter.nomem.js that
can be used, but it may take longer to load in a web browser
environment. It is the default for node.js enviroment.

To get a debug version or version enabled to be used with emrun run
the emcbuild.sh script it with -d or -e respectively.

Squeeze the size

If you want to squeeze the size to a minimum install
uglify-js and try running
uglifyjs lib/drafter.js -o drafter.js -c;, this will use
uglify-js with compression, beware that this might cause some
errors, if you encounter them try drafter.js without it to verify
that it is caused by uglify-js and report it please.

License

MIT License. See the LICENSE file.