npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

comment-patterns

v0.12.2

Published

A list of comment-patterns for different languages

Downloads

94,245

Readme

comment-patterns

A list of comment-patterns for different languages

This module contains an extract of the language-database of groc with information about how single- and multi-line comments are written in different languages.

Basic usage

var commentPattern = require('comment-patterns');
var p = commentPattern('filename.js');

This will lead to p being:

{
  name: "JavaScript",
  nameMatchers: [".js"],
  multiLineComment: [{
    start: /\/\*\*/,
    middle: "*",
    end: "*/",
    apidoc: true
  }, {
    start: /\/\*/,
    middle: "*",
    end: "*/"
  }],
  singleLineComment: [{
    start: "//"
  }]
}
  • name is the name of the language
  • nameMatchers is an array of file extensions of filenames that files in this language usually have.
  • multiLineComment is an array of patterns for comments that may span multiple lines
    • start is the beginning of a comment
    • middle is a character of a regex that occurs in front of each comment line
    • end marks the end of the comment
  • singleLineComment is the prefix of comments that go until the end of the line

Variation (regex)

It is also possible to retrieve a regular expression that matches comments (up to the next line of code):

var re = commentPattern.regex('filename.js');

The result re will be:

{
  regex: /^([ \t]*)(\/\*\*([\s\S]*?)\*\/|\/\*([\s\S]*?)\*\/|((?:[ \t]*?\/\/.*\r?\n?)+))[\r\n]*/gm,
  cg: {
    indent: 1,
    wholeComment: 2,
    contentStart: 3
  },
  middle: [/^[ \t]*\*/gm, /^[ \t]*\*/gm, /^[ \t]*\/\//gm],
  name: "JavaScript",
  info: [{
    type: "multiline",
    apidoc: true
  }, {
    type: "multiline"
  }, {
    type: "singleline"
  }]
}
  • regex is the actual regular expression. It matches the comments in a string, including any empty lines after the comment.
  • cg are constant values refering to capturing groups of the regex.
    • match[cg.indent] contains the spaces that indent comment-start-delimiter.
    • match[cg.wholeComment] matches the comment including delimiters.
    • match[cg.contentStart] is the first group that captures the contents of the comment In this case, there are multiple possible delimiters, so dependending on which delimiter is used, match[cg.contentStart] or match[cg.contentStart + 1] is filled. the others are undefined.
  • middle contains one pattern for each group after cg.contentStart that matches the prefix used before comment lines. It can be used to remove this prefix. If the middle-prefix for this capturing group is empty (''), the pattern is null.
  • info contains additional information for each group after cg.contentStart, currently this information is only { apidocs: true } if the group is matching an apidoc comment.
  • name is the language name for debugging purposes.

Variation (codeContext)

For API-documentation, it is important to determine the context of the comment (i.e. the thing that the comment is documenting). Although this does not strictly belong to the comment itself, this library also has methods to determine the code-context of a comment These are functions that return a json by matching a single-line of code against a regular expression.

var detector = commentPattern.codeContext("filename.js");
var cc = detector("function abc(param1,param2) {",2);

The result in cc will be

{
  begin: 2,
  type: "function statement",
  name: "abc",
  params: ["param1", "param2"],
  string: "abc()",
  original: "function abc(param1,param2) {"
}

This result (for 'JavaScript' is actuall taken from the parse-code-context module by Jon Schlinkert. The method codeContext returns a Detector

API-Reference

commentPattern

Load the comment-pattern for a given file. The file-language is determined by the file-extension.

Params

  • filename {string}: the name of the file
  • returns {object}: the comment-patterns

.commentPattern.regex

Load the comment-regex for a given file. The result contains a regex that matches the comments in the specification. It also has information about which the different capturing groups of an object.

Params

  • filename {string}: the name of the file
  • returns {object}: an object containing regular expressions and capturing-group metadata, see usage example for details

The code-context detector

Detector

Create a new detector. A detector contains a list of parsers which extract the code context from a list of nodes. It is an immutable object that can be extended, creating a new instance with more parsers.

Params

  • {function(string)}: parsers

.extend

Creates an extended Detector with additional parsers. A new instance will be created. The old Detector remains untouched.

Params

  • {function(string)}: moreParsers more parsers. Those are inserted at the beginning of the list, so they override existing parsers.
  • returns {Detector}: a new Detector instance

.detect

Perform detection. This method calls the included parsers one after another and returns the first-non-null result. The line-number is returned as begin-property in the result, but the parser-function can override it.

Params

  • {string}: string the line-of-code
  • {number}: lineNr the line-number
  • returns {object}

.parser

Helper function to create a parser from a regex that matches a string and a resolver that parses the

Params

  • {RegExp}: regex a regular expression that is matched against a code-line.
  • {function(...string)}: resolver a function that resolves the regex match into a code-context object. The function-parameters are the capturing groups of the regex
  • returns {function}: a function that can be used as parser

The database

The language-specification can be found in the languages-directory. There is one file for each language. The actual databases will be created from these files on prepublish.

The content of language database can be found here

Contributing

See the contributing guide

Run tests

Install dev dependencies:

$ npm i -d && npm test

Related

extract-comments: Uses esprima to extract line and block comments from a string of JavaScript. Also optionally… more | homepage

Author

Nils Knappmeier

License

Released under the MIT license.