prototype-3x5/peg.js

186 lines
6 KiB
JavaScript
Raw Normal View History

2023-07-29 04:26:29 +00:00
/**
* A Pattern is a function that matches against a string starting at a given index.
*
* If it matches successfully, it returns some captured value, and the index following the match.
*
* @template T
2023-07-29 20:26:41 +00:00
* @callback Peg.PatternCall
* @param {string} source - the string being parsed
* @param {number} index - the index in the string to begin matching from
* @returns {[true, T, number] | [false, number, string]} - if successful, true, the captured value, and the index to start parsing following symbols from.
* Else, false, the furthest index that could be understood, and a description of what was expected but not matchable.
2023-07-29 20:26:41 +00:00
*/
/**
* @template T
* @typedef {object} Peg.PatternExt
* @property {<U>(map: (value: T) => U) => Peg.Pattern<U>} map Creates a pattern that wraps another pattern, transforming the returned value on a match
* @property {string} expectLabel A human-readable annotation describing the pattern for error messages
* @property {(label: string) => Peg.Pattern<T>} expects Adds a human-readable annotation describing the pattern
2023-07-29 20:26:41 +00:00
*/
/**
* @template T
* @typedef {Peg.PatternCall<T> & Peg.PatternExt<T>} Peg.Pattern
2023-07-29 04:26:29 +00:00
*/
var Peg = window.Peg ?? {};
2023-07-29 04:26:29 +00:00
/**
* Makes a pattern from a function, adding helper methods.
*
* @template T
* @param {(source: string, index: number) => ([true, T, number] | [false, number, string])} matchFunc
* @returns {Peg.Pattern<T>}
*/
Peg.WrapPattern = function (matchFunc) {
const pattern = /** @type {Peg.Pattern<T>} */ (matchFunc);
pattern.map = function (map) {
2023-07-29 20:26:41 +00:00
return Peg.WrapPattern(function (source, index) {
const match = pattern(source, index);
return match[0] ? [true, map(match[1]), match[2]] : match;
}).expects(pattern.expectLabel);
2023-07-29 20:26:41 +00:00
};
pattern.expectLabel = pattern.name;
pattern.expects = (label) => {
pattern.expectLabel = label;
return pattern;
};
return pattern;
};
2023-07-29 04:26:29 +00:00
/**
* Proxies to a pattern retrieved from an accessor function.
*
* Allows using a pattern recursively in its own definition, by returning the value of the const assigned to.
*
* @template T
* @param {() => Peg.Pattern<T>} getPattern
* @returns {Peg.Pattern<T>}
*/
Peg.Use = function (getPattern) {
return Peg.WrapPattern(function (source, index) {
return getPattern()(source, index);
}).expects(String(getPattern));
};
/**
* Creates a pattern matching a regex & returning any captures. The regex needs to be sticky (using the //y modifier)
* @param {RegExp} regex
* @return {Peg.Pattern<RegExpExecArray>}
*/
Peg.Regex = function (regex) {
/** @type {Peg.Pattern<RegExpExecArray>} */
const pattern = Peg.WrapPattern(function (source, index) {
regex.lastIndex = index;
const matches = regex.exec(source);
return matches
? [true, matches, regex.lastIndex]
: [false, index, pattern.expectLabel];
}).expects(regex.source);
return pattern;
};
2023-07-29 04:26:29 +00:00
/**
* Creates a pattern that tries the given patterns, in order, until it finds one that matches at the current index.
* @template T
* @param {...Peg.Pattern<T>} patterns
* @return {Peg.Pattern<T>}
*/
Peg.Choose = function (...patterns) {
const expected = patterns.map((pattern) => pattern.expectLabel).join(" | ");
return Peg.WrapPattern(function (source, index) {
2023-08-04 04:17:14 +00:00
let furthest = index;
let furthestExpected = expected;
for (const pattern of patterns) {
const match = pattern(source, index);
2023-08-04 04:17:14 +00:00
if (match[0]) {
return match;
2023-08-04 04:17:14 +00:00
} else if (match[1] > furthest) {
furthest = match[1];
furthestExpected = match[2];
2023-07-29 04:26:29 +00:00
}
}
return [false, furthest, furthestExpected];
}).expects(expected);
};
2023-07-29 05:13:38 +00:00
/**
* Creates a pattern that concatenates the given patterns, returning a tuple of their captured values.
*
* For example, if A matches "a" and captures 1, while B matches "b" and captures null,
* then `Sequence(A,B)` will match "ab" and capture [1, null]
* @template {unknown[]} T
* @param {{[K in keyof T]: Peg.Pattern<T[K]>}} patterns
* @return {Peg.Pattern<T>}
*/
Peg.Sequence = function (...patterns) {
return Peg.WrapPattern(function (source, index) {
const values = /** @type {T} */ (/** @type {unknown} */ ([]));
for (const pattern of patterns) {
const match = pattern(source, index);
2023-08-04 04:17:14 +00:00
if (match[0] == false) {
return match;
2023-07-29 05:13:38 +00:00
}
2023-08-04 04:17:14 +00:00
values.push(match[1]);
index = match[2];
}
2023-08-04 04:17:14 +00:00
return [true, values, index];
}).expects(patterns[0]?.expectLabel ?? "(nothing)");
};
2023-07-29 05:45:34 +00:00
/**
* Creates a pattern that matches consecutive runs of the given pattern, returning an array of all captures.
*
2023-07-29 20:26:41 +00:00
* The match only succeeds if the run is at least {@link min} instances long.
*
* If the given pattern does not consume input, the matching will be terminated to prevent an eternal loop.
*
* Note that if the minimum run is zero, this pattern will always succeed, but might not consume any input.
* @template {unknown} T
* @param {number} min
* @param {Peg.Pattern<T>} pattern
* @return {Peg.Pattern<T[]>}
*/
Peg.AtLeast = function (min, pattern) {
return Peg.WrapPattern(function (source, index) {
const values = /** @type {T[]} */ ([]);
2023-08-04 04:17:14 +00:00
let furthest = index;
let expected = pattern.expectLabel;
do {
const match = pattern(source, index);
2023-08-04 04:17:14 +00:00
if (match[0] == false) {
furthest = match[1];
expected = match[2];
2023-08-04 04:17:14 +00:00
break;
}
values.push(match[1]);
if (index == match[2]) {
furthest = match[2];
break;
}
index = match[2];
} while (true);
if (values.length >= min) {
2023-08-04 04:17:14 +00:00
return [true, values, index];
2023-07-29 05:45:34 +00:00
} else {
return [false, furthest, expected];
2023-07-29 05:45:34 +00:00
}
}).expects(pattern.expectLabel);
2023-07-29 04:26:29 +00:00
};
/**
* Creates a pattern that matches the end of input
* @return {Peg.Pattern<true>}
*/
Peg.End = () => {
/** @type {Peg.Pattern<true>} */
const end = Peg.WrapPattern(function End(source, index) {
if (source.length == index) {
return [true, /** @type {true} */ (true), index];
} else {
return [false, index, end.expectLabel];
}
}).expects("<eof>");
return end;
};