parseman 0.39.0 → 0.40.0

package/dist/spec/index.cjs

@@ -82,6 +82,8 @@ function matchesEmpty(p, seen = /* @__PURE__ */ new Set(), resolve) {
       return d.value.length === 0;
     case "keywords":
       return false;
+    case "routed":
+      return false;
     case "regex":
       try {
         const m = new RegExp(d.source).exec("");
@@ -320,6 +322,7 @@ function markUnusedValues(root) {
       case "dispatch":
         visit(def.selector, consumed);
         for (const entry of def.cases) visit(entry.parser, consumed);
+        if (def.matchers) for (const entry of def.matchers) visit(entry.parser, consumed);
         if (def.otherwise) visit(def.otherwise, consumed);
         return;
       case "node":
@@ -773,6 +776,8 @@ function derive(c, seen) {
     case "not":
     case "peek":
       return deriveExpected2(def.parser);
+    case "routed":
+      return ["routed()"];
     case "lazy": {
       const name = c._ruleName;
       if (seen.has(c)) return name ? [name] : [];
@@ -2321,7 +2326,7 @@ function parserHasOwnFields(p, seen = /* @__PURE__ */ new Set()) {
     case "choice":
       return d.parsers.some((x) => parserHasOwnFields(x, seen));
     case "dispatch":
-      return parserHasOwnFields(d.selector, seen) || d.cases.some((x) => parserHasOwnFields(x.parser, seen)) || (d.otherwise ? parserHasOwnFields(d.otherwise, seen) : false);
+      return parserHasOwnFields(d.selector, seen) || d.cases.some((x) => parserHasOwnFields(x.parser, seen)) || (d.matchers ? d.matchers.some((entry) => parserHasOwnFields(entry.parser, seen)) : false) || (d.otherwise ? parserHasOwnFields(d.otherwise, seen) : false);
     case "sepBy":
       return parserHasOwnFields(d.parser, seen) || parserHasOwnFields(d.separator, seen);
     case "skip":
@@ -2437,42 +2442,195 @@ function keywords(words, opts = {}) {
 }
 
 // src/combinators/dispatch.ts
-function when(key, parser2) {
+function parserUsesRouted(parser2, seen = /* @__PURE__ */ new Set()) {
+  if (seen.has(parser2)) return false;
+  seen.add(parser2);
+  const def = parser2._def;
+  switch (def.tag) {
+    case "routed":
+      return true;
+    case "sequence":
+    case "choice":
+      return def.parsers.some((entry) => parserUsesRouted(entry, seen));
+    case "dispatch":
+      return false;
+    case "sepBy":
+      return parserUsesRouted(def.parser, seen) || parserUsesRouted(def.separator, seen);
+    case "skip":
+      return parserUsesRouted(def.main, seen) || parserUsesRouted(def.skipped, seen);
+    case "grammar":
+      return parserUsesRouted(def.parser, seen) || (def.triviaParser ? parserUsesRouted(def.triviaParser, seen) : false);
+    case "scanTo":
+      return parserUsesRouted(def.sentinel, seen) || def.skip.some((entry) => parserUsesRouted(entry, seen));
+    case "recover":
+      return parserUsesRouted(def.parser, seen) || parserUsesRouted(def.sentinel, seen);
+    case "lazy":
+      try {
+        return parserUsesRouted(def.thunk(), seen);
+      } catch {
+        return false;
+      }
+    case "many":
+    case "oneOrMore":
+    case "optional":
+    case "attempt":
+    case "transform":
+    case "trivia":
+    case "token":
+    case "leaf":
+    case "label":
+    case "field":
+    case "not":
+    case "peek":
+    case "node":
+    case "withCtx":
+    case "expect":
+      return parserUsesRouted(def.parser, seen);
+    default:
+      return false;
+  }
+}
+function branchUsesRouted(branch) {
+  return branch.usesRouted === true || parserUsesRouted(branch.parser);
+}
+function asciiFoldKey(key) {
+  let out = "";
+  for (let i = 0; i < key.length; i++) {
+    const c = key.charCodeAt(i);
+    out += String.fromCharCode(c >= 65 && c <= 90 ? c + 32 : c);
+  }
+  return out;
+}
+function matchesDispatchMatcher(value, matcher) {
+  const candidate = matcher.caseInsensitive ? asciiFoldKey(value) : value;
+  const expected = matcher.caseInsensitive ? asciiFoldKey(matcher.value) : matcher.value;
+  switch (matcher.kind) {
+    case "startsWith":
+      return candidate.startsWith(expected);
+    case "endsWith":
+      return candidate.endsWith(expected);
+    case "matches": {
+      const flags = matcher.caseInsensitive && !matcher.flags?.includes("i") ? `${matcher.flags ?? ""}i` : matcher.flags ?? "";
+      return new RegExp(matcher.value, flags).test(value);
+    }
+  }
+}
+function isStringMatcher(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const kind = value.kind;
+  return kind === "startsWith" || kind === "endsWith" || kind === "matches";
+}
+function fixedMatcher(kind, value) {
+  if (typeof value !== "string") throw new TypeError(`parseman: ${kind}() value must be a string`);
+  if (value.length === 0) throw new RangeError(`parseman: ${kind}() requires a non-empty value`);
+  return { kind, value };
+}
+function startsWith(prefix) {
+  return fixedMatcher("startsWith", prefix);
+}
+function endsWith(suffix) {
+  return fixedMatcher("endsWith", suffix);
+}
+function matches(pattern) {
+  if (!(pattern instanceof RegExp)) throw new TypeError("parseman: matches() requires a RegExp");
+  if (pattern.flags.includes("g") || pattern.flags.includes("y")) {
+    throw new TypeError("parseman: matches() does not accept global or sticky regex flags");
+  }
+  return { kind: "matches", value: pattern.source, flags: pattern.flags };
+}
+function when(key, parser2, opts = {}) {
+  const usesRouted = parserUsesRouted(parser2);
+  if (isStringMatcher(key)) {
+    return { kind: "whenMatcher", matcher: key, parser: parser2, caseInsensitive: opts.caseInsensitive ?? false, usesRouted };
+  }
   const keys = Array.isArray(key) ? [...key] : [key];
   if (keys.length === 0) throw new RangeError("parseman: when() requires at least one key");
   for (const item of keys) {
     if (typeof item !== "string") throw new TypeError("parseman: when() keys must be strings");
   }
-  return { kind: "when", keys, parser: parser2 };
+  return { kind: "when", keys, parser: parser2, caseInsensitive: opts.caseInsensitive ?? false, usesRouted };
 }
 function otherwise(parser2) {
-  return { kind: "otherwise", parser: parser2 };
+  return { kind: "otherwise", parser: parser2, usesRouted: parserUsesRouted(parser2) };
+}
+function routed() {
+  return {
+    _tag: "routed",
+    _meta: { firstSet: { kind: "any" }, canMatchNewline: false, isTrivia: false },
+    _def: { tag: "routed" },
+    parse(_input, pos, ctx) {
+      const item = ctx._routed;
+      if (item === void 0) {
+        return { ok: false, expected: ["routed()"], span: { start: pos, end: pos } };
+      }
+      if (pos !== item.span.start) {
+        return { ok: false, expected: ["routed()"], span: { start: pos, end: pos } };
+      }
+      if (cstCaptureActive(ctx)) {
+        pushCstLeaf(ctx, { _tag: "leaf", value: item.value, span: item.span });
+      }
+      return { ok: true, value: item.value, span: item.span };
+    }
+  };
 }
 function dispatch(selector, ...arms) {
+  if (parserUsesRouted(selector)) {
+    throw new Error("parseman: routed() can only appear inside a dispatch() branch");
+  }
   let fallback;
+  let fallbackUsesRouted = false;
+  const matchers = [];
   const cases = [];
-  const seen = /* @__PURE__ */ new Set();
+  const seen = [];
   for (let i = 0; i < arms.length; i++) {
     const arm = arms[i];
     if (arm.kind === "otherwise") {
       if (fallback !== void 0) throw new Error("parseman: dispatch() accepts at most one otherwise() arm");
       if (i !== arms.length - 1) throw new Error("parseman: otherwise() must be the last dispatch() arm");
       fallback = arm.parser;
+      fallbackUsesRouted = arm.usesRouted === true;
+      continue;
+    }
+    if (arm.kind === "whenMatcher") {
+      const matcher = arm.matcher;
+      matchers.push({
+        kind: matcher.kind,
+        value: matcher.value,
+        ...matcher.kind === "matches" ? { flags: matcher.flags } : {},
+        parser: arm.parser,
+        caseInsensitive: arm.caseInsensitive,
+        ...arm.usesRouted === true ? { usesRouted: true } : {}
+      });
       continue;
     }
     for (const key of arm.keys) {
-      if (seen.has(key)) throw new Error(`parseman: duplicate dispatch key ${JSON.stringify(key)}`);
-      seen.add(key);
+      const folded = asciiFoldKey(key);
+      for (const prior of seen) {
+        const overlaps = arm.caseInsensitive || prior.caseInsensitive ? folded === prior.folded : key === prior.raw;
+        if (overlaps) throw new Error(`parseman: duplicate dispatch key ${JSON.stringify(key)}`);
+      }
+      seen.push({ raw: key, folded, caseInsensitive: arm.caseInsensitive });
     }
-    cases.push({ keys: arm.keys, parser: arm.parser });
+    cases.push({
+      keys: arm.keys,
+      parser: arm.parser,
+      caseInsensitive: arm.caseInsensitive,
+      ...arm.usesRouted === true ? { usesRouted: true } : {}
+    });
   }
   const meta = {
     firstSet: selector._meta.firstSet,
-    canMatchNewline: selector._meta.canMatchNewline || cases.some((entry) => entry.parser._meta.canMatchNewline) || (fallback?._meta.canMatchNewline ?? false),
+    canMatchNewline: selector._meta.canMatchNewline || cases.some((entry) => entry.parser._meta.canMatchNewline) || matchers.some((entry) => entry.parser._meta.canMatchNewline) || (fallback?._meta.canMatchNewline ?? false),
     isTrivia: false
   };
   const byKey = /* @__PURE__ */ new Map();
-  for (const entry of cases) for (const key of entry.keys) byKey.set(key, entry.parser);
+  const byFoldedKey = /* @__PURE__ */ new Map();
+  for (const entry of cases) {
+    for (const key of entry.keys) {
+      if (entry.caseInsensitive) byFoldedKey.set(asciiFoldKey(key), entry);
+      else byKey.set(key, entry);
+    }
+  }
   return {
     _tag: "dispatch",
     _meta: meta,
@@ -2480,18 +2638,35 @@ function dispatch(selector, ...arms) {
       tag: "dispatch",
       selector,
       cases,
-      ...fallback === void 0 ? {} : { otherwise: fallback }
+      ...matchers.length === 0 ? {} : { matchers },
+      ...fallback === void 0 ? {} : { otherwise: fallback, ...fallbackUsesRouted ? { otherwiseUsesRouted: true } : {} }
     },
     parse(input, pos, ctx) {
+      if (parserUsesRouted(selector)) {
+        throw new Error("parseman: routed() can only appear inside a dispatch() branch");
+      }
+      const selectorMark = saveTriviaMark(ctx);
       const selected = selector.parse(input, pos, ctx);
       if (!selected.ok) return selected;
-      const tail = byKey.get(selected.value) ?? fallback;
-      if (tail === void 0) {
+      const branch = byKey.get(selected.value) ?? (byFoldedKey.size === 0 ? void 0 : byFoldedKey.get(asciiFoldKey(selected.value))) ?? matchers.find((matcher) => matchesDispatchMatcher(selected.value, matcher)) ?? (fallback === void 0 ? void 0 : { keys: [], parser: fallback, caseInsensitive: false, usesRouted: fallbackUsesRouted });
+      if (branch === void 0) {
         const expected = cases.flatMap((entry) => entry.keys.map((key) => JSON.stringify(key)));
         return { ok: false, expected, span: { start: selected.span.end, end: selected.span.end } };
       }
-      const mark = saveTriviaMark(ctx);
-      const result = tail.parse(input, selected.span.end, ctx);
+      const savedRouted = ctx._routed;
+      const usesRouted = branchUsesRouted(branch);
+      let mark = saveTriviaMark(ctx);
+      if (usesRouted) {
+        rollbackTrivia(ctx, selectorMark);
+        mark = saveTriviaMark(ctx);
+        ctx._routed = { value: selected.value, span: selected.span };
+      }
+      let result;
+      try {
+        result = branch.parser.parse(input, usesRouted ? pos : selected.span.end, ctx);
+      } finally {
+        if (usesRouted) ctx._routed = savedRouted;
+      }
       if (!result.ok) {
         rollbackTrivia(ctx, mark);
         return { ...result, committed: true };
@@ -2589,12 +2764,30 @@ function isCstChild(value) {
 function missingInferredType() {
   throw new Error('node(): inferred node type requires a rules() key; pass node("Type", parser) outside rules()');
 }
+function normalizeProject(project) {
+  if (project === void 0) return void 0;
+  if (!Number.isInteger(project) || project < 0) {
+    throw new Error("node() project child must be a non-negative integer");
+  }
+  return project;
+}
+function projectChild(children, project, type) {
+  if (!(project in children)) {
+    throw new Error(`node(${JSON.stringify(type)}) project child ${project} was not captured`);
+  }
+  return unwrapChild(children[project]);
+}
 function node(typeOrCombinator, combinatorOrBuild, buildOrOpts, maybeOpts) {
   const hasExplicitType = typeof typeOrCombinator === "string";
   const type = hasExplicitType ? typeOrCombinator : void 0;
   const combinator = hasExplicitType ? combinatorOrBuild : typeOrCombinator;
-  const build = hasExplicitType ? buildOrOpts : combinatorOrBuild;
-  const opts = hasExplicitType ? maybeOpts : buildOrOpts;
+  const buildArg = hasExplicitType ? buildOrOpts : combinatorOrBuild;
+  const build = typeof buildArg === "function" ? buildArg : void 0;
+  const opts = typeof buildArg === "function" ? maybeOpts : buildArg ?? maybeOpts;
+  const project = normalizeProject(opts?.project);
+  if (project !== void 0 && build !== void 0) {
+    throw new Error("node() options cannot combine project with a build callback");
+  }
   const baseDef = { tag: "node", parser: combinator, ...type === void 0 ? {} : { type }, ...build === void 0 ? {} : { build } };
   const meta = {
     firstSet: combinator._meta.firstSet,
@@ -2608,11 +2801,14 @@ function node(typeOrCombinator, combinatorOrBuild, buildOrOpts, maybeOpts) {
   if (unwrap && collapse) {
     throw new Error("node() options cannot set both unwrap and collapse");
   }
-  const def = unwrap || collapse || captureTrivia || trailingTrivia ? { ...baseDef, ...unwrap ? { unwrap: true } : {}, ...collapse ? { collapse: true } : {}, ...captureTrivia ? { captureTrivia: true } : {}, ...trailingTrivia ? { trailingTrivia: true } : {} } : baseDef;
-  const capturesTrivia = captureTrivia || trailingTrivia || (build ? buildReadsTrivia(def) : true);
-  const clonesState = build ? buildReadsState(def) : true;
+  if (project !== void 0 && (unwrap || collapse)) {
+    throw new Error("node() options cannot combine project with unwrap or collapse");
+  }
+  const def = unwrap || collapse || project !== void 0 || captureTrivia || trailingTrivia ? { ...baseDef, ...unwrap ? { unwrap: true } : {}, ...collapse ? { collapse: true } : {}, ...project !== void 0 ? { project } : {}, ...captureTrivia ? { captureTrivia: true } : {}, ...trailingTrivia ? { trailingTrivia: true } : {} } : baseDef;
+  const capturesTrivia = captureTrivia || trailingTrivia || (build ? buildReadsTrivia(def) : project === void 0);
+  const clonesState = build ? buildReadsState(def) : project === void 0;
   const hasOwnFields = parserHasOwnFields(combinator);
-  const capturesFields = hasOwnFields && (build ? buildReadsFields(def) : true);
+  const capturesFields = hasOwnFields && (build ? buildReadsFields(def) : project === void 0);
   const guardable = combinator._meta.firstSet.kind !== "any" && !matchesEmpty(combinator);
   let failExpected;
   return {
@@ -2627,14 +2823,15 @@ function node(typeOrCombinator, combinatorOrBuild, buildOrOpts, maybeOpts) {
         }
         return { ok: false, expected: failExpected, span: { start: pos, end: pos } };
       }
-      const hostCst = build !== void 0 && cstOutputHost(ctx.build);
+      const hasDirectValue = build !== void 0 || project !== void 0;
+      const hostCst = hasDirectValue && cstOutputHost(ctx.build);
       const effTrivia = capturesTrivia || hostCst;
       const effFields = capturesFields || hostCst && hasOwnFields;
       const saved = beginCstNodeCapture(ctx);
       const savedFields = ctx._fields;
       ctx._fields = effFields ? [] : void 0;
       const savedMask = ctx._triviaCaptureMask;
-      if (build === void 0 && ctx.build?._parsemanTriviaKinds !== void 0 && def.type !== void 0) {
+      if (build === void 0 && project === void 0 && ctx.build?._parsemanTriviaKinds !== void 0 && def.type !== void 0) {
         ctx._triviaCaptureMask = ctx.build._parsemanTriviaKinds(def.type);
       }
       if (!effTrivia) ctx.captureTrivia = false;
@@ -2652,7 +2849,7 @@ function node(typeOrCombinator, combinatorOrBuild, buildOrOpts, maybeOpts) {
       const nodeType = def.type ?? missingInferredType();
       const cstOutput = cstOutputHost(ctx.build);
       const hostState = clonesState ? st : ctx.state !== void 0 ? Object.assign({}, ctx.state) : void 0;
-      const built = unwrap && children.length === 1 ? unwrapChild(children[0]) : collapse && children.length === 1 ? children[0] : !build && ctx.build?._parsemanCstCollapse && children.length === 1 && rawChildren.length === 1 && ctx.build._parsemanCstCollapse(nodeType, children[0], children, rawChildren) ? children[0] : build ? cstOutput && ctx.build ? ctx.build(nodeType, children, fields, r.span, rawChildren, triviaLog, hostState) : build(children, fields, r.span, rawChildren, triviaLog, st) : ctx.build ? ctx.build(nodeType, children, fields, r.span, rawChildren, triviaLog, st) : { _tag: "node", type: nodeType, span: { start: r.span.start, end: r.span.end }, state: st ?? null, children };
+      const built = unwrap && children.length === 1 ? unwrapChild(children[0]) : collapse && children.length === 1 ? children[0] : !build && project === void 0 && ctx.build?._parsemanCstCollapse && children.length === 1 && rawChildren.length === 1 && ctx.build._parsemanCstCollapse(nodeType, children[0], children, rawChildren) ? children[0] : project !== void 0 ? cstOutput && ctx.build ? ctx.build(nodeType, children, fields, r.span, rawChildren, triviaLog, hostState) : projectChild(children, project, nodeType) : build ? cstOutput && ctx.build ? ctx.build(nodeType, children, fields, r.span, rawChildren, triviaLog, hostState) : build(children, fields, r.span, rawChildren, triviaLog, st) : ctx.build ? ctx.build(nodeType, children, fields, r.span, rawChildren, triviaLog, st) : { _tag: "node", type: nodeType, span: { start: r.span.start, end: r.span.end }, state: st ?? null, children };
       const rawEntry = isCstChild(built) ? built : { _tag: "leaf", value: typeof built === "string" ? built : typeof built === "object" && built !== null ? input.slice(r.span.start, r.span.end) : "", span: r.span };
       if (saved.buf !== void 0 || saved.ch !== void 0) {
         pushCstChild(ctx, built, rawEntry);
@@ -2939,7 +3136,11 @@ function evalRuleMapIR(ir) {
     "choice",
     "dispatch",
     "when",
+    "startsWith",
+    "endsWith",
+    "matches",
     "otherwise",
+    "routed",
     "attempt",
     "many",
     "oneOrMore",
@@ -2975,7 +3176,11 @@ function evalRuleMapIR(ir) {
     choice,
     dispatch,
     when,
+    startsWith,
+    endsWith,
+    matches,
     otherwise,
+    routed,
     attempt,
     many,
     oneOrMore,
@@ -3174,8 +3379,9 @@ var Builder = class {
         const selector = this.walk(def.selector);
         const tails = [
           ...def.cases.map((entry) => this.walk(entry.parser)),
+          ...def.matchers ? def.matchers.map((entry) => this.walk(entry.parser)) : [],
           ...def.otherwise ? [this.walk(def.otherwise)] : []
-        ].filter(nonEmpty);
+        ];
         return flattenSeq([selector, flattenChoice(tails)]);
       }
       // `max`/`min` are carried through so a BOUNDED repeat does not render as an
@@ -3207,6 +3413,8 @@ var Builder = class {
         return { kind: "not", item: this.walk(def.parser) };
       case "peek":
         return { kind: "peek", item: this.walk(def.parser) };
+      case "routed":
+        return { kind: "empty" };
       // Transparent semantic wrappers — render the inner syntax.
       case "transform":
       case "token":
@@ -3364,7 +3572,7 @@ function render(node2) {
     case "choice": {
       const text = node2.items.map((it) => {
         const r = render(it);
-        return wrap(r.text, r.level, ALT);
+        return r.text.length === 0 ? "/* empty */" : wrap(r.text, r.level, ALT);
       }).join(" | ");
       return { text, level: ALT };
     }