comment-parser 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,3 +1,6 @@
+# v0.3.2
+- fix RegExp for `description` extraction to allow $ char
+
 # v0.3.1
 - use `readable-stream` fro Node 0.8 comatibility
 - allow to pass optional parameters to `parse.file(path [,opts], done)`  
@@ -39,4 +42,4 @@
 
 # v0.1.0
 
-Initial implementation
+Initial implementation

package/README.md

@@ -74,7 +74,7 @@ Also you can parse entire file with `parse.file('path/to/file', callback)` or ac
 
 
 In case you need to parse tags in different way you can pass `opts.parsers = [parser1, ..., parserN]`, where each parser is `function name(str:String, data:Object):{source:String, data:Object}`.
-	
+
 Each parser function takes string left after previous parsers applied and data produced by them. And returns `null` or `{source: '', data:{}}` where `source` is consumed substring and `data` is a payload with tag node fields.
 
 Tag node data is build by merging result bits from all parsers. Here is some example that is not doing actual parsing but is demonstrating the flow:
@@ -86,23 +86,23 @@ Tag node data is build by merging result bits from all parsers. Here is some exa
  */
 parse(source, {parsers: [
 	// takes entire string
-	function parse_tag(str, data) { 
-		return {source: ' @tag', data: {tag: 'tag'}}; 
-	}, 
+	function parse_tag(str, data) {
+		return {source: ' @tag', data: {tag: 'tag'}};
+	},
 	// parser throwing exception
 	function check_tag(str, data) {
-		if (allowed_tags.indexOf(data.tag) === -1) { 
+		if (allowed_tags.indexOf(data.tag) === -1) {
 			throw new Error('Unrecognized tag "' + data.tag + '"');
 		}			
 	},
 	// takes the rest of the string after ' @tag''
-	function parse_name1(str, data) { 
-		return {source: ' name', data: {name: 'name1'}}; 
+	function parse_name1(str, data) {
+		return {source: ' name', data: {name: 'name1'}};
 	},
 	// alternative name parser
-	function parse_name2(str, data) { 
-		return {source: ' name', data: {name: 'name2'}}; 
-	}	
+	function parse_name2(str, data) {
+		return {source: ' name', data: {name: 'name2'}};
+	}
 ]});
 ```
 
@@ -135,9 +135,10 @@ This would produce following:
 ## Contributors
 
 
-- [Sergii Iavorskyi](https://github.com/yavorskiy)
 - [Alexej Yaroshevich](https://github.com/zxqfox)
+- [Evgeny Reznichenko](https://github.com/zxcabs)
 - [Jordan Harband](https://github.com/ljharb)
+- [Sergii Iavorskyi](https://github.com/yavorskiy)
 
 
 Happy coding :)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-parser",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Generic JSDoc-like comment parser. ",
   "main": "index.js",
   "directories": {
@@ -18,7 +18,7 @@
   },
   "scripts": {
     "test": "jshint --reporter node_modules/jshint-stylish/stylish.js index.js && mocha tests/*",
-    "watch": "nodemon -q -w index.js -w tests/ -x npm test"
+    "watch": "nodemon -q -w index.js -w parser.js -w tests/ -x npm test"
   },
   "repository": {
     "type": "git",

package/parser.js

@@ -1,6 +1,6 @@
 
 var RE_COMMENT_START = /^\s*\/\*\*\s*$/m;
-var RE_COMMENT_LINE  = /^\s*\*(?:\s|$)/m;
+var RE_COMMENT_LINE  = /^\s*\*(?:\s(\s*)|$)/m;
 var RE_COMMENT_END   = /^\s*\*\/\s*$/m;
 var RE_COMMENT_1LINE = /^\s*\/\*\*\s*(.*)\s*\*\/\s*$/;
 
@@ -115,7 +115,7 @@ PARSERS.parse_name = function parse_name(str, data) {
 PARSERS.parse_description = function parse_description(str, data) {
   if (data.errors && data.errors.length) { return null; }
 
-  var result = str.match(/^\s+([^$]+)?/);
+  var result = str.match(/^\s+((.|\s)+)?/);
 
   if (result) {
     return {
@@ -143,10 +143,7 @@ function parse_tag(str, parsers) {
 
     try {
       result = parser(state.source, merge({}, state.data));
-      // console.log('----------------');
-      // console.log(parser.name, ':', result);
     } catch (err) {
-      // console.warn('Parser "%s" failed: %s', parser.name, err.message);
       state.data.errors = (state.data.errors || [])
         .concat(parser.name + ': ' + err.message);
     }
@@ -175,10 +172,15 @@ function parse_tag(str, parsers) {
  */
 function parse_block(source, opts) {
 
+  function trim(s) {
+    return opts.trim ? s.trim() : s;
+  }
+
   var source_str = source
-      .map(function(line) { return line.source; })
-      .join('\n')
-      .trim();
+      .map(function(line) { return trim(line.source); })
+      .join('\n');
+
+  source_str = trim(source_str);
 
   var start = source[0].number;
 
@@ -186,9 +188,9 @@ function parse_block(source, opts) {
   // we assume tag starts with "@"
   source = source
     .reduce(function(tags, line) {
-      line.source = line.source.trim();
+      line.source = trim(line.source);
 
-      if (line.source.match(/^@(\w+)/)) { 
+      if (line.source.match(/^\s*@(\w+)/)) { 
         tags.push({source: [line.source], line: line.number});
       } else {
         var tag = tags[tags.length - 1];
@@ -198,7 +200,7 @@ function parse_block(source, opts) {
       return tags;
     }, [{source: []}])
     .map(function(tag) {
-      tag.source = tag.source.join('\n').trim();
+      tag.source = trim(tag.source.join('\n'));
       return tag;
     });
 
@@ -211,12 +213,7 @@ function parse_block(source, opts) {
   }
 
   var tags = source.reduce(function(tags, tag) {
-    var tag_node = parse_tag(tag.source, opts.parsers || [
-      PARSERS.parse_tag,
-      PARSERS.parse_type,
-      PARSERS.parse_name,
-      PARSERS.parse_description
-    ]);
+    var tag_node = parse_tag(tag.source, opts.parsers);
 
     if (!tag_node) { return tags; }
 
@@ -258,10 +255,7 @@ function parse_block(source, opts) {
 
     return tags.concat(tag_node);
   }, []);
-
-  // console.log('-----------');
-  // console.log(description, tags);
-
+  
   return {
     tags        : tags,
     line        : start,
@@ -274,10 +268,20 @@ function parse_block(source, opts) {
  * Produces `extract` function with internal state initialized
  */
 function mkextract(opts) {
-
   var chunk = null;
   var number = 0;
 
+  opts = merge({}, {
+    trim         : true,
+    dotted_names : false,
+    parsers      : [
+      PARSERS.parse_tag,
+      PARSERS.parse_type,
+      PARSERS.parse_name,
+      PARSERS.parse_description
+    ]
+  }, opts || {});
+
   /**
    * Cumulatively reading lines until they make one comment block
    * Returns block object or null.
@@ -287,8 +291,6 @@ function mkextract(opts) {
     // if oneliner
     // then parse it immediately
     if (line.match(RE_COMMENT_1LINE)) {
-      // console.log('line (1)', line);
-      // console.log('  clean:', line.replace(RE_COMMENT_1LINE, '$1'));
       return parse_block([{
         source: line.replace(RE_COMMENT_1LINE, '$1'), 
         number: number}], opts);
@@ -299,8 +301,6 @@ function mkextract(opts) {
     // if start of comment
     // then init the chunk
     if (line.match(RE_COMMENT_START)) {
-      // console.log('line (1)', line);
-      // console.log('  clean:', line.replace(RE_COMMENT_START, ''));
       chunk = [{source: line.replace(RE_COMMENT_START, ''), number: number - 1}];
       return null;
     }
@@ -308,17 +308,16 @@ function mkextract(opts) {
     // if comment line and chunk started
     // then append
     if (chunk && line.match(RE_COMMENT_LINE)) {
-      // console.log('line (2)', line);
-      // console.log('  clean:', line.replace(RE_COMMENT_LINE, ''));
-      chunk.push({source: line.replace(RE_COMMENT_LINE, ''), number: number - 1});
+      chunk.push({
+        number: number - 1,
+        source: line.replace(RE_COMMENT_LINE, opts.trim ? '' : '$1')
+      });
       return null;
     }
 
     // if comment end and chunk started
     // then parse the chunk and push
     if (chunk && line.match(RE_COMMENT_END)) {
-      // console.log('line (3)', line);
-      // console.log('  clean:', line.replace(RE_COMMENT_END, ''));
       chunk.push({source: line.replace(RE_COMMENT_END, ''), number: number - 1});
       return parse_block(chunk, opts);
     }
@@ -332,8 +331,6 @@ function mkextract(opts) {
 /* ------- Public API ------- */
 
 module.exports = function parse(source, opts) {
-  opts = opts || {};
-
   var block;
   var blocks  = [];
   var extract = mkextract(opts);
@@ -350,4 +347,4 @@ module.exports = function parse(source, opts) {
 };
 
 module.exports.PARSERS = PARSERS;
-module.exports.mkextract = mkextract;
+module.exports.mkextract = mkextract;

package/tests/parse.spec.js

@@ -10,7 +10,7 @@ describe('Comment string parsing', function() {
    * 0 function() {
    * 1  // source with comments
    * 2 }
-   * 
+   *
    */
 
   function parsed(func, opts) {
@@ -39,11 +39,11 @@ describe('Comment string parsing', function() {
     expect(parsed(function(){
       /**
        *
-       * 
+       *
        * Description first line
        *
        * Description second line
-       * 
+       *
        */
       var a;
     })[0])
@@ -59,7 +59,7 @@ describe('Comment string parsing', function() {
 
     expect(parsed(function(){
       /**
-       * 
+       *
        */
       var a;
     }).length)
@@ -132,6 +132,28 @@ describe('Comment string parsing', function() {
       .to.eq(0);
   });
 
+  it('should preserve empty lines and indentation with `opts.trim = false`', function() {
+    expect(parsed(function(){
+      /**
+       *
+       *
+       *   Description first line
+       *     second line
+       *
+       *       third line
+       */
+      var a;
+    }, {
+      trim: false
+    })[0])
+      .eql({
+        description : '\n\n\n  Description first line\n    second line\n\n      third line\n',
+        source      : '\n\n\n  Description first line\n    second line\n\n      third line\n',
+        line        : 1,
+        tags        : []
+      });
+  });
+
   it('should parse one line block with tag', function() {
     expect(parsed(function(){
       /** @tag */
@@ -156,7 +178,7 @@ describe('Comment string parsing', function() {
   it('should parse `@tag`', function() {
       expect(parsed(function(){
         /**
-         * 
+         *
          * @my-tag
          */
         var a;
@@ -230,14 +252,14 @@ describe('Comment string parsing', function() {
       })[0])
         .to.eql({
           line        : 1,
-          source      : '@my-tag {my.type} name',    
+          source      : '@my-tag {my.type} name',
           description : '',
           tags: [{
             tag         : 'my-tag',
             line        : 2,
             type        : 'my.type',
             name        : 'name',
-            source      : '@my-tag {my.type} name',    
+            source      : '@my-tag {my.type} name',
             description : '',
             optional    : false
           }]
@@ -259,7 +281,7 @@ describe('Comment string parsing', function() {
             line        : 2,
             type        : 'my.type',
             name        : 'name',
-            source      : '@my-tag {my.type} name description',    
+            source      : '@my-tag {my.type} name description',
             description : 'description',
             optional    : false
           }]
@@ -426,7 +448,7 @@ describe('Comment string parsing', function() {
         });
   });
 
-  it('should parse optionalrest names `@tag [...name] desc`', function() {
+  it('should parse optional rest names `@tag [...name] desc`', function() {
       expect(parsed(function(){
         /**
          * @tag {t} [...name] desc
@@ -567,4 +589,26 @@ describe('Comment string parsing', function() {
           }]
         });
   });
+
+  it('parses $ in description`', function() {
+    expect(parsed(function(){
+      /**
+       * @my-tag {String} name description with $ char
+       */
+    })[0])
+      .to.eql({
+        line        : 1,
+        source      : '@my-tag {String} name description with $ char',
+        description : '',
+        tags: [{
+          tag         : 'my-tag',
+          line        : 2,
+          type        : 'String',
+          name        : 'name',
+          source      : '@my-tag {String} name description with $ char',
+          optional    : false,
+          description : 'description with $ char'
+        }]
+      });
+  });
 });