brut-js 0.16.0-pre → 0.17.0

package/docs/node_modules/catharsis/README.md

@@ -0,0 +1,393 @@
+# Catharsis
+
+[![Build Status][travis-img]][travis-url]
+
+[travis-img]: https://travis-ci.com/hegemonic/catharsis.svg?branch=master
+[travis-url]: https://travis-ci.com/hegemonic/catharsis
+
+A JavaScript parser for
+[Google Closure Compiler](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#type-expressions)
+and [JSDoc](https://github.com/jsdoc/jsdoc) type expressions.
+
+Catharsis is designed to be:
+
++ **Accurate**. Catharsis is based on a [PEG.js](https://pegjs.org/) grammar
+that's designed to handle any valid type expression. It uses a thorough test
+suite to verify the parser's accuracy.
++ **Fast**. Parse results are cached, so the parser is invoked only when
+necessary.
++ **Flexible**. Catharsis can convert a parse result back into a type
+expression, or into a description of the type expression. In addition, Catharsis
+can parse [JSDoc](https://github.com/jsdoc/jsdoc)-style type expressions.
+
+
+## Example
+
+```js
+const catharsis = require('catharsis');
+
+// Closure Compiler parsing
+const type = '!Object';
+let parsedType;
+try {
+    parsedType = catharsis.parse(type); // {"type":"NameExpression,"name":"Object","nullable":false}
+} catch(e) {
+    console.error('unable to parse %s: %s', type, e);
+}
+
+// JSDoc-style type expressions enabled
+const jsdocType = 'string[]';  // Closure Compiler expects Array.<string>
+let parsedJsdocType;
+try {
+    parsedJsdocType = catharsis.parse(jsdocType, {jsdoc: true});
+} catch (e) {
+    console.error('unable to parse %s: %s', jsdocType, e);
+}
+
+// Converting parse results back to type expressions
+catharsis.stringify(parsedType);                              // !Object
+catharsis.stringify(parsedJsdocType);                         // string[]
+catharsis.stringify(parsedJsdocType, {restringify: true});    // Array.<string>
+
+// Converting parse results to descriptions of the type expression
+catharsis.describe(parsedType).simple;                        // non-null Object
+catharsis.describe(parsedJsdocType).simple;                   // Array of string
+```
+
+See the
+[`test/specs` directory](https://github.com/hegemonic/catharsis/tree/master/test/specs)
+for more examples of Catharsis' parse results.
+
+## Methods
+
+### `parse(typeExpression, options)`
+
+Parse a type expression, and return the parse results. Throws an error if the
+type expression cannot be parsed.
+
+When called without options, Catharsis attempts to parse type expressions in the
+same way as Closure Compiler. When the `jsdoc` option is enabled, Catharsis can
+also parse several kinds of type expressions that are permitted in
+[JSDoc](https://github.com/jsdoc/jsdoc):
+
++ The string `function` is treated as a function type with no parameters.
++ You can omit the period from type applications. For example,
+`Array.<string>` and `Array<string>` are parsed in the same way.
++ If can append `[]` to a name expression (for example, `string[]`), it is
+interpreted as a type application with the expression `Array` (for example,
+`Array.<string>`).
++ Name expressions can contain the characters `#`, `~`, `:`, and `/`.
++ Name expressions can contain a suffix that is similar to a function signature
+(for example, `MyClass(foo, bar)`).
++ Name expressions can contain a reserved word.
++ Record types can use types other than name expressions for keys.
+
+#### Parameters
+
++ `type`: A string containing a Closure Compiler type expression.
++ `options`: Options for parsing the type expression.
+    + `options.jsdoc`: Specifies whether to enable parsing of JSDoc-style type
+    expressions. Defaults to `false`.
+    + `options.useCache`: Specifies whether to use the cache of parsed types.
+    Defaults to `true`.
+
+#### Returns
+
+An object containing the parse results. See the
+[`test/specs` directory](https://github.com/hegemonic/catharsis/tree/master/test/specs)
+for examples of the parse results for different type expressions.
+
+The object also includes two non-enumerable properties:
+
++ `jsdoc`: A boolean that indicates whether the type expression was parsed with
+JSDoc support enabled.
++ `typeExpression`: A string that contains the type expression that was parsed.
+
+### `stringify(parsedType, options)`
+
+Stringify `parsedType`, and return the type expression. If validation is
+enabled, throws an error if the stringified type expression cannot be parsed.
+
+#### Parameters ####
++ `parsedType`: An object containing a parsed Closure Compiler type expression.
++ `options`: Options for stringifying the parse results.
+    + `options.cssClass`: Synonym for `options.linkClass`. Deprecated in version
+    0.8.0; will be removed in a future version.
+    + `options.htmlSafe`: Specifies whether to return an HTML-safe string that
+    replaces left angle brackets (`<`) with the corresponding entity (`&lt;`).
+    **Note**: Characters in name expressions are not escaped.
+    + `options.linkClass`: A CSS class to add to HTML links. Used only if
+    `options.links` is provided. By default, no CSS class is added.
+    + `options.links`: An object or map whose keys are name expressions and
+    whose values are URIs. If a name expression matches a key in
+    `options.links`, the name expression will be wrapped in an HTML `<a>` tag
+    that links to the URI. If you also specify `options.linkClass`, the `<a>`
+    tag includes a `class` attribute. **Note**: When using this option, parsed
+    types are always restringified, and the resulting string is not cached.
+    + `options.restringify`: Forces Catharsis to restringify the parsed type. If
+    this option is not specified, and the parsed type object includes a
+    `typeExpression` property, Catharsis returns the `typeExpression` property
+    without modification when possible. Defaults to `false`.
+    + `options.useCache`: Specifies whether to use the cache of stringified type
+    expressions. Defaults to `true`.
+    + `options.validate`: Specifies whether to validate the stringified parse
+    results by attempting to parse them as a type expression. If the stringified
+    results are not parsable with the default options, you must also provide the
+    appropriate options to pass to the `parse()` method. Defaults to `false`.
+
+#### Returns
+
+A string containing the type expression.
+
+### `describe(parsedType, options)`
+
+Convert a parsed type to a description of the type expression. This method is
+especially useful if your users are not familiar with the syntax for type
+expressions.
+
+The `describe()` method returns the description in two formats:
+
++ **Simple format**. A string that provides a complete description of the type
+expression.
++ **Extended format**. An object that separates out some of the details about
+the outermost type expression, such as whether the type is optional, nullable,
+or repeatable.
+
+For example, when you call `describe('?function(new:MyObject, string)=')`, the
+method returns the following data:
+
+```js
+{
+  simple: 'optional nullable function(constructs MyObject, string)',
+  extended: {
+    description: 'function(string)',
+    modifiers: {
+      functionNew: 'Returns MyObject when called with new.',
+      functionThis: '',
+      optional: 'Optional.',
+      nullable: 'May be null.',
+      repeatable: ''
+    },
+    returns: ''
+  }
+}
+```
+
+#### Parameters
+
++ `parsedType`: An object containing a parsed Closure Compiler type expression.
++ `options`: Options for creating the description.
+    + `options.codeClass`: A CSS class to add to the tag that is wrapped around
+    type names. Used only if you specify `options.codeTag`. By default, no CSS
+    class is added.
+    + `options.codeTag`: The name of an HTML tag (for example, `code`) to wrap
+    around type names. For example, if this option is set to `code`, the type
+    expression `Array.<string>` would have the simple description
+    `<code>Array</code> of <code>string</code>`.
+    + `options.language`: A string identifying the language in which to generate
+    the description. The identifier should be an
+    [ISO 639-1 language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
+    (for example, `en`). It can optionally be followed by a hyphen and an
+    [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
+    (for example, `en-US`). If you use values other than `en`, you must provide
+    translation resources in `options.resources`. Defaults to `en`.
+    + `options.linkClass`: A CSS class to add to HTML links. Used only if
+    `options.links` is provided. By default, no CSS class is added.
+    + `options.links`: An object or map whose keys are name expressions and
+    whose values are URIs. If a name expression matches a key in
+    `options.links`, the name expression will be wrapped in an HTML `<a>` tag
+    that links to the URI. If you also specify `options.linkClass`, the `<a>`
+    tag includes a `class` attribute. **Note**: When you use this option, the
+    description is not cached.
+    + `options.resources`: An object that specifies how to describe type
+    expressions for a given language. The object's property names should use the
+    same format as `options.language`. Each property should contain an object in
+    the same format as the translation resources in
+    [`res/en.json`](https://github.com/hegemonic/catharsis/blob/master/res/en.json).
+    If you specify a value for `options.resources.en`, that value overrides the
+    defaults in `res/en.json`.
+    + `options.useCache`: Specifies whether to use the cache of descriptions.
+    Defaults to `true`.
+
+### Returns
+
+An object with the following properties:
+
++ `simple`: A string that provides a complete description of the type
+expression.
++ `extended`: An object containing details about the outermost type expression.
+    + `extended.description`: A string that provides a basic description of the
+    type expression, excluding the information contained in other properties.
+    + `extended.modifiers`: Information about modifiers that apply to the type
+    expression.
+        + `extended.modifiers.functionNew`: A string that describes what a
+        function returns when called with `new`. Returned only for function
+        types.
+        + `extended.modifiers.functionThis`: A string that describes what the
+        keyword `this` refers to within a function. Returned only for function
+        types.
+        + `extended.modifiers.nullable`: A string that indicates whether the
+        type is nullable or non-nullable.
+        + `extended.modifiers.optional`: A string that indicates whether the
+        type is optional.
+        + `extended.modifiers.repeatable`: A string that indicates whether the
+        type can be repeated.
+    + `extended.returns`: A string that describes the function's return value.
+    Returned only for function types.
+
+## Changelog
+
++ 0.9.0 (June 2020):
+    + For the `describe()` and `stringify()` methods, the `options.links`
+    parameter now accepts either a map or an object.
+    + Catharsis now requires Node.js 10 or later.
++ 0.8.11 (July 2019): Updated dependencies.
++ 0.8.10 (May 2019): Updated dependencies.
++ 0.8.9 (July 2017): Type expressions that include an `@` sign (for example,
+`module:@prefix/mymodule~myCallback`) are now supported.
++ 0.8.8 (April 2016): Corrected the description of type applications other than
+arrays that contain a single type (for example, `Promise.<string>`).
++ 0.8.7 (June 2015):
+    + Record types that use numeric literals as property names (for example,
+    `{0: string}`) are now parsed correctly.
+    + Record types with a property that contains a function, with no space after
+    the preceding colon (for example, `{foo:function()}`), are now parsed
+    correctly.
+    + Repeatable function parameters are no longer required to be enclosed in
+    brackets, regardless of whether JSDoc-style type expressions are enabled. In
+    addition, the brackets are omitted when stringifying a parsed type
+    expression.
++ 0.8.6 (December 2014): Improved the description of the unknown type.
++ 0.8.5 (December 2014): Added support for postfix nullable/non-nullable
+operators combined with the optional operator (for example, `foo?=`).
++ 0.8.4 (December 2014): JSDoc-style nested arrays (for example, `number[][]`)
+are now parsed correctly when JSDoc-style type expressions are enabled.
++ 0.8.3 (October 2014):
+    + Type applications are no longer required to include a period (`.`) as a
+    separator, regardless of whether JSDoc-style type expressions are enabled.
+    + Type unions that are not enclosed in parentheses can now include the
+    repeatable (`...`) modifier when JSDoc-style type expressions are enabled.
+    + Name expressions may now be enclosed in single or double quotation marks
+    when JSDoc-style type expressions are enabled.
++ 0.8.2 (June 2014): Fixed a compatibility issue with the JSDoc fork of Mozilla
+Rhino.
++ 0.8.1 (June 2014): Added support for type unions that are not enclosed in
+parentheses, and that contain nullable or non-nullable modifiers (for example,
+`!string|!number`).
++ 0.8.0 (May 2014):
+    + Added a `describe()` method, which converts a parsed type to a description
+    of the type.
+    + Added a `linkClass` option to the `stringify()` method, and deprecated the
+    existing `cssClass` option. The `cssClass` option will be removed in a
+    future release.
+    + Clarified and corrected several sections in the `README`.
++ 0.7.1 (April 2014): In record types, property names that begin with a keyword
+(for example, `undefinedHTML`) are now parsed correctly when JSDoc-style type
+expressions are enabled.
++ 0.7.0 (October 2013):
+    + Repeatable type expressions other than name expressions (for example,
+    `...function()`) are now parsed and stringified correctly.
+    + Type expressions that are both repeatable and either nullable or
+    non-nullable (for example, `...!number`) are now parsed and stringified
+    correctly.
+    + Name expressions are now parsed correctly when they match a property name
+    in an object instance (for example, `constructor`).
++ 0.6.0 (September 2013): Added support for the type expression `function[]`
+when JSDoc-style type expressions are enabled.
++ 0.5.6 (April 2013):
+    + For consistency with Closure Compiler, parentheses are no longer required
+    around type unions, regardless of whether JSDoc-style type expressions are
+    enabled.
+    + For consistency with Closure Compiler, you can now use postfix notation
+    for the `?` (nullable) and `!` (non-nullable) modifiers. For example,
+    `?string` and `string?` are now treated as equivalent.
+    + String literals and numeric literals are now allowed as property names
+    within name expressions. For example, the name expression `Foo."bar"` is now
+    parsed correctly.
++ 0.5.5 (April 2013): Corrected a parsing issue with name expressions that end
+with a value enclosed in parentheses.
++ 0.5.4 (April 2013):
+    + Repeatable literals (for example, `...*`) are now parsed correctly.
+    + When JSDoc-style type expressions are enabled, a name expression can now
+    contain a value enclosed in parentheses at the end of the name expression
+    (for example, `MyClass(2)`).
++ 0.5.3 (March 2013): The `parse()` method now correctly parses name expressions
+that contain hyphens.
++ 0.5.2 (March 2013): The `parse()` method now correctly parses function types
+when JSDoc-style type expressions are enabled.
++ 0.5.1 (March 2013): Newlines and extra spaces are now removed from type
+expressions before they are parsed.
++ 0.5.0 (March 2013):
+    + The `parse()` method's `lenient` option has been renamed to `jsdoc`.
+    **Note**: This change is not backwards-compatible with previous versions.
+    + The `stringify()` method now accepts `cssClass` and `links` options, which
+    you can use to add HTML links to a type expression.
++ 0.4.3 (March 2013):
+    + The `stringify()` method no longer caches HTML-safe type expressions as if
+    they were normal type expressions.
+    + The `stringify()` method's options parameter may now include an
+    `options.restringify` property, and the behavior of the `options.useCache`
+    property has changed.
++ 0.4.2 (March 2013):
+    + When lenient parsing is enabled, name expressions can now contain the
+    characters `:` and `/`.
+    + When lenient parsing is enabled, a name expression followed by `[]` (for
+    example, `string[]`) will be interpreted as a type application with the
+    expression `Array` (for example, `Array.<string>`).
++ 0.4.1 (March 2013):
+    + The `parse()` and `stringify()` methods now honor all of the specified
+    options.
+    + When lenient parsing is enabled, name expressions can now contain a
+    reserved word.
++ 0.4.0 (March 2013):
+    + Catharsis now supports a lenient parsing option that can parse several
+    kinds of malformed type expressions. See the documentation for details.
+    + The objects containing parse results are now frozen.
+    + The objects containing parse results now have two non-enumerable
+    properties:
+        + `lenient`: A boolean indicating whether the type expression was parsed
+        in lenient mode.
+        + `typeExpression`: A string containing the original type expression.
+    + The `stringify()` method now honors the `useCache` option. If a parsed
+    type includes a `typeExpression` property, and `useCache` is not set to
+    `false`, the stringified type will be identical to the original type
+    expression.
++ 0.3.1 (March 2013): Type expressions that begin with a reserved word, such as
+`integer`, are now parsed correctly.
++ 0.3.0 (March 2013):
+    + The `parse()` and `stringify()` methods are now synchronous, and the
+    `parseSync()` and `stringifySync()` methods have been removed. **Note**:
+    This change is not backwards-compatible with previous versions.
+    + The parse results now use a significantly different format from previous
+    versions. The new format is more expressive and is similar, but not
+    identical, to the format used by the
+    [doctrine](https://github.com/eslint/doctrine) parser. **Note**: This change
+    is not backwards-compatible with previous versions.
+    + Name expressions that contain a reserved word now include a
+    `reservedWord: true` property.
+    + Union types that are optional or nullable, or that can be repeated, are
+    now parsed and stringified correctly.
+    + Optional function types and record types are now parsed and stringified
+    correctly.
+    + Function types now longer include `new` or `this` properties unless the
+    properties are defined in the type expression. In addition, the `new` and
+    `this` properties can now use any type expression.
+    + In record types, the key for a field type can now use any type expression.
+    + Standalone single-character literals, such as ALL (`*`), are now parsed
+    and stringified correctly.
+    + `null` and `undefined` literals with additional properties, such as
+    `repeatable`, are now stringified correctly.
++ 0.2.0 (November 2012):
+    + Added `stringify()` and `stringifySync()` methods, which convert a parsed
+    type to a type expression.
+    + Simplified the parse results for function signatures. **Note**: This
+    change is not backwards-compatible with previous versions.
+    + Corrected minor errors in README.md.
++ 0.1.1 (November 2012): Added `opts` argument to `parse()` and `parseSync()`
+methods. **Note**: The change to `parse()` is not backwards-compatible with
+previous versions.
++ 0.1.0 (November 2012): Initial release.
+
+## License
+
+[MIT license](https://github.com/hegemonic/catharsis/blob/master/LICENSE).

package/docs/node_modules/catharsis/bin/parse.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+// Command-line tool that parses a type expression and dumps a JSON version of the parse tree.
+const catharsis = require('../catharsis');
+const path = require('path');
+const util = require('util');
+
+const command = path.basename(process.argv[1]);
+const typeExpression = process.argv[2];
+const opts = {
+    describe: false,
+    jsdoc: false
+};
+let parsedType;
+
+function usage() {
+    console.log(util.format('Usage:\n    %s typeExpression [--jsdoc] [--describe]', command));
+}
+
+function done(err) {
+    /* eslint-disable no-process-exit */
+    process.exit(err === undefined ? 0 : err);
+    /* eslint-enable no-process-exit */
+}
+
+process.argv.slice(3).forEach(arg => {
+    const parsedArg = arg.replace(/^-{2}/, '');
+
+    if (opts[parsedArg] !== undefined) {
+        opts[parsedArg] = true;
+    } else {
+        console.error('Unknown option "%s"', arg);
+        usage();
+        done(1);
+    }
+});
+
+if (!typeExpression) {
+    usage();
+    done(1);
+} else {
+    try {
+        parsedType = catharsis.parse(typeExpression, opts);
+        if (opts.describe) {
+            parsedType = catharsis.describe(parsedType);
+        }
+    } catch (e) {
+        console.error(util.format('Unable to parse "%s" (exception follows):', typeExpression));
+        console.error(e.stack || e.message);
+        done(1);
+    }
+
+    console.log(JSON.stringify(parsedType, null, 2));
+    done();
+}

package/docs/node_modules/catharsis/catharsis.js

@@ -0,0 +1,169 @@
+/**
+ * Catharsis
+ * A parser for Google Closure Compiler type expressions, powered by PEG.js.
+ *
+ * @author Jeff Williams <jeffrey.l.williams@gmail.com>
+ * @license MIT
+ */
+
+const describe = require('./lib/describe');
+const { parse } = require('./lib/parser');
+const stringify = require('./lib/stringify');
+
+const typeExpressionCache = {
+    normal: new Map(),
+    jsdoc: new Map()
+};
+
+const parsedTypeCache = {
+    normal: new Map(),
+    htmlSafe: new Map()
+};
+
+const descriptionCache = {
+    normal: new Map()
+};
+
+function getTypeExpressionCache({useCache, jsdoc}) {
+    if (useCache === false) {
+        return null;
+    } else if (jsdoc === true) {
+        return typeExpressionCache.jsdoc;
+    } else {
+        return typeExpressionCache.normal;
+    }
+}
+
+function getParsedTypeCache({useCache, links, htmlSafe}) {
+    if (useCache === false || links !== null || links !== undefined) {
+        return null;
+    } else if (htmlSafe === true) {
+        return parsedTypeCache.htmlSafe;
+    } else {
+        return parsedTypeCache.normal;
+    }
+}
+
+function getDescriptionCache({useCache, links}) {
+    if (useCache === false || links !== null || links !== undefined) {
+        return null;
+    } else {
+        return descriptionCache.normal;
+    }
+}
+
+// can't return the original if any of the following are true:
+// 1. restringification was requested
+// 2. htmlSafe option was requested
+// 3. links option was provided
+// 4. typeExpression property is missing
+function canReturnOriginalExpression(parsedType, {restringify, htmlSafe, links}) {
+    return restringify !== true && htmlSafe !== true &&
+        (links === null || links === undefined) &&
+        Object.prototype.hasOwnProperty.call(parsedType, 'typeExpression');
+}
+
+// Add non-enumerable properties to a result object, then freeze it.
+function prepareFrozenObject(obj, expr, {jsdoc}) {
+    Object.defineProperty(obj, 'jsdoc', {
+        value: jsdoc === true ? jsdoc : false
+    });
+
+    if (expr) {
+        Object.defineProperty(obj, 'typeExpression', {
+            value: expr
+        });
+    }
+
+    return Object.freeze(obj);
+}
+
+function cachedParse(expr, options) {
+    const cache = getTypeExpressionCache(options);
+    let parsedType = cache ? cache.get(expr) : null;
+
+    if (parsedType) {
+        return parsedType;
+    } else {
+        parsedType = parse(expr, options);
+        parsedType = prepareFrozenObject(parsedType, expr, options);
+
+        if (cache) {
+            cache.set(expr, parsedType);
+        }
+
+        return parsedType;
+    }
+}
+
+function cachedStringify(parsedType, options) {
+    const cache = getParsedTypeCache(options);
+    let stringified;
+
+    if (canReturnOriginalExpression(parsedType, options)) {
+        return parsedType.typeExpression;
+    } else if (cache) {
+        stringified = cache.get(parsedType);
+        if (!stringified) {
+            stringified = stringify(parsedType, options);
+            cache.set(parsedType, stringified);
+        }
+
+        return stringified;
+    } else {
+        return stringify(parsedType, options);
+    }
+}
+
+function cachedDescribe(parsedType, options) {
+    const cache = getDescriptionCache(options);
+    let description = cache ? cache.get(parsedType) : null;
+
+    if (description) {
+        return description;
+    } else {
+        description = describe(parsedType, options);
+        description = prepareFrozenObject(description, null, options);
+
+        if (cache) {
+            cache.set(parsedType, description);
+        }
+
+        return description;
+    }
+}
+
+/* eslint-disable class-methods-use-this */
+class Catharsis {
+    constructor() {
+        this.Types = require('./lib/types');
+    }
+
+    parse(typeExpr, options = {}) {
+        typeExpr = typeExpr.replace(/[\r\n]/g, '')
+            .replace(/\s+/g, ' ')
+            .trim();
+
+        return cachedParse(typeExpr, options);
+    }
+
+    stringify(parsedType, options) {
+        let result;
+
+        options = options || {};
+
+        result = cachedStringify(parsedType, options);
+        if (options.validate) {
+            this.parse(result, options);
+        }
+
+        return result;
+    }
+
+    describe(parsedType, options = {}) {
+        return cachedDescribe(parsedType, options);
+    }
+}
+/* eslint-enable class-methods-use-this */
+
+module.exports = new Catharsis();