extract-comments - npm Package Compare versions

Comparing version 0.6.0 to 0.7.0

index.js

@@ -10,4 +10,2 @@ /*!
 
-var fs = require('fs');
-var mapFiles = require('map-files');
 var isWhitespace = require('is-whitespace');
@@ -43,14 +41,14 @@
 function extract(str, fn) {
-  var start = /^\s*\/\*\*?/;
-  var middle = /^\s*\*([^\n*]*)/;
-  var end = /^\s*\*\//;
+  var start = /^\/\*\*?/;
+  var middle = /^\*([^*][^\/])*/;
+  var end = /^\*\//;
 
-  var lines = str.split('\n');
+  var lines = str.split(/[\r\n]/);
   var len = lines.length, i = 0, m;
-  var comments = {}, o = {};
+  var comments = {};
   var isComment = false, afterCount;
-  var from, to;
+  var from, to, b, o;
 
   while (i < len) {
-    var line = lines[i++];
+    var line = lines[i++].trim();
 
@@ -60,6 +58,6 @@ if (!isComment && start.test(line)) {
       isComment = true;
-      o = {};
-      o.begin = i;
-      o.comment = '';
+      o = {begin: null, end: null};
+      o.begin = b = i;
       o.after = '';
+      o.content = '';
     }
@@ -69,12 +67,10 @@
       o.end = i;
-      o.type = 'comment';
-      comments[o.begin] = o;
+      comments[b] = o;
       isComment = false;
     }
 
