@thomasfosterau/effect-parse 0.1.0 → 0.3.0

package/src/Input.ts

@@ -8,13 +8,16 @@
  * failure.
  *
  * Most users never touch `State` directly. It is exposed for writing custom
- * low-level parsers with `Parser.make`.
+ * low-level parsers with `Parser.make`, and for drivers that run a parser's
+ * `step` many times over one input, reusing a state with {@link State.reset}.
  *
  * @since 0.1.0
  */
+import * as Predicate from "effect/Predicate"
 import * as Context from "effect/Context"
 import type { Encoding } from "./Encoding.js"
 import type { ErrorKind } from "./ParseError.js"
+import type { Builder as SyntaxBuilder } from "./internal/syntax.js"
 
 /**
  * The kinds of input a parser can consume.
@@ -70,7 +73,7 @@ export const fromSource: {
   (source: BinaryInput): Uint8Array
   <I extends Input>(source: Source<I>): I
 } = (source: Input | BinaryInput): any => {
-  if (typeof source === "string" || source instanceof Uint8Array || Array.isArray(source)) return source
+  if (Predicate.isString(source) || source instanceof Uint8Array || Array.isArray(source)) return source
   if (ArrayBuffer.isView(source)) return new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
   // An explicit length fixes the view's size even for a resizable buffer
   if (isArrayBufferLike(source)) return new Uint8Array(source, 0, source.byteLength)
@@ -78,7 +81,7 @@ export const fromSource: {
 }
 
 const isArrayBufferLike = (u: unknown): u is ArrayBufferLike =>
-  u instanceof ArrayBuffer || (typeof SharedArrayBuffer !== "undefined" && u instanceof SharedArrayBuffer)
+  u instanceof ArrayBuffer || (globalThis.SharedArrayBuffer !== undefined && u instanceof SharedArrayBuffer)
 
 /**
  * The type of a single token of an input.
@@ -86,10 +89,13 @@ const isArrayBufferLike = (u: unknown): u is ArrayBufferLike =>
  * @since 0.1.0
  * @category models
  */
-export type Token<I> = I extends string ? string
-  : I extends Uint8Array ? number
-  : I extends ReadonlyArray<infer T> ? T
-  : never
+export type Token<I> = I extends string
+  ? string
+  : I extends Uint8Array
+    ? number
+    : I extends ReadonlyArray<infer T>
+      ? T
+      : never
 
 /**
  * The type of a contiguous slice of an input.
@@ -97,10 +103,13 @@ export type Token<I> = I extends string ? string
  * @since 0.1.0
  * @category models
  */
-export type Slice<I> = I extends string ? string
-  : I extends Uint8Array ? Uint8Array
-  : I extends ReadonlyArray<infer T> ? ReadonlyArray<T>
-  : never
+export type Slice<I> = I extends string
+  ? string
+  : I extends Uint8Array
+    ? Uint8Array
+    : I extends ReadonlyArray<infer T>
+      ? ReadonlyArray<T>
+      : never
 
 /**
  * Sentinel returned by a parser step to signal failure. The failure details
@@ -109,7 +118,7 @@ export type Slice<I> = I extends string ? string
  * @since 0.1.0
  * @category failure
  */
-export const Fail: unique symbol = Symbol.for("effect-parse/Fail")
+export const Fail: unique symbol = /*#__PURE__*/ Symbol.for("effect-parse/Fail")
 
 /**
  * @since 0.1.0
@@ -158,6 +167,9 @@ export class Failure {
 
 const empty: ReadonlyArray<string> = []
 
+/** The failure a {@link State} starts with, before any step has failed. */
+const initialFailure = /*#__PURE__*/ new Failure(0, "Fail", empty, empty, false, undefined, undefined, 0)
+
 /** @internal */
 export const emptyStrings = empty
 
