X-Git-Url: https://git.ladys.computer/Pisces/blobdiff_plain/2989f964f0325a2d9c9294a8d3dab722313d5518..3b7b484743da35b1772b3fb04378dc88f75fc41f:/string.js?ds=sidebyside diff --git a/string.js b/string.js index d65d294..3dc39ac 100644 --- a/string.js +++ b/string.js @@ -8,7 +8,232 @@ // file, You can obtain one at . import { bind, call, identity, makeCallable } from "./function.js"; -import { getPrototype, objectCreate } from "./object.js"; +import { + defineOwnProperties, + getOwnPropertyDescriptors, + getPrototype, + objectCreate, + setPrototype, +} from "./object.js"; + +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, + * although other methods like `exec` coerce their arguments and may + * still return true. + */ + Matcher, +} = (() => { + const RE = RegExp; + const { prototype: rePrototype } = RE; + const { exec: reExec, toString: reToString } = rePrototype; + const getDotAll = + Object.getOwnPropertyDescriptor(rePrototype, "dotAll").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 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 the unicode 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 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 = (() => { + try { + call(reExec, source, [""]); // throws if source not a RegExp + } catch { + return new RE(`${source}`, "u"); + } + const unicode = call(getUnicode, source, []); + if (!unicode) { + // The provided regular expression does not have a unicode + // flag. + throw new TypeError( + `Piscēs: Cannot create Matcher from non‐Unicode RegExp: ${source}`, + ); + } else { + // The provided regular expression has a unicode flag. + return new RE(source); + } + })(); + 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: { + configurable: false, + enumerable: false, + value: 0, + writable: false, + }, + name: { + value: name != null + ? `${name}` + : `Matcher(${call(reToString, regExp, [])})`, + }, + }, + ); + } + } + + /** Gets whether the dotAll 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 whether the global flag is present on this Matcher. */ + get global() { + return call(getGlobal, this.#regExp, []); + } + + /** Gets whether the hasIndices flag is present on this Matcher. */ + get hasIndices() { + return call(getHasIndices, this.#regExp, []); + } + + /** Gets whether the ignoreCase 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. + * + * ※ This will always be true. + */ + get unicode() { + return call(getUnicode, this.#regExp, []); + } + }; + + const matcherConstructor = defineOwnProperties( + class extends RegExp { + constructor(...args) { + return new Matcher(...args); + } + }, + { + name: { value: "Matcher" }, + length: { value: 1 }, + }, + ); + const matcherPrototype = defineOwnProperties( + matcherConstructor.prototype, + getOwnPropertyDescriptors(Matcher.prototype), + { constructor: { value: matcherConstructor } }, + ); + + return { Matcher: matcherConstructor }; +})(); export const { /** @@ -94,7 +319,8 @@ export const { * An iterator object for iterating over code values (either code * units or codepoints) in a string. * - * ※ This constructor is not exposed. + * ※ This class is not exposed, although its methods are (through + * the prototypes of string code value iterator objects). */ const StringCodeValueIterator = class extends identity { #allowSurrogates; @@ -199,21 +425,21 @@ export const { return { codeUnits: ($) => - new StringCodeValueIterator(call(arrayIterator, $, [])), + new StringCodeValueIterator(call(arrayIterator, `${$}`, [])), codepoints: ($) => new StringCodeValueIterator( - call(stringIterator, $, []), + call(stringIterator, `${$}`, []), true, ), scalarValues: ($) => new StringCodeValueIterator( - call(stringIterator, $, []), + call(stringIterator, `${$}`, []), false, ), scalarValueString: ($) => stringFromCodepoints(...objectCreate( scalarValueIterablePrototype, - { source: { value: $ } }, + { source: { value: `${$}` } }, )), }; })(); @@ -478,3 +704,11 @@ export const stripLeadingAndTrailingASCIIWhitespace = (() => { * value according to the algorithm of String::substring. */ export const substring = makeCallable(String.prototype.substring); + +/** + * Returns the result of converting the provided value to a string. + * + * ☡ This method throws for symbols and other objects without a string + * representation. + */ +export const toString = ($) => `${$}`;