regex-explain 0.0.0 → 1.0.0

package/dist/cjs/strings.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeEscape = decodeEscape;
+exports.splitDelimitedPattern = splitDelimitedPattern;
+exports.translateFlags = translateFlags;
+/** Single-character escapes that mean the same in every supported language that has them. */
+const SIMPLE_ESCAPES = {
+    b: "\b",
+    f: "\f",
+    n: "\n",
+    r: "\r",
+    t: "\t",
+    v: "\v",
+};
+/** Closing delimiters of PCRE patterns that open with a bracket. */
+const CLOSING_BRACKETS = {
+    "(": ")",
+    "[": "]",
+    "{": "}",
+    "<": ">",
+};
+/**
+ * Decodes one escape sequence from a string literal.
+ *
+ * Unknown single-character escapes such as `\q` decode to the character, as in JavaScript and Ruby.
+ * Grammars for languages that keep the backslash, such as Python and PHP, do not mark those as
+ * escapes, so they never reach this function.
+ *
+ * @param escape The escape's source text, starting with a backslash.
+ *
+ * @returns The decoded text, or undefined for escapes that cannot be decoded without knowing the
+ *   language, such as Python's `\N{name}`, or `\a` and `\e`, which are control characters in some
+ *   languages and plain letters in JavaScript.
+ */
+function decodeEscape(escape) {
+    const body = escape.slice(1);
+    const hex = /^(?:x([\da-f]{1,2})|[xu]\{([\da-f]+)\}|u([\da-f]{4})|U([\da-f]{8}))$/i.exec(body);
+    if (hex) {
+        const codePoint = parseInt(hex.slice(1).find((group) => group !== undefined) ?? "", 16);
+        return codePoint <= 0x10ffff ? String.fromCodePoint(codePoint) : undefined;
+    }
+    if (/^[0-7]{1,3}$/.test(body)) {
+        return String.fromCodePoint(parseInt(body, 8));
+    }
+    if (/^\r?\n$/.test(body)) {
+        // A backslash before a line break continues the string on the next line.
+        return "";
+    }
+    if ([...body].length !== 1 || body === "a" || body === "e") {
+        return undefined;
+    }
+    return SIMPLE_ESCAPES[body] ?? body;
+}
+/**
+ * Splits a PCRE-style pattern such as PHP's `'/a+/i'` into its pattern and flags.
+ *
+ * @param value The string's value. Its first character is the delimiter; brackets close with their
+ *   pair.
+ *
+ * @returns The parts, or undefined if the value is not delimited.
+ */
+function splitDelimitedPattern(value) {
+    const open = value.charAt(0);
+    if (open === "" || /[\p{L}\p{N}\s\\]/u.test(open)) {
+        return undefined;
+    }
+    const close = value.lastIndexOf(CLOSING_BRACKETS[open] ?? open);
+    if (close < 1) {
+        return undefined;
+    }
+    return { pattern: value.slice(1, close), flags: value.slice(close + 1) };
+}
+/**
+ * Rewrites flags into their JavaScript equivalents.
+ *
+ * @param flags The flags as written in the source language.
+ * @param map Replacement for each flag that differs; an empty string drops a flag that does not
+ *   change what matches. Flags not in the map are kept, so the explainer reports unknown ones.
+ *
+ * @returns The JavaScript flags.
+ */
+function translateFlags(flags, map) {
+    return [...flags].map((flag) => map[flag] ?? flag).join("");
+}
+//# sourceMappingURL=strings.js.map

package/dist/cjs/text.d.ts

@@ -0,0 +1,49 @@
+/** Small wording helpers shared by the explainer and renderers. */
+/**
+ * Wraps text in a Markdown code span, choosing a fence that survives embedded backticks.
+ *
+ * @param text The text to wrap.
+ *
+ * @returns The code span.
+ */
+export declare function code(text: string): string;
+/**
+ * Describes a single code point as a noun phrase.
+ *
+ * @param cp The code point.
+ *
+ * @returns A phrase such as "the character `a`", "a tab", or "the character U+200B".
+ */
+export declare function describeCodePoint(cp: number): string;
+/**
+ * Lowercases the first character.
+ *
+ * @param text The text.
+ *
+ * @returns The text with its first character lowercased.
+ */
+export declare function lowerFirst(text: string): string;
+/**
+ * Prefixes a noun with "a" or "an".
+ *
+ * @param noun The noun phrase.
+ *
+ * @returns The phrase with its article.
+ */
+export declare function withArticle(noun: string): string;
+/** A run of description text, either plain or from a code span. */
+export interface TextPart {
+    /** The text, with code span fences and padding removed. */
+    readonly text: string;
+    /** Whether the text came from a code span. */
+    readonly code: boolean;
+}
+/**
+ * Splits text into plain runs and the contents of its Markdown code spans, so that descriptions can
+ * be rendered without a Markdown parser. It reverses {@link code}.
+ *
+ * @param text Text that may contain code spans, such as an explanation's description.
+ *
+ * @returns The parts in order. Adjacent plain text is one part.
+ */
+export declare function splitCodeSpans(text: string): TextPart[];

