mkast - npm Package Compare versions

Comparing version 1.0.3 to 1.1.0

doc/readme/introduction.md

@@ -5,4 +5,2 @@ [![Build Status](https://travis-ci.org/mkdoc/mkast.svg?v=3)](https://travis-ci.org/mkdoc/mkast)
 
-Transforms commonmark AST documents to and from JSON for piping between streams.
-
-See the [api docs](/API.md).
+Transforms commonmark AST documents to and from JSON for piping between processes.

doc/readme/usage.md

 ## Usage
 
-Parse a string or buffer:
+Serialize commonmark AST to line-delimited JSON:
 
 ```javascript
-var mkast = require('mkast')
-  , stream = mkast.parse('/**Compact comment*/');
-stream.on('comment', function(comment) {
-  console.dir(comment);
-});
+var cmark = require('commonmark')
+  , parser = new cmark.Parser()
+  , mkast = require('mkast')
+  , ast = parser.parse('# Title\n<? @include file.md ?>');
+mkast.serialize(ast).pipe(process.stdout);
 ```
 
-Load and parse file contents:
-
-```javascript
-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:
-
-```javascript
-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:
-
-```javascript
-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:
-
-```javascript
-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](/API.md).
+For more information see the [api docs](#api).

index.js

@@ -1,13 +0,58 @@
-var Walk = require('./lib/walk')
-  , Serialize = require('./lib/serialize');
+var through = require('through3')
+  , LineStream = require('stream-lines')
+  , EachStream = through.transform(each)
+  , Walk = require('./lib/walk')
+  , Serialize = require('./lib/serialize')
+  , Deserialize = require('./lib/deserialize');
 
 /**
+ *  Iterate the lines.
+ *
+ *  @private
+ */
+function each(chunk, encoding, cb) {
+  var scope = this;
+  chunk.forEach(function(item) {
+    scope.push(item); 
+  })
+  cb();
+}
+
+/**
+ *  Deserialize line-delimited JSON to commonmark AST.
+ *
+ *  When a callback function is given it is added as a listener for 
+ *  the error and eof events on the deserializer stream.
+ *
+ *  @function deserialize
+ *  @param {Object} stream input stream.
+ *  @param {Function} [cb] callback function.
+ *
+ *  @returns the deserializer stream.
+ */
+function deserialize(stream, cb) {
+  var deserializer = new Deserialize();
+  stream
+    .pipe(new LineStream())
+    .pipe(new EachStream())
+    .pipe(deserializer);
+
+  if(cb) {
+    deserializer
+      .once('error', cb)
+      .once('eof', function(doc) {
+        cb(null, doc); 
+      });
+  }
+  return deserializer;
+}
+
+/**
  *  Serialize a commonmark AST to line-delimited JSON.
  *
  *  When a callback function is given it is added as a listener for 
- *  the error and finish events on the parser stream.
+ *  the error and finish events on the serializer stream.
  *
  *  @function serialize
  *  @param {Object} buffer input AST.
- *  @param {Object} [opts] processing options.
  *  @param {Function} [cb] callback function.
@@ -17,13 +62,6 @@ *
  */
-function serialize(buffer, opts, cb) {
-  if(typeof opts === 'function') {
-    cb = opts;
-    opts =  null;
-  }
+function serialize(buffer, cb) {
+  var ast = new Walk()
+    , serialize = new Serialize();
 
-  opts = opts || {};
-
-  var ast = new Walk(opts)
-    , serialize = new Serialize(opts);
-
   ast.pipe(serialize);
@@ -46,3 +84,4 @@
 module.exports = {
-  serialize: serialize
+  serialize: serialize,
+  deserialize: deserialize
 }

lib/deserialize.js

@@ -44,2 +44,8 @@ var through = require('through3')
 function transform(ast, encoding, cb) {
+
+  // empty lines
+  if(!ast) {
+    return cb(); 
+  }
+
   var res;
@@ -46,0 +52,0 @@

package.json

 {
   "name": "mkast",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Commonmark AST transformer",
@@ -24,2 +24,3 @@ "main": "index.js",
     "commonmark": "~0.24.0",
+    "stream-lines": "~1.1.7",
     "through3": "~1.1.5"
@@ -35,5 +36,4 @@ },
     "clean": "rm -rf coverage",
-    "docs": "npm run api && npm run example && npm run readme",
+    "docs": "npm run readme",
     "readme": "mdp --force -v",
-    "api": "mdp --force -v -i doc/api.json -o API.md",
     "lint": "jshint . && jscs .",
@@ -45,3 +45,3 @@ "test": "NODE_env=test mocha ${SPEC:-test/spec/**}",
   "mdp": {
-    "title": "Comment Parser",
+    "title": "AST Transformer",
     "pedantic": true,
@@ -62,2 +62,5 @@ "include": "doc/readme",
       {
+        "bin": "mkapi index.js --level=2 --title=API"
+      },
+      {
         "inc": [
@@ -64,0 +67,0 @@ "license.md"

README.md

 Table of Contents
 =================
 
-* [Comment Parser](#comment-parser)
+* [AST Transformer](#ast-transformer)
   * [Install](#install)
   * [Usage](#usage)
-  * [Comments](#comments)
-    * [Tags](#tags)
-    * [Block](#block)
+  * [API](#api)
+    * [deserialize](#deserialize)
+    * [serialize](#serialize)
   * [License](#license)
 
-Comment Parser
-==============
+AST Transformer
+===============
 
@@ -19,16 +19,4 @@ [<img src="https://travis-ci.org/mkdoc/mkast.svg?v=3" alt="Build Status">](https://travis-ci.org/mkdoc/mkast)
 
-Fast, streaming and configurable comment parser; currently supports 30+ languages.
+Transforms commonmark AST documents to and from JSON for piping between processes.
 
-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](https://github.com/mkdoc/mkast/blob/master/API.md#pi)).
-* Document JSON files, read comments then strip in build process.
-
-See the [i/o sample](https://github.com/mkdoc/mkast/blob/master/EXAMPLE.md) and the [api docs](https://github.com/mkdoc/mkast/blob/master/API.md).
-
 ## Install
@@ -42,150 +30,48 @@
 
-Parse a string or buffer:
+Serialize commonmark AST to line-delimited JSON:
 
 ```javascript
-var mkast = require('mkast')
-  , stream = mkast.parse('/**Compact comment*/');
-stream.on('comment', function(comment) {
-  console.dir(comment);
-});
+var cmark = require('commonmark')
+  , parser = new cmark.Parser()
+  , mkast = require('mkast')
+  , ast = parser.parse('# Title\n<? @include file.md ?>');
+mkast.serialize(ast).pipe(process.stdout);
 ```
 
-Load and parse file contents:
+For more information see the [api docs](#api).
 
-```javascript
-var mkast = require('mkast')
-  , stream = mkast.load('index.js');
-stream.on('comment', function(comment) {
-  console.dir(comment);
-});
-```
+## API
 
-Parse and write comment data to file as newline delimited JSON:
+### deserialize
 
 ```javascript
-var mkast = require('mkast')
-  , fs = require('fs')
-  , stream = mkast.load('index.js').stringify();
-stream.pipe(fs.createWriteStream('index-ast.json.log'));
+deserialize(stream[, cb])
 ```
 
-Use a language pack:
+Deserialize line-delimited JSON to commonmark AST.
 
-```javascript
-var mkast = require('mkast')
-  , stream = mkast.parse(
-      '# @file spec.rb', {rules: require('mkast/lang/ruby')});
-stream.on('comment', function(comment) {
-  console.dir(comment);
-});
-```
+When a callback function is given it is added as a listener for
+the error and eof events on the deserializer stream.
 
-Combine language pack rules:
+Returns the deserializer stream.
 
-```javascript
-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);
-});
-```
+* `stream` Object input stream.
+* `cb` Function callback function.
 
-For more detail see the [api docs](https://github.com/mkdoc/mkast/blob/master/API.md).
+### serialize
 
-## Comments
-
-A comment consists of a multi-line description and optional tag annotations:
-
 ```javascript
-/**
- * Method description
- * that can span multiple lines.
- *
- * @name method
- */
-
-// Method description
-// that can span multiple lines.
-//
-// @name method
+serialize(buffer[, cb])
 ```
 
-All the following comments resolve to the same description with the default settings:
+Serialize a commonmark AST to line-delimited JSON.
 
-```javascript
-/** Comment description */
+When a callback function is given it is added as a listener for
+the error and finish events on the serializer stream.
 
-/**
- * Comment description
- */
+Returns the serializer stream.
 
-/*************************
- * Comment description   *
- ************************/
+* `buffer` Object input AST.
+* `cb` Function callback function.
 
-// 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:
-
-```javascript
-{
-  id: 'property',
-  type: 'String',
-  value: 'mkdoc',
-  name: 'nickname',
-  description: 'user',
-  optional: true
-}
-```
-
-See the [tag api docs](https://github.com/mkdoc/mkast/blob/master/API.md#tag) 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:
-
-```javascript
-// 
-// Comment description
-// 
-var foo; // Separate inline comment
-```
-
-Will result in two comments, whilst:
-
-```javascript
-// Comment description
-// 
-// More information.
-```
-
-Results in a single comment.
-
 ## License
@@ -192,0 +78,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Lines of code

274

increased by23.42%

Worsened metrics

Total package byte prevSize

13655

decreased by-14.03%

Dependency count

3

increased by50%

Number of lines in readme file

84

decreased by-57.58%

Dependency changes

• + Addedstream-lines@~1.1.7

• + Addedstream-lines@1.1.8(transitive)