// ♓🌟 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
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 =
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
*
* 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));
}
},
);
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.
*/
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 {
const {
toLowerCase: stringToLowercase,
toUpperCase: stringToUppercase,
- } = String.prototype;
+ } = stringPrototype;
return {
asciiLowercase: ($) =>
stringReplaceAll(
*/
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;
* 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;
value: stringCodeValueIteratorNext,
writable: true,
},
- [toStringTagSymbol]: {
+ [TO_STRING_TAG]: {
configurable: true,
enumerable: false,
value: "String Code Value Iterator",
},
);
const scalarValueIterablePrototype = {
- [iteratorSymbol]() {
+ [ITERATOR]() {
return {
next: bind(
stringCodeValueIteratorNext,
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: `${$}` } },
)),
};
})();
/**
* 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);
/**
* 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,
);
/**
* 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;
* 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;
/**
* 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,
);
/**
* ☡ 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
* 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 = ($) => `${$}`;
Lady’s Gitweb / Pisces / blobdiff