* 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 two
+ * third argument. If provided, it will be called with three
* arguments whenever a match appears successful: first, the string
- * being matched, and second, the Matcher object itself. If the
- * return value of this call is falsey, then the match will be
- * considered a failure.
+ * 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
// at a match matches the whole string and passes the
// provided constraint (if present).
regExp.lastIndex = 0;
- return call(reExec, regExp, [$])?.[0] === $ &&
- (constraint === null || constraint($, this));
+ const result = call(reExec, regExp, [$]);
+ return result?.[0] === $ &&
+ (constraint === null || constraint($, result, this));
}
},
);
*
* 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 result = call(reExec, regExp, [string]);
if (
result?.[0] === string &&
- (constraint === null || constraint(string, this))
+ (constraint === null || constraint(string, result, this))
) {
// The entire string was matched and the constraint, if
// present, returned a truthy value.
it("[[Call]] calls the constraint if the match succeeds", () => {
const constraint = spy((_) => true);
- const matcher = new Matcher(".*", undefined, constraint);
- matcher.exec({
+ const matcher = new Matcher("(.).*", undefined, constraint);
+ const result = matcher.exec({
toString() {
return "etaoin";
},
});
assertSpyCalls(constraint, 1);
assertSpyCall(constraint, 0, {
- args: ["etaoin", matcher],
+ args: ["etaoin", result, matcher],
self: undefined,
});
});
it("[[Call]] calls the constraint if the match succeeds", () => {
const constraint = spy((_) => true);
- const matcher = new Matcher(".*", undefined, constraint);
+ const matcher = new Matcher("(.).*", undefined, constraint);
matcher("etaoin");
assertSpyCalls(constraint, 1);
- assertSpyCall(constraint, 0, {
- args: ["etaoin", matcher],
- self: undefined,
- });
+ assertEquals(constraint.calls[0].args[0], "etaoin");
+ assertEquals([...constraint.calls[0].args[1]], ["etaoin", "e"]);
+ assertEquals(constraint.calls[0].args[2], matcher);
+ assertEquals(constraint.calls[0].self, undefined);
});
it("[[Call]] does not call the constraint if the match fails", () => {