+// SPDX-FileCopyrightText: 2022, 2023, 2025 Lady <https://www.ladys.computer/about/#lady>
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * ⁌ ♓🧩 Piscēs ∷ string.js
+ *
+ * Copyright © 2022–2023, 2025 Lady [@ Ladys Computer].
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at <https://mozilla.org/MPL/2.0/>.
+ */
+
+import {
+ bind,
+ call,
+ completesNormally,
+ createArrowFunction,
+ createCallableFunction,
+ identity,
+} from "./function.js";
+import {
+ arrayIteratorFunction,
+ stringIteratorFunction,
+} from "./iterable.js";
+import {
+ defineOwnDataProperty,
+ defineOwnProperties,
+ getOwnPropertyDescriptors,
+ objectCreate,
+ setPropertyValues,
+ setPrototype,
+} from "./object.js";
+import { sameValue, toLength, UNDEFINED } from "./value.js";
+
+const PISCĒS = "♓🧩 Piscēs";
+
+const RE = RegExp;
+const { prototype: rePrototype } = RE;
+const { prototype: arrayPrototype } = Array;
+const { prototype: stringPrototype } = String;
+
+const { exec: reExec } = rePrototype;
+
+export const {
+ /**
+ * A `RegExp´‐like object which only matches entire strings, and may
+ * have additional constraints specified.
+ *
+ * Matchers are callable objects and will return true if they are
+ * called with a string that they match, and false otherwise.
+ * Matchers will always return false if called with nonstrings, altho
+ * other methods like `::exec´ coerce their arguments and may still
+ * return true.
+ */
+ Matcher,
+} = (() => {
+ const { toString: reToString } = rePrototype;
+ const getDotAll =
+ Object.getOwnPropertyDescriptor(rePrototype, "dotAll").get;
+ const getFlags =
+ Object.getOwnPropertyDescriptor(rePrototype, "flags").get;
+ const getGlobal =
+ Object.getOwnPropertyDescriptor(rePrototype, "global").get;
+ const getHasIndices =
+ Object.getOwnPropertyDescriptor(rePrototype, "hasIndices").get;
+ const getIgnoreCase =
+ Object.getOwnPropertyDescriptor(rePrototype, "ignoreCase").get;
+ const getMultiline =
+ Object.getOwnPropertyDescriptor(rePrototype, "multiline").get;
+ const getSource =
+ Object.getOwnPropertyDescriptor(rePrototype, "source").get;
+ const getSticky =
+ Object.getOwnPropertyDescriptor(rePrototype, "sticky").get;
+ const getUnicode =
+ Object.getOwnPropertyDescriptor(rePrototype, "unicode").get;
+ const getUnicodeSets =
+ Object.getOwnPropertyDescriptor(rePrototype, "unicodeSets").get;
+
+ /**
+ * The internal implementation of `Matcher´.
+ *
+ * ※ This class extends the identity function to enable the addition
+ * of private fields to the callable matcher function it constructs.
+ *
+ * ※ This class is not exposed.
+ */
+ const Matcher = class extends identity {
+ #constraint;
+ #regExp;
+
+ /**
+ * Constructs a new `Matcher´ from the provided source.
+ *
+ * If the provided source is a regular expression, then it must
+ * have either the unicode flag set or the unicode sets flag set.
+ * Otherwise, it is interpreted as the string source of a regular
+ * expression with the unicode flag set.
+ *
+ * Other flags are taken from the provided regular expression
+ * object, if any are present.
+ *
+ * A name for the matcher may be provided as the second argument.
+ *
+ * A callable constraint on acceptable inputs may be provided as a
+ * third argument. If provided, it will be called with three
+ * arguments whenever a match appears successful: first, the string
+ * being matched, second, the match result, and third, the
+ * `Matcher´ object itself. If the return value of this call is
+ * falsey, then the match will be considered a failure.
+ *
+ * ☡ If the provided source regular expression uses nongreedy
+ * quantifiers, it may not match the whole string even if a match
+ * with the whole string is possible. Surround the regular
+ * expression with `^(?:´ and `)$´ if you don¦t want nongreedy
+ * regular expressions to fail when shorter matches are possible.
+ */
+ constructor(source, name = UNDEFINED, constraint = null) {
+ super(
+ ($) => {
+ if (typeof $ !== "string") {
+ // The provided value is not a string.
+ return false;
+ } else {
+ // The provided value is a string.
+ //
+ // Set the `.lastIndex´ of the regular expression to 0, and
+ // see if the first attempt at a match successfully matches
+ // the whole string and passes the provided constraint (if
+ // present).
+ regExp.lastIndex = 0;
+ const result = call(reExec, regExp, [$]);
+ return result?.[0] === $
+ && (constraint === null || constraint($, result, this));
+ }
+ },
+ );
+ const regExp = this.#regExp = (() => {
+ if (completesNormally(() => call(reExec, source, [""]))) {
+ // The provided source is a `RegExp´.
+ if (
+ !call(getUnicode, source, [])
+ && !call(getUnicodeSets, source, [])
+ ) {
+ // The provided regular expression does not have a unicode
+ // flag or unicode sets flag.
+ throw new TypeError(
+ `${PISCĒS}: Cannot create Matcher from non‐Unicode RegExp: ${source}`,
+ );
+ } else {
+ // The provided regular expression has a unicode flag or
+ // unicode sets flag.
+ return new RE(source);
+ }
+ } else {
+ // The provided source is not a `RegExp´.
+ //
+ // Create one using it as the source string.
+ return new RE(`${source}`, "u");
+ }
+ })();
+ if (constraint !== null && typeof constraint !== "function") {
+ throw new TypeError(
+ `${PISCĒS}: Cannot construct Matcher: Constraint is not callable.`,
+ );
+ } else {
+ this.#constraint = constraint;
+ return defineOwnProperties(
+ setPrototype(this, matcherPrototype),
+ {
+ lastIndex: setPropertyValues(objectCreate(null), {
+ configurable: false,
+ enumerable: false,
+ value: 0,
+ writable: false,
+ }),
+ name: defineOwnDataProperty(
+ objectCreate(null),
+ "value",
+ name != null
+ ? `${name}`
+ : `Matcher(${call(reToString, regExp, [])})`,
+ ),
+ },
+ );
+ }
+ }
+
+ /** Gets whether the dot‐all flag is present on this `Matcher´. */
+ get dotAll() {
+ return call(getDotAll, this.#regExp, []);
+ }
+
+ /**
+ * Executes this `Matcher´ on the provided value and returns the
+ * result if there is a match, or null otherwise.
+ *
+ * Matchers only match if they can match the entire value on the
+ * first attempt.
+ *
+ * ☡ The match result returned by this method will be the same as
+ * that passed to the constraint function—and may have been
+ * modified by said function prior to being returned.
+ */
+ exec($) {
+ const regExp = this.#regExp;
+ const constraint = this.#constraint;
+ const string = `${$}`;
+ regExp.lastIndex = 0;
+ const result = call(reExec, regExp, [string]);
+ if (
+ result?.[0] === string
+ && (constraint === null || constraint(string, result, this))
+ ) {
+ // The entire string was matched and the constraint, if
+ // present, returned a truthy value.
+ return result;
+ } else {
+ // The entire string was not matched or the constraint returned
+ // a falsey value.
+ return null;
+ }
+ }
+
+ /**
+ * Gets the flags present on this `Matcher´.
+ *
+ * ※ This needs to be defined because the internal `RegExp´ object
+ * may have flags which are not yet recognized by ♓🧩 Piscēs.
+ */
+ get flags() {
+ return call(getFlags, this.#regExp, []);
+ }
+
+ /** Gets whether the global flag is present on this `Matcher´. */
+ get global() {
+ return call(getGlobal, this.#regExp, []);
+ }
+
+ /**
+ * Gets whether the has‐indices flag is present on this `Matcher´.
+ */
+ get hasIndices() {
+ return call(getHasIndices, this.#regExp, []);
+ }
+
+ /**
+ * Gets whether the ignore‐case flag is present on this `Matcher´.
+ */
+ get ignoreCase() {
+ return call(getIgnoreCase, this.#regExp, []);
+ }
+
+ /**
+ * Gets whether the multiline flag is present on this `Matcher´.
+ */
+ get multiline() {
+ return call(getMultiline, this.#regExp, []);
+ }
+
+ /** Gets the regular expression source for this `Matcher´. */
+ get source() {
+ return call(getSource, this.#regExp, []);
+ }
+
+ /** Gets whether the sticky flag is present on this `Matcher´. */
+ get sticky() {
+ return call(getSticky, this.#regExp, []);
+ }
+
+ /**
+ * Gets whether the unicode flag is present on this `Matcher´.
+ */
+ get unicode() {
+ return call(getUnicode, this.#regExp, []);
+ }
+
+ /**
+ * Gets whether the unicode sets flag is present on this `Matcher´.
+ */
+ get unicodeSets() {
+ return call(getUnicodeSets, this.#regExp, []);
+ }
+ };
+
+ const matcherConstructor = Object.defineProperties(
+ class extends RegExp {
+ constructor(...args) {
+ return new Matcher(...args);
+ }
+ },
+ {
+ name: defineOwnDataProperty(
+ Object.create(null),
+ "value",
+ "Matcher",
+ ),
+ length: defineOwnDataProperty(Object.create(null), "value", 1),
+ },
+ );
+ const matcherPrototype = defineOwnProperties(
+ matcherConstructor.prototype,
+ getOwnPropertyDescriptors(Matcher.prototype),
+ {
+ constructor: defineOwnDataProperty(
+ Object.create(null),
+ "value",
+ matcherConstructor,
+ ),
+ },
+ );
+
+ return { Matcher: matcherConstructor };
+})();
Lady’s Gitweb / Pisces / blobdiff