1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 | 1 736 736 736 736 1 22 1 627 1 50 50 50 627 627 714 714 714 714 758 758 50 50 625 1 595 595 595 1 585 6 | /** * @module jsdoc/tag/inline * * @author Jeff Williams <jeffrey.l.williams@gmail.com> * @license Apache License 2.0 - See file 'LICENSE.md' in this project. */ 'use strict'; /** * Information about an inline tag that was found within a string. * * @typedef {Object} InlineTagInfo * @memberof module:jsdoc/tag/inline * @property {?string} completeTag - The entire inline tag, including its enclosing braces. * @property {?string} tag - The tag whose text was found. * @property {?string} text - The tag text that was found. */ /** * Information about the results of replacing inline tags within a string. * * @typedef {Object} InlineTagResult * @memberof module:jsdoc/tag/inline * @property {Array.<module:jsdoc/tag/inline.InlineTagInfo>} tags - The inline tags that were found. * @property {string} newString - The updated text string after extracting or replacing the inline * tags. */ /** * Text-replacing function for strings that contain an inline tag. * * @callback InlineTagReplacer * @memberof module:jsdoc/tag/inline * @param {string} string - The complete string containing the inline tag. * @param {module:jsdoc/tag/inline.InlineTagInfo} tagInfo - Information about the inline tag. * @return {string} An updated version of the complete string. */ /** * Create a regexp that matches a specific inline tag, or all inline tags. * * @private * @memberof module:jsdoc/tag/inline * @param {?string} tagName - The inline tag that the regexp will match. May contain regexp * characters. If omitted, matches any string. * @param {?string} prefix - A prefix for the regexp. Defaults to an empty string. * @param {?string} suffix - A suffix for the regexp. Defaults to an empty string. * @returns {RegExp} A regular expression that matches the requested inline tag. */ function regExpFactory(tagName, prefix, suffix) { tagName = tagName || '\\S+'; prefix = prefix || ''; suffix = suffix || ''; return new RegExp(prefix + '\\{@' + tagName + '\\s+((?:.|\n)+?)\\}' + suffix, 'i'); } /** * Check whether a string is an inline tag. You can check for a specific inline tag or for any valid * inline tag. * * @param {string} string - The string to check. * @param {?string} tagName - The inline tag to match. May contain regexp characters. If this * parameter is omitted, this method returns `true` for any valid inline tag. * @returns {boolean} Set to `true` if the string is a valid inline tag or `false` in all other * cases. */ exports.isInlineTag = function(string, tagName) { return regExpFactory(tagName, '^', '$').test(string); }; /** * Replace all instances of multiple inline tags with other text. * * @param {string} string - The string in which to replace the inline tags. * @param {Object} replacers - The functions that are used to replace text in the string. The keys * must contain tag names (for example, `link`), and the values must contain functions with the * type {@link module:jsdoc/tag/inline.InlineTagReplacer}. * @return {module:jsdoc/tag/inline.InlineTagResult} The updated string, as well as information * about the inline tags that were found. */ exports.replaceInlineTags = function(string, replacers) { var tagInfo = []; function replaceMatch(replacer, tag, match, text) { var matchedTag = { completeTag: match, tag: tag, text: text }; tagInfo.push(matchedTag); return replacer(string, matchedTag); } string = string || ''; Object.keys(replacers).forEach(function(replacer) { var tagRegExp = regExpFactory(replacer); var matches; var previousString; // call the replacer once for each match do { matches = tagRegExp.exec(string); if (matches) { previousString = string; string = replaceMatch(replacers[replacer], replacer, matches[0], matches[1]); } } while (matches && previousString !== string); }); return { tags: tagInfo, newString: string.trim() }; }; /** * Replace all instances of an inline tag with other text. * * @param {string} string - The string in which to replace the inline tag. * @param {string} tag - The name of the inline tag to replace. * @param {module:jsdoc/tag/inline.InlineTagReplacer} replacer - The function that is used to * replace text in the string. * @return {module:jsdoc/tag/inline.InlineTagResult} The updated string, as well as information * about the inline tags that were found. */ exports.replaceInlineTag = function(string, tag, replacer) { var replacers = {}; replacers[tag] = replacer; return exports.replaceInlineTags(string, replacers); }; /** * Extract inline tags from a string, replacing them with an empty string. * * @param {string} string - The string from which to extract text. * @param {?string} tag - The inline tag to extract. * @return {module:jsdoc/tag/inline.InlineTagResult} The updated string, as well as information * about the inline tags that were found. */ exports.extractInlineTag = function(string, tag) { return exports.replaceInlineTag(string, tag, function(str, tagInfo) { return str.replace(tagInfo.completeTag, ''); }); }; |