X-Git-Url: https://git.ladys.computer/Pisces/blobdiff_plain/8669d6cba4a0e88ba9fb0e4f9f025bcb417c3cbc..6e6d4e3261c1c943fe44fa9e381bcf8bf1441fd6:/string.js?ds=sidebyside diff --git a/string.js b/string.js index fb41e62..eb6f6fb 100644 --- a/string.js +++ b/string.js @@ -1,7 +1,7 @@ // ♓🌟 Piscēs ∷ string.js // ==================================================================== // -// Copyright © 2022 Lady [@ Lady’s Computer]. +// Copyright © 2022–2023 Lady [@ Lady’s 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 @@ -10,19 +10,23 @@ import { bind, call, identity, makeCallable } from "./function.js"; import { defineOwnProperties, + getOwnPropertyDescriptors, getPrototype, objectCreate, setPrototype, } from "./object.js"; +import { type } from "./value.js"; export const { /** - * A RegExp·like object which only matches entire strings. + * 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` may still return true. + * although other methods like `exec` coerce their arguments and may + * still return true. */ Matcher, } = (() => { @@ -31,6 +35,8 @@ export const { const { exec: reExec, 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 = @@ -47,6 +53,7 @@ export const { Object.getOwnPropertyDescriptor(rePrototype, "unicode").get; const Matcher = class extends identity { + #constraint; #regExp; /** @@ -61,13 +68,20 @@ export const { * * 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) { + constructor(source, name = undefined, constraint = null) { super( ($) => { if (typeof $ !== "string") { @@ -76,9 +90,12 @@ export const { } 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. + // at a match matches the whole string and passes the + // provided constraint (if present). regExp.lastIndex = 0; - return call(reExec, regExp, [$])?.[0] === $; + const result = call(reExec, regExp, [$]); + return result?.[0] === $ && + (constraint === null || constraint($, result, this)); } }, ); @@ -100,22 +117,29 @@ export const { return new RE(source); } })(); - return defineOwnProperties( - setPrototype(this, matcherPrototype), - { - lastIndex: { - configurable: false, - enumerable: false, - value: 0, - writable: false, - }, - name: { - value: name != null - ? `${name}` - : `Matcher(${call(reToString, regExp, [])})`, + 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. */ @@ -129,21 +153,41 @@ export const { * * 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) { - // The entire string was matched. + 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. + // 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, []); @@ -183,12 +227,25 @@ export const { return call(getUnicode, this.#regExp, []); } }; - const matcherPrototype = setPrototype( - Matcher.prototype, - rePrototype, + + 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 }; + return { Matcher: matcherConstructor }; })(); export const { @@ -275,7 +332,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; @@ -380,21 +438,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: `${$}` } }, )), }; })(); @@ -659,3 +717,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 = ($) => `${$}`;