@thomasfosterau/effect-parse 0.1.0 → 0.2.0

package/dist/Syntax.d.ts

@@ -0,0 +1,401 @@
+import { Input, Slice, Source } from "./Input.js";
+import { Parser } from "./Parser.js";
+import * as Option from "effect/Option";
+import * as Context from "effect/Context";
+import * as ParseError from "./ParseError.js";
+import { ErrorInfo, Green } from "./internal/syntax.js";
+//#region src/Syntax.d.ts
+/**
+ * Marks a parser as a rule of the syntax tree: in a {@link parse}, each
+ * match becomes a named node of the given kind, spanning the input it
+ * consumed, with the nodes built inside it as children and its output as
+ * its `value`. Outside {@link parse}, the parser is unchanged.
+ *
+ * A match that consumes nothing adds no node (as in Tree-sitter, where rules
+ * can't match the empty string).
+ *
+ * For {@link reparse} to reuse a node, its parser's output must depend only
+ * on the input from where the node starts: not on services, on state kept
+ * in closures, or on absolute offsets (`Parser.location`, `Parser.span`),
+ * which are not updated when the node moves. Use the node's `start` and
+ * `end` instead.
+ *
+ * @since 0.2.0
+ * @category annotations
+ */
+export declare const node: {
+  (kind: 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>, kind: string): Parser<A, E, R, I>;
+};
+/**
+ * Like {@link node}, but builds an *anonymous* node, Tree-sitter's name for
+ * punctuation and keywords: anonymous nodes are left out of
+ * `namedChildren` and of the tree's printed form. The kind defaults to the
+ * literal for a `Token.literal` of a string, and to the parser's name
+ * otherwise.
+ *
+ * @example
+ * ```ts
+ * import { Syntax, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const comma = Syntax.token(Token.literal(",")) // kind ","
+ * ```
+ *
+ * @since 0.2.0
+ * @category annotations
+ */
+export declare const token: {
+  (kind?: 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>, kind?: string): Parser<A, E, R, I>;
+};
+/**
+ * Gives the nodes built by a parser a field name in their parent, like
+ * Tree-sitter's `field(name, rule)`: find them with `childByField` and
+ * `childrenByField`. Outside {@link parse}, the parser is unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Syntax, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const name = Syntax.node(Ascii.alpha1, "name")
+ * const number = Syntax.node(Ascii.decInt, "number")
+ * const pair = Syntax.node(
+ *   Parser.separatedPair(Syntax.field(name, "key"), Token.literal("="), Syntax.field(number, "value")),
+ *   "pair"
+ * )
+ * Syntax.parse(pair, "x=1").root.childByField("value")?.value // 1
+ * ```
+ *
+ * @since 0.2.0
+ * @category annotations
+ */
+export declare const field: {
+  (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>;
+};
+/**
+ * The kind of the nodes that stand for input that could not be parsed.
+ *
+ * @since 0.2.0
+ * @category models
+ */
+export declare const ERROR: "ERROR";
+/**
+ * An edit to an input, as Tree-sitter's `TSInputEdit`: the input
+ * `[start, oldEnd)` was replaced by `[start, newEnd)`. Offsets are in the
+ * input's units (UTF-16 code units for strings, bytes, elements).
+ *
+ * @since 0.2.0
+ * @category models
+ */
+export interface Edit {
+  readonly start: number;
+  readonly oldEnd: number;
+  readonly newEnd: number;
+}
+/**
+ * Options for {@link parse}.
+ *
+ * @since 0.2.0
+ * @category models
+ */
+export interface ParseOptions {
+  /**
+   * The kind of the root node, when the grammar itself is not a
+   * {@link node}. Defaults to `"document"`.
+   */
+  readonly kind?: string | undefined;
+  /**
+   * For {@link reparse}: how many input units custom parsers may read past
+   * the furthest position they move the cursor to or record a failure at,
+   * besides one token there. Defaults to 0, which is right for the built-in
+   * parsers, and for custom parsers (`Parser.make`) that only read past
+   * where they stop to see that the token there doesn't match.
+   *
+   * A node is reused only when the input its parse looked at is unchanged.
+   * Built-in parsers that read further, such as a literal that fails part
+   * way or `Token.takeUntil`, record how far they read.
+   */
+  readonly lookahead?: number | undefined;
+}
+/**
+ * Options for {@link parse} with a parser that requires services.
+ *
+ * @since 0.2.0
+ * @category models
+ */
+export interface ParseOptionsWithContext<R> extends ParseOptions {
+  readonly context: Context.Context<R>;
+}
+interface Config {
+  readonly kind: string;
+  readonly inner: Parser.Any;
+  readonly lookahead: number;
+  readonly context: Context.Context<never> | undefined;
+}
+/**
+ * The result of a {@link parse}: a syntax tree over the whole input, the
+ * grammar's output, and the errors met on the way.
+ *
+ * @since 0.2.0
+ * @category models
+ */
+export declare class Tree<out A, out E = never, I extends Input = string> {
+  /** The input the tree was parsed from. */
+  readonly input: I;
+  /** The grammar's output: `none` when the parse failed. */
+  readonly value: Option.Option<A>;
+  /** How many nodes were reused from the previous tree by {@link reparse}. */
+  readonly reused: number;
+  /** @internal */
+  readonly green: Green;
+  /** @internal */
+  readonly config: Config;
+  /** @internal */
+  readonly encoding: ParseError.ParseError<never>["encoding"];
+  /** The root node. It always spans the whole input. */
+  readonly root: SyntaxNode<I>;
+  private lines;
+  private errorList;
+  /** @internal */
+  constructor(
+  /** The input the tree was parsed from. */
+  input: I,
+  /** The grammar's output: `none` when the parse failed. */
+  value: Option.Option<A>,
+  /** How many nodes were reused from the previous tree by {@link reparse}. */
+  reused: number,
+  /** @internal */
+  green: Green,
+  /** @internal */
+  config: Config,
+  /** @internal */
+  encoding: ParseError.ParseError<never>["encoding"]);
+  /**
+   * Every error of the parse, in input order: the failures recovered by
+   * `Parser.resumeAfter` and `Parser.retryAfter`, then the fatal one, if
+   * the parse failed. Each one belongs to an `ERROR` node.
+   */
+  get errors(): ReadonlyArray<ParseError.ParseError<E>>;
+  /** Whether the tree has any `ERROR` node. */
+  get hasErrors(): boolean;
+  /** The smallest node containing `[start, end)` (see {@link SyntaxNode.descendantAt}). */
+  descendantAt(start: number, end?: number): SyntaxNode<I>;
+  /** A cursor at the root. */
+  walk(): TreeCursor<I>;
+  /**
+   * The 1-based line and column (in code points) of an offset, as in
+   * `ParseError`. Lines of a string input are indexed once, so lookups take
+   * logarithmic time.
+   */
+  lineColumn(offset: number): ParseError.LineColumn;
+  /** The root's S-expression (see {@link SyntaxNode.toString}). */
+  toString(): string;
+  /** @internal */
+  toError(error: ErrorInfo, start: number): ParseError.ParseError<E>;
+}
+/**
+ * A node of a syntax tree: its kind, span and value, and its place in the
+ * tree. Nodes are views built on demand; two views of the same node are
+ * different objects but have the same `start`, `end` and `kind`.
+ *
+ * @since 0.2.0
+ * @category models
+ */
+export declare class SyntaxNode<I extends Input = string> {
+  /** The tree this node belongs to. */
+  readonly tree: Tree<unknown, unknown, I>;
+  /** @internal */
+  readonly green: Green;
+  /** The offset where the node starts. */
+  readonly start: number;
+  /** The parent node; `undefined` for the root. */
+  readonly parent: SyntaxNode<I> | undefined;
+  /** The node's index among its parent's children. */
+  readonly index: number;
+  private childList;
+  /** @internal */
+  constructor(
+  /** The tree this node belongs to. */
+  tree: Tree<unknown, unknown, I>,
+  /** @internal */
+  green: Green,
+  /** The offset where the node starts. */
+  start: number,
+  /** The parent node; `undefined` for the root. */
+  parent: SyntaxNode<I> | undefined,
+  /** The node's index among its parent's children. */
+  index: number);
+  /** The node's kind: the name given to {@link node} or {@link token}, or `"ERROR"`. */
+  get kind(): string;
+  /** `false` for the anonymous nodes built by {@link token}. */
+  get named(): boolean;
+  /** The field name given by {@link field}, if any. */
+  get field(): string | undefined;
+  /** The offset where the node ends (exclusive). */
+  get end(): number;
+  /** The number of input units the node spans. */
+  get length(): number;
+  /** The output of the node's parser (`undefined` for `ERROR` nodes, and for a root that failed). */
+  get value(): unknown;
+  /** The input the node spans. */
+  get text(): Slice<I>;
+  /** Whether this is an `ERROR` node. */
+  get isError(): boolean;
+  /** Whether this node or a descendant is an `ERROR` node. */
+  get hasError(): boolean;
+  /** For an `ERROR` node, the error it stands for. */
+  get error(): ParseError.ParseError<unknown> | undefined;
+  /** The child nodes, named and anonymous, in input order. */
+  get children(): ReadonlyArray<SyntaxNode<I>>;
+  /** The number of children. */
+  get childCount(): number;
+  /** The child at `index` (negative indices count from the end). */
+  child(index: number): SyntaxNode<I> | undefined;
+  /** The named children. */
+  get namedChildren(): ReadonlyArray<SyntaxNode<I>>;
+  /** The named child at `index`. */
+  namedChild(index: number): SyntaxNode<I> | undefined;
+  /** The first child with the given field name. */
+  childByField(name: string): SyntaxNode<I> | undefined;
+  /** The children with the given field name. */
+  childrenByField(name: string): ReadonlyArray<SyntaxNode<I>>;
+  /** The next sibling, named or anonymous. */
+  get nextSibling(): SyntaxNode<I> | undefined;
+  /** The previous sibling, named or anonymous. */
+  get previousSibling(): SyntaxNode<I> | undefined;
+  /** The next named sibling. */
+  get nextNamedSibling(): SyntaxNode<I> | undefined;
+  /** The previous named sibling. */
+  get previousNamedSibling(): SyntaxNode<I> | undefined;
+  /**
+   * The index of the child containing the input unit at `offset`, or -1.
+   * Takes logarithmic time.
+   */
+  childIndexAt(offset: number): number;
+  /** The child containing the input unit at `offset`. */
+  childAt(offset: number): SyntaxNode<I> | undefined;
+  /**
+   * The smallest node, this one or a descendant, that contains
+   * `[start, end)` (Tree-sitter's `descendant_for_byte_range`). With only
+   * `start`, the deepest node containing the input unit at `start`. Takes
+   * time proportional to the depth of the tree times the logarithm of the
+   * number of children.
+   */
+  descendantAt(start: number, end?: number): SyntaxNode<I>;
+  /** Like {@link descendantAt}, but only stops at named nodes. */
+  namedDescendantAt(start: number, end?: number): SyntaxNode<I>;
+  /** This node and its descendants, in pre-order. */
+  descendants(): Generator<SyntaxNode<I>, void, undefined>;
+  /** The descendants of the given kind, in pre-order. */
+  descendantsOfKind(kind: string): Generator<SyntaxNode<I>, void, undefined>;
+  /** A cursor at this node, which cannot move above it. */
+  walk(): TreeCursor<I>;
+  /**
+   * The node as an S-expression of its named descendants, with field
+   * names, as Tree-sitter prints it: `(pair key: (name) value: (number))`.
+   */
+  toString(): string;
+  toJSON(): unknown;
+  private makeChild;
+}
+/**
+ * A cursor for walking a tree, as Tree-sitter's `TreeCursor`. It starts at
+ * a node and cannot move above it.
+ *
+ * @since 0.2.0
+ * @category models
+ */
+export declare class TreeCursor<I extends Input = string> {
+  private current;
+  private depth;
+  /** @internal */
+  constructor(node: SyntaxNode<I>);
+  /** The node at the cursor. */
+  get node(): SyntaxNode<I>;
+  /** The field name of the node at the cursor, if any. */
+  get field(): string | undefined;
+  /** Moves to the first child; `false` if there is none. */
+  gotoFirstChild(): boolean;
+  /** Moves to the last child; `false` if there is none. */
+  gotoLastChild(): boolean;
+  /** Moves to the child containing the input unit at `offset`; `false` if there is none. */
+  gotoFirstChildForOffset(offset: number): boolean;
+  /** Moves to the next sibling; `false` if there is none. */
+  gotoNextSibling(): boolean;
+  /** Moves to the previous sibling; `false` if there is none. */
+  gotoPreviousSibling(): boolean;
+  /** Moves to the parent; `false` at the node the cursor started at. */
+  gotoParent(): boolean;
+  /** Moves to the deepest node containing the input unit at `offset`. */
+  gotoDescendantAt(offset: number): void;
+  /** Starts again at `node`. */
+  reset(node: SyntaxNode<I>): void;
+  private goto;
+}
+/**
+ * Parses an input into a syntax {@link Tree}. The grammar's output is the
+ * tree's `value`, and its {@link node}s are the tree's nodes. When the
+ * grammar is itself a {@link node}, that node is the root; otherwise the
+ * root is a node of kind `options.kind` (by default `"document"`).
+ *
+ * The parse never fails: recovered failures (see `Parser.resumeAfter`), a
+ * fatal failure and unparsed input at the end all become `ERROR` nodes, and
+ * are listed in `tree.errors`. The parse is interpreted, never compiled.
+ *
+ * @since 0.2.0
+ * @category parsing
+ */
+export declare const parse: {
+  <A, E, I extends Input>(grammar: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): Tree<A, E, I>;
+  <A, E, R, I extends Input>(grammar: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): Tree<A, E, I>;
+};
+/**
+ * Parses the new version of a tree's input, reusing the nodes of the tree
+ * that the edits leave unchanged (Tree-sitter's `ts_tree_edit` followed by
+ * `ts_parser_parse` with the old tree). The result is the tree a fresh
+ * {@link parse} of `input` would build, but only the parts of the tree
+ * around the edits are parsed again. `tree.reused` says how many nodes were
+ * reused.
+ *
+ * `edits` describe how the old input became the new one, applied in order,
+ * each in the coordinates of the input as the previous edits left it. When
+ * they are omitted, the edit is found by comparing the inputs (their common
+ * prefix and suffix), which takes time linear in their length but much less
+ * than parsing.
+ *
+ * Errors in the new tree are those a fresh parse reports, except that an
+ * error just after a reused node may list fewer expected alternatives.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Syntax } from "@thomasfosterau/effect-parse"
+ *
+ * const number = Syntax.node(Ascii.decInt, "number")
+ * const tree = Syntax.parse(number, "12")
+ * Syntax.reparse(tree, "123", [{ start: 2, oldEnd: 2, newEnd: 3 }]).root.value // 123
+ * ```
+ *
+ * @since 0.2.0
+ * @category parsing
+ */
+export declare const reparse: <A, E, I extends Input>(tree: Tree<A, E, I>, input: NoInfer<Source<I>>, edits?: Edit | ReadonlyArray<Edit>) => Tree<A, E, I>;
+/**
+ * Replaces `[start, end)` of a tree's string input with `text` and parses
+ * the result incrementally (see {@link reparse}).
+ *
+ * @since 0.2.0
+ * @category parsing
+ */
+export declare const replace: <A, E>(tree: Tree<A, E, string>, start: number, end: number, text: string) => Tree<A, E, string>;
+/**
+ * Finds the edit that turns `before` into `after`: the part between their
+ * longest common prefix and suffix. `undefined` when they are equal.
+ *
+ * @since 0.2.0
+ * @category parsing
+ */
+export declare const diff: <I extends Input>(before: I, after: I) => Edit | undefined;
+//#endregion
+export {};
+//# sourceMappingURL=Syntax.d.ts.map

package/dist/Syntax.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Syntax.d.ts","names":[],"sources":["../src/Syntax.ts"],"mappings":"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"}