Spaces:
Sleeping
Sleeping
File size: 7,425 Bytes
6abff73 | 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 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 | // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.
/**
* Helpers for validating various text string formats.
*/
export class StringChecks {
/**
* Tests whether the input string is a valid TSDoc tag name; if not, returns an error message.
* TSDoc tag names start with an at-sign ("@") followed by ASCII letters using
* "camelCase" capitalization.
*/
static explainIfInvalidTSDocTagName(tagName) {
if (tagName[0] !== '@') {
return 'A TSDoc tag name must start with an "@" symbol';
}
if (!StringChecks._tsdocTagNameRegExp.test(tagName)) {
return 'A TSDoc tag name must start with a letter and contain only letters and numbers';
}
return undefined;
}
/**
* Throws an exception if the input string is not a valid TSDoc tag name.
* TSDoc tag names start with an at-sign ("@") followed by ASCII letters using
* "camelCase" capitalization.
*/
static validateTSDocTagName(tagName) {
const explanation = StringChecks.explainIfInvalidTSDocTagName(tagName);
if (explanation) {
throw new Error(explanation);
}
}
/**
* Tests whether the input string is a URL form supported inside an "@link" tag; if not,
* returns an error message.
*/
static explainIfInvalidLinkUrl(url) {
if (url.length === 0) {
return 'The URL cannot be empty';
}
if (!StringChecks._urlSchemeRegExp.test(url)) {
return ('An @link URL must begin with a scheme comprised only of letters and numbers followed by "://".' +
' (For general URLs, use an HTML "<a>" tag instead.)');
}
if (!StringChecks._urlSchemeAfterRegExp.test(url)) {
return 'An @link URL must have at least one character after "://"';
}
return undefined;
}
/**
* Tests whether the input string is a valid HTML element or attribute name.
*/
static explainIfInvalidHtmlName(htmlName) {
if (!StringChecks._htmlNameRegExp.test(htmlName)) {
return 'An HTML name must be an ASCII letter followed by zero or more letters, digits, or hyphens';
}
return undefined;
}
/**
* Throws an exception if the input string is a not valid HTML element or attribute name.
*/
static validateHtmlName(htmlName) {
const explanation = StringChecks.explainIfInvalidHtmlName(htmlName);
if (explanation) {
throw new Error(explanation);
}
}
/**
* Tests whether the input string is a valid NPM package name.
*/
static explainIfInvalidPackageName(packageName) {
if (packageName.length === 0) {
return 'The package name cannot be an empty string';
}
if (!StringChecks._validPackageNameRegExp.test(packageName)) {
return `The package name ${JSON.stringify(packageName)} is not a valid package name`;
}
return undefined;
}
/**
* Tests whether the input string is a valid declaration reference import path.
*/
static explainIfInvalidImportPath(importPath, prefixedByPackageName) {
if (importPath.length > 0) {
if (importPath.indexOf('//') >= 0) {
return 'An import path must not contain "//"';
}
if (importPath[importPath.length - 1] === '/') {
return 'An import path must not end with "/"';
}
if (!prefixedByPackageName) {
if (importPath[0] === '/') {
return 'An import path must not start with "/" unless prefixed by a package name';
}
}
}
return undefined;
}
/**
* Returns true if the input string is a TSDoc system selector.
*/
static isSystemSelector(selector) {
return StringChecks._systemSelectors.has(selector);
}
/**
* Tests whether the input string is a valid ECMAScript identifier.
* A precise check is extremely complicated and highly dependent on the standard version
* and how faithfully the interpreter implements it, so here we use a conservative heuristic.
*/
static explainIfInvalidUnquotedIdentifier(identifier) {
if (identifier.length === 0) {
return 'The identifier cannot be an empty string';
}
if (StringChecks._identifierBadCharRegExp.test(identifier)) {
return 'The identifier cannot non-word characters';
}
if (StringChecks._identifierNumberStartRegExp.test(identifier)) {
return 'The identifier must not start with a number';
}
return undefined;
}
/**
* Tests whether the input string can be used without quotes as a member identifier in a declaration reference.
* If not, it should be enclosed in quotes.
*/
static explainIfInvalidUnquotedMemberIdentifier(identifier) {
const explanation = StringChecks.explainIfInvalidUnquotedIdentifier(identifier);
if (explanation !== undefined) {
return explanation;
}
if (StringChecks.isSystemSelector(identifier)) {
// We do this to avoid confusion about the declaration reference syntax rules.
// For example if someone were to see "MyClass.(static:instance)" it would be unclear which
// side the colon is the selector.
return `The identifier "${identifier}" must be quoted because it is a TSDoc system selector name`;
}
return undefined;
}
}
StringChecks._tsdocTagNameRegExp = /^@[a-z][a-z0-9]*$/i;
StringChecks._urlSchemeRegExp = /^[a-z][a-z0-9]*\:\/\//i;
StringChecks._urlSchemeAfterRegExp = /^[a-z][a-z0-9]*\:\/\/./i;
// HTML element definitions:
// https://spec.commonmark.org/0.29/#tag-name
// https://www.w3.org/TR/html5/syntax.html#tag-name
// https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name
//
// We use the CommonMark spec:
// "A tag name consists of an ASCII letter followed by zero or more ASCII letters, digits, or hyphens (-)."
StringChecks._htmlNameRegExp = /^[a-z]+[a-z0-9\-]*$/i;
// Note: In addition to letters, numbers, underscores, and dollar signs, modern ECMAScript
// also allows Unicode categories such as letters, combining marks, digits, and connector punctuation.
// These are mostly supported in all environments except IE11, so if someone wants it, we would accept
// a PR to allow them (although the test surface might be somewhat large).
StringChecks._identifierBadCharRegExp = /[^a-z0-9_$]/i;
// Identifiers most not start with a number.
StringChecks._identifierNumberStartRegExp = /^[0-9]/;
// For detailed notes about NPM package name syntax, see:
// tslint:disable-next-line:max-line-length
// https://github.com/Microsoft/web-build-tools/blob/a417ca25c63aca31dba43a34d39cc9cd529b9c78/libraries/node-core-library/src/PackageName.ts
StringChecks._validPackageNameRegExp = /^(?:@[a-z0-9\-_\.]+\/)?[a-z0-9\-_\.]+$/i;
StringChecks._systemSelectors = new Set([
// For classes:
'instance',
'static',
'constructor',
// For merged declarations:
'class',
'enum',
'function',
'interface',
'namespace',
'type',
'variable'
]);
//# sourceMappingURL=StringChecks.js.map |