/var/www/greso.tech/server/nsm/node_modules/jsdoc/lib/jsdoc/util
Edit: /var/www/greso.tech/server/nsm/node_modules/jsdoc/lib/jsdoc/util/templateHelper.js (31934B)
/**
* @module jsdoc/util/templateHelper
*/
const catharsis = require('catharsis');
let dictionary = require('jsdoc/tag/dictionary');
const env = require('jsdoc/env');
const inline = require('jsdoc/tag/inline');
const logger = require('jsdoc/util/logger');
const name = require('jsdoc/name');
const util = require('util');
const hasOwnProp = Object.prototype.hasOwnProperty;
const MODULE_NAMESPACE = 'module:';
const files = {};
const ids = {};
// each container gets its own html file
const containers = ['class', 'module', 'external', 'namespace', 'mixin', 'interface'];
let tutorials;
/** Sets tutorials map.
@param {jsdoc.tutorial.Tutorial} root - Root tutorial node.
*/
exports.setTutorials = root => {
tutorials = root;
};
exports.globalName = name.SCOPE.NAMES.GLOBAL;
exports.fileExtension = '.html';
exports.scopeToPunc = name.scopeToPunc;
const linkMap = {
// two-way lookup
longnameToUrl: {},
urlToLongname: {},
// one-way lookup (IDs are only unique per file)
longnameToId: {}
};
// two-way lookup
const tutorialLinkMap = {
nameToUrl: {},
urlToName: {}
};
const longnameToUrl = exports.longnameToUrl = linkMap.longnameToUrl;
const longnameToId = exports.longnameToId = linkMap.longnameToId;
const registerLink = exports.registerLink = (longname, fileUrl) => {
linkMap.longnameToUrl[longname] = fileUrl;
linkMap.urlToLongname[fileUrl] = longname;
};
const registerId = exports.registerId = (longname, fragment) => {
linkMap.longnameToId[longname] = fragment;
};
function getNamespace(kind) {
if (dictionary.isNamespace(kind)) {
return `${kind}:`;
}
return '';
}
function formatNameForLink(doclet) {
let newName = getNamespace(doclet.kind) + (doclet.name || '') + (doclet.variation || '');
const scopePunc = exports.scopeToPunc[doclet.scope] || '';
// Only prepend the scope punctuation if it's not the same character that marks the start of a
// fragment ID. Using `#` in HTML5 fragment IDs is legal, but URLs like `foo.html##bar` are
// just confusing.
if (scopePunc !== '#') {
newName = scopePunc + newName;
}
return newName;
}
function makeUniqueFilename(filename, str) {
let key = filename.toLowerCase();
let nonUnique = true;
// don't allow filenames to begin with an underscore
if (!filename.length || filename[0] === '_') {
filename = `-${filename}`;
key = filename.toLowerCase();
}
// append enough underscores to make the filename unique
while (nonUnique) {
if ( hasOwnProp.call(files, key) ) {
filename += '_';
key = filename.toLowerCase();
} else {
nonUnique = false;
}
}
files[key] = str;
return filename;
}
/**
* Convert a string to a unique filename, including an extension.
*
* Filenames are cached to ensure that they are used only once. For example, if the same string is
* passed in twice, two different filenames will be returned.
*
* Also, filenames are not considered unique if they are capitalized differently but are otherwise
* identical.
*
* @function
* @param {string} str The string to convert.
* @return {string} The filename to use for the string.
*/
const getUniqueFilename = exports.getUniqueFilename = str => {
const namespaces = dictionary.getNamespaces().join('|');
let basename = (str || '')
// use - instead of : in namespace prefixes
.replace(new RegExp(`^(${namespaces}):`), '$1-')
// replace characters that can cause problems on some filesystems
.replace(/[\\/?*:|'"<>]/g, '_')
// use - instead of ~ to denote 'inner'
.replace(/~/g, '-')
// use _ instead of # to denote 'instance'
.replace(/#/g, '_')
// use _ instead of / (for example, in module names)
.replace(/\//g, '_')
// remove the variation, if any
.replace(/\([\s\S]*\)$/, '')
// make sure we don't create hidden files, or files whose names start with a dash
.replace(/^[.-]/, '');
// in case we've now stripped the entire basename (uncommon, but possible):
basename = basename.length ? basename : '_';
return makeUniqueFilename(basename, str) + exports.fileExtension;
};
/**
* Get a longname's filename if one has been registered; otherwise, generate a unique filename, then
* register the filename.
* @private
*/
function getFilename(longname) {
let fileUrl;
if ( hasOwnProp.call(longnameToUrl, longname) ) {
fileUrl = longnameToUrl[longname];
}
else {
fileUrl = getUniqueFilename(longname);
registerLink(longname, fileUrl);
}
return fileUrl;
}
/**
* Check whether a symbol is the only symbol exported by a module (as in
* `module.exports = function() {};`).
*
* @private
* @param {module:jsdoc/doclet.Doclet} doclet - The doclet for the symbol.
* @return {boolean} `true` if the symbol is the only symbol exported by a module; otherwise,
* `false`.
*/
function isModuleExports(doclet) {
return doclet.longname && doclet.longname === doclet.name &&
doclet.longname.indexOf(MODULE_NAMESPACE) === 0 && doclet.kind !== 'module';
}
function makeUniqueId(filename, id) {
let key;
let nonUnique = true;
key = id.toLowerCase();
// HTML5 IDs cannot contain whitespace characters
id = id.replace(/\s/g, '');
// append enough underscores to make the identifier unique
while (nonUnique) {
if ( hasOwnProp.call(ids, filename) && hasOwnProp.call(ids[filename], key) ) {
id += '_';
key = id.toLowerCase();
}
else {
nonUnique = false;
}
}
ids[filename] = ids[filename] || {};
ids[filename][key] = id;
return id;
}
/**
* Get a doclet's ID if one has been registered; otherwise, generate a unique ID, then register
* the ID.
* @private
*/
function getId(longname, id) {
if ( hasOwnProp.call(longnameToId, longname) ) {
id = longnameToId[longname];
}
else if (!id) {
// no ID required
return '';
}
else {
id = makeUniqueId(longname, id);
registerId(longname, id);
}
return id;
}
/**
* Convert a doclet to an identifier that is unique for a specified filename.
*
* Identifiers are not considered unique if they are capitalized differently but are otherwise
* identical.
*
* @method
* @param {string} filename - The file in which the identifier will be used.
* @param {string} doclet - The doclet to convert.
* @return {string} A unique identifier based on the file and doclet.
*/
exports.getUniqueId = makeUniqueId;
const htmlsafe = exports.htmlsafe = str => {
if (typeof str !== 'string') {
str = String(str);
}
return str.replace(/&/g, '&')
.replace(/$/.test(expr);
}
function fragmentHash(fragmentId) {
if (!fragmentId) {
return '';
}
return `#${fragmentId}`;
}
function getShortName(longname) {
return name.shorten(longname).name;
}
/**
* Build an HTML link to the symbol with the specified longname. If the longname is not
* associated with a URL, this method simply returns the link text, if provided, or the longname.
*
* The `longname` parameter can also contain a URL rather than a symbol's 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 (or URL) 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 {Object} options - Options for building the link.
* @param {string=} options.cssClass - The CSS class (or classes) to include in the link's ``
* tag.
* @param {string=} options.fragmentId - The fragment identifier (for example, `name` in
* `foo.html#name`) to append to the link target.
* @param {string=} options.linkMap - The link map in which to look up the longname.
* @param {boolean=} options.monospace - Indicates whether to display the link text in a monospace
* font.
* @param {boolean=} options.shortenName - Indicates whether to extract the short name from the
* longname and display the short name in the link text. Ignored if `linkText` is specified.
* @return {string} The HTML link, or the link text if the link is not available.
*/
function buildLink(longname, linkText, options) {
const classString = options.cssClass ? util.format(' class="%s"', options.cssClass) : '';
let fileUrl;
const fragmentString = fragmentHash(options.fragmentId);
let stripped;
let text;
let parsedType;
// handle cases like:
// @see
// @see http://example.org
stripped = longname ? longname.replace(/^<|>$/g, '') : '';
if ( hasUrlPrefix(stripped) ) {
fileUrl = stripped;
text = linkText || stripped;
}
// handle complex type expressions that may require multiple links
// (but skip anything that looks like an inline tag or HTML tag)
else if (longname && isComplexTypeExpression(longname) && /\{@.+\}/.test(longname) === false &&
/^<[\s\S]+>/.test(longname) === false) {
parsedType = parseType(longname);
return stringifyType(parsedType, options.cssClass, options.linkMap);
}
else {
fileUrl = hasOwnProp.call(options.linkMap, longname) ? options.linkMap[longname] : '';
text = linkText || (options.shortenName ? getShortName(longname) : longname);
}
text = options.monospace ? `${text}` : text;
if (!fileUrl) {
return text;
}
else {
return util.format('%s', encodeURI(fileUrl + fragmentString),
classString, text);
}
}
/**
* Retrieve an HTML link to the symbol with the specified longname. If the longname is not
* associated with a URL, this method simply returns the link text, if provided, or the longname.
*
* The `longname` parameter can also contain a URL rather than a symbol's 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.
*
* @function
* @param {string} longname - The longname (or URL) 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.
* @param {string=} fragmentId - The fragment identifier (for example, `name` in `foo.html#name`) to
* append to the link target.
* @return {string} The HTML link, or a plain-text string if the link is not available.
*/
const linkto = exports.linkto = (longname, linkText, cssClass, fragmentId) => buildLink(longname, linkText, {
cssClass: cssClass,
fragmentId: fragmentId,
linkMap: longnameToUrl
});
function useMonospace(tag, text) {
let cleverLinks;
let monospaceLinks;
let result;
if ( hasUrlPrefix(text) ) {
result = false;
}
else if (tag === 'linkplain') {
result = false;
}
else if (tag === 'linkcode') {
result = true;
}
else {
cleverLinks = env.conf.templates.cleverLinks;
monospaceLinks = env.conf.templates.monospaceLinks;
if (monospaceLinks || cleverLinks) {
result = true;
}
}
return result || false;
}
function splitLinkText(text) {
let linkText;
let target;
let splitIndex;
// if a pipe is not present, we split on the first space
splitIndex = text.indexOf('|');
if (splitIndex === -1) {
splitIndex = text.search(/\s/);
}
if (splitIndex !== -1) {
linkText = text.substr(splitIndex + 1);
// Normalize subsequent newlines to a single space.
linkText = linkText.replace(/\n+/, ' ');
target = text.substr(0, splitIndex);
}
if (linkText) {
linkText = linkText.trim();
}
if (target) {
target = target.trim();
}
return {
linkText: linkText,
target: target || text
};
}
const tutorialToUrl = exports.tutorialToUrl = tutorial => {
let fileUrl;
const node = tutorials.getByName(tutorial);
// no such tutorial
if (!node) {
logger.error( new Error(`No such tutorial: ${tutorial}`) );
return null;
}
// define the URL if necessary
if (!hasOwnProp.call(tutorialLinkMap.nameToUrl, node.name)) {
fileUrl = `tutorial-${getUniqueFilename(node.name)}`;
tutorialLinkMap.nameToUrl[node.name] = fileUrl;
tutorialLinkMap.urlToName[fileUrl] = node.name;
}
return tutorialLinkMap.nameToUrl[node.name];
};
/**
* Retrieve a link to a tutorial, or the name of the tutorial if the tutorial is missing. If the
* `missingOpts` parameter is supplied, the names of missing tutorials will be prefixed by the
* specified text and wrapped in the specified HTML tag and CSS class.
*
* @function
* @todo Deprecate missingOpts once we have a better error-reporting mechanism.
* @param {string} tutorial The name of the tutorial.
* @param {string} content The link text to use.
* @param {object} [missingOpts] Options for displaying the name of a missing tutorial.
* @param {string} missingOpts.classname The CSS class to wrap around the tutorial name.
* @param {string} missingOpts.prefix The prefix to add to the tutorial name.
* @param {string} missingOpts.tag The tag to wrap around the tutorial name.
* @return {string} An HTML link to the tutorial, or the name of the tutorial with the specified
* options.
*/
const toTutorial = exports.toTutorial = (tutorial, content, missingOpts) => {
let classname;
let link;
let node;
let tag;
if (!tutorial) {
logger.error( new Error('Missing required parameter: tutorial') );
return null;
}
node = tutorials.getByName(tutorial);
// no such tutorial
if (!node) {
missingOpts = missingOpts || {};
tag = missingOpts.tag;
classname = missingOpts.classname;
link = tutorial;
if (missingOpts.prefix) {
link = missingOpts.prefix + link;
}
if (tag) {
link = `<${tag}${classname ? (` class="${classname}">`) : '>'}${link}`;
link += ``;
}
return link;
}
content = content || node.title;
return `${content}`;
};
function shouldShortenLongname() {
if (env.conf && env.conf.templates && env.conf.templates.useShortNamesInLinks) {
return true;
}
return false;
}
/**
* Find `{@link ...}` and `{@tutorial ...}` inline tags and turn them into HTML links.
*
* @param {string} str - The string to search for `{@link ...}` and `{@tutorial ...}` tags.
* @return {string} The linkified text.
*/
exports.resolveLinks = str => {
let replacers;
function extractLeadingText(string, completeTag) {
const tagIndex = string.indexOf(completeTag);
let leadingText = null;
const leadingTextRegExp = /\[(.+?)\]/g;
let leadingTextInfo = leadingTextRegExp.exec(string);
// did we find leading text, and if so, does it immediately precede the tag?
while (leadingTextInfo && leadingTextInfo.length) {
if (leadingTextInfo.index + leadingTextInfo[0].length === tagIndex) {
string = string.replace(leadingTextInfo[0], '');
leadingText = leadingTextInfo[1];
break;
}
leadingTextInfo = leadingTextRegExp.exec(string);
}
return {
leadingText: leadingText,
string: string
};
}
function processLink(string, {completeTag, text, tag}) {
const leading = extractLeadingText(string, completeTag);
let linkText = leading.leadingText;
let monospace;
let split;
let target;
string = leading.string;
split = splitLinkText(text);
target = split.target;
linkText = linkText || split.linkText;
monospace = useMonospace(tag, text);
return string.replace( completeTag, buildLink(target, linkText, {
linkMap: longnameToUrl,
monospace: monospace,
shortenName: shouldShortenLongname()
}) );
}
function processTutorial(string, {completeTag, text}) {
const leading = extractLeadingText(string, completeTag);
string = leading.string;
return string.replace( completeTag, toTutorial(text, leading.leadingText) );
}
replacers = {
link: processLink,
linkcode: processLink,
linkplain: processLink,
tutorial: processTutorial
};
return inline.replaceInlineTags(str, replacers).newString;
};
/**
* Convert tag text like `Jane Doe ` into a `mailto:` link.
*
* @param {string} str - The tag text.
* @return {string} The linkified text.
*/
exports.resolveAuthorLinks = str => {
let author = '';
let matches;
if (str) {
matches = str.match(/^\s?([\s\S]+)\b\s+<(\S+@\S+)>\s?$/);
if (matches && matches.length === 3) {
author = `${htmlsafe(matches[1])}`;
}
else {
author = htmlsafe(str);
}
}
return author;
};
/**
* Find items in a TaffyDB database that match the specified key-value pairs.
*
* @function
* @param {TAFFY} data The TaffyDB database to search.
* @param {object|function} spec Key-value pairs to match against (for example,
* `{ longname: 'foo' }`), or a function that returns `true` if a value matches or `false` if it
* does not match.
* @return {array