X-Git-Url: https://git.ladys.computer/Pisces/blobdiff_plain/8669d6cba4a0e88ba9fb0e4f9f025bcb417c3cbc..83f6aae0d1b8181dc2b0c6ccdba9f2fe2fdba3e6:/string.js diff --git a/string.js b/string.js index fb41e62..e697a1f 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,27 +10,38 @@ import { bind, call, identity, makeCallable } from "./function.js"; import { defineOwnProperties, + getOwnPropertyDescriptors, getPrototype, objectCreate, setPrototype, } from "./object.js"; +import { ITERATOR, TO_STRING_TAG } from "./value.js"; + +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. + * 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, } = (() => { - const RE = RegExp; - const { prototype: rePrototype } = RE; - const { exec: reExec, toString: reToString } = rePrototype; + 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 = @@ -47,10 +58,11 @@ export const { Object.getOwnPropertyDescriptor(rePrototype, "unicode").get; const Matcher = class extends identity { + #constraint; #regExp; /** - * Constructs a new Matcher from the provided source. + * 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 @@ -61,24 +73,34 @@ 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") { // The provided value is not a string. return false; } else { - // The provided value is a string. Set the `lastIndex` of + // 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,82 +122,115 @@ 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. */ + /** 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 + * 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) { - // 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 whether the global flag is present on this Matcher. */ + /** + * 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 hasIndices flag is present on this Matcher. */ + /** + * Gets whether the has‐indices flag is present on this `Matcher`. + */ get hasIndices() { return call(getHasIndices, this.#regExp, []); } - /** Gets whether the ignoreCase flag is present on this Matcher. */ + /** + * 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. */ + /** + * 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. */ + /** 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. */ + /** 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. + * Gets whether the unicode flag is present on this `Matcher`. * * ※ This will always be true. */ @@ -183,12 +238,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 { @@ -207,7 +275,7 @@ export const { const { toLowerCase: stringToLowercase, toUpperCase: stringToUppercase, - } = String.prototype; + } = stringPrototype; return { asciiLowercase: ($) => stringReplaceAll( @@ -253,21 +321,17 @@ export const { */ scalarValueString, } = (() => { - const { - iterator: iteratorSymbol, - toStringTag: toStringTagSymbol, - } = Symbol; - const { [iteratorSymbol]: arrayIterator } = Array.prototype; + const { [ITERATOR]: arrayIterator } = arrayPrototype; const arrayIteratorPrototype = Object.getPrototypeOf( - [][iteratorSymbol](), + [][ITERATOR](), ); const { next: arrayIteratorNext } = arrayIteratorPrototype; const iteratorPrototype = Object.getPrototypeOf( arrayIteratorPrototype, ); - const { [iteratorSymbol]: stringIterator } = String.prototype; + const { [ITERATOR]: stringIterator } = stringPrototype; const stringIteratorPrototype = Object.getPrototypeOf( - ""[iteratorSymbol](), + ""[ITERATOR](), ); const { next: stringIteratorNext } = stringIteratorPrototype; @@ -275,7 +339,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; @@ -355,7 +420,7 @@ export const { value: stringCodeValueIteratorNext, writable: true, }, - [toStringTagSymbol]: { + [TO_STRING_TAG]: { configurable: true, enumerable: false, value: "String Code Value Iterator", @@ -364,7 +429,7 @@ export const { }, ); const scalarValueIterablePrototype = { - [iteratorSymbol]() { + [ITERATOR]() { return { next: bind( stringCodeValueIteratorNext, @@ -380,21 +445,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: `${$}` } }, )), }; })(); @@ -402,16 +467,16 @@ export const { /** * Returns an iterator over the codepoints in the string representation * of the provided value according to the algorithm of - * String::[Symbol.iterator]. + * `String::[Symbol.iterator]`. */ export const characters = makeCallable( - String.prototype[Symbol.iterator], + stringPrototype[ITERATOR], ); /** * Returns the character at the provided position in the string * representation of the provided value according to the algorithm of - * String::codePointAt. + * `String::codePointAt`. */ export const getCharacter = ($, pos) => { const codepoint = getCodepoint($, pos); @@ -423,33 +488,33 @@ export const getCharacter = ($, pos) => { /** * Returns the code unit at the provided position in the string * representation of the provided value according to the algorithm of - * String::charAt. + * `String::charAt`. */ -export const getCodeUnit = makeCallable(String.prototype.charCodeAt); +export const getCodeUnit = makeCallable(stringPrototype.charCodeAt); /** * Returns the codepoint at the provided position in the string * representation of the provided value according to the algorithm of - * String::codePointAt. + * `String::codePointAt`. */ -export const getCodepoint = makeCallable(String.prototype.codePointAt); +export const getCodepoint = makeCallable(stringPrototype.codePointAt); /** * Returns the index of the first occurrence of the search string in * the string representation of the provided value according to the - * algorithm of String::indexOf. + * algorithm of `String::indexOf`. */ export const getFirstSubstringIndex = makeCallable( - String.prototype.indexOf, + stringPrototype.indexOf, ); /** * Returns the index of the last occurrence of the search string in the * string representation of the provided value according to the - * algorithm of String::lastIndexOf. + * algorithm of `String::lastIndexOf`. */ export const getLastSubstringIndex = makeCallable( - String.prototype.lastIndexOf, + stringPrototype.lastIndexOf, ); /** @@ -460,7 +525,7 @@ export const getLastSubstringIndex = makeCallable( * If a value is nullish, it will be stringified as the empty string. */ export const join = (() => { - const { join: arrayJoin } = Array.prototype; + const { join: arrayJoin } = arrayPrototype; const join = ($, separator = ",") => call(arrayJoin, [...$], [`${separator}`]); return join; @@ -471,21 +536,21 @@ export const { * Returns a string created from the raw value of the tagged template * literal. * - * ※ This is an alias for String.raw. + * ※ This is an alias for `String.raw`. */ raw: rawString, /** * Returns a string created from the provided code units. * - * ※ This is an alias for String.fromCharCode. + * ※ This is an alias for `String.fromCharCode`. */ fromCharCode: stringFromCodeUnits, /** * Returns a string created from the provided codepoints. * - * ※ This is an alias for String.fromCodePoint. + * ※ This is an alias for `String.fromCodePoint`. */ fromCodePoint: stringFromCodepoints, } = String; @@ -516,110 +581,110 @@ export const splitOnCommas = ($) => /** * Returns the result of catenating the string representations of the * provided values, returning a new string according to the algorithm - * of String::concat. + * of `String::concat`. */ -export const stringCatenate = makeCallable(String.prototype.concat); +export const stringCatenate = makeCallable(stringPrototype.concat); /** * Returns whether the string representation of the provided value ends * with the provided search string according to the algorithm of - * String::endsWith. + * `String::endsWith`. */ -export const stringEndsWith = makeCallable(String.prototype.endsWith); +export const stringEndsWith = makeCallable(stringPrototype.endsWith); /** * Returns whether the string representation of the provided value * contains the provided search string according to the algorithm of - * String::includes. + * `String::includes`. */ -export const stringIncludes = makeCallable(String.prototype.includes); +export const stringIncludes = makeCallable(stringPrototype.includes); /** * Returns the result of matching the string representation of the * provided value with the provided matcher according to the algorithm - * of String::match. + * of `String::match`. */ -export const stringMatch = makeCallable(String.prototype.match); +export const stringMatch = makeCallable(stringPrototype.match); /** * Returns the result of matching the string representation of the * provided value with the provided matcher according to the algorithm - * of String::matchAll. + * of `String::matchAll`. */ -export const stringMatchAll = makeCallable(String.prototype.matchAll); +export const stringMatchAll = makeCallable(stringPrototype.matchAll); /** * Returns the normalized form of the string representation of the - * provided value according to the algorithm of String::matchAll. + * provided value according to the algorithm of `String::matchAll`. */ export const stringNormalize = makeCallable( - String.prototype.normalize, + stringPrototype.normalize, ); /** * Returns the result of padding the end of the string representation * of the provided value padded until it is the desired length - * according to the algorithm of String::padEnd. + * according to the algorithm of `String::padEnd`. */ -export const stringPadEnd = makeCallable(String.prototype.padEnd); +export const stringPadEnd = makeCallable(stringPrototype.padEnd); /** * Returns the result of padding the start of the string representation * of the provided value padded until it is the desired length - * according to the algorithm of String::padStart. + * according to the algorithm of `String::padStart`. */ -export const stringPadStart = makeCallable(String.prototype.padStart); +export const stringPadStart = makeCallable(stringPrototype.padStart); /** * Returns the result of repeating the string representation of the * provided value the provided number of times according to the - * algorithm of String::repeat. + * algorithm of `String::repeat`. */ -export const stringRepeat = makeCallable(String.prototype.repeat); +export const stringRepeat = makeCallable(stringPrototype.repeat); /** * Returns the result of replacing the string representation of the * provided value with the provided replacement, using the provided - * matcher and according to the algorithm of String::replace. + * matcher and according to the algorithm of `String::replace`. */ -export const stringReplace = makeCallable(String.prototype.replace); +export const stringReplace = makeCallable(stringPrototype.replace); /** * Returns the result of replacing the string representation of the * provided value with the provided replacement, using the provided - * matcher and according to the algorithm of String::replaceAll. + * matcher and according to the algorithm of `String::replaceAll`. */ export const stringReplaceAll = makeCallable( - String.prototype.replaceAll, + stringPrototype.replaceAll, ); /** * Returns the result of searching the string representation of the * provided value using the provided matcher and according to the - * algorithm of String::search. + * algorithm of `String::search`. */ -export const stringSearch = makeCallable(String.prototype.search); +export const stringSearch = makeCallable(stringPrototype.search); /** * Returns a slice of the string representation of the provided value - * according to the algorithm of String::slice. + * according to the algorithm of `String::slice`. */ -export const stringSlice = makeCallable(String.prototype.slice); +export const stringSlice = makeCallable(stringPrototype.slice); /** * Returns the result of splitting of the string representation of the * provided value on the provided separator according to the algorithm - * of String::split. + * of `String::split`. */ -export const stringSplit = makeCallable(String.prototype.split); +export const stringSplit = makeCallable(stringPrototype.split); /** * Returns whether the string representation of the provided value * starts with the provided search string according to the algorithm of - * String::startsWith. + * `String::startsWith`. */ export const stringStartsWith = makeCallable( - String.prototype.startsWith, + stringPrototype.startsWith, ); /** @@ -628,7 +693,7 @@ export const stringStartsWith = makeCallable( * ☡ This function will throw if the provided object does not have a * `[[StringData]]` internal slot. */ -export const stringValue = makeCallable(String.prototype.valueOf); +export const stringValue = makeCallable(stringPrototype.valueOf); /** * Returns the result of stripping leading and trailing A·S·C·I·I @@ -648,14 +713,19 @@ export const stripAndCollapseASCIIWhitespace = ($) => * Returns the result of stripping leading and trailing A·S·C·I·I * whitespace from the string representation of the provided value. */ -export const stripLeadingAndTrailingASCIIWhitespace = (() => { - const { exec: reExec } = RegExp.prototype; - return ($) => - call(reExec, /^[\n\r\t\f ]*([^]*?)[\n\r\t\f ]*$/u, [$])[1]; -})(); +export const stripLeadingAndTrailingASCIIWhitespace = ($) => + call(reExec, /^[\n\r\t\f ]*([^]*?)[\n\r\t\f ]*$/u, [$])[1]; /** * Returns a substring of the string representation of the provided - * value according to the algorithm of String::substring. + * value according to the algorithm of `String::substring`. + */ +export const substring = makeCallable(stringPrototype.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 substring = makeCallable(String.prototype.substring); +export const toString = ($) => `${$}`;