extract-comments

Uses esprima to extract line and block comments from a string of JavaScript. Also optionally parses code context (the next line of code after a comment).

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.

Install

Install with npm:

$ npm install --save extract-comments

Usage

var extract = require('extract-comments');

// pass a string of JavaScript
extract(string);

Example

var str = '/**\n * this is\n *\n * a comment\n*/\n\n\nvar foo = "bar";\n';
var comments = extract(str);
console.log(comments);

[{
  type: 'block',
  raw: '/**\n * this is\n *\n * a comment\n*/',
  value: 'this is\na comment',
  loc: { start: { line: 1, column: 0 }, end: { line: 5, column: 33 } },
  code:
   { line: 7,
     loc: { start: { line: 7, column: 36 }, end: { line: 7, column: 52 } },
     value: 'var foo = "bar";' }

Extractors

By default, esprima is used for extracting comments. This can easily be changed by passing a function to options.extractor.

The easy way

Use a published module, such as:

• babel-extract-comments
• esprima-extract-comments
• espree-extract-comments

Example:

extract(str, {extractor: require('babel-extract-comments')});

If you create a compatible extractor, feel free to do pr or create an issue to add it to the readme!

Roll your own

extract(str, {
  extractor: function(str) {
    // must return an array of tokens with:
    // - type: 'Block', 'CommentBlock', 'Line' or 'CommentLine'
    // - value: the comment inner string
    // - loc: with `start` and `end` line and column
    // example:
    return [
      { 
        type: 'Block',
        {start: { line: 1, column: 0 },
          end: { line: 5, column: 33 }},
        value: ' this is a comment string '
      }
    ];
  }
});

API

extract

Extract comments from the given string.

Params

• string {String}
• options {Object}: Pass first: true to return after the first comment is found.
• tranformFn {Function}: (optional) Tranform function to modify each comment
• returns {Array}: Returns an array of comment objects

Example

const extract = require('extract-comments');
console.log(extract(string, options));

.block

Extract block comments from the given string.

Params

• string {String}
• options {Object}: Pass first: true to return after the first comment is found.
• returns {String}

Example

console.log(extract.block(string, options));

.line

Extract line comments from the given string.

Params

• string {String}
• options {Object}: Pass first: true to return after the first comment is found.
• returns {String}

Example

console.log(extract.line(string, options));

.first

Extract the first comment from the given string.

Params

• string {String}
• options {Object}: Pass first: true to return after the first comment is found.
• returns {String}

Example

console.log(extract.first(string, options));

Release history

v0.10.0

• Parsing is now handled by esprima, so only JavaScript can be parsed. I'm working on parsers for other languages and will cross-link those here when they're pushed up.
• Breaking change: since parsing is now done by esprima, on both the line and block comment objects, the loc.start.pos and loc.end.pos properties have been renamed to loc.start.column and loc.end.column.

v0.9.0

• Breaking change: lines property was removed from Block comments, since this can easily be done by splitting value

About

Related projects

You might also be interested in these projects:

• babel-extract-comments: Uses babel (babylon) to extract JavaScript code comments from a JavaScript string or file. | homepage
• code-context: Parse a string of javascript to determine the context for functions, variables and comments based… more | homepage
• espree-extract-comments: Uses espree to extract JavaScript code comments from a string. Returns an array of comment… more | homepage
• esprima-extract-comments: Extract code comments from string or from a glob of files using esprima. | homepage
• parse-comments: Parse code comments from JavaScript or any language that uses the same format. | homepage

Contributors

Author

Jon Schlinkert

• linkedin/in/jonschlinkert
• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2018, Jon Schlinkert. Released under the MIT License.

This file was generated by verb-generate-readme, v0.6.0, on February 12, 2018.