jsdoc/node_modules/catharsis/package.json

{
  "version": "0.4.2",
  "name": "catharsis",
  "description": "A JavaScript parser for Google Closure Compiler type expressions.",
  "author": {
    "name": "Jeff Williams",
    "email": "jeffrey.l.williams@gmail.com"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/hegemonic/catharsis"
  },
  "bugs": "https://github.com/hegemonic/catharsis/issues",
  "main": "catharsis.js",
  "devDependencies": {
    "mocha": "1.6.0",
    "pegjs": "git+ssh://git@github.com:dmajda/pegjs.git#76cc5d55",
    "should": "1.2.2",
    "underscore": "1.4.4"
  },
  "engines": {
    "node": ">= 0.6"
  },
  "scripts": {
    "prepublish": "pegjs ./lib/parser.pegjs",
    "test": "mocha"
  },
  "licenses": [
    {
      "type": "MIT",
      "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.<string>` and\n`Array<string>` 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.<string>`).\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 (`&lt;`). **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.<string>`).\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@"
}