-    if (isComment && i > o.begin) {
-      m = middle.exec(line);
-      if (m) line = m[1];
-
-      o.comment += (line || '').trim() + '\n';
+    if (isComment && i > b) {
+      if (isMiddle(line)) {
+        o.content += stripStars(line) + '\n';
+      }
     }
@@ -90,8 +86,9 @@
 
-    if (o.begin && o.after !== '') {
+    if (b && o.after !== '') {
       o.after = o.after.trim().split('\n')[0];
+      comments[b].blocks = comments[b].content.split('\n\n');
 
       // callback
       if (typeof fn === 'function') {
-        comments[o.begin] = fn(comments[o.begin], o.begin, o.end);
+        comments[b] = fn(comments[b], b, o.end);
       }
@@ -104,29 +101,29 @@ }
 /**
- * Extract code comments from a file or glob of files.
- * You may also pass a custom `rename` function on the options
- * to change the key of each object returned.
- *
- * See [map-files] for more details and available options.
- *
- * ```js
- * var extract = require('extract-comments');
- * extract.fromFiles(['lib/*.js']);
- * ```
- *
- * @param  {String} `patterns` Glob patterns to used.
- * @param  {Object} `options` Options to pass to [globby], or [map-files].
- * @return {Object} Object of code comments.
- * @api public
+ * Strip the leading `*` from a line, ensuring
+ * not to eat too many whitespaces afterwards.
  */
 
-extract.fromFiles = function(patterns, opts) {
-  opts = opts || {};
-  opts.name = opts.rename || function(fp) {
-    return fp;
-  };
-  opts.read = opts.read || function(fp, options) {
-    var code = fs.readFileSync(fp, 'utf8');
-    return extract(code, options);
-  };
-  return mapFiles(patterns, opts);
-};
+function stripStars(str) {
+  str = str.replace(/^\s*/, '');
+  if (str.charAt(0) === '/') {
+    str = str.slice(1);
+  }
+  if (str.charAt(0) === '*') {
+    str = str.slice(1);
+  }
+  if (str.charAt(0) === ' ') {
+    str = str.slice(1);
+  }
+  return str;
+}
+
+/**
+ * Detect if the given line is in the middle
+ * of a comment.
+ */
+
+function isMiddle(str) {
+  return typeof str === 'string'
+   && str.charAt(0) === '*'
+   && str.charAt(1) !== '/';
+}

package.json

 {
   "name": "extract-comments",
   "description": "Extract code comments from string or from a glob of files.",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "homepage": "https://github.com/jonschlinkert/extract-comments",
@@ -36,2 +36,3 @@ "author": {
   "devDependencies": {
+    "code-context": "^0.5.0",
     "mocha": "~1.18.2",
@@ -38,0 +39,0 @@ "should": "^4.0.4"

README.md

@@ -13,69 +13,84 @@ # extract-comments [![NPM version](https://badge.fury.io/js/extract-comments.svg)](http://badge.fury.io/js/extract-comments)
 
-## API
+## Usage
 
-### [extract](index.js#L41)
-
-Extract code comments from the given `string`.
-
-* `string` **{String}**    
-* `returns` **{Object}**: Object of code comments.  
-
 ```js
 var extract = require('extract-comments');
-extract('// this is a code comment');
 
-// pass a callback to process each comment
-// directly after it's parsed
-var context = require('code-context');
-extract(str, function(comment) {
-  comment.context = context(comment.after);
-  return comment;
-});
+// pass a string of javascript, CSS, LESS etc
+extract(string);
 ```
 
-### [.fromFiles](index.js#L116)
+**Example**
 
-Extract code comments from a file or glob of files. You may also pass a custom `rename` function on the options to change the key of each object returned.
+```js
+var str = '/**\n * this is\n *\n * a comment\n*/\nvar foo = "bar";\n';
+extract(str);
+```
 
-* `patterns` **{String}**: Glob patterns to used.    
-* `options` **{Object}**: Options to pass to [globby], or [map-files].    
-* `returns` **{Object}**: Object of code comments.  
+Results in:
 
-See [map-files] for more details and available options.
-
 ```js
-var extract = require('extract-comments');
-extract.fromFiles(['lib/*.js']);
+// key is the starting line number
+{ '1':
+   { begin: 1,
+     end: 5,
+     // line number of the code after the comment
+     codeStart: 7 } }
+     content: 'this is\n\na comment\n',
+     // sames as content, but split into blocks at double newlines
+     blocks: [
+       'this is',
+       'a comment\n'
+     ],
+     // first line of code after the comment
+     after: 'var foo = "bar";',
 ```
 
+_(The reason the key is the starting line number is that it's easy to use this format with templates)_
 
-## Usage example
 
+**Customize output**
+
 ```js
-var extract = require('extract-comments');
-var comments = extract.fromFile('fixtures/assemble.js');
+// use code-context to parse the first line of code following
+// the comment
+var context = require('code-context');
 
-// we'll just pick an arbitrary comment:
-comments['122'];
+// pass a function to modify the returned object
+// and avoid looping more than once
+var comments = extract(str, function(comment) {
+  comment.context = context(comment.after);
+  return comment;
+});
+```
+Results in:
 
-{ 'fixtures/assemble.js':
-   // the line number
-   { '122':
-        // the starting line number (same as object key)
-      { begin: 122,
-        // the actual comment
-        comment: 'Initialize default configuration.\n\n@api private\n',
-        // the first non-whitespace line after the comment ends
-        after: 'Assemble.prototype.defaultConfig = function (opts) {',
-        // ending line number
-        end: 126,
-        // used when this object is merged with "code context", see below
-        type: 'comment' }
+```js
+{ begin: 1,
+  content: 'this is\n\na comment\n',
+  after: 'var foo = "bar";',
+  end: 5,
+  codeStart: 7,
+  blocks: [ 'this is', 'a comment\n' ],
+  context:
+   [ { begin: 1,
+       type: 'declaration',
+       name: 'foo',
+       value: '"bar"',
+       string: 'foo',
+       original: 'var foo = "bar";' } ] }
 ```
 
 
+## Related
+* [parse-comments](https://github.com/jonschlinkert/parse-comments): Parse code comments from JavaScript or any language that uses the same format.
+* [code-context](https://github.com/jonschlinkert/code-context): Parse a string of javascript to determine the context for functions, variables and comments based on the code that follows.
+* [esprima-extract-comments](https://github.com/jonschlinkert/esprima-extract-comments): Extract code comments from string or from a glob of files using esprima.
+
+## Contributing
+Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/jonschlinkert/extract-comments/issues)
+
 ## Run tests
+Install dev dependencies.
 
-Install dev dependencies:
-
 ```bash
@@ -98,4 +113,4 @@ npm i -d && npm test
 
-_This file was generated by [verb](https://github.com/assemble/verb) on February 13, 2015._
+_This file was generated by [verb-cli](https://github.com/assemble/verb-cli) on March 11, 2015._
 
 [map-files]: https://github.com/jonschlinkert/map-files

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

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

7724

increased by18.14%

Number of package files

4

increased by33.33%

Number of lines in readme file

114

increased by15.15%

Number of low supply chain risk alerts

0

decreased by-100%

Worsened metrics

Dev dependency count

3

increased by50%

Lines of code

105

decreased by-3.67%

No dependency changes