prototype-3x5/peg.js

/**
 * 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
 * @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.
 */
/**
 * @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
 */
/**
 * @template T
 * @typedef {Peg.PatternCall<T> & Peg.PatternExt<T>} Peg.Pattern
 */
var Peg = window.Peg ?? {};

/**
 * 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) {
    return Peg.WrapPattern(function (source, index) {
      const match = pattern(source, index);
      return match[0] ? [true, map(match[1]), match[2]] : match;
    }).expects(pattern.expectLabel);
  };

  pattern.expectLabel = pattern.name;
  pattern.expects = (label) => {
    pattern.expectLabel = label;
    return pattern;
  };

  return pattern;
};

/**
 * 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;
};

/**
 * 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) {
    let furthest = index;
    let furthestExpected = expected;
    for (const pattern of patterns) {
      const match = pattern(source, index);
      if (match[0]) {
        return match;
      } else if (match[1] > furthest) {
        furthest = match[1];
        furthestExpected = match[2];
      }
    }
    return [false, furthest, furthestExpected];
  }).expects(expected);
};

/**
 * 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);
      if (match[0] == false) {
        return match;
      }
      values.push(match[1]);
      index = match[2];
    }
    return [true, values, index];
  }).expects(patterns[0]?.expectLabel ?? "(nothing)");
};

/**
 * Creates a pattern that matches consecutive runs of the given pattern, returning an array of all captures.
 *
 * 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[]} */ ([]);
    let furthest = index;
    let expected = pattern.expectLabel;
    do {
      const match = pattern(source, index);
      if (match[0] == false) {
        furthest = match[1];
        expected = match[2];
        break;
      }
      values.push(match[1]);
      if (index == match[2]) {
        furthest = match[2];
        break;
      }
      index = match[2];
    } while (true);
    if (values.length >= min) {
      return [true, values, index];
    } else {
      return [false, furthest, expected];
    }
  }).expects(pattern.expectLabel);
};

/**
 * 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;
};