diff --git a/node_modules/catharsis/catharsis.js b/node_modules/catharsis/catharsis.js index 2ac252b6..9f1c9cfb 100644 --- a/node_modules/catharsis/catharsis.js +++ b/node_modules/catharsis/catharsis.js @@ -11,17 +11,46 @@ var parse = require('./lib/parser').parse; var stringify = require('./lib/stringify'); -var typeExpressionCache = {}; -var lenientTypeExpressionCache = {}; +var typeExpressionCache = { + normal: {}, + lenient: {} +}; -var parsedTypeCache = {}; -var lenientParsedTypeCache = {}; +var parsedTypeCache = { + normal: {}, + htmlSafe: {} +}; + +function getTypeExpressionCache(options) { + if (options.useCache === false) { + return null; + } else if (options.lenient === true) { + return typeExpressionCache.lenient; + } else { + return typeExpressionCache.normal; + } +} + +function getParsedTypeCache(options) { + if (options.useCache === false) { + return null; + } else if (options.htmlSafe === true) { + return parsedTypeCache.htmlSafe; + } else { + return parsedTypeCache.normal; + } +} + +function canReturnOriginalExpression(parsedType, options) { + return options.restringify !== true && options.htmlSafe !== true && + Object.prototype.hasOwnProperty.call(parsedType, 'typeExpression'); +} function cachedParse(expr, options) { - var cache = options.lenient ? lenientTypeExpressionCache : typeExpressionCache; + var cache = getTypeExpressionCache(options); var parsedType; - if (options.useCache !== false && cache[expr]) { + if (cache && cache[expr]) { return cache[expr]; } else { parsedType = parse(expr, options); @@ -36,7 +65,7 @@ function cachedParse(expr, options) { }); parsedType = Object.freeze(parsedType); - if (options.useCache !== false) { + if (cache) { cache[expr] = parsedType; } @@ -45,14 +74,12 @@ function cachedParse(expr, options) { } function cachedStringify(parsedType, options) { - var cache = options.lenient ? lenientParsedTypeCache : parsedTypeCache; + var cache = getParsedTypeCache(options); var json; - if (options.useCache !== false && Object.prototype.hasOwnProperty.call(parsedType, - 'typeExpression')) { - // return the original type expression + if (canReturnOriginalExpression(parsedType, options)) { return parsedType.typeExpression; - } else if (options.useCache !== false) { + } else if (cache) { json = JSON.stringify(parsedType); cache[json] = cache[json] || stringify(parsedType, options); return cache[json]; diff --git a/node_modules/catharsis/package.json b/node_modules/catharsis/package.json index 226a4cd7..03729ebe 100644 --- a/node_modules/catharsis/package.json +++ b/node_modules/catharsis/package.json @@ -1,5 +1,5 @@ { - "version": "0.4.2", + "version": "0.4.3", "name": "catharsis", "description": "A JavaScript parser for Google Closure Compiler type expressions.", "author": { @@ -31,8 +31,12 @@ "url": "http://github.com/hegemonic/catharsis/raw/master/LICENSE" } ], - "readme": "# Catharsis #\n\nA JavaScript parser for Google Closure Compiler\n[type expressions](https://developers.google.com/closure/compiler/docs/js-for-compiler#types).\n\nCatharsis is designed to be:\n\n+ **Accurate**. Catharsis is based on a [PEG.js](http://pegjs.majda.cz/) grammar that's designed to\nhandle any valid type expression. It uses a [Mocha](http://visionmedia.github.com/mocha/) test suite\nto verify the parser's accuracy.\n+ **Fast**. Parse results are cached, so the parser is invoked only when necessary.\n+ **Flexible**. Catharsis can convert parse results back into type expressions. In addition, it\nprovides a lenient mode that also accepts [JSDoc](https://github.com/jsdoc3/jsdoc)-style type\nexpressions.\n\n\n## Example ##\n\n\tvar catharsis = require('catharsis');\n\n var type;\n var jsdocType;\n\tvar parsedType;\n var parsedJsdocType;\n\n // normal parsing\n\ttry {\n type = '!Object';\n\t\tparsedType = catharsis.parse(type);\n\t\tconsole.log('%j', parsedType); // {\"type\":\"NameExpression,\"name\":\"Object\",\"nullable\":false}\n\t}\n\tcatch(e) {\n\t\tconsole.error('unable to parse %s: %s', type, e);\n\t}\n\n // lenient parsing\n try {\n jsdocType = 'number|string'; // should be (number|string)\n parsedJsdocType = catharsis.parse(jsdocType, {lenient: true});\n }\n catch (e) {\n console.error('you will not see this error, thanks to lenient mode!');\n }\n\n console.log(catharsis.stringify(parsedType)); // !Object\n console.log(catharsis.stringify(parsedJsdocType)); // number|string\n console.log(catharsis.stringify(parsedJsdocType, // (number|string)\n {useCache: false}));\n\n\nSee the `test/specs/` directory for more examples of Catharsis' parse results.\n\n\n## Methods ##\n\n### parse(type, options) ###\nParse the Closure Compiler type `type`, and return the parse results. Throws an error if the type\ncannot be parsed.\n\nWhen called without options, Catharsis attempts to parse type expressions in the same way as\nClosure Compiler. When the `lenient` option is enabled, Catharsis can also parse several kinds of\ntype expressions that are used in [JSDoc](https://github.com/jsdoc3/jsdoc):\n\n+ The string `function` is treated as a function type with no parameters.\n+ The period may be omitted from type applications. For example, `Array.` and\n`Array` will be parsed in the same way.\n+ You may append `[]` to a name expression (for example, `string[]`) to interpret it as a type\napplication with the expression `Array` (for example, `Array.`).\n+ The enclosing parentheses may be omitted from type unions. For example, `(number|string)` and\n`number|string` will be parsed in the same way.\n+ Name expressions may contain the characters `#`, `~`, `:`, and `/`.\n+ Name expressions may contain a reserved word.\n+ Record types may use types other than name expressions for keys.\n\n#### Parameters ####\n+ `type`: A string containing a Closure Compiler type expression.\n+ `options`: Options for parsing the type expression.\n + `options.lenient`: Specifies whether to enable lenient mode. Defaults to `false`.\n + `options.useCache`: Specifies whether to use the cache of parsed types. Defaults to `true`.\n\n#### Returns ####\nAn object containing the parse results. See the `test/specs/` directory for examples of the parse\nresults for different type expressions.\n\nThe object also includes two non-enumerable properties:\n\n+ `lenient`: A boolean indicating whether the type expression was parsed in lenient mode.\n+ `typeExpression`: A string containing the type expression that was parsed.\n\n### stringify(parsedType, options) ###\nStringify the parsed Closure Compiler type expression `parsedType`, and return the type expression.\nIf validation is enabled, throws an error if the stringified type expression cannot be parsed.\n\n#### Parameters ####\n+ `parsedType`: An object containing a parsed Closure Compiler type expression.\n+ `options`: Options for stringifying the parse results.\n + `options.htmlSafe`: Specifies whether to return an HTML-safe string that replaces left angle\n brackets (`<`) with the corresponding entity (`<`). **Note**: Characters in name expressions\n are not escaped.\n + `options.useCache`: Specifies whether to use the cache of stringified parse results. If the\n cache is enabled, and the parsed type expression includes a `typeExpression` property, the\n `typeExpression` property will be returned as-is. Defaults to `true`.\n + `options.validate`: Specifies whether to validate the stringified parse results by attempting\n to parse them as a type expression. Defaults to `false`.\n\n#### Returns ####\nA string containing the type expression.\n\n\n## Installation ##\n\nWith [npm](http://npmjs.org):\n\n npm install catharsis\n\nOr without:\n\n git clone git://github.com/hegemonic/catharsis.git\n\n\n## Roadmap and known issues ##\n\nTake a look at the [issue tracker](https://github.com/hegemonic/catharsis/issues) to see what's in\nstore for Catharsis.\n\nBug reports, feature requests, and pull requests are always welcome! If you're working on a large\npull request, please contact me in advance so I can help things go smoothly.\n\n**Note**: The parse tree's format should not be considered final until Catharsis reaches version\n1.0. I'll do my best to provide release notes for any changes.\n\n\n## Changelog ##\n\n+ 0.4.2 (March 2013):\n + When lenient parsing is enabled, name expressions can now contain the characters `:` and `/`.\n + When lenient parsing is enabled, a name expression followed by `[]` (for example, `string[]`)\n will be interpreted as a type application with the expression `Array` (for example,\n `Array.`).\n+ 0.4.1 (March 2013):\n + The `parse()` and `stringify()` methods now honor all of the specified options.\n + When lenient parsing is enabled, name expressions can now contain a reserved word.\n+ 0.4.0 (March 2013):\n + Catharsis now supports a lenient parsing option that can parse several kinds of malformed type\n expressions. See the documentation for details.\n + The objects containing parse results are now frozen.\n + The objects containing parse results now have two non-enumerable properties:\n + `lenient`: A boolean indicating whether the type expression was parsed in lenient mode.\n + `typeExpression`: A string containing the original type expression.\n + The `stringify()` method now honors the `useCache` option. If a parsed type includes a\n `typeExpression` property, and `useCache` is not set to `false`, the stringified type will be\n identical to the original type expression.\n+ 0.3.1 (March 2013): Type expressions that begin with a reserved word, such as `integer`, are now\nparsed correctly.\n+ 0.3.0 (March 2013):\n + The `parse()` and `stringify()` methods are now synchronous, and the `parseSync()` and\n `stringifySync()` methods have been removed. **Note**: This change is not backwards-compatible\n with previous versions.\n + The parse results now use a significantly different format from previous versions. The new\n format is more expressive and is similar, but not identical, to the format used by the\n [doctrine](https://github.com/Constellation/doctrine) parser. **Note**: This change is not\n backwards-compatible with previous versions.\n + Name expressions that contain a reserved word now include a `reservedWord: true` property.\n + Union types that are optional or nullable, or that can be passed a variable number of times,\n are now parsed and stringified correctly.\n + Optional function types and record types are now parsed and stringified correctly.\n + Function types now longer include `new` or `this` properties unless the properties are defined\n in the type expression. In addition, the `new` and `this` properties can now use any type\n expression.\n + In record types, the key for a field type can now use any type expression.\n + Standalone single-character literals, such as ALL (`*`), are now parsed and stringified\n correctly.\n + `null` and `undefined` literals with additional properties, such as `repeatable`, are now\n stringified correctly.\n+ 0.2.0 (November 2012):\n + Added `stringify()` and `stringifySync()` methods, which convert a parsed type to a type\n expression.\n + Simplified the parse results for function signatures. **Note**: This change is not\n backwards-compatible with previous versions.\n + Corrected minor errors in README.md.\n+ 0.1.1 (November 2012): Added `opts` argument to `parse()` and `parseSync()` methods. **Note**: The\nchange to `parse()` is not backwards-compatible with previous versions.\n+ 0.1.0 (November 2012): Initial release.\n\n## License ##\n\n[MIT license](https://github.com/hegemonic/catharsis/blob/master/LICENSE).\n", + "readme": "# Catharsis #\n\nA JavaScript parser for Google Closure Compiler\n[type expressions](https://developers.google.com/closure/compiler/docs/js-for-compiler#types).\n\nCatharsis is designed to be:\n\n+ **Accurate**. Catharsis is based on a [PEG.js](http://pegjs.majda.cz/) grammar that's designed to\nhandle any valid type expression. It uses a [Mocha](http://visionmedia.github.com/mocha/) test suite\nto verify the parser's accuracy.\n+ **Fast**. Parse results are cached, so the parser is invoked only when necessary.\n+ **Flexible**. Catharsis can convert parse results back into type expressions. In addition, it\nprovides a lenient mode that also accepts [JSDoc](https://github.com/jsdoc3/jsdoc)-style type\nexpressions.\n\n\n## Example ##\n\n\tvar catharsis = require('catharsis');\n\n var type;\n var jsdocType;\n\tvar parsedType;\n var parsedJsdocType;\n\n // normal parsing\n\ttry {\n type = '!Object';\n\t\tparsedType = catharsis.parse(type);\n\t\tconsole.log('%j', parsedType); // {\"type\":\"NameExpression,\"name\":\"Object\",\"nullable\":false}\n\t}\n\tcatch(e) {\n\t\tconsole.error('unable to parse %s: %s', type, e);\n\t}\n\n // lenient parsing\n try {\n jsdocType = 'number|string'; // should be (number|string)\n parsedJsdocType = catharsis.parse(jsdocType, {lenient: true});\n }\n catch (e) {\n console.error('you will not see this error, thanks to lenient mode!');\n }\n\n console.log(catharsis.stringify(parsedType)); // !Object\n console.log(catharsis.stringify(parsedJsdocType)); // number|string\n console.log(catharsis.stringify(parsedJsdocType, // (number|string)\n {restringify: true}));\n\n\nSee the `test/specs/` directory for more examples of Catharsis' parse results.\n\n\n## Methods ##\n\n### parse(type, options) ###\nParse the Closure Compiler type `type`, and return the parse results. Throws an error if the type\ncannot be parsed.\n\nWhen called without options, Catharsis attempts to parse type expressions in the same way as\nClosure Compiler. When the `lenient` option is enabled, Catharsis can also parse several kinds of\ntype expressions that are used in [JSDoc](https://github.com/jsdoc3/jsdoc):\n\n+ The string `function` is treated as a function type with no parameters.\n+ The period may be omitted from type applications. For example, `Array.` and\n`Array` will be parsed in the same way.\n+ You may append `[]` to a name expression (for example, `string[]`) to interpret it as a type\napplication with the expression `Array` (for example, `Array.`).\n+ The enclosing parentheses may be omitted from type unions. For example, `(number|string)` and\n`number|string` will be parsed in the same way.\n+ Name expressions may contain the characters `#`, `~`, `:`, and `/`.\n+ Name expressions may contain a reserved word.\n+ Record types may use types other than name expressions for keys.\n\n#### Parameters ####\n+ `type`: A string containing a Closure Compiler type expression.\n+ `options`: Options for parsing the type expression.\n + `options.lenient`: Specifies whether to enable lenient mode. Defaults to `false`.\n + `options.useCache`: Specifies whether to use the cache of parsed types. Defaults to `true`.\n\n#### Returns ####\nAn object containing the parse results. See the `test/specs/` directory for examples of the parse\nresults for different type expressions.\n\nThe object also includes two non-enumerable properties:\n\n+ `lenient`: A boolean indicating whether the type expression was parsed in lenient mode.\n+ `typeExpression`: A string containing the type expression that was parsed.\n\n### stringify(parsedType, options) ###\nStringify the parsed Closure Compiler type expression `parsedType`, and return the type expression.\nIf validation is enabled, throws an error if the stringified type expression cannot be parsed.\n\n#### Parameters ####\n+ `parsedType`: An object containing a parsed Closure Compiler type expression.\n+ `options`: Options for stringifying the parse results.\n + `options.htmlSafe`: Specifies whether to return an HTML-safe string that replaces left angle\n brackets (`<`) with the corresponding entity (`<`). **Note**: Characters in name expressions\n are not escaped.\n + `options.restringify`: Forces Catharsis to restringify the parsed type. If this option is not\n specified, and the parsed type object includes a `typeExpression` property, Catharsis will\n return the `typeExpression` property without modification. Defaults to `false`.\n + `options.useCache`: Specifies whether to use the cache of stringified parse results. Defaults\n to `true`.\n + `options.validate`: Specifies whether to validate the stringified parse results by attempting\n to parse them as a type expression. Defaults to `false`.\n\n#### Returns ####\nA string containing the type expression.\n\n\n## Installation ##\n\nWith [npm](http://npmjs.org):\n\n npm install catharsis\n\nOr without:\n\n git clone git://github.com/hegemonic/catharsis.git\n\n\n## Roadmap and known issues ##\n\nTake a look at the [issue tracker](https://github.com/hegemonic/catharsis/issues) to see what's in\nstore for Catharsis.\n\nBug reports, feature requests, and pull requests are always welcome! If you're working on a large\npull request, please contact me in advance so I can help things go smoothly.\n\n**Note**: The parse tree's format should not be considered final until Catharsis reaches version\n1.0. I'll do my best to provide release notes for any changes.\n\n\n## Changelog ##\n\n+ 0.4.3 (March 2013):\n + The `stringify()` method no longer caches HTML-safe type expressions as if they were normal\n type expressions.\n + The `stringify()` method's options parameter may now include an `options.restringify`\n property, and the behavior of the `options.useCache` property has changed.\n+ 0.4.2 (March 2013):\n + When lenient parsing is enabled, name expressions can now contain the characters `:` and `/`.\n + When lenient parsing is enabled, a name expression followed by `[]` (for example, `string[]`)\n will be interpreted as a type application with the expression `Array` (for example,\n `Array.`).\n+ 0.4.1 (March 2013):\n + The `parse()` and `stringify()` methods now honor all of the specified options.\n + When lenient parsing is enabled, name expressions can now contain a reserved word.\n+ 0.4.0 (March 2013):\n + Catharsis now supports a lenient parsing option that can parse several kinds of malformed type\n expressions. See the documentation for details.\n + The objects containing parse results are now frozen.\n + The objects containing parse results now have two non-enumerable properties:\n + `lenient`: A boolean indicating whether the type expression was parsed in lenient mode.\n + `typeExpression`: A string containing the original type expression.\n + The `stringify()` method now honors the `useCache` option. If a parsed type includes a\n `typeExpression` property, and `useCache` is not set to `false`, the stringified type will be\n identical to the original type expression.\n+ 0.3.1 (March 2013): Type expressions that begin with a reserved word, such as `integer`, are now\nparsed correctly.\n+ 0.3.0 (March 2013):\n + The `parse()` and `stringify()` methods are now synchronous, and the `parseSync()` and\n `stringifySync()` methods have been removed. **Note**: This change is not backwards-compatible\n with previous versions.\n + The parse results now use a significantly different format from previous versions. The new\n format is more expressive and is similar, but not identical, to the format used by the\n [doctrine](https://github.com/Constellation/doctrine) parser. **Note**: This change is not\n backwards-compatible with previous versions.\n + Name expressions that contain a reserved word now include a `reservedWord: true` property.\n + Union types that are optional or nullable, or that can be passed a variable number of times,\n are now parsed and stringified correctly.\n + Optional function types and record types are now parsed and stringified correctly.\n + Function types now longer include `new` or `this` properties unless the properties are defined\n in the type expression. In addition, the `new` and `this` properties can now use any type\n expression.\n + In record types, the key for a field type can now use any type expression.\n + Standalone single-character literals, such as ALL (`*`), are now parsed and stringified\n correctly.\n + `null` and `undefined` literals with additional properties, such as `repeatable`, are now\n stringified correctly.\n+ 0.2.0 (November 2012):\n + Added `stringify()` and `stringifySync()` methods, which convert a parsed type to a type\n expression.\n + Simplified the parse results for function signatures. **Note**: This change is not\n backwards-compatible with previous versions.\n + Corrected minor errors in README.md.\n+ 0.1.1 (November 2012): Added `opts` argument to `parse()` and `parseSync()` methods. **Note**: The\nchange to `parse()` is not backwards-compatible with previous versions.\n+ 0.1.0 (November 2012): Initial release.\n\n## License ##\n\n[MIT license](https://github.com/hegemonic/catharsis/blob/master/LICENSE).\n", "readmeFilename": "README.md", - "_id": "catharsis@0.4.2", - "_from": "catharsis@" + "_id": "catharsis@0.4.3", + "dist": { + "shasum": "707d9450b1e173fa3c6b1247e22951452f2ba34c" + }, + "_from": "catharsis@0.4.3", + "_resolved": "https://registry.npmjs.org/catharsis/-/catharsis-0.4.3.tgz" } diff --git a/package.json b/package.json index 105a0db9..da770812 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,7 @@ ], "dependencies": { "async": "0.1.22", - "catharsis": "0.4.2", + "catharsis": "0.4.3", "crypto-browserify": "git://github.com/dominictarr/crypto-browserify.git#95c5d505", "github-flavored-markdown": "git://github.com/hegemonic/github-flavored-markdown.git", "js2xmlparser": "0.1.0",