@thomasfosterau/effect-parse 0.0.0-stage → 0.0.0

package/dist/Parser.d.ts

@@ -0,0 +1,1312 @@
+/**
+ * The `Parser` data type and its general-purpose combinators.
+ *
+ * A `Parser<A, E, R, I>` consumes input of type `I` and produces a value of
+ * type `A`. It may fail with a `ParseError<E>`, where `E` is the type of
+ * user supplied error causes, and it may require services `R` from an Effect
+ * `Context`.
+ *
+ * Under the hood a parser is a function over a mutable cursor (`Input.State`),
+ * as in winnow. Failure is cheap and backtracking is a matter of resetting an
+ * offset. On the surface the API follows Effect's conventions: parsers are
+ * pipeable, combinators are dual (data-first or data-last), and parsers can
+ * be written with generators:
+ *
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const point = Parser.gen(function*() {
+ *   yield* Token.literal("(")
+ *   const x = yield* Ascii.decInt
+ *   yield* Token.literal(",")
+ *   const y = yield* Ascii.decInt
+ *   yield* Token.literal(")")
+ *   return { x, y }
+ * })
+ *
+ * Parser.parse(point, "(1,-2)") // Result.succeed({ x: 1, y: -2 })
+ * ```
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import type { Pipeable } from "effect/Pipeable";
+import * as Result from "effect/Result";
+import type { Contravariant, Covariant, Simplify } from "effect/Types";
+import type { Input, Slice, Source, TraceEvent } from "./Input.js";
+import { Fail, State } from "./Input.js";
+import type { ErrorKind } from "./ParseError.js";
+import * as ParseError from "./ParseError.js";
+import type { Node } from "./internal/node.js";
+/**
+ * @since 0.1.0
+ * @category type ids
+ */
+export declare const TypeId: "~effect-parse/Parser";
+/**
+ * A parser that consumes input of type `I`, producing a value of type `A`,
+ * possibly failing with a user cause of type `E`, and requiring services `R`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Parser<out A, out E = never, out R = never, in I extends Input = string> extends Pipeable {
+    readonly [TypeId]: Parser.Variance<A, E, R, I>;
+    /**
+     * Runs one parsing step against a cursor. Returns the parsed value, or the
+     * `Fail` sentinel after recording the failure on the state.
+     *
+     * Calling `step` directly is how custom combinators built with
+     * {@link make} invoke other parsers.
+     */
+    readonly step: (state: State<I>) => A | Fail;
+    /** A human-readable name, used by `toString` and tracing. */
+    readonly name: string | undefined;
+    [Symbol.iterator](): ParserIterator<Parser<A, E, R, I>>;
+}
+/**
+ * The iterator used by `yield*` inside {@link gen}.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface ParserIterator<P extends Parser.Any> {
+    next(...args: ReadonlyArray<any>): IteratorResult<P, Parser.Success<P>>;
+}
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export declare namespace Parser {
+    /**
+     * @since 0.1.0
+     */
+    interface Variance<A, E, R, I> {
+        readonly _A: Covariant<A>;
+        readonly _E: Covariant<E>;
+        readonly _R: Covariant<R>;
+        readonly _I: Contravariant<I>;
+    }
+    /**
+     * Any parser.
+     *
+     * @since 0.1.0
+     */
+    type Any = Parser<any, any, any, any>;
+    /**
+     * The output type of a parser.
+     *
+     * @since 0.1.0
+     */
+    type Success<P> = P extends Parser<infer A, infer _E, infer _R, infer _I> ? A : never;
+    /**
+     * The user error type of a parser.
+     *
+     * @since 0.1.0
+     */
+    type Error<P> = P extends Parser<infer _A, infer E, infer _R, infer _I> ? E : never;
+    /**
+     * The services required by a parser.
+     *
+     * @since 0.1.0
+     */
+    type Services<P> = P extends Parser<infer _A, infer _E, infer R, infer _I> ? R : never;
+    /**
+     * The input accepted by a parser (or by every member of a union of
+     * parsers).
+     *
+     * @since 0.1.0
+     */
+    type InputOf<P> = [P] extends [never] ? Input : [P] extends [Parser<infer _A, infer _E, infer _R, infer I>] ? I : never;
+}
+/**
+ * A repetition range, in the spirit of winnow's `impl Into<Range>`:
+ *
+ * - `n`: exactly `n` times
+ * - `{ min, max }`: between `min` and `max` times (inclusive); `min`
+ *   defaults to 0 and `max` to unbounded.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type Range = number | {
+    readonly min?: number | undefined;
+    readonly max?: number | undefined;
+};
+/**
+ * The output of a repetition: a non-empty array when the range has a literal
+ * positive minimum.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type Repeated<A, Rg> = Rg extends number ? number extends Rg ? Array<A> : Rg extends 0 ? Array<A> : NonEmpty<A> : Rg extends {
+    readonly min: infer M extends number;
+} ? number extends M ? Array<A> : M extends 0 ? Array<A> : NonEmpty<A> : Array<A>;
+type NonEmpty<A> = [A, ...Array<A>];
+/**
+ * A span of input offsets, `[start, end)`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Span {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Tests whether a value is a `Parser`.
+ *
+ * @since 0.1.0
+ * @category guards
+ */
+export declare const isParser: (u: unknown) => u is Parser<unknown, unknown, unknown, never>;
+/**
+ * Creates a parser from a step function over the mutable {@link State}
+ * cursor. This is the escape hatch for writing low-level parsers, much like
+ * passing a plain function as a parser in winnow.
+ *
+ * The step function must either return the parsed value, having advanced
+ * `state.pos` past the consumed input, or return the result of one of
+ * `state.backtrack`, `state.cut`, `state.incomplete`, ... to signal failure.
+ *
+ * @example
+ * ```ts
+ * import { Parser } from "@thomasfosterau/effect-parse"
+ *
+ * // Parses a single ASCII uppercase letter
+ * const upper = Parser.make<string>((state) => {
+ *   const c = state.input.charCodeAt(state.pos)
+ *   if (state.pos < state.end && c >= 65 && c <= 90) {
+ *     state.pos++
+ *     return String.fromCharCode(c)
+ *   }
+ *   return state.pos >= state.end
+ *     ? state.eoi("Token", ["uppercase letter"], 1)
+ *     : state.backtrack("Token", ["uppercase letter"])
+ * })
+ * ```
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const make: <A, E = never, R = never, I extends Input = string>(step: (state: State<I>) => A | Fail, name?: string) => Parser<A, E, R, I>;
+/**
+ * Creates a parser together with its description, used by the compiler.
+ *
+ * @internal
+ */
+export declare const described: <A, E = never, R = never, I extends Input = string>(step: (state: State<I>) => A | Fail, name: string | undefined, node: Node) => Parser<A, E, R, I>;
+/**
+ * Gives a parser a name, used by `toString`.
+ *
+ * @since 0.1.0
+ * @category utils
+ */
+export declare const named: {
+    (name: string): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, name: string): Parser<A, E, R, I>;
+};
+/**
+ * A parser that consumes nothing and succeeds with the given value.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const succeed: <A>(value: A) => Parser<A, never, never, Input>;
+/**
+ * A parser that consumes nothing and succeeds with the result of a thunk.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const sync: <A>(evaluate: () => A) => Parser<A, never, never, Input>;
+/**
+ * A parser that consumes nothing and succeeds with `undefined` (winnow's
+ * `empty`, nom's `success(())`).
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const empty: Parser<void, never, never, Input>;
+/**
+ * Alias of {@link empty}, following Effect's `Effect.void`.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const void_: Parser<void, never, never, Input>;
+export { 
+/**
+ * @since 0.1.0
+ * @category constructors
+ */
+void_ as void };
+/**
+ * A parser that always fails (backtracks) with the given user error as its
+ * cause.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const fail: <E>(error: E) => Parser<never, E, never, Input>;
+/**
+ * A parser that always fails (backtracks) without a cause. This is winnow's
+ * `fail` and nom's `fail()`.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const reject: Parser<never, never, never, Input>;
+/**
+ * A parser that always fails with a message.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const failMessage: (message: string) => Parser<never, never, never, Input>;
+/**
+ * A placeholder parser that fails with an unrecoverable error (winnow's
+ * `todo`).
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const todo: Parser<never, never, never, Input>;
+/**
+ * Lazily constructs a parser, which is needed to define recursive grammars.
+ * The thunk is evaluated once, on first use.
+ *
+ * @example
+ * ```ts
+ * import { Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * type Nested = ReadonlyArray<Nested>
+ * const nested: Parser.Parser<Nested> = Parser.delimited(
+ *   Token.literal("["),
+ *   Parser.repeat(Parser.suspend(() => nested)),
+ *   Token.literal("]")
+ * )
+ * ```
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const suspend: <A, E = never, R = never, I extends Input = string>(evaluate: () => Parser<A, E, R, I>) => Parser<A, E, R, I>;
+/**
+ * The current offset into the input (winnow's `Location`).
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const location: Parser<number, never, never, Input>;
+/**
+ * Succeeds (with `undefined`) only at the end of the input; nom's and
+ * winnow's `eof`. On partial input, reaching the end of the available data
+ * is reported as `Incomplete` since more data may follow.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const eof: Parser<void, never, never, Input>;
+/**
+ * Transforms the output of a parser.
+ *
+ * @since 0.1.0
+ * @category mapping
+ */
+export declare const map: {
+    <A, B>(f: (a: A) => B): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
+    <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, f: (a: A) => B): Parser<B, E, R, I>;
+};
+/**
+ * Builds an object from the `[key, value]` entries a parser returns, as
+ * `Object.fromEntries` does: `fromEntries(self)` is
+ * `map(self, Object.fromEntries)`.
+ *
+ * Compiled parsers build the object directly when `self` repeats a pair
+ * (`separated` or `repeat` of `separatedPair` or a two-element `seq`,
+ * possibly inside `preceded`, `terminated`, `delimited` or `cut`), without
+ * the pairs and the array. They do the same for `map(Object.fromEntries)`.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const entry = Parser.separatedPair(Ascii.alpha1, Token.literal("="), Ascii.decUint)
+ * const record = Parser.fromEntries(Parser.separated(entry, Token.literal(",")))
+ * Parser.parse(record, "a=1,b=2") // Result.succeed({ a: 1, b: 2 })
+ * ```
+ *
+ * @since 0.2.0
+ * @category mapping
+ */
+export declare const fromEntries: <K extends PropertyKey, V, E, R, I extends Input>(self: Parser<Iterable<readonly [K, V]>, E, R, I>) => Parser<{ [P in K]: V; }, E, R, I>;
+/**
+ * Replaces the output of a parser with a constant (winnow's `value`, nom's
+ * `value`).
+ *
+ * @since 0.1.0
+ * @category mapping
+ */
+export declare const as: {
+    <B>(value: B): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
+    <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, value: B): Parser<B, E, R, I>;
+};
+/**
+ * Discards the output of a parser (winnow's `void`).
+ *
+ * @since 0.1.0
+ * @category mapping
+ */
+export declare const asVoid: <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<void, E, R, I>;
+/**
+ * Replaces the output of a parser with `Option.some(output)`.
+ *
+ * @since 0.1.0
+ * @category mapping
+ */
+export declare const asSome: <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Option.Option<A>, E, R, I>;
+/**
+ * Runs a side effect on the output of a parser, keeping the output.
+ *
+ * @since 0.1.0
+ * @category mapping
+ */
+export declare const tap: {
+    <A>(f: (a: A) => void): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, f: (a: A) => void): Parser<A, E, R, I>;
+};
+/**
+ * Uses the output of a parser to choose the parser that consumes the rest
+ * of the input (winnow's `flat_map`, nom's `flat_map`).
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export declare const flatMap: {
+    <A, B, E2, R2, I2 extends Input>(f: (a: A) => Parser<B, E2, R2, I2>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R | R2, I & I2>;
+    <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, f: (a: A) => Parser<B, E2, R2, I2>): Parser<B, E | E2, R | R2, I & I2>;
+};
+/**
+ * Applies a second parser to the *output* of the first (winnow's
+ * `and_then`, nom's `map_parser`). The output of the first parser must
+ * itself be an input, e.g. a slice produced by {@link taken} or
+ * `Token.take`.
+ *
+ * Error offsets reported by the inner parser are translated relative to the
+ * start of the outer parser.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * // Take exactly 4 characters, then require them all to be digits
+ * const year = Token.take(4).pipe(Parser.mapParser(Parser.allConsuming(Ascii.decUint)))
+ * ```
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export declare const mapParser: {
+    <A extends Input, B, E2, R2>(inner: Parser<B, E2, R2, A>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R | R2, I>;
+    <A extends Input, E, R, I extends Input, B, E2, R2>(self: Parser<A, E, R, I>, inner: Parser<B, E2, R2, A>): Parser<B, E | E2, R | R2, I>;
+};
+/**
+ * Transforms the output of a parser with a function that may fail with a
+ * `Result` (winnow's `try_map`, nom's `map_res`). On failure the parser
+ * backtracks to where it started and the error becomes the `cause` of the
+ * `ParseError`.
+ *
+ * @since 0.1.0
+ * @category mapping
+ */
+export declare const tryMap: {
+    <A, B, E2>(f: (a: A) => Result.Result<B, E2>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R, I>;
+    <A, E, R, I extends Input, B, E2>(self: Parser<A, E, R, I>, f: (a: A) => Result.Result<B, E2>): Parser<B, E | E2, R, I>;
+};
+/**
+ * Like {@link tryMap}, but the function may throw. Thrown values become the
+ * `cause` of the error.
+ *
+ * @since 0.1.0
+ * @category mapping
+ */
+export declare const tryMapUnknown: {
+    <A, B>(f: (a: A) => B): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | unknown, R, I>;
+    <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, f: (a: A) => B): Parser<B, E | unknown, R, I>;
+};
+/**
+ * Transforms the output of a parser with a function returning an `Option`;
+ * `None` makes the parser backtrack (winnow's `verify_map`, nom's
+ * `map_opt`).
+ *
+ * @since 0.1.0
+ * @category filtering
+ */
+export declare const filterMap: {
+    <A, B>(f: (a: A) => Option.Option<B>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
+    <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, f: (a: A) => Option.Option<B>): Parser<B, E, R, I>;
+};
+/**
+ * Keeps the output of a parser only if it satisfies a predicate, otherwise
+ * backtracks (winnow's and nom's `verify`).
+ *
+ * @since 0.1.0
+ * @category filtering
+ */
+export declare const filter: {
+    <A, B extends A>(refinement: (a: NoInfer<A>) => a is B): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
+    <A>(predicate: (a: NoInfer<A>) => boolean): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+    <A, E, R, I extends Input, B extends A>(self: Parser<A, E, R, I>, refinement: (a: A) => a is B): Parser<B, E, R, I>;
+    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, predicate: (a: A) => boolean): Parser<A, E, R, I>;
+};
+/**
+ * Keeps the output of a parser only if it satisfies a predicate, otherwise
+ * backtracks with the given user error.
+ *
+ * @since 0.1.0
+ * @category filtering
+ */
+export declare const filterOrFail: {
+    <A, B extends A, E2>(refinement: (a: NoInfer<A>) => a is B, orFailWith: (a: NoInfer<A>) => E2): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R, I>;
+    <A, E2>(predicate: (a: NoInfer<A>) => boolean, orFailWith: (a: NoInfer<A>) => E2): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E | E2, R, I>;
+    <A, E, R, I extends Input, B extends A, E2>(self: Parser<A, E, R, I>, refinement: (a: A) => a is B, orFailWith: (a: A) => E2): Parser<B, E | E2, R, I>;
+    <A, E, R, I extends Input, E2>(self: Parser<A, E, R, I>, predicate: (a: A) => boolean, orFailWith: (a: A) => E2): Parser<A, E | E2, R, I>;
+};
+/**
+ * Returns the slice of input consumed by a parser instead of its output
+ * (winnow's `take`, nom's `recognize`).
+ *
+ * @since 0.1.0
+ * @category consumed input
+ */
+export declare const taken: <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Slice<I>, E, R, I>;
+/**
+ * Returns both the output of a parser and the slice of input it consumed
+ * (winnow's `with_taken`; nom's `consumed` returns them in the other order).
+ *
+ * @since 0.1.0
+ * @category consumed input
+ */
+export declare const withTaken: <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<[output: A, taken: Slice<I>], E, R, I>;
+/**
+ * Returns the span (`[start, end)` offsets) consumed by a parser instead of
+ * its output (winnow's `span`).
+ *
+ * @since 0.1.0
+ * @category consumed input
+ */
+export declare const span: <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Span, E, R, I>;
+/**
+ * Returns both the output of a parser and the span it consumed (winnow's
+ * `with_span`).
+ *
+ * @since 0.1.0
+ * @category consumed input
+ */
+export declare const withSpan: <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<[output: A, span: Span], E, R, I>;
+/**
+ * Commits to the current branch: recoverable failures of the parser become
+ * unrecoverable, so enclosing `alt`, `opt`, `repeat`, ... do not try
+ * alternatives (winnow's `cut_err`, nom's `cut`).
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * // Once we have seen "-", a number must follow
+ * const negative = Parser.preceded(Token.literal("-"), Parser.cut(Ascii.decUint))
+ * ```
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export declare const cut: <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+/**
+ * Turns unrecoverable failures back into recoverable ones (winnow's
+ * `backtrack_err`).
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export declare const backtrack: <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+/**
+ * Turns `Incomplete` failures into recoverable ones, treating the input as
+ * complete for this parser (winnow's `complete_err`, nom's `complete`).
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export declare const complete: <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+/**
+ * Adds a context label to failures of a parser (winnow's
+ * `context(StrContext::Label(..))`, nom's `context`). Labels are rendered as
+ * "while parsing <label>" in the error message.
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export declare const context: {
+    (label: string): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, label: string): Parser<A, E, R, I>;
+};
+/**
+ * Names what a parser expects. When the parser fails without consuming any
+ * input, its expectations are replaced with `description`, so a failure is
+ * reported as `expected <description>` rather than in terms of the parser's
+ * internals (Parsec's `<?>`, winnow's `StrContext::Expected`).
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export declare const expected: {
+    (description: string): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, description: string): Parser<A, E, R, I>;
+};
+/**
+ * Transforms the user error (cause) of a parser's failures.
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export declare const mapError: {
+    <E, E2>(f: (e: E) => E2): <A, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E2, R, I>;
+    <A, E, R, I extends Input, E2>(self: Parser<A, E, R, I>, f: (e: E) => E2): Parser<A, E2, R, I>;
+};
+/**
+ * Replaces any failure of a parser with the given user error, keeping the
+ * failure's position and mode.
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export declare const orFail: {
+    <E2>(error: () => E2): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E2, R, I>;
+    <A, E, R, I extends Input, E2>(self: Parser<A, E, R, I>, error: () => E2): Parser<A, E2, R, I>;
+};
+/**
+ * If the parser fails recoverably, tries `that` from the same position.
+ * `p.pipe(Parser.orElse(() => q))` is equivalent to `Parser.alt(p, q)`.
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export declare const orElse: {
+    <B, E2, R2, I2 extends Input>(that: () => Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A | B, E | E2, R | R2, I & I2>;
+    <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, that: () => Parser<B, E2, R2, I2>): Parser<A | B, E | E2, R | R2, I & I2>;
+};
+/**
+ * If the parser fails recoverably, succeeds with the given value without
+ * consuming input.
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export declare const orElseSucceed: {
+    <B>(value: () => B): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A | B, E, R, I>;
+    <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, value: () => B): Parser<A | B, E, R, I>;
+};
+/**
+ * Makes a parser optional: returns `Option.none()` without consuming input if
+ * it fails recoverably (winnow's and nom's `opt`).
+ *
+ * @since 0.1.0
+ * @category control
+ */
+export declare const opt: <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Option.Option<A>, E, R, I>;
+/**
+ * Like {@link opt}, but returns `undefined` instead of `None`.
+ *
+ * @since 0.1.0
+ * @category control
+ */
+export declare const optional: <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A | undefined, E, R, I>;
+/**
+ * Runs the parser only if `condition` holds, otherwise succeeds with
+ * `Option.none()` (winnow's and nom's `cond`).
+ *
+ * @since 0.1.0
+ * @category control
+ */
+export declare const cond: <A, E, R, I extends Input>(condition: boolean, self: Parser<A, E, R, I>) => Parser<Option.Option<A>, E, R, I>;
+/**
+ * Runs a parser without consuming input (winnow's and nom's `peek`).
+ *
+ * @since 0.1.0
+ * @category control
+ */
+export declare const peek: <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+/**
+ * Succeeds, without consuming input, only if the parser fails recoverably
+ * (winnow's and nom's `not`).
+ *
+ * @since 0.1.0
+ * @category control
+ */
+export declare const not: <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<void, E, R, I>;
+/**
+ * Requires the parser to consume the whole input (nom's `all_consuming`).
+ *
+ * @since 0.1.0
+ * @category control
+ */
+export declare const allConsuming: <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+/**
+ * Runs parsers in sequence, collecting their outputs in a tuple (winnow's
+ * and nom's tuple parsers, winnow's `seq!`).
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export declare const seq: <const Ps extends ReadonlyArray<Parser.Any>>(...parsers: Ps) => Parser<{ -readonly [K in keyof Ps]: Parser.Success<Ps[K]>; }, Parser.Error<Ps[number]>, Parser.Services<Ps[number]>, Parser.InputOf<Ps[number]>>;
+/**
+ * Runs a record of parsers in sequence (in key order), collecting their
+ * outputs in a record. This is the Effect counterpart to winnow's
+ * `seq!(Struct { .. })`.
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export declare const struct: <const Fields extends Readonly<Record<string, Parser.Any>>>(fields: Fields) => Parser<Simplify<{ -readonly [K in keyof Fields]: Parser.Success<Fields[K]>; }>, Parser.Error<Fields[keyof Fields]>, Parser.Services<Fields[keyof Fields]>, Parser.InputOf<Fields[keyof Fields]>>;
+/**
+ * Runs two parsers in sequence and returns both outputs.
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export declare const zip: {
+    <B, E2, R2, I2 extends Input>(that: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<[A, B], E | E2, R | R2, I & I2>;
+    <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, that: Parser<B, E2, R2, I2>): Parser<[A, B], E | E2, R | R2, I & I2>;
+};
+/**
+ * Runs two parsers in sequence and combines their outputs.
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export declare const zipWith: {
+    <B, E2, R2, I2 extends Input, A, C>(that: Parser<B, E2, R2, I2>, f: (a: A, b: B) => C): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<C, E | E2, R | R2, I & I2>;
+    <A, E, R, I extends Input, B, E2, R2, I2 extends Input, C>(self: Parser<A, E, R, I>, that: Parser<B, E2, R2, I2>, f: (a: A, b: B) => C): Parser<C, E | E2, R | R2, I & I2>;
+};
+/**
+ * Runs two parsers in sequence, keeping the output of the first.
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export declare const zipLeft: {
+    <B, E2, R2, I2 extends Input>(that: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E | E2, R | R2, I & I2>;
+    <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, that: Parser<B, E2, R2, I2>): Parser<A, E | E2, R | R2, I & I2>;
+};
+/**
+ * Runs two parsers in sequence, keeping the output of the second.
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export declare const zipRight: {
+    <B, E2, R2, I2 extends Input>(that: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R | R2, I & I2>;
+    <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, that: Parser<B, E2, R2, I2>): Parser<B, E | E2, R | R2, I & I2>;
+};
+/**
+ * Runs `prefix` then `parser`, keeping the output of `parser` (winnow's and
+ * nom's `preceded`).
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export declare const preceded: <A1, E1, R1, I1 extends Input, A2, E2, R2, I2 extends Input>(prefix: Parser<A1, E1, R1, I1>, parser: Parser<A2, E2, R2, I2>) => Parser<A2, E1 | E2, R1 | R2, I1 & I2>;
+/**
+ * Runs `parser` then `suffix`, keeping the output of `parser` (winnow's and
+ * nom's `terminated`).
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export declare const terminated: <A1, E1, R1, I1 extends Input, A2, E2, R2, I2 extends Input>(parser: Parser<A1, E1, R1, I1>, suffix: Parser<A2, E2, R2, I2>) => Parser<A1, E1 | E2, R1 | R2, I1 & I2>;
+/**
+ * Runs `open`, `parser` and `close`, keeping the output of `parser`
+ * (winnow's and nom's `delimited`).
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export declare const delimited: <A1, E1, R1, I1 extends Input, A2, E2, R2, I2 extends Input, A3, E3, R3, I3 extends Input>(open: Parser<A1, E1, R1, I1>, parser: Parser<A2, E2, R2, I2>, close: Parser<A3, E3, R3, I3>) => Parser<A2, E1 | E2 | E3, R1 | R2 | R3, I1 & I2 & I3>;
+/**
+ * Runs `first`, `separator` and `second`, keeping the outputs of `first` and
+ * `second` (winnow's and nom's `separated_pair`).
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export declare const separatedPair: <A1, E1, R1, I1 extends Input, A2, E2, R2, I2 extends Input, A3, E3, R3, I3 extends Input>(first: Parser<A1, E1, R1, I1>, separator: Parser<A2, E2, R2, I2>, second: Parser<A3, E3, R3, I3>) => Parser<[A1, A3], E1 | E2 | E3, R1 | R2 | R3, I1 & I2 & I3>;
+/**
+ * Writes a parser in imperative style with a generator, Effect style:
+ * `yield*` a parser to run it and get its output.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const keyValue = Parser.gen(function*() {
+ *   const key = yield* Ascii.alpha1
+ *   yield* Token.literal("=")
+ *   const value = yield* Ascii.decInt
+ *   return [key, value] as const
+ * })
+ * ```
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export declare const gen: <Eff extends Parser.Any, AEff>(f: () => Generator<Eff, AEff, never>) => Parser<AEff, Parser.Error<Eff>, Parser.Services<Eff>, Parser.InputOf<Eff>>;
+/**
+ * The starting point for Do notation.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const range = Parser.Do.pipe(
+ *   Parser.bind("start", () => Ascii.decUint),
+ *   Parser.zipLeft(Token.literal("..")),
+ *   Parser.bind("end", () => Ascii.decUint)
+ * )
+ * ```
+ *
+ * @since 0.1.0
+ * @category do notation
+ */
+export declare const Do: Parser<{}, never, never, Input>;
+/**
+ * Binds the output of a parser to a field of the Do record.
+ *
+ * @since 0.1.0
+ * @category do notation
+ */
+export declare const bind: {
+    <N extends string, A extends object, B, E2, R2, I2 extends Input>(name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => Parser<B, E2, R2, I2>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Simplify<Omit<A, N> & {
+        [K in N]: B;
+    }>, E | E2, R | R2, I & I2>;
+    <A extends object, E, R, I extends Input, N extends string, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => Parser<B, E2, R2, I2>): Parser<Simplify<Omit<A, N> & {
+        [K in N]: B;
+    }>, E | E2, R | R2, I & I2>;
+};
+/**
+ * Wraps the output of a parser in a record with a single field.
+ *
+ * @since 0.1.0
+ * @category do notation
+ */
+export declare const bindTo: {
+    <N extends string>(name: N): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<{
+        [K in N]: A;
+    }, E, R, I>;
+    <A, E, R, I extends Input, N extends string>(self: Parser<A, E, R, I>, name: N): Parser<{
+        [K in N]: A;
+    }, E, R, I>;
+};
+declare const let_: {
+    <N extends string, A extends object, B>(name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => B): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Simplify<Omit<A, N> & {
+        [K in N]: B;
+    }>, E, R, I>;
+    <A extends object, E, R, I extends Input, N extends string, B>(self: Parser<A, E, R, I>, name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => B): Parser<Simplify<Omit<A, N> & {
+        [K in N]: B;
+    }>, E, R, I>;
+};
+export { 
+/**
+ * Adds a computed field to the Do record.
+ *
+ * @since 0.1.0
+ * @category do notation
+ */
+let_ as let };
+/**
+ * Tries each parser in turn and returns the output of the first that
+ * succeeds (winnow's and nom's `alt`).
+ *
+ * Unrecoverable (`Cut`) and `Incomplete` failures stop the search
+ * immediately. If every alternative fails recoverably, the failures are
+ * merged: the one that got furthest wins, and failures at the same offset
+ * combine their expectations, e.g. `expected "true", "false" or "null"`.
+ *
+ * @since 0.1.0
+ * @category choice
+ */
+export declare const alt: <const Ps extends ReadonlyArray<Parser.Any>>(...parsers: Ps) => Parser<Parser.Success<Ps[number]>, Parser.Error<Ps[number]>, Parser.Services<Ps[number]>, Parser.InputOf<Ps[number]>>;
+/**
+ * Selects the parser to run next based on the output of `selector`, like a
+ * `match` over the input (winnow's `dispatch!`). If no case matches, the
+ * parser backtracks to where it started.
+ *
+ * Cases are given either as a record keyed by the selector's output (with
+ * an optional `otherwise` parser for unlisted keys, like winnow's `_ =>`
+ * arm), or as a function returning a parser (or `undefined` for no match).
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const escape = Parser.preceded(
+ *   Token.literal("\\"),
+ *   Parser.dispatch(Token.any, {
+ *     n: Parser.succeed("\n"),
+ *     t: Parser.succeed("\t"),
+ *     u: Parser.preceded(Token.literal("{"), Ascii.hexUint).pipe(
+ *       Parser.zipLeft(Token.literal("}")),
+ *       Parser.map((cp) => String.fromCodePoint(cp))
+ *     )
+ *   })
+ * )
+ * ```
+ *
+ * @since 0.1.0
+ * @category choice
+ */
+export declare const dispatch: {
+    <K, E, R, I extends Input, P extends Parser.Any>(selector: Parser<K, E, R, I>, cases: (key: K) => P | undefined): Parser<Parser.Success<P>, E | Parser.Error<P>, R | Parser.Services<P>, I & Parser.InputOf<P>>;
+    <K extends PropertyKey, E, R, I extends Input, const Cases extends {
+        readonly [key in K]?: Parser.Any;
+    }, Otherwise extends Parser.Any = never>(selector: Parser<K, E, R, I>, cases: Cases, otherwise?: Otherwise): Parser<Parser.Success<NonNullable<Cases[keyof Cases]> | Otherwise>, E | Parser.Error<NonNullable<Cases[keyof Cases]> | Otherwise>, R | Parser.Services<NonNullable<Cases[keyof Cases]> | Otherwise>, I & Parser.InputOf<NonNullable<Cases[keyof Cases]> | Otherwise>>;
+};
+/**
+ * Applies every parser exactly once, in whatever order they match, and
+ * returns their outputs in the order the parsers were given (winnow's and
+ * nom's `permutation`).
+ *
+ * @since 0.1.0
+ * @category choice
+ */
+export declare const permutation: <const Ps extends ReadonlyArray<Parser.Any>>(...parsers: Ps) => Parser<{ -readonly [K in keyof Ps]: Parser.Success<Ps[K]>; }, Parser.Error<Ps[number]>, Parser.Services<Ps[number]>, Parser.InputOf<Ps[number]>>;
+/**
+ * Applies a parser repeatedly, collecting the outputs in an array (winnow's
+ * `repeat`, nom's `many0`, `many1`, `many_m_n` and `count`).
+ *
+ * The range defaults to `{ min: 0 }` (zero or more). A number repeats
+ * exactly that many times. With a literal positive `min`, the output is
+ * typed as a non-empty array.
+ *
+ * As in winnow, an unbounded repetition of a parser that succeeds without
+ * consuming input fails with an unrecoverable assertion instead of looping
+ * forever.
+ *
+ * @example
+ * ```ts
+ * import { Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const abs = Parser.repeat(Token.literal("ab"), { min: 1 })
+ * Parser.parse(abs, "ababab") // Result.succeed(["ab", "ab", "ab"])
+ * ```
+ *
+ * @since 0.1.0
+ * @category repetition
+ */
+export declare const repeat: {
+    <const Rg extends Range = {
+        readonly min: 0;
+    }>(range?: Rg): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Repeated<A, Rg>, E, R, I>;
+    <A, E, R, I extends Input, const Rg extends Range = {
+        readonly min: 0;
+    }>(self: Parser<A, E, R, I>, range?: Rg): Parser<Repeated<A, Rg>, E, R, I>;
+};
+/**
+ * Applies a parser repeatedly, folding the outputs into an accumulator
+ * (winnow's `repeat(..).fold(..)`, nom's `fold_many0`/`fold_many1`/
+ * `fold_many_m_n`).
+ *
+ * @since 0.1.0
+ * @category repetition
+ */
+export declare const fold: {
+    <A, B>(options: {
+        readonly init: () => B;
+        readonly f: (acc: B, a: A) => B;
+        readonly range?: Range | undefined;
+    }): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
+    <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, options: {
+        readonly init: () => B;
+        readonly f: (acc: B, a: A) => B;
+        readonly range?: Range | undefined;
+    }): Parser<B, E, R, I>;
+};
+/**
+ * Applies `self` repeatedly until `end` succeeds, returning the collected
+ * outputs and the output of `end` (winnow's `repeat_till`, nom's
+ * `many_till`).
+ *
+ * @since 0.1.0
+ * @category repetition
+ */
+export declare const repeatTill: {
+    <B, E2, R2, I2 extends Input, const Rg extends Range = {
+        readonly min: 0;
+    }>(end: Parser<B, E2, R2, I2>, range?: Rg): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<[Repeated<A, Rg>, B], E | E2, R | R2, I & I2>;
+    <A, E, R, I extends Input, B, E2, R2, I2 extends Input, const Rg extends Range = {
+        readonly min: 0;
+    }>(self: Parser<A, E, R, I>, end: Parser<B, E2, R2, I2>, range?: Rg): Parser<[Repeated<A, Rg>, B], E | E2, R | R2, I & I2>;
+};
+export declare const separated: {
+    <S, E2, R2, I2 extends Input, const Rg extends Range = {
+        readonly min: 0;
+    }>(separator: Parser<S, E2, R2, I2>, range?: Rg): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Repeated<A, Rg>, E | E2, R | R2, I & I2>;
+    <A, E, R, I extends Input, S, E2, R2, I2 extends Input, const Rg extends Range = {
+        readonly min: 0;
+    }>(self: Parser<A, E, R, I>, separator: Parser<S, E2, R2, I2>, range?: Rg): Parser<Repeated<A, Rg>, E | E2, R | R2, I & I2>;
+};
+/**
+ * Parses one or more `self` separated by `separator`, folding them from the
+ * left with the separator's output: `((a op b) op c)` (winnow's
+ * `separated_foldl1`). This is the classic way to parse left-associative
+ * binary operators.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const sum = Parser.separatedFoldl1(
+ *   Ascii.decInt,
+ *   Parser.alt(Token.literal("+"), Token.literal("-")),
+ *   (l, op, r) => op === "+" ? l + r : l - r
+ * )
+ * Parser.parse(sum, "10-3+2") // Result.succeed(9)
+ * ```
+ *
+ * @since 0.1.0
+ * @category repetition
+ */
+export declare const separatedFoldl1: <A, E, R, I extends Input, S, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, separator: Parser<S, E2, R2, I2>, op: (left: A, separator: S, right: A) => A) => Parser<A, E | E2, R | R2, I & I2>;
+/**
+ * Parses one or more `self` separated by `separator`, folding them from the
+ * right with the separator's output: `(a op (b op c))` (winnow's
+ * `separated_foldr1`). Useful for right-associative operators such as
+ * exponentiation.
+ *
+ * @since 0.1.0
+ * @category repetition
+ */
+export declare const separatedFoldr1: <A, E, R, I extends Input, S, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, separator: Parser<S, E2, R2, I2>, op: (left: A, separator: S, right: A) => A) => Parser<A, E | E2, R | R2, I & I2>;
+/**
+ * Accesses a service from the parser's context. Services take the place of
+ * winnow's `Stateful` input: they can hold configuration, or mutable state
+ * such as an indentation stack or a symbol table.
+ *
+ * Services are provided with {@link provideService} / {@link provide}, with
+ * the `context` option of the runners, or taken from the surrounding Effect
+ * by {@link parseEffect}.
+ *
+ * Mutations made to a service's state are not undone on backtracking (as
+ * with winnow's `Stateful`).
+ *
+ * @example
+ * ```ts
+ * import { Context } from "effect"
+ * import { Ascii, Parser } from "@thomasfosterau/effect-parse"
+ *
+ * class Radix extends Context.Service<Radix, number>()("Radix") {}
+ *
+ * const number = Parser.service(Radix).pipe(
+ *   Parser.flatMap((radix) =>
+ *     Ascii.alphanumeric1.pipe(Parser.map((digits) => parseInt(digits, radix)))
+ *   )
+ * )
+ *
+ * Parser.parse(Parser.provideService(number, Radix, 16), "ff") // Result.succeed(255)
+ * ```
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export declare const service: <Id, S>(key: Context.Key<Id, S>) => Parser<S, never, Id, Input>;
+/**
+ * Provides a service to a parser.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export declare const provideService: {
+    <Id, S>(key: Context.Key<Id, S>, service: NoInfer<S>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, Exclude<R, Id>, I>;
+    <A, E, R, I extends Input, Id, S>(self: Parser<A, E, R, I>, key: Context.Key<Id, S>, service: NoInfer<S>): Parser<A, E, Exclude<R, Id>, I>;
+};
+/**
+ * Provides a context of services to a parser.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export declare const provide: {
+    <R2>(context: Context.Context<R2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, Exclude<R, R2>, I>;
+    <A, E, R, I extends Input, R2>(self: Parser<A, E, R, I>, context: Context.Context<R2>): Parser<A, E, Exclude<R, R2>, I>;
+};
+/**
+ * Error recovery: if the parser fails, record the failure, skip input with
+ * `recover`, and continue with `Option.none()` (winnow's `resume_after`).
+ *
+ * Recovery is only active when running with {@link parseRecoverable}. Under
+ * the other runners the parser behaves like `Parser.asSome(self)`.
+ *
+ * @since 0.1.0
+ * @category error recovery
+ */
+export declare const resumeAfter: {
+    <B, E2, R2, I2 extends Input>(recover: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Option.Option<A>, E | E2, R | R2, I & I2>;
+    <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, recover: Parser<B, E2, R2, I2>): Parser<Option.Option<A>, E | E2, R | R2, I & I2>;
+};
+/**
+ * Error recovery: if the parser fails, record the failure, skip input with
+ * `recover`, and try the parser again (winnow's `retry_after`).
+ *
+ * Recovery is only active when running with {@link parseRecoverable}. Under
+ * the other runners the parser behaves like `self`.
+ *
+ * @since 0.1.0
+ * @category error recovery
+ */
+export declare const retryAfter: {
+    <B, E2, R2, I2 extends Input>(recover: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E | E2, R | R2, I & I2>;
+    <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, recover: Parser<B, E2, R2, I2>): Parser<A, E | E2, R | R2, I & I2>;
+};
+/**
+ * Traces the execution of a parser (winnow's `trace`). When a tracer is
+ * installed (see the `trace` option of {@link parse}), `Enter` and `Exit`
+ * events are reported for each traced parser; otherwise tracing has no
+ * effect.
+ *
+ * @since 0.1.0
+ * @category debugging
+ */
+export declare const trace: {
+    (name: string): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, name: string): Parser<A, E, R, I>;
+};
+/**
+ * A tracer that writes an indented trace to `console.log`, similar to
+ * winnow's `debug` feature.
+ *
+ * @since 0.1.0
+ * @category debugging
+ */
+export declare const consoleTracer: (event: TraceEvent) => void;
+/**
+ * Options for {@link compile}.
+ *
+ * @since 0.1.0
+ * @category compilation
+ */
+export interface CompileOptions {
+    /**
+     * Which compiler to use:
+     *
+     * - `"auto"` (the default): generated code (a JIT) where `new Function`
+     *   is allowed, otherwise specialized closures
+     * - `"closure"`: specialized closures only. It never generates code, so
+     *   it is the choice under a Content Security Policy, where even probing
+     *   for `new Function` is reported as a violation.
+     */
+    readonly backend?: "auto" | "closure" | undefined;
+}
+/**
+ * Compiles a parser into fused, specialized code, and returns the same
+ * parser. Grammars are written as usual; compilation only makes
+ * {@link parse}, {@link parseSync}, {@link parsePeek} and
+ * {@link parseEffect} faster. Compile the root of a grammar once, where it
+ * is defined:
+ *
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * export const list = Parser.compile(
+ *   Parser.separated(Ascii.decInt, Token.literal(","))
+ * )
+ * Parser.parse(list, "1,2,3") // Result.succeed([1, 2, 3]), compiled
+ * ```
+ *
+ * The code is generated lazily on the first run, for each kind of input
+ * (string, bytes or array), and cached with the parser.
+ *
+ * **Results and errors are unchanged.** Compiled code records no
+ * diagnostics. When it fails, the parser runs again, interpreted, from the
+ * start, so every `ParseError` (offset, expected, context, cause and
+ * message) is exactly the one the interpreter reports.
+ *
+ * **Callbacks should be pure.** On an input that fails, the callbacks given
+ * to `map`, `filter`, `tryMap`, `tap`, `fold`, ... may run twice, once
+ * compiled and once interpreted. Callbacks whose results are discarded
+ * (a `map` inside `taken` or `preceded`, for example) may not run at all,
+ * nor those of a branch that is certain to fail, and token-set predicates
+ * may be called once per character code and cached.
+ *
+ * Runs on partial input ({@link parsePartial}, `ParserStream`), with
+ * {@link parseRecoverable} or with the `trace` option are always
+ * interpreted. Parsers that can't be described, such as {@link make} and
+ * {@link gen}, run interpreted inside compiled code.
+ *
+ * @since 0.1.0
+ * @category compilation
+ */
+export declare const compile: {
+    (options?: CompileOptions): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, options?: CompileOptions): Parser<A, E, R, I>;
+};
+/**
+ * Options accepted by the runners.
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export interface ParseOptions {
+    /**
+     * Install a tracer for {@link trace}d parsers: `true` uses
+     * {@link consoleTracer}.
+     */
+    readonly trace?: boolean | ((event: TraceEvent) => void) | undefined;
+}
+/**
+ * Options accepted by the runners for parsers that require services.
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export interface ParseOptionsWithContext<R> extends ParseOptions {
+    readonly context: Context.Context<R>;
+}
+/**
+ * Runs a parser against a complete input, requiring the whole input to be
+ * consumed (winnow's `Parser::parse`).
+ *
+ * @example
+ * ```ts
+ * import { Result } from "effect"
+ * import { Ascii, Parser } from "@thomasfosterau/effect-parse"
+ *
+ * Parser.parse(Ascii.decInt, "-42") // Result.succeed(-42)
+ * Result.isFailure(Parser.parse(Ascii.decInt, "42x")) // true
+ * ```
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export declare const parse: {
+    <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): Result.Result<A, ParseError.ParseError<E>>;
+    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): Result.Result<A, ParseError.ParseError<E>>;
+};
+/**
+ * Like {@link parse}, but throws the `ParseError` on failure.
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export declare const parseSync: {
+    <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): A;
+    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): A;
+};
+/**
+ * Runs a parser against the start of an input, returning the remaining
+ * input along with the output, nom-style (winnow's `parse_peek`, nom's
+ * `IResult`).
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export declare const parsePeek: {
+    <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): Result.Result<[remaining: Slice<I>, output: A], ParseError.ParseError<E>>;
+    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): Result.Result<[remaining: Slice<I>, output: A], ParseError.ParseError<E>>;
+};
+/**
+ * The outcome of parsing a partial (streaming) input.
+ *
+ * - `Done`: the parser succeeded, consuming input up to `offset`.
+ * - `Incomplete`: more input is needed (`needed` tokens, if known).
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export type PartialResult<A> = {
+    readonly _tag: "Done";
+    readonly value: A;
+    readonly offset: number;
+} | {
+    readonly _tag: "Incomplete";
+    readonly needed: Option.Option<number>;
+};
+/**
+ * Runs a parser against a *partial* input, i.e. a chunk of a stream that may
+ * be followed by more data (winnow's `Partial`, nom's `streaming` parsers).
+ * Token parsers that reach the end of the chunk report `Incomplete` instead
+ * of failing or succeeding early.
+ *
+ * The parser does not have to consume the whole input; the returned
+ * `offset` says how much was consumed.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser } from "@thomasfosterau/effect-parse"
+ *
+ * Parser.parsePartial(Ascii.digit1, "123")
+ * // Result.succeed({ _tag: "Incomplete", needed: Option.some(1) })
+ * Parser.parsePartial(Ascii.digit1, "123;")
+ * // Result.succeed({ _tag: "Done", value: "123", offset: 3 })
+ * ```
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export declare const parsePartial: {
+    <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): Result.Result<PartialResult<A>, ParseError.ParseError<E>>;
+    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): Result.Result<PartialResult<A>, ParseError.ParseError<E>>;
+};
+/**
+ * Runs a parser against a complete input as an `Effect`. Services required
+ * by the parser are taken from the Effect's context.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Ascii, Parser } from "@thomasfosterau/effect-parse"
+ *
+ * const program = Effect.gen(function*() {
+ *   const n = yield* Parser.parseEffect(Ascii.decInt, "42")
+ *   return n + 1
+ * })
+ * ```
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export declare const parseEffect: <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options?: ParseOptions) => Effect.Effect<A, ParseError.ParseError<E>, R>;
+/**
+ * The outcome of {@link parseRecoverable}.
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export interface RecoverableResult<A, E> {
+    /** The output, if parsing ultimately succeeded. */
+    readonly value: Option.Option<A>;
+    /** Every error encountered: recovered ones, then the fatal one (if any). */
+    readonly errors: ReadonlyArray<ParseError.ParseError<E>>;
+}
+/**
+ * Runs a parser with error recovery enabled (winnow's `Recoverable`
+ * stream). Failures handled by {@link resumeAfter} and {@link retryAfter}
+ * are collected instead of aborting the parse.
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export declare const parseRecoverable: {
+    <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): RecoverableResult<A, E>;
+    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): RecoverableResult<A, E>;
+};
+/**
+ * Records a failure kind for use in custom parsers; re-exported for
+ * convenience.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type { ErrorKind };
+//# sourceMappingURL=Parser.d.ts.map