comment-parser 1.0.0 → 1.1.2

package/es6/index.d.ts

@@ -1,5 +1,22 @@
 import { Options as ParserOptions } from './parser/index';
-import { Block } from './primitives';
-export declare function parse(source: string, options?: Partial<ParserOptions>): Block[];
-export declare const stringify: (block: Block) => string;
-export * as transforms from './transforms/index';
+import descriptionTokenizer from './parser/tokenizers/description';
+import nameTokenizer from './parser/tokenizers/name';
+import tagTokenizer from './parser/tokenizers/tag';
+import typeTokenizer from './parser/tokenizers/type';
+import alignTransform from './transforms/align';
+import indentTransform from './transforms/indent';
+import { flow as flowTransform } from './transforms/index';
+export declare function parse(source: string, options?: Partial<ParserOptions>): import("./primitives").Block[];
+export declare const stringify: import("./stringifier").Stringifier;
+export { default as inspect } from './stringifier/inspect';
+export declare const transforms: {
+    flow: typeof flowTransform;
+    align: typeof alignTransform;
+    indent: typeof indentTransform;
+};
+export declare const tokenizers: {
+    tag: typeof tagTokenizer;
+    type: typeof typeTokenizer;
+    name: typeof nameTokenizer;
+    description: typeof descriptionTokenizer;
+};

package/es6/index.js

@@ -1,9 +1,25 @@
 import getParser from './parser/index';
+import descriptionTokenizer from './parser/tokenizers/description';
+import nameTokenizer from './parser/tokenizers/name';
+import tagTokenizer from './parser/tokenizers/tag';
+import typeTokenizer from './parser/tokenizers/type';
 import getStringifier from './stringifier/index';
