@thomasfosterau/effect-parse 0.4.1 → 0.6.0

package/src/Syntax.ts

@@ -66,11 +66,15 @@ import { described, isParser } from "./Parser.js"
 // Grammar annotations
 // -----------------------------------------------------------------------------
 
-const syntaxNode = (self: Parser.Any, kind: string, named: boolean): Parser.Any => {
+const syntaxNode = <A, E, R, I extends Input>(
+  self: Parser<A, E, R, I>,
+  kind: string,
+  named: boolean
+): Parser<A, E, R, I> => {
   const step = self.step
   // Identifies the nodes this parser builds, so a reparse can reuse them
   const key = new Key()
-  return described<unknown, unknown, unknown, Input>(
+  return described<A, E, R, I>(
     (state) => {
       const builder = state.syntax
       return builder === undefined ? step(state) : builder.node(state, step, key, kind, named)
@@ -101,10 +105,8 @@ const syntaxNode = (self: Parser.Any, kind: string, named: boolean): Parser.Any
 export 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>
-} = /*#__PURE__*/ dual(
-  2,
-  <A, E, R, I extends Input>(self: Parser<A, E, R, I>, kind: string): Parser<A, E, R, I> =>
-    syntaxNode(self, kind, true) as Parser<A, E, R, I>
+} = /*#__PURE__*/ dual(2, <A, E, R, I extends Input>(self: Parser<A, E, R, I>, kind: string): Parser<A, E, R, I> =>
+  syntaxNode(self, kind, true)
 )
 
 /**
@@ -130,7 +132,7 @@ export const token: {
 } = /*#__PURE__*/ dual(
   (args) => isParser(args[0]),
   <A, E, R, I extends Input>(self: Parser<A, E, R, I>, kind?: string): Parser<A, E, R, I> =>
-    syntaxNode(self, kind ?? defaultTokenKind(self), false) as Parser<A, E, R, I>
+    syntaxNode(self, kind ?? defaultTokenKind(self), false)
 )
 
 const defaultTokenKind = (self: Parser.Any): string => {
@@ -168,7 +170,7 @@ export const field: {
   return described<A, E, R, I>(
     (state) => {
       const builder = state.syntax
-      return (builder === undefined ? step(state) : builder.field(state, step, name)) as A | typeof Fail
+      return builder === undefined ? step(state) : builder.field(state, step, name)
     },
     self.name,
     { _tag: "Syntax", self, kind: undefined, named: false }
@@ -346,6 +348,18 @@ export class Tree<out A, out E = never, I extends Input = string> {
   }
 }
 
+/**
+ * What `JSON.stringify` writes for a {@link SyntaxNode}: its kind and span.
+ *
+ * @since 0.5.0
+ * @category models
+ */
+export interface SyntaxNodeJson {
+  readonly kind: string
+  readonly start: number
+  readonly end: number
+}
+
 /**
  * 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
@@ -403,10 +417,11 @@ export class SyntaxNode<I extends Input = string> {
 
   /** The input the node spans. */
   get text(): Slice<I> {
-    const input = this.tree.input as any
-    return input instanceof Uint8Array
-      ? (input.subarray(this.start, this.end) as any)
-      : input.slice(this.start, this.end)
+    const input: Input = this.tree.input
+    // SAFETY: a `subarray` of a `Uint8Array`, or a `slice` of a string or array, has the input's own kind, `Slice<I>`
+    return (
+      input instanceof Uint8Array ? input.subarray(this.start, this.end) : input.slice(this.start, this.end)
+    ) as Slice<I>
   }
 
   /** Whether this is an `ERROR` node. */
@@ -592,7 +607,7 @@ export class SyntaxNode<I extends Input = string> {
     return out
   }
 
-  toJSON(): unknown {
+  toJSON(): SyntaxNodeJson {
     return { kind: this.kind, start: this.start, end: this.end }
   }
 
@@ -723,6 +738,8 @@ const run = <A, E, I extends Input>(config: Config, input: I, previous: Previous
     state.backtrack("Eof", expectedEof)
     fatal = { failure: state.reportedFailure(), mode: "Backtrack" }
   } else {
+    // SAFETY: `config.inner` is the `Parser<A, ...>` given to `parse` or the parser its root `node` wraps, which returns
+    // the same `A` (a `reparse` reuses the tree's config)
     value = Option.some(a as A)
   }
   const green = builder.finish(config.kind, Option.getOrUndefined(value), fatal, state.pos)
@@ -730,19 +747,12 @@ const run = <A, E, I extends Input>(config: Config, input: I, previous: Previous
 }
 
 /**
- * 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.
+ * The overloads of {@link parse}.
  *
- * @since 0.2.0
+ * @since 0.5.0
  * @category parsing
  */
-export const parse: {
+export interface ParseFn {
   <A, E, I extends Input>(
     grammar: Parser<A, E, never, I>,
     input: NoInfer<Source<I>>,
@@ -753,7 +763,22 @@ export const parse: {
     input: NoInfer<Source<I>>,
     options: ParseOptionsWithContext<R>
   ): Tree<A, E, I>
-} = <A, E, R, I extends Input>(
+}
+
+/**
+ * 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 const parse: ParseFn = <A, E, R, I extends Input>(
   grammar: Parser<A, E, R, I>,
   input: I | Source<I>,
   options?: ParseOptions & { readonly context?: Context.Context<R> }
@@ -762,11 +787,12 @@ export const parse: {
   const isRoot = Predicate.isTagged(n, "Syntax") && n.kind !== undefined && n.named
   const config: Config = {
     kind: isRoot ? n.kind : (options?.kind ?? "document"),
+    // SAFETY: a `Syntax` node's `self` is the parser that `node` wrapped, a parser built by this library
     inner: isRoot ? (n.self as Parser.Any) : grammar,
     lookahead: options?.lookahead ?? 0,
-    context: options?.context as Context.Context<never> | undefined
+    context: options?.context
   }
-  return run(config, fromSource(input as Input) as I, undefined)
+  return run(config, fromSource<I>(input), undefined)
 }
 
 /**
@@ -803,13 +829,8 @@ export const reparse = <A, E, I extends Input>(
   input: NoInfer<Source<I>>,
   edits?: Edit | ReadonlyArray<Edit>
 ): Tree<A, E, I> => {
-  const next = fromSource(input as Input) as I
-  const list =
-    edits === undefined
-      ? diffList(tree.input, next)
-      : "start" in edits
-        ? [edits as Edit]
-        : (edits as ReadonlyArray<Edit>)
+  const next = fromSource<I>(input)
+  const list = edits === undefined ? diffList(tree.input, next) : "start" in edits ? [edits] : edits
   const previous: Previous = {
     root: tree.green,
     oldLength: tree.input.length,
@@ -854,9 +875,12 @@ export const replace = <A, E>(
  * @category parsing
  */
 export const diff = <I extends Input>(before: I, after: I): Edit | undefined => {
-  const a = before as any
-  const b = after as any
-  const at = Predicate.isString(a) ? (s: string, i: number) => s.charCodeAt(i) : (s: any, i: number) => s[i]
+  const a: Input = before
+  const b: Input = after
+  // SAFETY: the string reader is chosen only when `a` is a string, and `b` has the same type `I`
+  const at = Predicate.isString(a)
+    ? (s: Input, i: number) => (s as string).charCodeAt(i)
+    : (s: Input, i: number) => s[i]
   const max = Math.min(a.length, b.length)
   let prefix = 0
   while (prefix < max && at(a, prefix) === at(b, prefix)) prefix++

package/src/Text.ts

@@ -39,13 +39,14 @@
 import * as Predicate from "effect/Predicate"
 import type { Encoding } from "./Encoding.js"
 import * as Encodings from "./Encoding.js"
-import type { Input, State } from "./Input.js"
+import type { State } from "./Input.js"
 import { Fail } from "./Input.js"
 import { escapedImpl, overflow, takeEscapedImpl, toFloat } from "./Ascii.js"
 import { codePointPredicate, compile, indexOf, matchLiteral } from "./internal/tokens.js"
 import { floatText as markFloatText } from "./internal/numbers.js"
 import * as internal from "./internal/text.js"
 import type { Node } from "./internal/node.js"
+import { bounds, checkCount, controlCode } from "./internal/node.js"
 import type { ErrorKind } from "./ParseError.js"
 import type { Parser, Range } from "./Parser.js"
 import * as P from "./Parser.js"
@@ -354,9 +355,8 @@ export interface TextParsers<I extends string | Uint8Array> {
 }
 
 const normalize = (r: Range | undefined): [number, number] => {
-  if (r === undefined) return [0, Infinity]
-  if (Predicate.isNumber(r)) return [r, r]
-  return [r.min ?? 0, r.max ?? Infinity]
+  const { max, min } = bounds(r)
+  return [min, max]
 }
 
 const isAsciiDigit = /*#__PURE__*/ codePointPredicate("isAsciiDigit", (c: number): boolean => c >= 48 && c <= 57, [
@@ -392,7 +392,7 @@ const expectedIdentifier = ["identifier"]
  * @category constructors
  */
 export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): TextParsers<I> => {
-  const enc = encoding as Encoding<any>
+  const enc = encoding
   const fast = internal.fastLimit(enc)
 
   // Each parser records its encoding on byte input (`state.encoding`), so
@@ -410,7 +410,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
   ): string | Fail => {
     const count = internal.validate(enc, state, start, end)
     if (count < 0) return backtrack(state, kind, expected, -1 - count)
-    return enc.text(state.input, start, end)
+    return internal.textIn(enc, state, start, end)
   }
 
   const takeWhileText = (
@@ -438,7 +438,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
         // More matching characters would have been accepted where we stopped
         if (hint && count < max) state.setHint(offset, expected)
         state.pos = offset
-        return enc.text(state.input, start, offset)
+        return internal.textIn(enc, state, start, offset)
       },
       name,
       { _tag: "TakeWhile", set, negate, min, max, encoding: enc }
@@ -471,6 +471,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
           if (state.inputKind === 1) state.encoding = enc
           if (pos >= state.end) return state.eoi("Literal", expected, 1)
           const input = state.input
+          // SAFETY: a `Text` parser runs on strings or `Uint8Array`s, and `inputKind` 0 is set only for a string
           if ((state.inputKind === 0 ? (input as string).charCodeAt(pos) : (input as Uint8Array)[pos]) !== unit) {
             return backtrack(state, "Literal", expected)
           }
@@ -518,7 +519,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
           pos += internal.width
         }
         state.pos = pos
-        return enc.text(state.input, start, pos)
+        return internal.textIn(enc, state, start, pos)
       },
       expected[0],
       { _tag: "Literal", literal: lit, caseless: true, encoding: enc }
@@ -546,6 +547,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
   }
 
   const take = (count: number): Parser<string, never, never, I> => {
+    checkCount(count)
     const expected = [count === 1 ? "1 character" : `${count} characters`]
     return P.described<string, never, never, I>(
       (state: State<any>) => {
@@ -559,7 +561,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
           pos += internal.width
         }
         state.pos = pos
-        return enc.text(state.input, start, pos)
+        return internal.textIn(enc, state, start, pos)
       },
       "take",
       { _tag: "Take", count, encoding: enc }
@@ -575,9 +577,9 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
       (state: State<any>) => {
         if (state.inputKind === 1) state.encoding = enc
         const start = state.pos
-        let idx = indexOf(state, needle as Input, start)
+        let idx = indexOf(state, needle, start)
         // Multi-unit encodings: only accept matches on a character boundary
-        while (unit > 1 && idx >= 0 && (idx - start) % unit !== 0) idx = indexOf(state, needle as Input, idx + 1)
+        while (unit > 1 && idx >= 0 && (idx - start) % unit !== 0) idx = indexOf(state, needle, idx + 1)
         if (idx < 0) {
           if (state.partial) return state.incomplete(0, expected)
           return backtrack(state, "TakeUntil", expected, state.end)
@@ -590,7 +592,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
         if (count < min) return backtrack(state, "TakeUntil", expected, idx)
         if (count > max) return backtrack(state, "TakeUntil", expected)
         state.pos = idx
-        return enc.text(state.input, start, idx)
+        return internal.textIn(enc, state, start, idx)
       },
       "takeUntil",
       { _tag: "TakeUntil", literal: lit, min, max, encoding: enc }
@@ -607,7 +609,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
       if (internal.scanStop === internal.Truncated) return state.incomplete(1, expectedAny)
       if (internal.scanStop === internal.Invalid) return backtrack(state, "Token", expectedAny, offset)
       state.pos = offset
-      return enc.text(state.input, start, offset)
+      return internal.textIn(enc, state, start, offset)
     },
     "rest",
     { _tag: "Rest", encoding: enc }
@@ -628,7 +630,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
   }
 
   const cls = (test: CharPredicate, min: 0 | 1, description: string, kind: ErrorKind, hint = true) =>
-    takeWhileText(test as any, { min }, false, `${kind.toLowerCase()}${min}`, [description], kind, hint)
+    takeWhileText(test, { min }, false, `${kind.toLowerCase()}${min}`, [description], kind, hint)
 
   const identifierStart = (cp: number) => cp === 95 || isIdStart(cp)
   const identifier: Parser<string, never, never, I> = P.described<string, never, never, I>(
@@ -638,13 +640,13 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
       const cp = internal.next(enc, state)
       if (cp < 0) return internal.failAt(state, cp, "TakeWhile", expectedIdentifier)
       if (!identifierStart(cp)) return state.backtrack("TakeWhile", expectedIdentifier)
-      internal.scan(enc, state, isIdContinue as any, false, Infinity, start + internal.width, fast)
+      internal.scan(enc, state, isIdContinue, false, Infinity, start + internal.width, fast)
       const stop = internal.scanStop
       if (state.partial && (stop === internal.End || stop === internal.Truncated)) {
         return state.incomplete(1, expectedIdentifier)
       }
       state.pos = internal.scanOffset
-      return enc.text(state.input, start, state.pos)
+      return internal.textIn(enc, state, start, state.pos)
     },
     "identifier",
     { _tag: "Identifier", encoding: enc }
@@ -691,7 +693,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
         if (after !== 10) return backtrack(state, "LineEnding", expectedLineEnding, offset)
       }
       state.pos = offset
-      return enc.text(state.input, start, offset)
+      return internal.textIn(enc, state, start, offset)
     },
     "tillLineEnding",
     { _tag: "TillLineEnding", encoding: enc }
@@ -718,8 +720,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
   )
   const floatText = markFloatText(taken(P.alt(caseless("nan"), P.seq(sign, unsignedFloat))).pipe(P.expected("number")))
 
-  const matchControl = (control: string) => {
-    const ctrl = control.codePointAt(0)
+  const matchControl = (ctrl: number) => {
     return (state: State<any>): boolean => {
       if (internal.next(enc, state) !== ctrl) return false
       state.pos += internal.width
@@ -778,17 +779,21 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
       P.named("hexUint")
     ),
     float: floatText.pipe(P.map(toFloat), P.named("float")),
-    takeEscaped: (normal, control, escapable) =>
-      takeEscapedImpl(
+    takeEscaped: (normal, control, escapable) => {
+      const ctrl = controlCode(control, internal.firstCodePoint)
+      return takeEscapedImpl(
         normal,
-        matchControl(control),
+        matchControl(ctrl),
         escapable,
-        (state, start) => enc.text(state.input, start, state.pos),
-        internal.firstCodePoint(control),
+        (state, start) => internal.textIn(enc, state, start, state.pos),
+        ctrl,
         enc
-      ),
-    escaped: (normal, control, escape) =>
-      escapedImpl(normal, matchControl(control), escape, internal.firstCodePoint(control), enc)
+      )
+    },
+    escaped: (normal, control, escape) => {
+      const ctrl = controlCode(control, internal.firstCodePoint)
+      return escapedImpl(normal, matchControl(ctrl), escape, ctrl, enc)
+    }
   }
 }