A JavaScript parser for
Google Closure Compiler
and JSDoc type expressions.
Catharsis is designed to be:
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 thetest/specs directory
for more examples of Catharsis' parse results.
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:
function is treated as a function type with no parameters.Array.<string> and Array<string> are parsed in the same way.[] to a name expression (for example, string[]), it isArray (for example,Array.<string>).#, ~, :, and /.MyClass(foo, bar)).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 typefalse.options.useCache: Specifies whether to use the cache of parsed types.true.An object containing the parse results. See thetest/specs directory
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 withtypeExpression: 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.
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 versionoptions.htmlSafe: Specifies whether to return an HTML-safe string that<) with the corresponding entity (<).options.linkClass: A CSS class to add to HTML links. Used only ifoptions.links is provided. By default, no CSS class is added.options.links: An object or map whose keys are name expressions andoptions.links, the name expression will be wrapped in an HTML <a> tagoptions.linkClass, the <a>class attribute. Note: When using this option, parsedoptions.restringify: Forces Catharsis to restringify the parsed type. IftypeExpression property, Catharsis returns the typeExpression propertyfalse.options.useCache: Specifies whether to use the cache of stringified typetrue.options.validate: Specifies whether to validate the stringified parseparse() method. Defaults to false.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:
For example, when you call describe('?function(new:MyObject, string)='), the
method returns the following data:
{
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: ''
}
}
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 aroundoptions.codeTag. By default, no CSSoptions.codeTag: The name of an HTML tag (for example, code) to wrapcode, the typeArray.<string> would have the simple description<code>Array</code> of <code>string</code>.options.language: A string identifying the language in which to generateen). It can optionally be followed by a hyphen and anen-US). If you use values other than en, you must provideoptions.resources. Defaults to en.options.linkClass: A CSS class to add to HTML links. Used only ifoptions.links is provided. By default, no CSS class is added.options.links: An object or map whose keys are name expressions andoptions.links, the name expression will be wrapped in an HTML <a> tagoptions.linkClass, the <a>class attribute. Note: When you use this option, theoptions.resources: An object that specifies how to describe typeoptions.language. Each property should contain an object inres/en.json.options.resources.en, that value overrides theres/en.json.options.useCache: Specifies whether to use the cache of descriptions.true.An object with the following properties:
simple: A string that provides a complete description of the typeextended: An object containing details about the outermost type expression.
extended.description: A string that provides a basic description of theextended.modifiers: Information about modifiers that apply to the typeextended.modifiers.functionNew: A string that describes what anew. Returned only for functionextended.modifiers.functionThis: A string that describes what thethis refers to within a function. Returned only for functionextended.modifiers.nullable: A string that indicates whether theextended.modifiers.optional: A string that indicates whether theextended.modifiers.repeatable: A string that indicates whether theextended.returns: A string that describes the function's return value.describe() and stringify() methods, the options.links@ sign (for example,module:@prefix/mymodule~myCallback) are now supported.Promise.<string>).{0: string}) are now parsed correctly.{foo:function()}), are now parsedfoo?=).number[][]).) as a...) modifier when JSDoc-style type expressions are enabled.!string|!number).describe() method, which converts a parsed type to a descriptionlinkClass option to the stringify() method, and deprecated thecssClass option. The cssClass option will be removed in aREADME.undefinedHTML) are now parsed correctly when JSDoc-style type...function()) are now parsed and stringified correctly....!number) are now parsed and stringifiedconstructor).function[]? (nullable) and ! (non-nullable) modifiers. For example,?string and string? are now treated as equivalent.Foo."bar" is now...*) are now parsed correctly.MyClass(2)).parse() method now correctly parses name expressionsparse() method now correctly parses function typesparse() method's lenient option has been renamed to jsdoc.stringify() method now accepts cssClass and links options, whichstringify() method no longer caches HTML-safe type expressions as ifstringify() method's options parameter may now include anoptions.restringify property, and the behavior of the options.useCache: and /.[] (forstring[]) will be interpreted as a type application with theArray (for example, Array.<string>).parse() and stringify() methods now honor all of the specifiedlenient: A boolean indicating whether the type expression was parsedtypeExpression: A string containing the original type expression.stringify() method now honors the useCache option. If a parsedtypeExpression property, and useCache is not set tofalse, the stringified type will be identical to the original typeinteger, are now parsed correctly.parse() and stringify() methods are now synchronous, and theparseSync() and stringifySync() methods have been removed. Note:reservedWord: true property.new or this properties unless thenew andthis properties can now use any type expression.*), are now parsednull and undefined literals with additional properties, such asrepeatable, are now stringified correctly.stringify() and stringifySync() methods, which convert a parsedopts argument to parse() and parseSync()parse() is not backwards-compatible with