package/dist/cjs/text.js

@@ -0,0 +1,109 @@
+"use strict";
+/** Small wording helpers shared by the explainer and renderers. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.code = code;
+exports.describeCodePoint = describeCodePoint;
+exports.lowerFirst = lowerFirst;
+exports.withArticle = withArticle;
+exports.splitCodeSpans = splitCodeSpans;
+/** Names for code points that have no visible glyph or are easy to misread. */
+const NAMED_CODE_POINTS = {
+    0x00: "a null character",
+    0x08: "a backspace",
+    0x09: "a tab",
+    0x0a: "a line feed (newline)",
+    0x0b: "a vertical tab",
+    0x0c: "a form feed",
+    0x0d: "a carriage return",
+    0x20: "a space",
+    0xa0: "a non-breaking space",
+    0x2028: "a line separator",
+    0x2029: "a paragraph separator",
+    0xfeff: "a byte order mark",
+};
+/**
+ * Wraps text in a Markdown code span, choosing a fence that survives embedded backticks.
+ *
+ * @param text The text to wrap.
+ *
+ * @returns The code span.
+ */
+function code(text) {
+    const longest = Math.max(0, ...(text.match(/`+/g) ?? []).map((m) => m.length));
+    const fence = "`".repeat(longest + 1);
+    // CommonMark strips one space from each side when both are present, so pad text that starts or
+    // ends with a backtick, or that is already padded.
+    const pad = text.startsWith("`") || text.endsWith("`") || /^ .* $/.test(text) ? " " : "";
+    return `${fence}${pad}${text}${pad}${fence}`;
+}
+/**
+ * Describes a single code point as a noun phrase.
+ *
+ * @param cp The code point.
+ *
+ * @returns A phrase such as "the character `a`", "a tab", or "the character U+200B".
+ */
+function describeCodePoint(cp) {
+    const named = NAMED_CODE_POINTS[cp];
+    if (named) {
+        return named;
+    }
+    const ch = String.fromCodePoint(cp);
+    if (/^[\p{C}\p{Z}]$/u.test(ch)) {
+        return `the character U+${cp.toString(16).toUpperCase().padStart(4, "0")}`;
+    }
+    return `the character ${code(ch)}`;
+}
+/**
+ * Lowercases the first character.
+ *
+ * @param text The text.
+ *
+ * @returns The text with its first character lowercased.
+ */
+function lowerFirst(text) {
+    return text.charAt(0).toLowerCase() + text.slice(1);
+}
+/**
+ * Prefixes a noun with "a" or "an".
+ *
+ * @param noun The noun phrase.
+ *
+ * @returns The phrase with its article.
+ */
+function withArticle(noun) {
+    return `${/^[aeiou]/i.test(noun) ? "an" : "a"} ${noun}`;
+}
+/**
+ * Splits text into plain runs and the contents of its Markdown code spans, so that descriptions can
+ * be rendered without a Markdown parser. It reverses {@link code}.
+ *
+ * @param text Text that may contain code spans, such as an explanation's description.
+ *
+ * @returns The parts in order. Adjacent plain text is one part.
+ */
+function splitCodeSpans(text) {
+    const spans = [...text.matchAll(/(?<!`)(`+)(?!`)([\s\S]+?)(?<!`)\1(?!`)/g)];
+    // Where the plain text before each span starts, then where the text after the last span starts.
+    const plainStarts = [0, ...spans.map((span) => span.index + span[0].length)];
+    const parts = spans.flatMap((span, i) => {
+        const content = span[2];
+        const padded = content.length > 2 && content.startsWith(" ") && content.endsWith(" ");
+        return [
+            ...plainPart(text.slice(plainStarts[i], span.index)),
+            { text: padded ? content.slice(1, -1) : content, code: true },
+        ];
+    });
+    return [...parts, ...plainPart(text.slice(plainStarts[spans.length]))];
+}
+/**
+ * Wraps plain text as a part, unless it is empty.
+ *
+ * @param text The text.
+ *
+ * @returns One plain part, or none for empty text.
+ */
+function plainPart(text) {
+    return text === "" ? [] : [{ text, code: false }];
+}
+//# sourceMappingURL=text.js.map