diff --git a/Jake/templates/package.json.tmpl b/Jake/templates/package.json.tmpl index 16f83e03..171caf32 100644 --- a/Jake/templates/package.json.tmpl +++ b/Jake/templates/package.json.tmpl @@ -18,6 +18,7 @@ ], "dependencies": { "async": "0.1.22", + "catharsis": "0.5.0", "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", diff --git a/LICENSE.md b/LICENSE.md index 5bc540c9..e06fb138 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -66,6 +66,16 @@ The source code for Async.js is available at: https://github.com/caolan/async +## Catharsis ## + +Catharsis is distributed under the MIT license, which is reproduced above. + +Copyright (c) 2012-2013 Jeff Williams. + +The source code for Catharsis is available at: +https://github.com/hegemonic/catharsis + + ## crypto-browserify ## License information for crypto-browserify is not available. It is assumed that diff --git a/lib/jsdoc/tag/dictionary/definitions.js b/lib/jsdoc/tag/dictionary/definitions.js index 59a66113..9935c70c 100644 --- a/lib/jsdoc/tag/dictionary/definitions.js +++ b/lib/jsdoc/tag/dictionary/definitions.js @@ -146,8 +146,8 @@ exports.defineTags = function(dictionary) { // Allow augments value to be specified as a normal type, e.g. {Type} onTagText: function(text) { var type = require('jsdoc/tag/type'), - tagType = type.getTagInfo(text, false, true); - return tagType.type || text; + tagType = type.parse(text, false, true); + return tagType.typeExpression || text; }, onTagged: function(doclet, tag) { doclet.augment( firstWordOf(tag.value) ); diff --git a/lib/jsdoc/tag/inline.js b/lib/jsdoc/tag/inline.js new file mode 100644 index 00000000..4b6a36fc --- /dev/null +++ b/lib/jsdoc/tag/inline.js @@ -0,0 +1,115 @@ +/** + * @module jsdoc/tag/inline + * + * @author Jeff Williams + * @license Apache License 2.0 - See file 'LICENSE.md' in this project. + */ + +/** + * Information about the result of extracting an inline tag from a text string. + * + * @typedef {Object} InlineTagInfo + * @memberof module:jsdoc/tag/inline + * @property {?string} tag - The tag whose text was found, or `null` if no tag was specified. + * @property {string} text - The tag text that was found. + * @property {string} newString - The updated text string after extracting or replacing the inline + * tag. + */ + +/** + * Function that replaces an inline tag with other text. + * + * @callback InlineTagReplacer + * @memberof module:jsdoc/tag/inline + * @param {string} string - The complete string containing the inline tag. + * @param {string} completeTag - The entire inline tag, including its enclosing braces. + * @param {string} tagText - The text contained in the inline tag. + * @return {string} An updated version of the string that contained the inline tag. + */ + +/** @private */ +function unescapeBraces(text) { + return text.replace(/\\\{/g, '{') + .replace(/\\\}/g, '}'); +} + +/** + * Replace an inline tag with other text. + * + * To replace untagged text that is enclosed in braces, set the `tag` parameter to `null`. + * + * @param {string} string - The string in which to replace the inline tag. + * @param {?string} tag - The inline tag that must follow the opening brace (for example, `@link`). + * @param {module:jsdoc/tag/inline.InlineTagReplacer} replacer - The function that is used to + * replace text in the string. + * @return {module:jsdoc/tag/inline.InlineTagInfo} The updated string, as well as information about + * the inline tag. + */ +exports.replaceInlineTag = function(string, tag, replacer) { + string = string || ''; + tag = tag || ''; + + var count = 0; + var position = 0; + var completeTag = ''; + var text = ''; + var start = '{' + tag; + var startIndex = string.indexOf(start); + var textStartIndex; + + if (startIndex !== -1) { + // advance to the first character after `start` + position = textStartIndex = startIndex + start.length; + count++; + + while (position < string.length) { + switch (string[position]) { + case '\\': + // backslash is an escape character, so skip the next character + position++; + break; + case '{': + count++; + break; + case '}': + count--; + break; + default: + // do nothing + } + + if (count === 0) { + completeTag = string.slice(startIndex, position + 1); + text = string.slice(textStartIndex, position).trim(); + break; + } + + position++; + } + } + + string = replacer.call(this, string, completeTag, text); + + return { + tag: tag || null, + text: unescapeBraces(text), + newString: string.trim() + }; +}; + +/** + * Extract the first portion of a string that is enclosed in braces, with the `tag` parameter + * immediately following the opening brace. + * + * To extract untagged text that is enclosed in braces, omit the `tag` parameter. + * + * @param {string} string - The string from which to extract text. + * @param {?string} tag - The inline tag that must follow the opening brace (for example, `@link`). + * @return {module:jsdoc/tag/inline.InlineTagInfo} Information about the string and inline tag. + */ +exports.extractInlineTag = function(string, tag) { + return exports.replaceInlineTag(string, tag, function(string, completeTag, + tagText) { + return string.replace(completeTag, ''); + }); +}; diff --git a/lib/jsdoc/tag/type.js b/lib/jsdoc/tag/type.js index 3451288b..eee05445 100644 --- a/lib/jsdoc/tag/type.js +++ b/lib/jsdoc/tag/type.js @@ -1,59 +1,26 @@ /** - @module jsdoc/tag/type - - @author Michael Mathews - @author Jeff Williams - @license Apache License 2.0 - See file 'LICENSE.md' in this project. + * @module jsdoc/tag/type + * + * @author Michael Mathews + * @author Jeff Williams + * @license Apache License 2.0 - See file 'LICENSE.md' in this project. */ -function parseTypes(type) { - var types = []; - - if ( type.indexOf('|') !== -1 ) { - // remove optional parens, like: { ( string | number ) } - // see: http://code.google.com/closure/compiler/docs/js-for-compiler.html#types - if ( /^\s*\(\s*(.+)\s*\)\s*$/.test(type) ) { - type = RegExp.$1; - } - types = type.split(/\s*\|\s*/g); - } - else if (type) { - types = [type]; - } - - return types; -} /** @private */ -function trim(text) { - return text.trim(); -} +function getTagInfo(tagValue, canHaveName, canHaveType) { + var extractInlineTag = require('jsdoc/tag/inline').extractInlineTag; -var getTagInfo = exports.getTagInfo = function(tagValue, canHaveName, canHaveType) { - var name = '', - type = '', - text = tagValue, - count = 0; + var name = ''; + var typeExpression = ''; + var text = tagValue; + var typeAndText; + var typeOverride; - // type expressions start with '{' - if (canHaveType && tagValue[0] === '{') { - count++; - - // find matching closer '}' - for (var i = 1, leni = tagValue.length; i < leni; i++) { - if (tagValue[i] === '\\') { i++; continue; } // backslash escapes the next character - - if (tagValue[i] === '{') { count++; } - else if (tagValue[i] === '}') { count--; } - - if (count === 0) { - type = trim(tagValue.slice(1, i)) - .replace(/\\\{/g, '{') // unescape escaped curly braces - .replace(/\\\}/g, '}'); - text = trim(tagValue.slice(i+1)); - break; - } - } + if (canHaveType) { + typeAndText = extractInlineTag(text); + typeExpression = typeAndText.text || typeExpression; + text = typeAndText.newString; } if (canHaveName) { @@ -62,33 +29,181 @@ var getTagInfo = exports.getTagInfo = function(tagValue, canHaveName, canHaveTyp name = RegExp.$1; text = RegExp.$3; } - - return { name: name, type: type, text: text }; -}; + // an inline @type tag, like {@type Foo}, overrides the type expression + if (canHaveType) { + typeOverride = extractInlineTag(text, '@type'); + typeExpression = typeOverride.text || typeExpression; + text = typeOverride.newString; + } + + return { + name: name, + typeExpression: typeExpression, + text: text + }; +} /** - @param {string} tagValue - @param {boolean} canHaveName - @param {boolean} canHaveType - @returns {object} Hash with name, type, text, optional, nullable, variable, and defaultvalue properties + * Information provided in a JSDoc tag. + * + * @typedef {Object} TagInfo + * @memberof module:jsdoc/tag/type + * @property {string} TagInfo.defaultvalue - The default value of the member. + * @property {string} TagInfo.name - The name of the member (for example, `myParamName`). + * @property {boolean} TagInfo.nullable - Indicates whether the member can be set to `null` or + * `undefined`. + * @property {boolean} TagInfo.optional - Indicates whether the member is optional. + * @property {string} TagInfo.text - Descriptive text for the member (for example, `The user's email + * address.`). + * @property {Array.} TagInfo.type - The type or types that the member can contain (for + * example, `string` or `MyNamespace.MyClass`). + * @property {string} TagInfo.typeExpression - The type expression that was parsed to identify the + * types. + * @property {boolean} TagInfo.variable - Indicates whether the number of members that are provided + * can vary (for example, in a function that accepts any number of parameters). + */ + +/** + * Extract JSDoc-style type information from the name specified in the tag info, including the + * member name; whether the member is optional; and the default value of the member. + * + * @private + * @param {module:jsdoc/tag/type.TagInfo} tagInfo - Information contained in the tag. + * @return {module:jsdoc/tag/type.TagInfo} Updated information from the tag. + */ +function parseName(tagInfo) { + // like '[foo]' or '[ foo ]' or '[foo=bar]' or '[ foo=bar ]' or '[ foo = bar ]' + if ( /^\[\s*(.+?)\s*\]$/.test(tagInfo.name) ) { + tagInfo.name = RegExp.$1; + tagInfo.optional = true; + + // like 'foo=bar' or 'foo = bar' + if ( /^(.+?)\s*=\s*(.+)$/.test(tagInfo.name) ) { + tagInfo.name = RegExp.$1; + tagInfo.defaultvalue = RegExp.$2; + } + } + + return tagInfo; +} + +/** @private */ +function getTypeStrings(parsedType) { + var types = []; + + var catharsis = require('catharsis'); + var TYPES = catharsis.Types; + var util = require('util'); + + switch(parsedType.type) { + case TYPES.AllLiteral: + types.push('*'); + break; + case TYPES.FunctionType: + types.push('function'); + break; + case TYPES.NameExpression: + types.push(parsedType.name); + break; + case TYPES.NullLiteral: + types.push('null'); + break; + case TYPES.RecordType: + types.push('Object'); + break; + case TYPES.TypeApplication: + types.push( catharsis.stringify(parsedType) ); + break; + case TYPES.TypeUnion: + parsedType.elements.forEach(function(element) { + types = types.concat( getTypeStrings(element) ); + }); + break; + case TYPES.UndefinedLiteral: + types.push('undefined'); + break; + case TYPES.UnknownLiteral: + types.push('?'); + break; + default: + // this shouldn't happen + throw new Error( util.format('unrecognized type %s in parsed type: %j', parsedType.type, + parsedType) ); + } + + return types; +} + +/** + * Extract JSDoc-style and Closure Compiler-style type information from the type expression + * specified in the tag info. + * + * @private + * @param {module:jsdoc/tag/type.TagInfo} tagInfo - Information contained in the tag. + * @return {module:jsdoc/tag/type.TagInfo} Updated information from the tag. + */ +function parseTypeExpression(tagInfo) { + var catharsis = require('catharsis'); + var util = require('util'); + + var errorMessage; + var parsedType; + + // don't try to parse empty type expressions + if (!tagInfo.typeExpression) { + return tagInfo; + } + + try { + parsedType = catharsis.parse(tagInfo.typeExpression, {jsdoc: true}); + } + catch (e) { + errorMessage = util.format('unable to parse the type expression "%s": %s', + tagInfo.typeExpression, e.message); + require('jsdoc/util/error').handle( new Error(errorMessage) ); + } + + if (parsedType) { + tagInfo.type = tagInfo.type.concat( getTypeStrings(parsedType) ); + + ['optional', 'nullable', 'variable'].forEach(function(key) { + if (parsedType[key] !== null && parsedType[key] !== undefined) { + tagInfo[key] = parsedType[key]; + } + }); + } + + return tagInfo; +} + +// TODO: allow users to add/remove type parsers (perhaps via plugins) +var typeParsers = [parseName, parseTypeExpression]; + +/** + * Parse the value of a JSDoc tag. + * + * @param {string} tagValue - The value of the tag. For example, the tag `@param {string} name` has + * a value of `{string} name`. + * @param {boolean} canHaveName - Indicates whether the value can include a member name. + * @param {boolean} canHaveType - Indicates whether the value can include a type expression that + * describes the member. + * @return {module:jsdoc/tag/type.TagInfo} Information obtained from the tag. */ exports.parse = function(tagValue, canHaveName, canHaveType) { if (typeof tagValue !== 'string') { tagValue = ''; } var tagInfo = getTagInfo(tagValue, canHaveName, canHaveType); + tagInfo.type = tagInfo.type || []; - // extract JSDoc-style type info, then Closure Compiler-style type info - tagInfo = require('jsdoc/tag/type/jsdocType').parse(tagInfo); - tagInfo = require('jsdoc/tag/type/closureCompilerType').parse(tagInfo); + typeParsers.forEach(function(parser) { + tagInfo = parser.call(this, tagInfo); + }); - return { - name: tagInfo.name, - type: parseTypes(tagInfo.type), // make it into an array - text: tagInfo.text, - optional: tagInfo.optional, - nullable: tagInfo.nullable, - variable: tagInfo.variable, - defaultvalue: tagInfo.defaultvalue - }; + // if we wanted a type, but the parsers didn't add any type names, use the type expression + if (canHaveType && !tagInfo.type.length && tagInfo.typeExpression) { + tagInfo.type = [tagInfo.typeExpression]; + } + + return tagInfo; }; diff --git a/lib/jsdoc/tag/type/closureCompilerType.js b/lib/jsdoc/tag/type/closureCompilerType.js deleted file mode 100644 index 2b2f8aa6..00000000 --- a/lib/jsdoc/tag/type/closureCompilerType.js +++ /dev/null @@ -1,64 +0,0 @@ -/** - @module jsdoc/tag/type/closureCompilerType - - @author Michael Mathews - @author Jeff Williams - @license Apache License 2.0 - See file 'LICENSE.md' in this project. - */ - -function parseOptional(type) { - var optional = null; - - // {sometype=} means optional - if ( /(.+)=$/.test(type) ) { - type = RegExp.$1; - optional = true; - } - - return { type: type, optional: optional }; -} - -function parseNullable(type) { - var nullable = null; - - // {?sometype} means nullable, {!sometype} means not-nullable - if ( /^([\?\!])(.+)$/.test(type) ) { - type = RegExp.$2; - nullable = (RegExp.$1 === '?')? true : false; - } - - return { type: type, nullable: nullable }; -} - -function parseVariable(type) { - var variable = null; - - // {...sometype} means variable number of that type - if ( /^(\.\.\.)(.+)$/.test(type) ) { - type = RegExp.$2; - variable = true; - } - - return { type: type, variable: variable }; -} - -/** - Extract Closure Compiler-style type information from the tag info. - @param {object} tagInfo Hash with name, type, and text properties. - @return {object} Hash with name, type, text, optional, nullable, variable, and default properties. - */ -exports.parse = function(tagInfo) { - var optional = parseOptional(tagInfo.type), - nullable = parseNullable(optional.type), - variable = parseVariable(nullable.type); - - return { - name: tagInfo.name, - type: variable.type, - text: tagInfo.text, - optional: tagInfo.optional || optional.optional, // don't override if already true - nullable: nullable.nullable, - variable: variable.variable, - defaultvalue: tagInfo.defaultvalue - }; -}; diff --git a/lib/jsdoc/tag/type/jsdocType.js b/lib/jsdoc/tag/type/jsdocType.js deleted file mode 100644 index 412082cf..00000000 --- a/lib/jsdoc/tag/type/jsdocType.js +++ /dev/null @@ -1,40 +0,0 @@ -/** - @module jsdoc/tag/type/jsdocType - - @author Michael Mathews - @author Jeff Williams - @license Apache License 2.0 - See file 'LICENSE.md' in this project. - */ - - /** - Extract JSDoc-style type information from the tag info. - @param {object} tagInfo Hash with name, type, text, optional, nullable, variable, and default properties. - @return {object} Hash with the same properties as tagInfo. - */ -exports.parse = function(tagInfo) { - var name = tagInfo.name, - optional, - tagDefault; - - // like '[foo]' or '[ foo ]' or '[foo=bar]' or '[ foo=bar ]' or '[ foo = bar ]' - if ( /^\[\s*(.+?)\s*\]$/.test(name) ) { - name = RegExp.$1; - optional = true; - - // like 'foo=bar' or 'foo = bar' - if ( /^(.+?)\s*=\s*(.+)$/.test(name) ) { - name = RegExp.$1; - tagDefault = RegExp.$2; - } - } - - return { - name: name, - type: tagInfo.type, - text: tagInfo.text, - optional: optional, - nullable: tagInfo.nullable, - variable: tagInfo.variable, - defaultvalue: tagDefault - }; -}; \ No newline at end of file diff --git a/lib/jsdoc/tutorial/resolver.js b/lib/jsdoc/tutorial/resolver.js index 2314c86e..c07a3f7e 100644 --- a/lib/jsdoc/tutorial/resolver.js +++ b/lib/jsdoc/tutorial/resolver.js @@ -25,7 +25,7 @@ var tutorial = require('jsdoc/tutorial'), */ function isTutorialJSON(json) { // if conf.title exists or conf.children exists, it is metadata for a tutorial - return (json.hasOwnProperty('title') || json.hasOwnProperty('children')); + return (hasOwnProp.call(json, 'title') || hasOwnProp.call(json, 'children')); } /** Helper function that adds tutorial configuration to the `conf` variable. @@ -50,7 +50,7 @@ function addTutorialConf(name, meta) { if (isTutorialJSON(meta)) { // if the children are themselves tutorial defintions as opposed to an // array of strings, add each child. - if (meta.hasOwnProperty('children') && !Array.isArray(meta.children)) { + if (hasOwnProp.call(meta, 'children') && !Array.isArray(meta.children)) { names = Object.keys(meta.children); for (i = 0; i < names.length; ++i) { addTutorialConf(names[i], meta.children[names[i]]); @@ -59,7 +59,7 @@ function addTutorialConf(name, meta) { meta.children = names; } // check if the tutorial has already been defined... - if (conf.hasOwnProperty(name)) { + if (hasOwnProp.call(conf, name)) { error.handle(new Error("Tutorial " + name + "'s metadata is defined multiple times, only the first will be used.")); } else { conf[name] = meta; @@ -77,7 +77,7 @@ function addTutorialConf(name, meta) { @param {tutorial.Tutorial} current - New tutorial. */ exports.addTutorial = function(current) { - if (tutorials.hasOwnProperty(current.name)) { + if (hasOwnProp.call(tutorials, current.name)) { error.handle(new Error("Tutorial with name " + current.name + " exists more than once, not adding (same name, different file extensions?)")); } else { tutorials[current.name] = current; diff --git a/lib/jsdoc/util/templateHelper.js b/lib/jsdoc/util/templateHelper.js index 50d4dc2b..92de911b 100644 --- a/lib/jsdoc/util/templateHelper.js +++ b/lib/jsdoc/util/templateHelper.js @@ -100,11 +100,42 @@ var tutorialLinkMap = { var longnameToUrl = exports.longnameToUrl = linkMap.longnameToUrl; +/** + * Retrieve an HTML link to the member with the specified longname. If the longname is not + * associated with a URL, this method returns the link text, if provided, or the longname. + * + * This method supports type applications that can contain one or more types, such as + * `Array.` or `Array.<(MyClass|YourClass)>`. In these examples, the method attempts to + * replace `Array`, `MyClass`, and `YourClass` with links to the appropriate types. The link text + * is ignored for type applications. + * + * @param {string} longname - The longname that is the target of the link. + * @param {string=} linktext - The text to display for the link, or `longname` if no text is + * provided. + * @param {string=} cssClass - The CSS class (or classes) to include in the link's `` tag. + * @return {string} The HTML link, or a plain-text string if the link is not available. + */ var linkto = exports.linkto = function(longname, linktext, cssClass) { + var catharsis = require('catharsis'); + var classString = cssClass ? util.format(' class="%s"', cssClass) : ''; var text = linktext || longname; var url = hasOwnProp.call(longnameToUrl, longname) && longnameToUrl[longname]; + var parsedType; + // type applications require special treatment + var typeAppInfo = /(\S+)<(\S+)>/.exec(longname); + if (typeAppInfo) { + typeAppInfo[1] = linkto(typeAppInfo[1], null, cssClass); + parsedType = catharsis.parse(typeAppInfo[2], {jsdoc: true}); + typeAppInfo[2] = catharsis.stringify(parsedType, { + cssClass: cssClass, + htmlSafe: true, + links: longnameToUrl + }); + return typeAppInfo[1] + '<' + typeAppInfo[2] + '>'; + } + if (!url) { return text; } diff --git a/node_modules/catharsis/LICENSE b/node_modules/catharsis/LICENSE new file mode 100644 index 00000000..9a454a29 --- /dev/null +++ b/node_modules/catharsis/LICENSE @@ -0,0 +1,16 @@ +Copyright (c) 2012-2013 Jeff Williams + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and +associated documentation files (the "Software"), to deal in the Software without restriction, +including without limitation the rights to use, copy, modify, merge, publish, distribute, +sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial +portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT +NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES +OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file diff --git a/node_modules/catharsis/catharsis.js b/node_modules/catharsis/catharsis.js new file mode 100644 index 00000000..f416ab3f --- /dev/null +++ b/node_modules/catharsis/catharsis.js @@ -0,0 +1,119 @@ +/** + * catharsis 0.4.2 + * A parser for Google Closure Compiler type expressions, powered by PEG.js. + * + * @author Jeff Williams + * @license MIT License + */ + +'use strict'; + +var parse = require('./lib/parser').parse; +var stringify = require('./lib/stringify'); + +var typeExpressionCache = { + normal: {}, + jsdoc: {} +}; + +var parsedTypeCache = { + normal: {}, + htmlSafe: {} +}; + +function getTypeExpressionCache(options) { + if (options.useCache === false) { + return null; + } else if (options.jsdoc === true) { + return typeExpressionCache.jsdoc; + } else { + return typeExpressionCache.normal; + } +} + +function getParsedTypeCache(options) { + if (options.useCache === false || options.links !== null || options.links !== undefined) { + return null; + } else if (options.htmlSafe === true) { + return parsedTypeCache.htmlSafe; + } else { + return parsedTypeCache.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, options) { + return options.restringify !== true && options.htmlSafe !== true && + (options.links === null || options.links === undefined) && + Object.prototype.hasOwnProperty.call(parsedType, 'typeExpression'); +} + +function cachedParse(expr, options) { + var cache = getTypeExpressionCache(options); + var parsedType; + + if (cache && cache[expr]) { + return cache[expr]; + } else { + parsedType = parse(expr, options); + + Object.defineProperties(parsedType, { + typeExpression: { + value: expr + }, + jsdoc: { + value: options.jsdoc === true ? true : false + } + }); + parsedType = Object.freeze(parsedType); + + if (cache) { + cache[expr] = parsedType; + } + + return parsedType; + } +} + +function cachedStringify(parsedType, options) { + var cache = getParsedTypeCache(options); + var json; + + if (canReturnOriginalExpression(parsedType, options)) { + return parsedType.typeExpression; + } else if (cache) { + json = JSON.stringify(parsedType); + cache[json] = cache[json] || stringify(parsedType, options); + return cache[json]; + } else { + return stringify(parsedType, options); + } +} + +function Catharsis() { + this.Types = require('./lib/types'); +} + +Catharsis.prototype.parse = function(typeExpr, options) { + options = options || {}; + + return cachedParse(typeExpr, options); +}; + +Catharsis.prototype.stringify = function(parsedType, options) { + options = options || {}; + var result; + + result = cachedStringify(parsedType, options); + if (options.validate) { + this.parse(result, options); + } + + return result; +}; + +module.exports = new Catharsis(); diff --git a/node_modules/catharsis/lib/parser.js b/node_modules/catharsis/lib/parser.js new file mode 100644 index 00000000..be792f3b --- /dev/null +++ b/node_modules/catharsis/lib/parser.js @@ -0,0 +1,3 @@ +module.exports=function(){function peg$subclass(child,parent){function ctor(){this.constructor=child}ctor.prototype=parent.prototype;child.prototype=new ctor}function SyntaxError(expected,found,offset,line,column){function buildMessage(expected,found){function stringEscape(s){function hex(ch){return ch.charCodeAt(0).toString(16).toUpperCase()}return s.replace(/\\/g,"\\\\").replace(/"/g,'\\"').replace(/\x08/g,"\\b").replace(/\t/g,"\\t").replace(/\n/g,"\\n").replace(/\f/g,"\\f").replace(/\r/g,"\\r").replace(/[\x00-\x07\x0B\x0E\x0F]/g,function(ch){return"\\x0"+hex(ch)}).replace(/[\x10-\x1F\x80-\xFF]/g,function(ch){return"\\x"+hex(ch)}).replace(/[\u0180-\u0FFF]/g,function(ch){return"\\u0"+hex(ch)}).replace(/[\u1080-\uFFFF]/g,function(ch){return"\\u"+hex(ch)})}var expectedDesc,foundDesc;switch(expected.length){case 0:expectedDesc="end of input";break;case 1:expectedDesc=expected[0];break;default:expectedDesc=expected.slice(0,-1).join(", ")+" or "+expected[expected.length-1]}foundDesc=found?'"'+stringEscape(found)+'"':"end of input";return"Expected "+expectedDesc+" but "+foundDesc+" found."}this.expected=expected;this.found=found;this.offset=offset;this.line=line;this.column=column;this.name="SyntaxError";this.message=buildMessage(expected,found)}peg$subclass(SyntaxError,Error);function parse(input){var options=arguments.length>1?arguments[1]:{},peg$startRuleFunctions={TypeExpression:peg$parseTypeExpression},peg$startRuleFunction=peg$parseTypeExpression,peg$c0=null,peg$c1="",peg$c2=function(unk){return unk},peg$c3="?",peg$c4='"?"',peg$c5="!",peg$c6='"!"',peg$c7=function(modifier,expr){if(modifier!==""){expr.nullable=modifier==="?"?true:false}return expr},peg$c8=function(lit,opt){var result=lit;if(opt.optional){result.optional=true}return result},peg$c9="*",peg$c10='"*"',peg$c11=function(){return{type:Types.AllLiteral}},peg$c12=function(){return{type:Types.NullLiteral}},peg$c13=function(){return{type:Types.UndefinedLiteral}},peg$c14="=",peg$c15='"="',peg$c16=function(){return{optional:true}},peg$c17="[]",peg$c18='"[]"',peg$c19=function(name){var result;if(!options.jsdoc){return null}result={type:Types.TypeApplication,expression:{type:Types.NameExpression,name:"Array"},applications:[name]};result.applications[0].type=Types.NameExpression;return result},peg$c20=function(exp,appl,opt){var result={};var nameExp={type:Types.NameExpression,name:exp.name};if(appl.length){result.type=Types.TypeApplication;result.expression=nameExp;result.applications=appl}else{result=nameExp}if(exp.repeatable){result.repeatable=true}if(opt.optional){result.optional=true}return result},peg$c21=function(name){if(!options.jsdoc){return null}return name},peg$c22=function(exp,opt){var result={type:Types.NameExpression,name:exp.name,reservedWord:true};if(exp.repeatable){result.repeatable=true}if(opt.optional){result.optional=true}return result},peg$c23=".",peg$c24='"."',peg$c25="<",peg$c26='"<"',peg$c27=">",peg$c28='">"',peg$c29=function(sep,l){if(sep===""&&!options.jsdoc){return null}return l},peg$c30=[],peg$c31=",",peg$c32='","',peg$c33=function(expr,list){var result=[expr];for(var i=0,l=list.length;ipos){peg$cachedPos=0;peg$cachedPosDetails={line:1,column:1,seenCR:false}}peg$cachedPos=pos;advance(peg$cachedPosDetails,peg$cachedPos)}return peg$cachedPosDetails}function peg$fail(expected){if(peg$currPospeg$maxFailPos){peg$maxFailPos=peg$currPos;peg$maxFailExpected=[]}peg$maxFailExpected.push(expected)}function peg$cleanupExpected(expected){var i=0;expected.sort();while(ipeg$currPos){s0=input.charAt(peg$currPos);peg$currPos++}else{s0=null;if(peg$silentFails===0){peg$fail(peg$c265)}}return s0}function peg$parseHexEscapeSequence(){var s0,s1,s2,s3,s4,s5;s0=peg$currPos;if(input.charCodeAt(peg$currPos)===120){s1=peg$c263;peg$currPos++}else{s1=null;if(peg$silentFails===0){peg$fail(peg$c264)}}if(s1!==null){s2=peg$currPos;s3=peg$currPos;s4=peg$parseHexDigit();if(s4!==null){s5=peg$parseHexDigit();if(s5!==null){s4=[s4,s5];s3=s4}else{peg$currPos=s3;s3=peg$c0}}else{peg$currPos=s3;s3=peg$c0}if(s3!==null){s3=input.substring(s2,peg$currPos)}s2=s3;if(s2!==null){peg$reportedPos=s0;s1=peg$c210(s2);if(s1===null){peg$currPos=s0;s0=s1}else{s0=s1}}else{peg$currPos=s0;s0=peg$c0}}else{peg$currPos=s0;s0=peg$c0}return s0}function peg$parseLineContinuation(){var s0,s1,s2;s0=peg$currPos;if(input.charCodeAt(peg$currPos)===92){s1=peg$c206;peg$currPos++}else{s1=null;if(peg$silentFails===0){peg$fail(peg$c207)}}if(s1!==null){s2=peg$parseLineTerminatorSequence();if(s2!==null){peg$reportedPos=s0;s1=peg$c266(s2);if(s1===null){peg$currPos=s0;s0=s1}else{s0=s1}}else{peg$currPos=s0;s0=peg$c0}}else{peg$currPos=s0;s0=peg$c0}return s0}function peg$parse_(){var s0,s1;peg$silentFails++;s0=[];s1=peg$parseWhitespace();while(s1!==null){s0.push(s1);s1=peg$parseWhitespace()}peg$silentFails--;if(s0===null){s1=null;if(peg$silentFails===0){peg$fail(peg$c267)}}return s0}function peg$parse__(){var s0,s1;peg$silentFails++;s0=peg$c1;peg$silentFails--;if(s0===null){s1=null;if(peg$silentFails===0){peg$fail(peg$c268)}}return s0}function peg$parseWhitespace(){var s0;if(peg$c269.test(input.charAt(peg$currPos))){s0=input.charAt(peg$currPos);peg$currPos++}else{s0=null;if(peg$silentFails===0){peg$fail(peg$c270)}}if(s0===null){s0=peg$parseUnicodeZs()}return s0}var Types=require("./types");peg$result=peg$startRuleFunction();if(peg$result!==null&&peg$currPos===input.length){return peg$result}else{peg$cleanupExpected(peg$maxFailExpected);peg$reportedPos=Math.max(peg$currPos,peg$maxFailPos);throw new SyntaxError(peg$maxFailExpected,peg$reportedPos'; + + return result; +}; + +Stringifier.prototype.elements = function(elements) { + if (!elements) { + return ''; + } + + var result = []; + + for (var i = 0, l = elements.length; i < l; i++) { + result.push(this.type(elements[i])); + } + + return '(' + result.join('|') + ')'; +}; + +Stringifier.prototype.name = function(name) { + return name || ''; +}; + +Stringifier.prototype['new'] = function(funcNew) { + return funcNew ? 'new:' + this.type(funcNew) : ''; +}; + +Stringifier.prototype.nullable = function(nullable) { + switch (nullable) { + case true: + return '?'; + case false: + return '!'; + default: + return ''; + } +}; + +Stringifier.prototype.optional = function(optional) { + /*jshint boss: true */ // TODO: remove after JSHint releases the fix for jshint/jshint#878 + if (optional === true) { + return '='; + } else { + return ''; + } +}; + +Stringifier.prototype.params = function(params) { + if (!params || params.length === 0) { + return ''; + } + + var result = []; + + var param; + for (var i = 0, l = params.length; i < l; i++) { + result.push(this.type(params[i])); + } + + return result.join(', '); +}; + +Stringifier.prototype.properties = function(props) { + if (!props) { + return ''; + } + + var result = []; + + for (var i = 0, l = props.length; i < l; i++) { + result.push(this._formatNameAndType(props[i].name, props[i].type)); + } + + return result; +}; + +Stringifier.prototype.result = function(result) { + return result ? ': ' + this.type(result) : ''; +}; + +Stringifier.prototype['this'] = function(funcThis) { + return funcThis ? 'this:' + this.type(funcThis) : ''; +}; + +Stringifier.prototype.type = function(type) { + if (!type) { + return ''; + } + + // nullable comes first + var result = this.nullable(type.nullable); + + // next portion varies by type + switch(type.type) { + case Types.AllLiteral: + result += this._formatNameAndType(type, '*'); + break; + case Types.FunctionType: + result += this._signature(type); + break; + case Types.NullLiteral: + result += this._formatNameAndType(type, 'null'); + break; + case Types.RecordType: + result += this._record(type); + break; + case Types.TypeApplication: + result += this.type(type.expression); + result += this.applications(type.applications); + break; + case Types.UndefinedLiteral: + result += this._formatNameAndType(type, 'undefined'); + break; + case Types.TypeUnion: + result += this.elements(type.elements); + break; + case Types.UnknownLiteral: + result += this._formatNameAndType(type, '?'); + break; + default: + result += this._formatNameAndType(type); + } + + // finally, optionality + result += this.optional(type.optional); + + return result; +}; + +Stringifier.prototype.stringify = Stringifier.prototype.type; + +Stringifier.prototype.key = Stringifier.prototype.type; + +Stringifier.prototype._record = function(type) { + var fields = this._recordFields(type.fields); + + return '{' + fields.join(', ') + '}'; +}; + +Stringifier.prototype._recordFields = function(fields) { + if (!fields) { + return ''; + } + + var result = []; + + var field; + var keyAndValue; + + for (var i = 0, l = fields.length; i < l; i++) { + field = fields[i]; + + keyAndValue = this.key(field.key); + keyAndValue += field.value ? ': ' + this.type(field.value) : ''; + + result.push(keyAndValue); + } + + return result; +}; + +function combineNameAndType(nameString, typeString) { + var separator = (nameString && typeString) ? ':' : ''; + return nameString + separator + typeString; +} + +Stringifier.prototype._formatRepeatable = function(nameString, typeString) { + var open = this._inFunctionSignatureParams ? '...[' : '...'; + var close = this._inFunctionSignatureParams ? ']' : ''; + + return open + combineNameAndType(nameString, typeString) + close; +}; + +Stringifier.prototype._formatNameAndType = function(type, literal) { + var nameString = type.name || literal || ''; + var typeString = type.type ? this.type(type.type) : ''; + var cssClass; + var openTag; + + // replace the type with an HTML link if necessary + if (this._options.links && Object.prototype.hasOwnProperty.call(this._options.links, + nameString)) { + cssClass = this._options.cssClass ? ' class="' + this._options.cssClass + '"' : ''; + + openTag = ''; + nameString = openTag + nameString + ''; + } + + if (type.repeatable === true) { + return this._formatRepeatable(nameString, typeString); + } else { + return combineNameAndType(nameString, typeString); + } +}; + +Stringifier.prototype._signature = function(type) { + var params = []; + var param; + var result; + + // these go within the signature's parens, in this order + var props = [ + 'new', + 'this', + 'params' + ]; + var prop; + + this._inFunctionSignatureParams = true; + for (var i = 0, l = props.length; i < l; i++) { + prop = props[i]; + param = this[prop](type[prop]); + if (param.length > 0) { + params.push(param); + } + } + this._inFunctionSignatureParams = false; + + result = 'function(' + params.join(', ') + ')'; + result += this.result(type.result); + + return result; +}; + + +module.exports = function(type, options) { + return new Stringifier(options).stringify(type); +}; diff --git a/node_modules/catharsis/lib/types.js b/node_modules/catharsis/lib/types.js new file mode 100644 index 00000000..017aba6b --- /dev/null +++ b/node_modules/catharsis/lib/types.js @@ -0,0 +1,24 @@ +'use strict'; + +module.exports = Object.freeze({ + // `*` + AllLiteral: 'AllLiteral', + // like `blah` in `{blah: string}` + FieldType: 'FieldType', + // like `function(string): string` + FunctionType: 'FunctionType', + // any string literal, such as `string` or `My.Namespace` + NameExpression: 'NameExpression', + // null + NullLiteral: 'NullLiteral', + // like `{foo: string}` + RecordType: 'RecordType', + // like `Array.` + TypeApplication: 'TypeApplication', + // like `(number|string)` + TypeUnion: 'TypeUnion', + // undefined + UndefinedLiteral: 'UndefinedLiteral', + // `?` + UnknownLiteral: 'UnknownLiteral' +}); diff --git a/node_modules/catharsis/package.json b/node_modules/catharsis/package.json new file mode 100644 index 00000000..c5f7f16e --- /dev/null +++ b/node_modules/catharsis/package.json @@ -0,0 +1,44 @@ +{ + "version": "0.5.0", + "name": "catharsis", + "description": "A JavaScript parser for Google Closure Compiler and JSDoc 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", + "uglify-js": "2.2.5", + "underscore": "1.4.4" + }, + "engines": { + "node": ">= 0.6" + }, + "scripts": { + "build": "pegjs ./lib/parser.pegjs", + "prepublish": "pegjs ./lib/parser.pegjs; uglifyjs ./lib/parser.js -o ./lib/parser.js", + "test": "mocha" + }, + "licenses": [ + { + "type": "MIT", + "url": "http://github.com/hegemonic/catharsis/raw/master/LICENSE" + } + ], + "readme": "# Catharsis #\n\nA JavaScript parser for\n[Google Closure Compiler](https://developers.google.com/closure/compiler/docs/js-for-compiler#types)\nand [JSDoc](https://github.com/jsdoc3/jsdoc) type expressions.\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 can\nparse [JSDoc](https://github.com/jsdoc3/jsdoc)-style type expressions.\n\n\n## Example ##\n\n\tvar catharsis = require('catharsis');\n\n var type;\n var jsdocType;\n var parsedType;\n var parsedJsdocType;\n\n // Google Closure Compiler parsing\n try {\n type = '!Object';\n parsedType = catharsis.parse(type);\n console.log('%j', parsedType); // {\"type\":\"NameExpression,\"name\":\"Object\",\"nullable\":false}\n }\n catch(e) {\n console.error('unable to parse %s: %s', type, e);\n }\n\n // JSDoc-style type expressions enabled\n try {\n jsdocType = 'number|string'; // Closure Compiler expects (number|string)\n parsedJsdocType = catharsis.parse(jsdocType, {jsdoc: true});\n }\n catch (e) {\n console.error('unable to parse %s: %s', jsdocType, e);\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(typeExpression, options) ###\nParse `typeExpression`, and return the parse results. Throws an error if the type expression cannot\nbe parsed.\n\nWhen called without options, Catharsis attempts to parse type expressions in the same way as\nClosure Compiler. When the `jsdoc` option is enabled, Catharsis can also parse several kinds of\ntype expressions that are permitted 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.jsdoc`: Specifies whether to enable parsing of JSDoc-style type expressions. Defaults\n 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+ `jsdoc`: A boolean indicating whether the type expression was parsed with JSDoc support enabled.\n+ `typeExpression`: A string containing the type expression that was parsed.\n\n### stringify(parsedType, options) ###\nStringify `parsedType`, and return the type expression. If validation is enabled, throws an error if\nthe 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.cssClass`: A CSS class to add to HTML links. Used only if `options.links` is\n provided. By default, no CSS class is added.\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.links`: An object whose keys are name expressions and whose values are URIs. If a\n name expression matches a key in `options.links`, the name expression will be wrapped in an\n HTML tag that links to the URI. If `options.cssClass` is specified, the tag will include\n a `class` attribute. **Note**: When using this option, parsed types are always restringified,\n and the resulting string is not cached.\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 when possible. 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. If the stringified results are not parsable by default, you\n must also provide the appropriate options to pass to the `parse()` method. 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.5.0 (March 2013):\n + The `parse()` method's `lenient` option has been renamed to `jsdoc`. **Note**: This change is\n not backwards-compatible with previous versions.\n + The `stringify()` method now accepts `cssClass` and `links` options, which you can use to\n add HTML links to a type expression.\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.5.0", + "dist": { + "shasum": "01cea3d4922dd8a5da66b9298c1478e614f36dd1" + }, + "_from": "catharsis@0.5.0", + "_resolved": "https://registry.npmjs.org/catharsis/-/catharsis-0.5.0.tgz" +} diff --git a/package.json b/package.json index 60620450..59290097 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "jsdoc", "version": "3.2.0-dev", - "revision": "1359085455394", + "revision": "1363617959876", "description": "An API documentation generator for JavaScript.", "keywords": [ "documentation", "javascript" ], "licenses": [ @@ -18,6 +18,7 @@ ], "dependencies": { "async": "0.1.22", + "catharsis": "0.5.0", "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", diff --git a/test/specs/jsdoc/tag/inline.js b/test/specs/jsdoc/tag/inline.js new file mode 100644 index 00000000..5cc9b5bd --- /dev/null +++ b/test/specs/jsdoc/tag/inline.js @@ -0,0 +1,201 @@ +/*global describe: true, expect: true, it: true */ + +describe('jsdoc/tag/inline', function() { + var jsdoc = { + tag: { + inline: require('jsdoc/tag/inline') + } + }; + + it('should exist', function() { + expect(jsdoc.tag.inline).toBeDefined(); + expect(typeof jsdoc.tag.inline).toBe('object'); + }); + + it('should export a replaceInlineTag function', function() { + expect(jsdoc.tag.inline.replaceInlineTag).toBeDefined(); + expect(typeof jsdoc.tag.inline.replaceInlineTag).toBe('function'); + }); + + it('should export an extractInlineTag function', function() { + expect(jsdoc.tag.inline.extractInlineTag).toBeDefined(); + expect(typeof jsdoc.tag.inline.replaceInlineTag).toBe('function'); + }); + + describe('replaceInlineTag', function() { + it('should throw if the replacer parameter is invalid', function() { + function badReplacerUndefined() { + jsdoc.tag.inline.replaceInlineTag('foo', '@bar'); + } + + function badReplacerString() { + jsdoc.tag.inline.replaceInlineTag('foo', '@bar', 'hello'); + } + + expect(badReplacerUndefined).toThrow(); + expect(badReplacerString).toThrow(); + }); + + it('should not find anything if there is no text in braces', function() { + function replacer(string, completeTag, tagText) { + expect(string).toBe('braceless text'); + expect(completeTag).toBe(''); + expect(tagText).toBe(''); + + return string; + } + + var result = jsdoc.tag.inline.replaceInlineTag('braceless text', null, replacer); + expect(result.tag).toBe(null); + expect(result.text).toBe(''); + expect(result.newString).toBe('braceless text'); + }); + + it('should cope with bad escapement at the end of the string', function() { + function replacer(string, completeTag, tagText) { + expect(string).toBe('bad {escapement \\'); + expect(completeTag).toBe(''); + expect(tagText).toBe(''); + + return string; + } + + var result = jsdoc.tag.inline.replaceInlineTag('bad {escapement \\', null, replacer); + expect(result.tag).toBe(null); + expect(result.text).toBe(''); + expect(result.newString).toBe('bad {escapement \\'); + }); + + it('should handle escaped braces correctly', function() { + function replacer(string, completeTag, tagText) { + expect(string).toBe('a {braces \\} test}'); + expect(completeTag).toBe('{braces \\} test}'); + expect(tagText).toBe('braces \\} test'); + + return string; + } + + var result = jsdoc.tag.inline.replaceInlineTag('a {braces \\} test}', null, replacer); + expect(result.tag).toBe(null); + expect(result.text).toBe('braces } test'); + expect(result.newString).toBe('a {braces \\} test}'); + }); + + it('should work if the tag is the entire string', function() { + function replacer(string, completeTag, tagText) { + expect(string).toBe('{text in braces}'); + expect(completeTag).toBe('{text in braces}'); + expect(tagText).toBe('text in braces'); + + return string; + } + + var result = jsdoc.tag.inline.replaceInlineTag('{text in braces}', null, replacer); + expect(result.tag).toBe(null); + expect(result.text).toBe('text in braces'); + expect(result.newString).toBe('{text in braces}'); + }); + + it('should work if the tag is at the beginning of the string', function() { + function replacer(string, completeTag, tagText) { + expect(string).toBe('{test string} ahoy'); + expect(completeTag).toBe('{test string}'); + expect(tagText).toBe('test string'); + + return string; + } + + var result = jsdoc.tag.inline.replaceInlineTag('{test string} ahoy', null, replacer); + expect(result.tag).toBe(null); + expect(result.text).toBe('test string'); + expect(result.newString).toBe('{test string} ahoy'); + }); + + it('should work if the tag is in the middle of the string', function() { + function replacer(string, completeTag, tagText) { + expect(string).toBe('a {test string} yay'); + expect(completeTag).toBe('{test string}'); + expect(tagText).toBe('test string'); + + return string; + } + + var result = jsdoc.tag.inline.replaceInlineTag('a {test string} yay', null, replacer); + expect(result.tag).toBe(null); + expect(result.text).toBe('test string'); + expect(result.newString).toBe('a {test string} yay'); + }); + + it('should work if the tag is at the end of the string', function() { + function replacer(string, completeTag, tagText) { + expect(string).toBe('a {test string}'); + expect(completeTag).toBe('{test string}'); + expect(tagText).toBe('test string'); + + return string; + } + + var result = jsdoc.tag.inline.replaceInlineTag('a {test string}', null, replacer); + expect(result.tag).toBe(null); + expect(result.text).toBe('test string'); + expect(result.newString).toBe('a {test string}'); + }); + + it('should replace the string with the specified value', function() { + function replacer() { + return 'REPLACED!'; + } + + var result = jsdoc.tag.inline.replaceInlineTag('a {test string}', null, replacer); + expect(result.newString).toBe('REPLACED!'); + }); + + it('should work when there are nested braces', function() { + function replacer(string, completeTag, tagText) { + expect(string).toBe('some {{double}} braces'); + expect(completeTag).toBe('{{double}}'); + expect(tagText).toBe('{double}'); + + return string; + } + + var result = jsdoc.tag.inline.replaceInlineTag('some {{double}} braces', null, + replacer); + expect(result.tag).toBe(null); + expect(result.text).toBe('{double}'); + expect(result.newString).toBe('some {{double}} braces'); + }); + + it('should work when a tag is specified', function() { + function replacer(string, completeTag, tagText) { + expect(string).toBe('a {@foo tag} test'); + expect(completeTag).toBe('{@foo tag}'); + expect(tagText).toBe('tag'); + + return string; + } + + var result = jsdoc.tag.inline.replaceInlineTag('a {@foo tag} test', '@foo', replacer); + expect(result.tag).toBe('@foo'); + expect(result.text).toBe('tag'); + expect(result.newString).toBe('a {@foo tag} test'); + }); + }); + + // largely covered by the replaceInlineTag tests + describe('extractInlineTag', function() { + it('should work when there is no tag specified', function() { + var result = jsdoc.tag.inline.extractInlineTag('some {braced text}'); + expect(result.tag).toBe(null); + expect(result.text).toBe('braced text'); + expect(result.newString).toBe('some'); + }); + + it('should work when a tag is specified', function() { + var result = jsdoc.tag.inline.extractInlineTag('some {@tagged text}', '@tagged'); + expect(result.tag).toBe('@tagged'); + expect(result.text).toBe('text'); + expect(result.newString).toBe('some'); + }); + }); +}); diff --git a/test/specs/jsdoc/tag/type.js b/test/specs/jsdoc/tag/type.js index 5f985b33..a5ed0830 100644 --- a/test/specs/jsdoc/tag/type.js +++ b/test/specs/jsdoc/tag/type.js @@ -3,16 +3,16 @@ function buildText(type, name, desc) { var text = ''; if (type) { - text += "{" + type + "}"; + text += '{' + type + '}'; if (name || desc) { - text += " "; + text += ' '; } } if (name) { text += name; if (desc) { - text += " "; + text += ' '; } } @@ -23,129 +23,157 @@ function buildText(type, name, desc) { return text; } -describe("jsdoc/tag/type", function() { +describe('jsdoc/tag/type', function() { var jsdoc = { tag: { type: require('jsdoc/tag/type') } }; - it("should exist", function() { + it('should exist', function() { expect(jsdoc.tag.type).toBeDefined(); - expect(typeof jsdoc.tag.type).toEqual("object"); + expect(typeof jsdoc.tag.type).toBe('object'); }); - it("should export a getTagInfo function", function() { - expect(jsdoc.tag.type.getTagInfo).toBeDefined(); - expect(typeof jsdoc.tag.type.getTagInfo).toEqual("function"); - }); - - it("should export a parse function", function() { + it('should export a parse function', function() { expect(jsdoc.tag.type.parse).toBeDefined(); - expect(typeof jsdoc.tag.type.parse).toEqual("function"); + expect(typeof jsdoc.tag.type.parse).toBe('function'); }); - describe("getTagInfo", function() { - it("should return an object with name, type, and text properties", function() { - var info = jsdoc.tag.type.getTagInfo(""); + describe('parse', function() { + it('should return an object with name, type, and text properties', function() { + var info = jsdoc.tag.type.parse(''); expect(info.name).toBeDefined(); expect(info.type).toBeDefined(); expect(info.text).toBeDefined(); }); - it("should not extract a name or type if canHaveName and canHaveType are not set", function() { - var desc = "{number} foo The foo parameter."; - var info = jsdoc.tag.type.getTagInfo(desc); - expect(info.type).toEqual(''); - expect(info.name).toEqual(''); - expect(info.text).toEqual(desc); + it('should not extract a name or type if canHaveName and canHaveType are not set', function() { + var desc = '{number} foo The foo parameter.'; + var info = jsdoc.tag.type.parse(desc); + expect(info.type).toEqual([]); + expect(info.name).toBe(''); + expect(info.text).toBe(desc); }); - it("should extract a name, but not a type, if canHaveName === true and canHaveType === false", function() { - var name = "bar"; - var desc = "The bar parameter."; - var info = jsdoc.tag.type.getTagInfo( buildText(null, name, desc), true, false ); - expect(info.type).toEqual(''); - expect(info.name).toEqual(name); - expect(info.text).toEqual(desc); + it('should extract a name, but not a type, if canHaveName === true and canHaveType === false', function() { + var name = 'bar'; + var desc = 'The bar parameter.'; + var info = jsdoc.tag.type.parse( buildText(null, name, desc), true, false ); + expect(info.type).toEqual([]); + expect(info.name).toBe(name); + expect(info.text).toBe(desc); }); - it("should extract a type, but not a name, if canHaveName === false and canHaveType === true", function() { - var type = "boolean"; - var desc = "Set to true on alternate Thursdays."; - var info = jsdoc.tag.type.getTagInfo( buildText(type, null, desc), false, true ); - expect(info.type).toEqual(type); - expect(info.name).toEqual(''); - expect(info.text).toEqual(desc); + it('should extract a type, but not a name, if canHaveName === false and canHaveType === true', function() { + var type = 'boolean'; + var desc = 'Set to true on alternate Thursdays.'; + var info = jsdoc.tag.type.parse( buildText(type, null, desc), false, true ); + expect(info.type).toEqual([type]); + expect(info.name).toBe(''); + expect(info.text).toBe(desc); }); - it("should extract a name and type if canHaveName and canHaveType are true", function() { - var type = "string"; - var name = "baz"; - var desc = "The baz parameter."; - var info = jsdoc.tag.type.getTagInfo( buildText(type, name, desc), true, true ); - expect(info.type).toEqual(type); - expect(info.name).toEqual(name); - expect(info.text).toEqual(desc); + it('should extract a name and type if canHaveName and canHaveType are true', function() { + var type = 'string'; + var name = 'baz'; + var desc = 'The baz parameter.'; + var info = jsdoc.tag.type.parse( buildText(type, name, desc), true, true ); + expect(info.type).toEqual([type]); + expect(info.name).toBe(name); + expect(info.text).toBe(desc); }); - - it("should work with JSDoc-style optional parameters", function() { - var name = "[qux]"; - var desc = "The qux parameter."; - var info = jsdoc.tag.type.getTagInfo( buildText(null, name, desc), true, false ); - expect(info.name).toEqual(name); - expect(info.text).toEqual(desc); - - name = "[ qux ]"; - info = jsdoc.tag.type.getTagInfo( buildText(null, name, desc), true, false ); - expect(info.name).toEqual(name); - expect(info.text).toEqual(desc); - - name = "[qux=hooray]"; - info = jsdoc.tag.type.getTagInfo( buildText(null, name, desc), true, false ); - expect(info.name).toEqual(name); - expect(info.text).toEqual(desc); - - name = "[ qux = hooray ]"; - info = jsdoc.tag.type.getTagInfo( buildText(null, name, desc), true, false ); - expect(info.name).toEqual(name); - expect(info.text).toEqual(desc); - }); - }); - - describe("parse", function() { - it("should report optional types correctly no matter which syntax we use", function() { - var desc = "{string} [foo]"; + + it('should report optional types correctly no matter which syntax we use', function() { + var desc = '{string} [foo]'; var info = jsdoc.tag.type.parse(desc, true, true); - expect(info.optional).toEqual(true); + expect(info.optional).toBe(true); - desc = "{string=} [foo]"; + desc = '{string=} [foo]'; info = jsdoc.tag.type.parse(desc, true, true); - expect(info.optional).toEqual(true); + expect(info.optional).toBe(true); }); - it("should return the types as an array", function() { - var desc = "{string} foo"; + it('should return the types as an array', function() { + var desc = '{string} foo'; var info = jsdoc.tag.type.parse(desc, true, true); - expect(info.type).toEqual( ["string"] ); + expect(info.type).toEqual( ['string'] ); }); - it("should recognize the entire list of possible types", function() { - var desc = "{string|number} foo"; + it('should recognize the entire list of possible types', function() { + var desc = '{(string|number)} foo'; var info = jsdoc.tag.type.parse(desc, true, true); - expect(info.type).toEqual( ["string", "number"] ); + expect(info.type).toEqual( ['string', 'number'] ); - desc = "{ string | number } foo"; + desc = '{ ( string | number ) } foo'; info = jsdoc.tag.type.parse(desc, true, true); - expect(info.type).toEqual( ["string", "number"] ); + expect(info.type).toEqual( ['string', 'number'] ); - desc = "{ ( string | number)} foo"; + desc = '{ ( string | number)} foo'; info = jsdoc.tag.type.parse(desc, true, true); - expect(info.type).toEqual( ["string", "number"] ); + expect(info.type).toEqual( ['string', 'number'] ); - desc = "{(string|number|boolean|function)} foo"; + desc = '{(string|number|boolean|function)} foo'; info = jsdoc.tag.type.parse(desc, true, true); - expect(info.type).toEqual( ["string", "number", "boolean", "function"] ); + expect(info.type).toEqual( ['string', 'number', 'boolean', 'function'] ); + }); + + it('should override the type expression if an inline @type tag is specified', function() { + var desc = '{Object} cookie {@type Monster}'; + var info = jsdoc.tag.type.parse(desc, true, true); + expect(info.type).toEqual( ['Monster'] ); + expect(info.text).toBe(''); + + desc = '{Object} cookie - {@type Monster}'; + info = jsdoc.tag.type.parse(desc, true, true); + expect(info.type).toEqual( ['Monster'] ); + expect(info.text).toBe(''); + + desc = '{Object} cookie - The cookie parameter. {@type Monster}'; + info = jsdoc.tag.type.parse(desc, true, true); + expect(info.type).toEqual( ['Monster'] ); + expect(info.text).toBe('The cookie parameter.'); + + desc = '{Object} cookie - The cookie parameter. {@type (Monster|Jar)}'; + info = jsdoc.tag.type.parse(desc, true, true); + expect(info.type).toEqual( ['Monster', 'Jar'] ); + expect(info.text).toBe('The cookie parameter.'); + + desc = '{Object} cookie - The cookie parameter. {@type (Monster|Jar)} Mmm, cookie.'; + info = jsdoc.tag.type.parse(desc, true, true); + expect(info.type).toEqual( ['Monster', 'Jar'] ); + expect(info.text).toBe('The cookie parameter. Mmm, cookie.'); + }); + + describe('JSDoc-style type info', function() { + it('should parse JSDoc-style optional parameters', function() { + var name = '[qux]'; + var desc = 'The qux parameter.'; + var info = jsdoc.tag.type.parse( buildText(null, name, desc), true, false ); + expect(info.name).toBe('qux'); + expect(info.text).toBe(desc); + expect(info.optional).toBe(true); + + name = '[ qux ]'; + info = jsdoc.tag.type.parse( buildText(null, name, desc), true, false ); + expect(info.name).toBe('qux'); + expect(info.text).toBe(desc); + expect(info.optional).toBe(true); + + name = '[qux=hooray]'; + info = jsdoc.tag.type.parse( buildText(null, name, desc), true, false ); + expect(info.name).toBe('qux'); + expect(info.text).toBe(desc); + expect(info.optional).toBe(true); + expect(info.defaultvalue).toBe('hooray'); + + name = '[ qux = hooray ]'; + info = jsdoc.tag.type.parse( buildText(null, name, desc), true, false ); + expect(info.name).toBe('qux'); + expect(info.text).toBe(desc); + expect(info.optional).toBe(true); + expect(info.defaultvalue).toBe('hooray'); + }); }); }); }); diff --git a/test/specs/jsdoc/tag/type/closureCompilerType.js b/test/specs/jsdoc/tag/type/closureCompilerType.js deleted file mode 100644 index 61c556ca..00000000 --- a/test/specs/jsdoc/tag/type/closureCompilerType.js +++ /dev/null @@ -1,25 +0,0 @@ -/*global describe: true, expect: true, it: true */ -describe('jsdoc/tag/type/closureCompilerType', function() { - // TODO: more tests - - var type = require('jsdoc/tag/type/closureCompilerType'); - - it('should exist', function() { - expect(type).toBeDefined(); - expect(typeof type).toEqual('object'); - }); - - it('should export a parse function', function() { - expect(type.parse).toBeDefined(); - expect(typeof type.parse).toEqual('function'); - }); - - describe('parse', function() { - it('should correctly parse types that are both optional and nullable', function() { - var info = type.parse( {type: '?string='} ); - expect(info.type).toEqual('string'); - expect(info.optional).toEqual(true); - expect(info.nullable).toEqual(true); - }); - }); -}); diff --git a/test/specs/jsdoc/tag/type/jsdocType.js b/test/specs/jsdoc/tag/type/jsdocType.js deleted file mode 100644 index d62a6fe8..00000000 --- a/test/specs/jsdoc/tag/type/jsdocType.js +++ /dev/null @@ -1,68 +0,0 @@ -/*global describe: true, expect: true, it: true */ - -var hasOwnProp = Object.prototype.hasOwnProperty; - -describe("jsdoc/tag/type/jsdocType", function() { - var jsdocType = require("jsdoc/tag/type/jsdocType"); - - it("should exist", function() { - expect(jsdocType).toBeDefined(); - expect(typeof jsdocType).toEqual("object"); - }); - - it("should export a parse function", function() { - expect(jsdocType.parse).toBeDefined(); - expect(typeof jsdocType.parse).toEqual("function"); - }); - - describe("parse", function() { - it("should recognize optional properties without default values", function() { - var info = jsdocType.parse( { name: "[foo]" } ); - expect(info.name).toEqual("foo"); - expect(info.optional).toEqual(true); - expect( info.defaultvalue ).toEqual(null); - - info = jsdocType.parse( { name: "[ bar ]" } ); - expect(info.name).toEqual("bar"); - expect(info.optional).toEqual(true); - expect( info.defaultvalue ).toEqual(null); - }); - - it("should recognize optional properties with default values", function() { - var info = jsdocType.parse( { name: "[foo=bar]" } ); - expect(info.name).toEqual("foo"); - expect(info.optional).toEqual(true); - expect( info.defaultvalue ).toEqual("bar"); - - info = jsdocType.parse( { name: "[ baz = qux ]" } ); - expect(info.name).toEqual("baz"); - expect(info.optional).toEqual(true); - expect( info.defaultvalue ).toEqual("qux"); - }); - - it("should only change the `name`, `optional`, and `defaultvalue` properties", function() { - var obj = { - name: "[foo=bar]", - type: "boolean|string", - text: "Sample text.", - optional: null, - nullable: null, - variable: null, - defaultvalue: null - }; - var shouldChange = [ "name", "optional", "defaultvalue" ]; - - var info = jsdocType.parse(obj); - for (var key in info) { - if ( hasOwnProp.call(info, key) ) { - if ( shouldChange.indexOf(key) !== -1 ) { - expect( info[key] ).not.toEqual( obj[key] ); - } - else { - expect( info[key] ).toEqual( obj[key] ); - } - } - } - }); - }); -}); diff --git a/test/specs/jsdoc/util/templateHelper.js b/test/specs/jsdoc/util/templateHelper.js index c434af4a..f4392fb5 100644 --- a/test/specs/jsdoc/util/templateHelper.js +++ b/test/specs/jsdoc/util/templateHelper.js @@ -223,10 +223,12 @@ describe("jsdoc/util/templateHelper", function() { describe("linkto", function() { beforeEach(function() { helper.longnameToUrl.linktoTest = 'test.html'; + helper.longnameToUrl.LinktoFakeClass = 'fakeclass.html'; }); afterEach(function() { delete helper.longnameToUrl.linktoTest; + delete helper.longnameToUrl.LinktoFakeClass; }); it('returns the longname if only the longname is specified and has no URL', function() { @@ -260,12 +262,34 @@ describe("jsdoc/util/templateHelper", function() { expect(link).toBe('link text'); }); - it("is careful with longnames that are reserved words in JS", function() { + it('is careful with longnames that are reserved words in JS', function() { // we don't have a registered link for 'constructor' so it should return the text 'link text'. var link = helper.linkto('constructor', 'link text'); expect(typeof link).toBe('string'); expect(link).toBe('link text'); }); + + it('works correctly with type applications if only the longname is specified', function() { + var link = helper.linkto('Array.'); + expect(link).toBe('Array.<LinktoFakeClass>'); + }); + + it('works correctly with type applications if a class is not specified', function() { + var link = helper.linkto('Array.', 'link text'); + expect(link).toBe('Array.<LinktoFakeClass>'); + }); + + it('works correctly with type applications if a class is specified', function() { + var link = helper.linkto('Array.', 'link text', 'myclass'); + expect(link).toBe('Array.<LinktoFakeClass' + + '>'); + }); + + it('works correctly with type applications that include a type union', function() { + var link = helper.linkto('Array.<(linktoTest|LinktoFakeClass)>', 'link text'); + expect(link).toBe('Array.<(linktoTest|' + + 'LinktoFakeClass)>'); + }); }); describe("htmlsafe", function() { diff --git a/test/specs/tags/paramtag.js b/test/specs/tags/paramtag.js index 3e7b2696..10e847fa 100644 --- a/test/specs/tags/paramtag.js +++ b/test/specs/tags/paramtag.js @@ -11,7 +11,7 @@ describe("@param tag", function() { it('When a symbol has an @param tag with a type before the name, the doclet has a params property that includes that param.', function() { expect(typeof find.params).toBe('object'); expect(find.params.length).toBe(1); - expect(find.params[0].type.names.join(', ')).toBe('String, Array'); + expect(find.params[0].type.names.join(', ')).toBe('String, Array.'); expect(find.params[0].name).toBe('targetName'); expect(find.params[0].description).toBe('The name (or names) of what to find.'); }); diff --git a/test/specs/tags/returnstag.js b/test/specs/tags/returnstag.js index f459b236..2fcf2e59 100644 --- a/test/specs/tags/returnstag.js +++ b/test/specs/tags/returnstag.js @@ -6,7 +6,7 @@ describe("@returns tag", function() { it('When a symbol has an @returns tag with a type and description, the doclet has a returns array that includes that return.', function() { expect(typeof find.returns).toBe('object'); expect(find.returns.length).toBe(1); - expect(find.returns[0].type.names.join(', ')).toBe('String, Array'); + expect(find.returns[0].type.names.join(', ')).toBe('String, Array.'); expect(find.returns[0].description).toBe('The names of the found item(s).'); }); diff --git a/test/specs/tags/typetag.js b/test/specs/tags/typetag.js index eb48b9c7..055fa81d 100644 --- a/test/specs/tags/typetag.js +++ b/test/specs/tags/typetag.js @@ -6,7 +6,7 @@ describe("@type tag", function() { it('When a symbol has an @type tag, the doclet has a type property set to that value\'s type.', function() { expect(typeof foo.type).toBe('object'); expect(typeof foo.type.names).toBe('object'); - expect(foo.type.names.join(', ')).toBe('string, Array'); + expect(foo.type.names.join(', ')).toBe('string, Array.'); }); it('When a symbol has an @type tag set to a plain string, the doclet has a type property set to that string as if it were a type.', function() {