@@ -189,7 +201,8 @@ export class State<I extends Input = Input> {
   /** The full input being parsed. */
   readonly input: I
   /** The current offset. Advanced by parsers, rewound on backtracking. */
-  pos: number
+  // Declared, not defined, so that a subclass can make it an accessor
+  declare pos: number
   /** The end offset (the input's length; in bits inside `Bits.bits`). */
   end: number
   /** 0 = string, 1 = Uint8Array, 2 = array. */
@@ -200,8 +213,31 @@ export class State<I extends Input = Input> {
   context: Context.Context<never>
   /** Mode of the latest failure. Only meaningful after a step returned {@link Fail}. */
   mode: ErrMode = "Backtrack"
-  /** Details of the latest failure. Only meaningful after a step returned {@link Fail}. */
-  failure: Failure
+  /**
+   * The latest failure, kept unmerged: the failure is `failureHead` merged
+   * (as `mergeFailures` does) with `failureTie1` and then `failureTie2`, all
+   * at the same offset. `Parser.alt` records its tied branch failures here
+   * with {@link failTies} instead of merging them, so that an enclosing `alt`
+   * whose next branch succeeds never pays for the merge. Reading
+   * {@link failure} performs the merge, once.
+   *
+   * @internal
+   */
+  failureHead: Failure
+  /** @internal */
+  failureTie1: Failure | undefined = undefined
+  /** @internal */
+  failureTie2: Failure | undefined = undefined
+  /** Backs {@link deepest}. @internal */
+  deepestFailure: Failure | undefined = undefined
+  /**
+   * Whether the furthest failure is the latest failure, still unmerged, so
+   * that {@link deepest} is that failure once merged. Only set while
+   * `failureTie1` is.
+   *
+   * @internal
+   */
+  deepestIsLatest = false
   /**
    * The offset of a recoverable failure that occurred without consuming
    * input (for example the last attempt of a `repeat`). Its
@@ -216,9 +252,18 @@ export class State<I extends Input = Input> {
    * were later swallowed by backtracking (for example a trailing separator
    * followed by an invalid element). It is reported instead of the final
    * failure when it lies further into the input. This is the classic PEG
-   * "farthest failure" heuristic.
+   * "farthest failure" heuristic. `Parser.cut` keeps only the failures
+   * recorded inside it when it commits, and `Parser.peek` and `Parser.not`
+   * forget the failures of a lookahead that succeeded.
    */
-  deepest: Failure | undefined = undefined
+  get deepest(): Failure | undefined {
+    if (this.deepestIsLatest) this.settleFailure()
+    return this.deepestFailure
+  }
+  set deepest(failure: Failure | undefined) {
+    this.deepestIsLatest = false
+    this.deepestFailure = failure
+  }
   /** When defined, `Parser.resumeAfter`/`retryAfter` record failures here. */
   recovered: Array<Failure> | undefined = undefined
   /** When defined, `Parser.trace` reports events here. */
@@ -237,20 +282,114 @@ export class State<I extends Input = Input> {
    * @internal
    */
   resume: Map<object, Map<number, unknown>> | undefined = undefined
+  /**
+   * The tree builder of a `Syntax` parse; `undefined` otherwise.
+   *
+   * @internal
+   */
+  syntax: SyntaxBuilder | undefined = undefined
 
-  constructor(source: I | Source<I>, options?: {
-    readonly partial?: boolean | undefined
-    readonly context?: Context.Context<never> | undefined
-    readonly offset?: number | undefined
-  }) {
+  constructor(
+    source: I | Source<I>,
+    options?: {
+      readonly partial?: boolean | undefined
+      readonly context?: Context.Context<never> | undefined
+      readonly offset?: number | undefined
+    }
+  ) {
     const input = fromSource(source as Input) as I
     this.input = input
     this.end = input.length
     this.pos = options?.offset ?? 0
     this.partial = options?.partial ?? false
     this.context = options?.context ?? Context.empty()
-    this.inputKind = typeof input === "string" ? 0 : input instanceof Uint8Array ? 1 : 2
-    this.failure = new Failure(0, "Fail", empty, empty, false, undefined, undefined, 0)
+    this.inputKind = Predicate.isString(input) ? 0 : input instanceof Uint8Array ? 1 : 2
+    this.failureHead = initialFailure
+  }
+
+  /** Details of the latest failure. Only meaningful after a step returned {@link Fail}. */
+  get failure(): Failure {
+    if (this.failureTie1 !== undefined) this.settleFailure()
+    return this.failureHead
+  }
+  set failure(failure: Failure) {
+    if (this.deepestIsLatest) this.settleFailure()
+    this.failureHead = failure
+    this.failureTie1 = undefined
+    this.failureTie2 = undefined
+  }
+
+  /** Merges the latest failure's ties into it (see {@link failureHead}). */
+  private settleFailure(): void {
+    let failure = this.failureHead
+    const tie1 = this.failureTie1
+    if (tie1 !== undefined) {
+      failure = mergeTiedFailures(failure, tie1, mergeExpected(failure.expected, tie1.expected))
+      const tie2 = this.failureTie2
+      if (tie2 !== undefined) failure = mergeTiedFailures(failure, tie2, mergeExpected(failure.expected, tie2.expected))
+      this.failureHead = failure
+      this.failureTie1 = undefined
+      this.failureTie2 = undefined
+    }
+    if (this.deepestIsLatest) {
+      this.deepestFailure = failure
+      this.deepestIsLatest = false
+    }
+  }
+
+  /**
+   * Prepares the state for another run over the same input, starting at
+   * `offset`: afterwards it behaves exactly like
+   * `new State(state.input, { ...options, offset })`, without allocating a
+   * new state.
+   *
+   * Every per-run field is reset: the cursor and end, the latest failure,
+   * hints and furthest failure, recorded recoveries, the tracer and tracing
+   * depth, the recorded encoding and streaming checkpoints. Like the
+   * constructor, `partial` defaults to `false` and `context` to the empty
+   * context, so pass them again on every reset.
+   *
+   * Use it to run many small parses over one buffer, for example one per
+   * token, with `parser.step`. A state can be reused after any run,
+   * including one that failed, returned `Incomplete` or threw.
+   *
+   * @example
+   * ```ts
+   * import { Ascii, Input } from "@thomasfosterau/effect-parse"
+   *
+   * const state = new Input.State("12 34")
+   * Ascii.decUint.step(state) // 12
+   * state.reset(3)
+   * Ascii.decUint.step(state) // 34
+   * ```
+   *
+   * @since 0.2.0
+   */
+  reset(
+    offset: number = 0,
+    options?: {
+      readonly partial?: boolean | undefined
+      readonly context?: Context.Context<never> | undefined
+    }
+  ): this {
+    this.pos = offset
+    this.end = this.input.length
+    this.partial = options?.partial ?? false
+    this.context = options?.context ?? Context.empty()
+    this.mode = "Backtrack"
+    this.failureHead = initialFailure
+    this.failureTie1 = undefined
+    this.failureTie2 = undefined
+    this.hintOffset = -1
+    this.hintExpected = empty
+    this.deepestFailure = undefined
+    this.deepestIsLatest = false
+    this.recovered = undefined
+    this.tracer = undefined
+    this.depth = 0
+    this.encoding = undefined
+    this.resume = undefined
+    return this
   }
 
   /**
@@ -334,13 +473,37 @@ export class State<I extends Input = Input> {
    */
   failWith(mode: ErrMode, failure: Failure): Fail {
     this.mode = mode
-    this.failure = failure
-    if (mode === "Backtrack" && (this.deepest === undefined || failure.offset >= this.deepest.offset)) {
-      this.deepest = failure
+    if (this.deepestIsLatest) {
+      // The furthest failure is the latest one: it is replaced below, unmerged, if `failure` is as far
+      if (mode === "Backtrack" && failure.offset >= this.failureHead.offset) this.deepestIsLatest = false
+      else this.settleFailure()
+    }
+    this.failureHead = failure
+    this.failureTie1 = undefined
+    this.failureTie2 = undefined
+    if (mode === "Backtrack" && (this.deepestFailure === undefined || failure.offset >= this.deepestFailure.offset)) {
+      this.deepestFailure = failure
     }
     return Fail
   }
 
+  /**
+   * Records a recoverable failure made of tied failures, merged only when
+   * read: `failWith("Backtrack", f)` where `f` merges `head` with `tie1`
+   * and then `tie2` (all at the same offset), as `mergeFailures` would.
+   *
+   * @internal
+   */
+  failTies(head: Failure, tie1: Failure, tie2: Failure | undefined): Fail {
+    this.mode = "Backtrack"
+    if (this.deepestIsLatest && head.offset < this.failureHead.offset) this.settleFailure()
+    this.failureHead = head
+    this.failureTie1 = tie1
+    this.failureTie2 = tie2
+    this.deepestIsLatest = this.deepestFailure === undefined || head.offset >= this.deepestFailure.offset
+    return Fail
+  }
+
   /**
    * Replaces the details of the current failure (for example to add context),
    * keeping the record of the furthest failure consistent.
@@ -359,12 +522,17 @@ export class State<I extends Input = Input> {
     const f = this.failure
     const d = this.deepest
     if (
-      d === undefined || d === f || d.offset <= f.offset || this.mode === "Incomplete" ||
-      f.hasCause || f.message !== undefined
+      d === undefined ||
+      d === f ||
+      d.offset <= f.offset ||
+      this.mode === "Incomplete" ||
+      f.hasCause ||
+      f.message !== undefined
     ) {
       return f
     }
-    const context = d.context.length === 0 ? f.context : [...d.context, ...f.context.filter((l) => !d.context.includes(l))]
+    const context =
+      d.context.length === 0 ? f.context : [...d.context, ...f.context.filter((l) => !d.context.includes(l))]
     return new Failure(d.offset, d.kind, d.expected, context, d.hasCause, d.cause, d.message, d.needed)
   }
 
@@ -392,10 +560,7 @@ export class State<I extends Input = Input> {
 }
 
 /** @internal */
-export const mergeExpected = (
-  a: ReadonlyArray<string>,
-  b: ReadonlyArray<string>
-): ReadonlyArray<string> => {
+export const mergeExpected = (a: ReadonlyArray<string>, b: ReadonlyArray<string>): ReadonlyArray<string> => {
   if (a.length === 0) return b
   if (b.length === 0) return a
   const out = a.slice()
@@ -414,7 +579,17 @@ export const mergeExpected = (
 export const mergeFailures = (a: Failure, b: Failure): Failure => {
   if (a.offset > b.offset) return a
   if (b.offset > a.offset) return b
-  const expected = mergeExpected(a.expected, b.expected)
+  return mergeTiedFailures(a, b, mergeExpected(a.expected, b.expected))
+}
+
+/**
+ * {@link mergeFailures} for two failures at the same offset, given their
+ * merged expectations (`mergeExpected(a.expected, b.expected)`, possibly
+ * memoised by the caller).
+ *
+ * @internal
+ */
+export const mergeTiedFailures = (a: Failure, b: Failure, expected: ReadonlyArray<string>): Failure => {
   if (expected === b.expected) return b
   return new Failure(
     b.offset,

package/src/Nom.ts

@@ -116,8 +116,9 @@ export const isA = <I extends Input = string>(set: TokenSet<I>): Parser<Slice<No
  * @since 0.1.0
  * @category bytes
  */
-export const isNot = <I extends Input = string>(set: TokenSet<I>): Parser<Slice<NoInfer<I>>, never, never, NoInfer<I>> =>
-  Token.takeTill<I>(set, { min: 1 })
+export const isNot = <I extends Input = string>(
+  set: TokenSet<I>
+): Parser<Slice<NoInfer<I>>, never, never, NoInfer<I>> => Token.takeTill<I>(set, { min: 1 })
 
 /**
  * @since 0.1.0
@@ -265,7 +266,7 @@ export const double = Ascii.float
  * @since 0.1.0
  * @category number
  */
-export const recognizeFloat: Parser<string> = P.taken(Ascii.float)
+export const recognizeFloat: Parser<string> = /*#__PURE__*/ P.taken(Ascii.float)
 
 /**
  * nom's `hex_u32`.

package/src/ParseError.ts

@@ -19,6 +19,7 @@
  *
  * @since 0.1.0
  */
+import * as Predicate from "effect/Predicate"
 import * as Data from "effect/Data"
 import * as Option from "effect/Option"
 import type { Encoding } from "./Encoding.js"
@@ -29,6 +30,9 @@ import * as text from "./internal/text.js"
  * The kind of parser that produced an error, in the spirit of nom's
  * `ErrorKind`.
  *
+ * `"TooDeep"` is not produced by a parser: the runners report it when
+ * deeply nested input exhausts the call stack (see `Parser.suspend`).
+ *
  * @since 0.1.0
  * @category models
  */
@@ -64,13 +68,14 @@ export type ErrorKind =
   | "TakeUntil"
   | "TakeWhile"
   | "Token"
+  | "TooDeep"
   | "Verify"
 
 /**
  * @since 0.1.0
  * @category type ids
  */
-export const TypeId: "~effect-parse/ParseError" = "~effect-parse/ParseError"
+export const TypeId = "~effect-parse/ParseError" as const
 
 /**
  * An error produced by running a parser.
@@ -78,29 +83,31 @@ export const TypeId: "~effect-parse/ParseError" = "~effect-parse/ParseError"
  * @since 0.1.0
  * @category models
  */
-export class ParseError<out E = never> extends Data.TaggedError("ParseError")<{
-  /** The input that was being parsed. */
-  readonly input: Input
-  /** The offset of the failure in the input. */
-  readonly offset: number
-  /** The kind of parser that failed. */
-  readonly kind: ErrorKind
-  /** How the error propagated before parsing stopped. */
-  readonly mode: ErrMode
-  /** Descriptions of what was expected at `offset`. */
-  readonly expected: ReadonlyArray<string>
-  /** Context labels (`Parser.context`), innermost first. */
-  readonly context: ReadonlyArray<string>
-  /** The user supplied cause, if any. */
-  readonly cause: E | undefined
-  /** An optional free-form description. */
-  readonly description: string | undefined
-  /**
-   * For byte inputs parsed by `Text` parsers, the text encoding. Errors
-   * then show the input as text, with line and column numbers.
-   */
-  readonly encoding?: Encoding<Uint8Array> | undefined
-}> {
+export class ParseError<out E = never>
+  extends /*#__PURE__*/ Data.TaggedError("ParseError")<{
+    /** The input that was being parsed. */
+    readonly input: Input
+    /** The offset of the failure in the input. */
+    readonly offset: number
+    /** The kind of parser that failed. */
+    readonly kind: ErrorKind
+    /** How the error propagated before parsing stopped. */
+    readonly mode: ErrMode
+    /** Descriptions of what was expected at `offset`. */
+    readonly expected: ReadonlyArray<string>
+    /** Context labels (`Parser.context`), innermost first. */
+    readonly context: ReadonlyArray<string>
+    /** The user supplied cause, if any. */
+    readonly cause: E | undefined
+    /** An optional free-form description. */
+    readonly description: string | undefined
+    /**
+     * For byte inputs parsed by `Text` parsers, the text encoding. Errors
+     * then show the input as text, with line and column numbers.
+     */
+    readonly encoding?: Encoding<Uint8Array> | undefined
+  }>
+{
   /**
    * @since 0.1.0
    */
@@ -137,8 +144,7 @@ export class ParseError<out E = never> extends Data.TaggedError("ParseError")<{
  * @since 0.1.0
  * @category guards
  */
-export const isParseError = (u: unknown): u is ParseError<unknown> =>
-  typeof u === "object" && u !== null && TypeId in u
+export const isParseError = (u: unknown): u is ParseError<unknown> => Predicate.isObjectOrArray(u) && TypeId in u
 
 /**
  * Builds a `ParseError` from the failure details recorded while parsing.
@@ -159,7 +165,7 @@ export const fromFailure = <E = never>(
     mode,
     expected: failure.expected,
     context: failure.context,
-    cause: failure.hasCause ? failure.cause as E : undefined,
+    cause: failure.hasCause ? (failure.cause as E) : undefined,
     description: failure.message,
     encoding: input instanceof Uint8Array ? encoding : undefined
   })
@@ -207,7 +213,7 @@ export const lineColumn = (input: Input, offset: number, encoding?: Encoding<any
     })
     return { line, column }
   }
-  if (typeof input !== "string") return { line: 1, column: offset + 1 }
+  if (!Predicate.isString(input)) return { line: 1, column: offset + 1 }
   let line = 1
   let lineStart = 0
   for (let i = 0; i < offset && i < input.length; i++) {
@@ -240,7 +246,7 @@ const codePointCount = (s: string, start: number, end: number): number => {
  */
 export const formatExpected = (expected: ReadonlyArray<string>): string => {
   if (expected.length === 0) return ""
-  if (expected.length === 1) return expected[0]!
+  if (expected.length === 1) return expected[0]
   return `${expected.slice(0, -1).join(", ")} or ${expected[expected.length - 1]}`
 }
 
@@ -257,20 +263,20 @@ const describeFound = (input: Input, offset: number, encoding: Encoding<any> | u
       ? `incomplete ${encoding.name} sequence ${hexBytes(input.subarray(offset))}`
       : `invalid ${encoding.name} ${hexBytes(bad)}`
   }
-  if (typeof input === "string") {
-    const cp = input.codePointAt(offset)!
+  if (Predicate.isString(input)) {
+    const cp = input.codePointAt(offset) ?? Number.NaN
     return JSON.stringify(String.fromCodePoint(cp))
   }
   if (input instanceof Uint8Array) {
-    return `0x${input[offset]!.toString(16).padStart(2, "0")}`
+    return `0x${input[offset].toString(16).padStart(2, "0")}`
   }
   return inspectToken(input[offset])
 }
 
 /** @internal */
 export const inspectToken = (u: unknown): string => {
-  if (typeof u === "string") return JSON.stringify(u)
-  if (typeof u === "object" && u !== null) {
+  if (Predicate.isString(u)) return JSON.stringify(u)
+  if (Predicate.isObjectOrArray(u)) {
     try {
       return JSON.stringify(u)
     } catch {
@@ -282,9 +288,9 @@ export const inspectToken = (u: unknown): string => {
 
 const causeMessage = (cause: unknown): string | undefined => {
   if (cause === undefined) return undefined
-  if (typeof cause === "string") return cause
-  if (cause instanceof Error) return cause.message
-  if (typeof cause === "object" && cause !== null && "message" in cause && typeof cause.message === "string") {
+  if (Predicate.isString(cause)) return cause
+  // An `Error`'s message, or any other object's string `message`
+  if (Predicate.isObjectOrArray(cause) && "message" in cause && Predicate.isString(cause.message)) {
     return cause.message
   }
   return inspectToken(cause)
@@ -314,12 +320,9 @@ const renderSnippet = (input: Input, offset: number, encoding: Encoding<any> | u
     if (line.endsWith("\r")) line = line.slice(0, -1)
     const gutter = String(lineColumn(input, offset, encoding).line)
     const pad = " ".repeat(gutter.length)
-    return [
-      `${gutter} | ${line}`,
-      `${pad} | ${" ".repeat(column - 1)}^`
-    ]
+    return [`${gutter} | ${line}`, `${pad} | ${" ".repeat(column - 1)}^`]
   }
-  if (typeof input === "string") {
+  if (Predicate.isString(input)) {
     const { column, line } = lineColumn(input, offset)
     let start = offset
     while (start > 0 && input.charCodeAt(start - 1) !== 10) start--
@@ -329,21 +332,15 @@ const renderSnippet = (input: Input, offset: number, encoding: Encoding<any> | u
     if (text.endsWith("\r")) text = text.slice(0, -1)
     const gutter = String(line)
     const pad = " ".repeat(gutter.length)
-    return [
-      `${gutter} | ${text}`,
-      `${pad} | ${" ".repeat(column - 1)}^`
-    ]
+    return [`${gutter} | ${text}`, `${pad} | ${" ".repeat(column - 1)}^`]
   }
   if (input instanceof Uint8Array) {
     const start = Math.max(0, offset - 8)
     const end = Math.min(input.length, offset + 8)
     const bytes: Array<string> = []
-    for (let i = start; i < end; i++) bytes.push(input[i]!.toString(16).padStart(2, "0"))
+    for (let i = start; i < end; i++) bytes.push(input[i].toString(16).padStart(2, "0"))
     const caret = (offset - start) * 3
-    return [
-      `${start.toString(16).padStart(8, "0")} | ${bytes.join(" ")}`,
-      `${" ".repeat(8)} | ${" ".repeat(caret)}^`
-    ]
+    return [`${start.toString(16).padStart(8, "0")} | ${bytes.join(" ")}`, `${" ".repeat(8)} | ${" ".repeat(caret)}^`]
   }
   return []
 }
@@ -351,7 +348,7 @@ const renderSnippet = (input: Input, offset: number, encoding: Encoding<any> | u
 const render = (error: ParseError<unknown>): string => {
   const { encoding, input, offset } = error
   const lines: Array<string> = []
-  if (typeof input === "string") {
+  if (Predicate.isString(input)) {
     const { column, line } = lineColumn(input, offset)
     lines.push(`Parse error at line ${line}, column ${column}:`)
   } else if (encoding !== undefined) {