-export function parse(source, options) {
-    if (options === void 0) { options = {}; }
+import alignTransform from './transforms/align';
+import indentTransform from './transforms/indent';
+import { flow as flowTransform } from './transforms/index';
+export function parse(source, options = {}) {
     return getParser(options)(source);
 }
-export var stringify = getStringifier();
-import * as transforms_1 from './transforms/index';
-export { transforms_1 as transforms };
+export const stringify = getStringifier();
+export { default as inspect } from './stringifier/inspect';
+export const transforms = {
+    flow: flowTransform,
+    align: alignTransform,
+    indent: indentTransform,
+};
+export const tokenizers = {
+    tag: tagTokenizer,
+    type: typeTokenizer,
+    name: nameTokenizer,
+    description: descriptionTokenizer,
+};

package/es6/parser/block-parser.d.ts

@@ -1,8 +1,24 @@
 import { Line } from '../primitives';
+/**
+ * Groups source lines in sections representing tags.
+ * First section is a block description if present. Last section captures lines starting with
+ * the last tag to the end of the block, including dangling closing marker.
+ * @param {Line[]} block souce lines making a single comment block
+ */
 export declare type Parser = (block: Line[]) => Line[][];
-declare type Fencer = (source: string) => boolean;
+/**
+ * Predicate telling if string contains opening/closing escaping sequence
+ * @param {string} source raw source line
+ */
+export declare type Fencer = (source: string) => boolean;
+/**
+ * `Parser` configuration options
+ */
 export interface Options {
     fence: string | Fencer;
 }
+/**
+ * Creates configured `Parser`
+ * @param {Partial<Options>} options
+ */
 export default function getParser({ fence, }?: Partial<Options>): Parser;
-export {};

package/es6/parser/block-parser.js

@@ -1,16 +1,16 @@
-var reTag = /^@\S+/;
-export default function getParser(_a) {
-    var _b = (_a === void 0 ? {} : _a).fence, fence = _b === void 0 ? '```' : _b;
-    var fencer = getFencer(fence);
-    var toggleFence = function (source, isFenced) {
-        return fencer(source) ? !isFenced : isFenced;
-    };
+const reTag = /^@\S+/;
+/**
+ * Creates configured `Parser`
+ * @param {Partial<Options>} options
+ */
+export default function getParser({ fence = '```', } = {}) {
+    const fencer = getFencer(fence);
+    const toggleFence = (source, isFenced) => fencer(source) ? !isFenced : isFenced;
     return function parseBlock(source) {
         // start with description section
-        var sections = [[]];
-        var isFenced = false;
-        for (var _i = 0, source_1 = source; _i < source_1.length; _i++) {
-            var line = source_1[_i];
+        const sections = [[]];
+        let isFenced = false;
+        for (const line of source) {
             if (reTag.test(line.tokens.description) && !isFenced) {
                 sections.push([line]);
             }
@@ -24,6 +24,6 @@ export default function getParser(_a) {
 }
 function getFencer(fence) {
     if (typeof fence === 'string')
-        return function (source) { return source.split(fence).length % 2 === 0; };
+        return (source) => source.split(fence).length % 2 === 0;
     return fence;
 }

package/es6/parser/index.d.ts

@@ -1,10 +1,10 @@
-import { Tokenizer } from './spec-parser';
 import { Block } from '../primitives';
-import { Spacer } from './spacer';
+import { Tokenizer } from './tokenizers/index';
 export interface Options {
     startLine: number;
     fence: string;
-    spacing: 'compact' | 'preserve' | Spacer;
+    spacing: 'compact' | 'preserve';
     tokenizers: Tokenizer[];
 }
-export default function getParser({ startLine, fence, spacing, tokenizers, }?: Partial<Options>): (source: string) => Block[];
+export declare type Parser = (source: string) => Block[];
+export default function getParser({ startLine, fence, spacing, tokenizers, }?: Partial<Options>): Parser;

package/es6/parser/index.js

@@ -1,40 +1,39 @@
-import sourceParser from './source-parser';
-import blockParser from './block-parser';
-import specParser, { tagTokenizer, nameTokenizer, typeTokenizer, descriptionTokenizer, } from './spec-parser';
-import getSpacer from './spacer';
 import { splitLines } from '../util';
-export default function getParser(_a) {
-    var _b = _a === void 0 ? {} : _a, _c = _b.startLine, startLine = _c === void 0 ? 0 : _c, _d = _b.fence, fence = _d === void 0 ? '```' : _d, _e = _b.spacing, spacing = _e === void 0 ? 'compact' : _e, _f = _b.tokenizers, tokenizers = _f === void 0 ? [
-        tagTokenizer(),
-        typeTokenizer(),
-        nameTokenizer(),
-        descriptionTokenizer(getSpacer(spacing)),
-    ] : _f;
+import blockParser from './block-parser';
+import sourceParser from './source-parser';
+import specParser from './spec-parser';
+import tokenizeTag from './tokenizers/tag';
+import tokenizeType from './tokenizers/type';
+import tokenizeName from './tokenizers/name';
+import tokenizeDescription, { getJoiner as getDescriptionJoiner, } from './tokenizers/description';
+export default function getParser({ startLine = 0, fence = '```', spacing = 'compact', tokenizers = [
+    tokenizeTag(),
+    tokenizeType(spacing),
+    tokenizeName(),
+    tokenizeDescription(spacing),
+], } = {}) {
     if (startLine < 0 || startLine % 1 > 0)
         throw new Error('Invalid startLine');
-    var parseSource = sourceParser({ startLine: startLine });
-    var parseBlock = blockParser({ fence: fence });
-    var parseSpec = specParser({ tokenizers: tokenizers });
-    var join = getSpacer(spacing);
-    var notEmpty = function (line) {
-        return line.tokens.description.trim() != '';
-    };
+    const parseSource = sourceParser({ startLine });
+    const parseBlock = blockParser({ fence });
+    const parseSpec = specParser({ tokenizers });
+    const joinDescription = getDescriptionJoiner(spacing);
+    const notEmpty = (line) => line.tokens.description.trim() != '';
     return function (source) {
-        var blocks = [];
-        for (var _i = 0, _a = splitLines(source); _i < _a.length; _i++) {
-            var line = _a[_i];
-            var lines = parseSource(line);
+        const blocks = [];
+        for (const line of splitLines(source)) {
+            const lines = parseSource(line);
             if (lines === null)
                 continue;
             if (lines.find(notEmpty) === undefined)
                 continue;
-            var sections = parseBlock(lines);
-            var specs = sections.slice(1).map(parseSpec);
+            const sections = parseBlock(lines);
+            const specs = sections.slice(1).map(parseSpec);
             blocks.push({
-                description: join(sections[0]),
+                description: joinDescription(sections[0]),
                 tags: specs,
                 source: lines,
-                problems: specs.reduce(function (acc, spec) { return acc.concat(spec.problems); }, []),
+                problems: specs.reduce((acc, spec) => acc.concat(spec.problems), []),
             });
         }
         return blocks;

package/es6/parser/source-parser.js

@@ -1,44 +1,42 @@
-import { splitSpace, seedTokens } from '../util';
 import { Markers } from '../primitives';
-export default function getParser(_a) {
-    var _b = (_a === void 0 ? {} : _a).startLine, startLine = _b === void 0 ? 0 : _b;
-    var block = null;
-    var num = startLine;
+import { seedTokens, splitSpace } from '../util';
+export default function getParser({ startLine = 0, } = {}) {
+    let block = null;
+    let num = startLine;
     return function parseSource(source) {
-        var _a, _b, _c;
-        var rest = source;
-        var tokens = seedTokens();
-        _a = splitSpace(rest), tokens.start = _a[0], rest = _a[1];
+        let rest = source;
+        const tokens = seedTokens();
+        [tokens.start, rest] = splitSpace(rest);
         if (block === null &&
             rest.startsWith(Markers.start) &&
             !rest.startsWith(Markers.nostart)) {
             block = [];
             tokens.delimiter = rest.slice(0, Markers.start.length);
             rest = rest.slice(Markers.start.length);
-            _b = splitSpace(rest), tokens.postDelimiter = _b[0], rest = _b[1];
+            [tokens.postDelimiter, rest] = splitSpace(rest);
         }
         if (block === null) {
             num++;
             return null;
         }
-        var isClosed = rest.trimRight().endsWith(Markers.end);
+        const isClosed = rest.trimRight().endsWith(Markers.end);
         if (tokens.delimiter === '' &&
             rest.startsWith(Markers.delim) &&
             !rest.startsWith(Markers.end)) {
             tokens.delimiter = Markers.delim;
             rest = rest.slice(Markers.delim.length);
-            _c = splitSpace(rest), tokens.postDelimiter = _c[0], rest = _c[1];
+            [tokens.postDelimiter, rest] = splitSpace(rest);
         }
         if (isClosed) {
-            var trimmed = rest.trimRight();
+            const trimmed = rest.trimRight();
             tokens.end = rest.slice(trimmed.length - Markers.end.length);
             rest = trimmed.slice(0, -Markers.end.length);
         }
         tokens.description = rest;
-        block.push({ number: num, source: source, tokens: tokens });
+        block.push({ number: num, source, tokens });
         num++;
         if (isClosed) {
-            var result = block.slice();
+            const result = block.slice();
             block = null;
             return result;
         }

package/es6/parser/spec-parser.d.ts

@@ -1,12 +1,7 @@
 import { Line, Spec } from '../primitives';
-import { Spacer } from './spacer';
+import { Tokenizer } from './tokenizers/index';
 export declare type Parser = (source: Line[]) => Spec;
-export declare type Tokenizer = (spec: Spec) => Spec;
 export interface Options {
     tokenizers: Tokenizer[];
 }
 export default function getParser({ tokenizers }: Options): Parser;
-export declare function tagTokenizer(): Tokenizer;
-export declare function typeTokenizer(): Tokenizer;
-export declare function nameTokenizer(): Tokenizer;
-export declare function descriptionTokenizer(join: Spacer): Tokenizer;

package/es6/parser/spec-parser.js

@@ -1,11 +1,9 @@
-import { splitSpace, isSpace, seedSpec } from '../util';
-export default function getParser(_a) {
-    var tokenizers = _a.tokenizers;
+import { seedSpec } from '../util';
+export default function getParser({ tokenizers }) {
     return function parseSpec(source) {
         var _a;
-        var spec = seedSpec({ source: source });
-        for (var _i = 0, tokenizers_1 = tokenizers; _i < tokenizers_1.length; _i++) {
-            var tokenize = tokenizers_1[_i];
+        let spec = seedSpec({ source });
+        for (const tokenize of tokenizers) {
             spec = tokenize(spec);
             if ((_a = spec.problems[spec.problems.length - 1]) === null || _a === void 0 ? void 0 : _a.critical)
                 break;
@@ -13,148 +11,3 @@ export default function getParser(_a) {
         return spec;
     };
 }
-export function tagTokenizer() {
-    return function (spec) {
-        var tokens = spec.source[0].tokens;
-        var match = tokens.description.match(/\s*(@(\S+))(\s*)/);
-        if (match === null) {
-            spec.problems.push({
-                code: 'spec:tag:prefix',
-                message: 'tag should start with "@" symbol',
-                line: spec.source[0].number,
-                critical: true,
-            });
-            return spec;
-        }
-        tokens.tag = match[1];
-        tokens.postTag = match[3];
-        tokens.description = tokens.description.slice(match[0].length);
-        spec.tag = match[2];
-        return spec;
-    };
-}
-export function typeTokenizer() {
-    return function (spec) {
-        var _a;
-        var res = '';
-        var curlies = 0;
-        var tokens = spec.source[0].tokens;
-        var source = tokens.description.trimLeft();
-        if (source[0] !== '{')
-            return spec;
-        for (var _i = 0, source_1 = source; _i < source_1.length; _i++) {
-            var ch = source_1[_i];
-            if (ch === '{')
-                curlies++;
-            if (ch === '}')
-                curlies--;
-            res += ch;
-            if (curlies === 0) {
-                break;
-            }
-        }
-        if (curlies !== 0) {
-            spec.problems.push({
-                code: 'spec:type:unpaired-curlies',
-                message: 'unpaired curlies',
-                line: spec.source[0].number,
-                critical: true,
-            });
-            return spec;
-        }
-        spec.type = res.slice(1, -1);
-        tokens.type = res;
-        _a = splitSpace(source.slice(tokens.type.length)), tokens.postType = _a[0], tokens.description = _a[1];
-        return spec;
-    };
-}
-export function nameTokenizer() {
-    return function (spec) {
-        var _a, _b;
-        var _c;
-        var tokens = spec.source[0].tokens;
-        var source = tokens.description.trimLeft();
-        var quotedGroups = source.split('"');
-        // if it starts with quoted group, assume it is a literal
-        if (quotedGroups.length > 1 &&
-            quotedGroups[0] === '' &&
-            quotedGroups.length % 2 === 1) {
-            spec.name = quotedGroups[1];
-            tokens.name = "\"" + quotedGroups[1] + "\"";
-            _a = splitSpace(source.slice(tokens.name.length)), tokens.postName = _a[0], tokens.description = _a[1];
-            return spec;
-        }
-        var brackets = 0;
-        var name = '';
-        var optional = false;
-        var defaultValue;
-        // assume name is non-space string or anything wrapped into brackets
-        for (var _i = 0, source_2 = source; _i < source_2.length; _i++) {
-            var ch = source_2[_i];
-            if (brackets === 0 && isSpace(ch))
-                break;
-            if (ch === '[')
-                brackets++;
-            if (ch === ']')
-                brackets--;
-            name += ch;
-        }
-        if (brackets !== 0) {
-            spec.problems.push({
-                code: 'spec:name:unpaired-brackets',
-                message: 'unpaired brackets',
-                line: spec.source[0].number,
-                critical: true,
-            });
-            return spec;
-        }
-        var nameToken = name;
-        if (name[0] === '[' && name[name.length - 1] === ']') {
-            optional = true;
-            name = name.slice(1, -1);
-            var parts = name.split('=');
-            name = parts[0].trim();
-            defaultValue = (_c = parts[1]) === null || _c === void 0 ? void 0 : _c.trim();
-            if (name === '') {
-                spec.problems.push({
-                    code: 'spec:name:empty-name',
-                    message: 'empty name',
-                    line: spec.source[0].number,
-                    critical: true,
-                });
-                return spec;
-            }
-            if (parts.length > 2) {
-                spec.problems.push({
-                    code: 'spec:name:invalid-default',
-                    message: 'invalid default value syntax',
-                    line: spec.source[0].number,
-                    critical: true,
-                });
-                return spec;
-            }
-            if (defaultValue === '') {
-                spec.problems.push({
-                    code: 'spec:name:empty-default',
-                    message: 'empty default value',
-                    line: spec.source[0].number,
-                    critical: true,
-                });
-                return spec;
-            }
-        }
-        spec.optional = optional;
-        spec.name = name;
-        tokens.name = nameToken;
-        if (defaultValue !== undefined)
-            spec.default = defaultValue;
-        _b = splitSpace(source.slice(tokens.name.length)), tokens.postName = _b[0], tokens.description = _b[1];
-        return spec;
-    };
-}
-export function descriptionTokenizer(join) {
-    return function (spec) {
-        spec.description = join(spec.source);
-        return spec;
-    };
-}

package/es6/parser/tokenizers/description.d.ts

@@ -0,0 +1,19 @@
+import { Line } from '../../primitives';
+import { Tokenizer } from './index';
+/**
+ * Walks over provided lines joining description token into a single string.
+ * */
+export declare type Joiner = (lines: Line[]) => string;
+/**
+ * Shortcut for standard Joiners
+ * compact - strip surrounding whitespace and concat lines using a single string
+ * preserve - preserves original whitespace and line breaks as is
+ */
+export declare type Spacing = 'compact' | 'preserve' | Joiner;
+/**
+ * Makes no changes to `spec.lines[].tokens` but joins them into `spec.description`
+ * following given spacing srtategy
+ * @param {Spacing} spacing tells how to handle the whitespace
+ */
+export default function descriptionTokenizer(spacing?: Spacing): Tokenizer;
+export declare function getJoiner(spacing: Spacing): Joiner;

package/es6/parser/tokenizers/description.js

@@ -0,0 +1,46 @@
+import { Markers } from '../../primitives';
+/**
+ * Makes no changes to `spec.lines[].tokens` but joins them into `spec.description`
+ * following given spacing srtategy
+ * @param {Spacing} spacing tells how to handle the whitespace
+ */
+export default function descriptionTokenizer(spacing = 'compact') {
+    const join = getJoiner(spacing);
+    return (spec) => {
+        spec.description = join(spec.source);
+        return spec;
+    };
+}
+export function getJoiner(spacing) {
+    if (spacing === 'compact')
+        return compactJoiner;
+    if (spacing === 'preserve')
+        return preserveJoiner;
+    return spacing;
+}
+function compactJoiner(lines) {
+    return lines
+        .map(({ tokens: { description } }) => description.trim())
+        .filter((description) => description !== '')
+        .join(' ');
+}
+const lineNo = (num, { tokens }, i) => tokens.type === '' ? num : i;
+const getDescription = ({ tokens }) => (tokens.delimiter === '' ? tokens.start : tokens.postDelimiter.slice(1)) +
+    tokens.description;
+function preserveJoiner(lines) {
+    if (lines.length === 0)
+        return '';
+    // skip the opening line with no description
+    if (lines[0].tokens.description === '' &&
+        lines[0].tokens.delimiter === Markers.start)
+        lines = lines.slice(1);
+    // skip the closing line with no description
+    const lastLine = lines[lines.length - 1];
+    if (lastLine !== undefined &&
+        lastLine.tokens.description === '' &&
+        lastLine.tokens.end.endsWith(Markers.end))
+        lines = lines.slice(0, -1);
+    // description starts at the last line of type definition
+    lines = lines.slice(lines.reduce(lineNo, 0));
+    return lines.map(getDescription).join('\n');
+}

package/es6/parser/tokenizers/index.d.ts

@@ -0,0 +1,7 @@
+import { Spec } from '../../primitives';
+/**
+ * Splits `spect.lines[].token.description` into other tokens,
+ * and populates the spec.{tag, name, type, description}. Invoked in a chaing
+ * with other tokens, operations listed above can be moved to separate tokenizers
+ */
+export declare type Tokenizer = (spec: Spec) => Spec;

package/es6/parser/tokenizers/index.js

@@ -0,0 +1 @@
+export {};

package/es6/parser/tokenizers/name.d.ts

@@ -0,0 +1,6 @@
+import { Tokenizer } from './index';
+/**
+ * Splits remaining `spec.lines[].tokens.description` into `name` and `descriptions` tokens,
+ * and populates the `spec.name`
+ */
+export default function nameTokenizer(): Tokenizer;

package/es6/parser/tokenizers/name.js

@@ -0,0 +1,91 @@
+import { splitSpace, isSpace } from '../../util';
+const isQuoted = (s) => s && s.startsWith('"') && s.endsWith('"');
+/**
+ * Splits remaining `spec.lines[].tokens.description` into `name` and `descriptions` tokens,
+ * and populates the `spec.name`
+ */
+export default function nameTokenizer() {
+    const typeEnd = (num, { tokens }, i) => tokens.type === '' ? num : i;
+    return (spec) => {
+        // look for the name in the line where {type} ends
+        const { tokens } = spec.source[spec.source.reduce(typeEnd, 0)];
+        const source = tokens.description.trimLeft();
+        const quotedGroups = source.split('"');
+        // if it starts with quoted group, assume it is a literal
+        if (quotedGroups.length > 1 &&
+            quotedGroups[0] === '' &&
+            quotedGroups.length % 2 === 1) {
+            spec.name = quotedGroups[1];
+            tokens.name = `"${quotedGroups[1]}"`;
+            [tokens.postName, tokens.description] = splitSpace(source.slice(tokens.name.length));
+            return spec;
+        }
+        let brackets = 0;
+        let name = '';
+        let optional = false;
+        let defaultValue;
+        // assume name is non-space string or anything wrapped into brackets
+        for (const ch of source) {
+            if (brackets === 0 && isSpace(ch))
+                break;
+            if (ch === '[')
+                brackets++;
+            if (ch === ']')
+                brackets--;
+            name += ch;
+        }
+        if (brackets !== 0) {
+            spec.problems.push({
+                code: 'spec:name:unpaired-brackets',
+                message: 'unpaired brackets',
+                line: spec.source[0].number,
+                critical: true,
+            });
+            return spec;
+        }
+        const nameToken = name;
+        if (name[0] === '[' && name[name.length - 1] === ']') {
+            optional = true;
+            name = name.slice(1, -1);
+            const parts = name.split('=');
+            name = parts[0].trim();
+            if (parts[1] !== undefined)
+                defaultValue = parts.slice(1).join('=').trim();
+            if (name === '') {
+                spec.problems.push({
+                    code: 'spec:name:empty-name',
+                    message: 'empty name',
+                    line: spec.source[0].number,
+                    critical: true,
+                });
+                return spec;
+            }
+            if (defaultValue === '') {
+                spec.problems.push({
+                    code: 'spec:name:empty-default',
+                    message: 'empty default value',
+                    line: spec.source[0].number,
+                    critical: true,
+                });
+                return spec;
+            }
+            // has "=" and is not a string, except for "=>"
+            if (!isQuoted(defaultValue) && /=(?!>)/.test(defaultValue)) {
+                spec.problems.push({
+                    code: 'spec:name:invalid-default',
+                    message: 'invalid default value syntax',
+                    line: spec.source[0].number,
+                    critical: true,
+                });
+                return spec;
+            }
+        }
+        spec.optional = optional;
+        spec.name = name;
+        tokens.name = nameToken;
+        if (defaultValue !== undefined)
+            spec.default = defaultValue;
+        [tokens.postName, tokens.description] = splitSpace(source.slice(tokens.name.length));
+        return spec;
+    };
+}

package/es6/parser/tokenizers/tag.d.ts

@@ -0,0 +1,6 @@
+import { Tokenizer } from './index';
+/**
+ * Splits the `@prefix` from remaining `Spec.lines[].token.descrioption` into the `tag` token,
+ * and populates `spec.tag`
+ */
+export default function tagTokenizer(): Tokenizer;

package/es6/parser/tokenizers/tag.js

@@ -0,0 +1,24 @@
+/**
+ * Splits the `@prefix` from remaining `Spec.lines[].token.descrioption` into the `tag` token,
+ * and populates `spec.tag`
+ */
+export default function tagTokenizer() {
+    return (spec) => {
+        const { tokens } = spec.source[0];
+        const match = tokens.description.match(/\s*(@(\S+))(\s*)/);
+        if (match === null) {
+            spec.problems.push({
+                code: 'spec:tag:prefix',
+                message: 'tag should start with "@" symbol',
+                line: spec.source[0].number,
+                critical: true,
+            });
+            return spec;
+        }
+        tokens.tag = match[1];
+        tokens.postTag = match[3];
+        tokens.description = tokens.description.slice(match[0].length);
+        spec.tag = match[2];
+        return spec;
+    };
+}