README

logo

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.

Building is easy using Docker.

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

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.

Usage no npm install needed!