@herb-tools/core 0.1.0

package/src/herb-backend.ts

@@ -0,0 +1,152 @@
+import packageJSON from "../package.json" with { type: "json" }
+
+import { ensureString } from "./util.js"
+import { LexResult } from "./lex-result.js"
+import { ParseResult } from "./parse-result.js"
+
+import type { LibHerbBackend, BackendPromise } from "./backend.js"
+
+/**
+ * The main Herb parser interface, providing methods to lex and parse input.
+ */
+export abstract class HerbBackend {
+  /** The backend instance handling lexing and parsing. */
+  public backend: LibHerbBackend | undefined = undefined
+  public readonly backendPromise: BackendPromise
+
+  /**
+   * Creates a new Herb instance.
+   * @param backendPromise - A promise resolving to a `LibHerbBackend` implementation for lexing and parsing.
+   * @throws Error if no valid backend is provided.
+   */
+  constructor(backendPromise: BackendPromise) {
+    if (!backendPromise) {
+      throw new Error("No LibHerb backend provided")
+    }
+
+    this.backendPromise = backendPromise
+  }
+
+  /**
+   * Loads the backend by resolving the backend promise.
+   * @returns A promise containing the resolved `HerbBackend` instance after loading it.
+   */
+  async load(): Promise<HerbBackend> {
+    const backend = await this.backendPromise()
+    this.backend = backend
+    return this
+  }
+
+  /**
+   * Lexes the given source string into a `LexResult`.
+   * @param source - The source code to lex.
+   * @returns A `LexResult` instance.
+   * @throws Error if the backend is not loaded.
+   */
+  lex(source: string): LexResult {
+    this.ensureBackend()
+
+    return LexResult.from(this.backend.lex(ensureString(source)))
+  }
+
+  /**
+   * Lexes a file.
+   * @param path - The file path to lex.
+   * @returns A `LexResult` instance.
+   * @throws Error if the backend is not loaded.
+   */
+  lexFile(path: string): LexResult {
+    this.ensureBackend()
+
+    return LexResult.from(this.backend.lexFile(ensureString(path)))
+  }
+
+  /**
+   * Parses the given source string into a `ParseResult`.
+   * @param source - The source code to parse.
+   * @returns A `ParseResult` instance.
+   * @throws Error if the backend is not loaded.
+   */
+  parse(source: string): ParseResult {
+    this.ensureBackend()
+
+    return ParseResult.from(this.backend.parse(ensureString(source)))
+  }
+
+  /**
+   * Parses a file.
+   * @param path - The file path to parse.
+   * @returns A `ParseResult` instance.
+   * @throws Error if the backend is not loaded.
+   */
+  parseFile(path: string): ParseResult {
+    this.ensureBackend()
+
+    return ParseResult.from(this.backend.parseFile(ensureString(path)))
+  }
+
+  /**
+   * Extracts embedded Ruby code from the given source.
+   * @param source - The source code to extract Ruby from.
+   * @returns The extracted Ruby code as a string.
+   * @throws Error if the backend is not loaded.
+   */
+  extractRuby(source: string): string {
+    this.ensureBackend()
+
+    return this.backend.extractRuby(ensureString(source))
+  }
+
+  /**
+   * Extracts HTML from the given source.
+   * @param source - The source code to extract HTML from.
+   * @returns The extracted HTML as a string.
+   * @throws Error if the backend is not loaded.
+   */
+  extractHTML(source: string): string {
+    this.ensureBackend()
+
+    return this.backend.extractHTML(ensureString(source))
+  }
+
+  /**
+   * Gets the Herb version information, including the core and backend versions.
+   * @returns A version string containing backend, core, and libherb versions.
+   * @throws Error if the backend is not loaded.
+   */
+  get version(): string {
+    this.ensureBackend()
+
+    const backend = this.backendVersion()
+    const core = `${packageJSON.name}@${packageJSON.version}`
+    const libherb = this.backend.version()
+
+    return `${backend}, ${core}, ${libherb}`
+  }
+
+  /**
+   * Ensures that the backend is loaded.
+   * @throws Error if the backend is not loaded.
+   */
+  ensureBackend(): asserts this is { backend: LibHerbBackend } {
+    if (!this.isLoaded) {
+      throw new Error(
+        "Herb backend is not loaded. Call `await Herb.load()` first.",
+      )
+    }
+  }
+
+  /**
+   * Checks if the backend is loaded.
+   * @returns True if the backend is loaded, false otherwise.
+   */
+  get isLoaded() {
+    return this.backend !== undefined
+  }
+
+  /**
+   * Abstract method to get the backend version.
+   * @returns A string representing the backend version.
+   */
+  abstract backendVersion(): string
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from "./ast.js"
+export * from "./backend.js"
+export * from "./errors.js"
+export * from "./herb-backend.js"
+export * from "./lex-result.js"
+export * from "./location.js"
+export * from "./nodes.js"
+export * from "./parse-result.js"
+export * from "./position.js"
+export * from "./range.js"
+export * from "./result.js"
+export * from "./token-list.js"
+export * from "./token.js"
+export * from "./util.js"
+export * from "./visitor.js"

package/src/lex-result.ts

@@ -0,0 +1,78 @@
+import { Result } from "./result.js"
+import { TokenList, SerializedTokenList } from "./token-list.js"
+
+export type SerializedLexResult = {
+  tokens: SerializedTokenList
+  source: string
+  warnings: any[]
+  errors: any[]
+}
+
+/**
+ * Represents the result of a lexical analysis, extending the base `Result` class.
+ * It contains the token list, source code, warnings, and errors.
+ */
+export class LexResult extends Result {
+  /** The list of tokens generated from the source code. */
+  readonly value: TokenList
+
+  /**
+   * Creates a `LexResult` instance from a serialized result.
+   * @param result - The serialized lexical result containing tokens, source, warnings, and errors.
+   * @returns A new `LexResult` instance.
+   */
+  static from(result: SerializedLexResult) {
+    return new LexResult(
+      TokenList.from(result.tokens || []),
+      result.source,
+      result.warnings,
+      result.errors,
+    )
+  }
+
+  /**
+   * Constructs a new `LexResult`.
+   * @param value - The list of tokens.
+   * @param source - The source code that was lexed.
+   * @param warnings - An array of warnings encountered during lexing.
+   * @param errors - An array of errors encountered during lexing.
+   */
+  constructor(
+    value: TokenList,
+    source: string,
+    warnings: any[] = [],
+    errors: any[] = [],
+  ) {
+    super(source, warnings, errors)
+    this.value = value
+  }
+
+  /**
+   * Determines if the lexing was successful.
+   * @returns `true` if there are no errors, otherwise `false`.
+   */
+  override success(): boolean {
+    return this.errors.length === 0
+  }
+
+  /**
+   * Determines if the lexing failed.
+   * @returns `true` if there are errors, otherwise `false`.
+   */
+  override failed(): boolean {
+    return this.errors.length > 0
+  }
+
+  /**
+   * Converts the `LexResult` to a JSON representation.
+   * @returns An object containing the token list, source, warnings, and errors.
+   */
+  toJSON() {
+    return {
+      value: this.value,
+      source: this.source,
+      warnings: this.warnings,
+      errors: this.errors,
+    }
+  }
+}

package/src/location.ts

@@ -0,0 +1,51 @@
+import { Position } from "./position.js"
+import type { SerializedPosition } from "./position.js"
+
+export type SerializedLocation = {
+  start: SerializedPosition
+  end: SerializedPosition
+}
+
+export class Location {
+  readonly start: Position
+  readonly end: Position
+
+  static from(location: SerializedLocation) {
+    const start = Position.from(location.start)
+    const end = Position.from(location.end)
+
+    return new Location(start, end)
+  }
+
+  constructor(start: Position, end: Position) {
+    this.start = start
+    this.end = end
+  }
+
+  toHash(): SerializedLocation {
+    return {
+      start: this.start.toHash(),
+      end: this.end.toHash(),
+    }
+  }
+
+  toJSON(): SerializedLocation {
+    return this.toHash()
+  }
+
+  treeInspect(): string {
+    return `${this.start.treeInspect()}-${this.end.treeInspect()}`
+  }
+
+  treeInspectWithLabel(): string {
+    return `(location: ${this.treeInspect()})`
+  }
+
+  inspect(): string {
+    return `#<Herb::Location ${this.treeInspect()}>`
+  }
+
+  toString(): string {
+    return this.inspect()
+  }
+}

package/src/node.ts

@@ -0,0 +1,106 @@
+import { Location, SerializedLocation } from "./location.js"
+import { HerbError, SerializedHerbError } from "./error.js"
+import { NodeType, SerializedNodeType, fromSerializedNode } from "./nodes.js"
+
+export interface SerializedNode {
+  type: SerializedNodeType
+  location: SerializedLocation
+  errors: SerializedHerbError[]
+}
+
+export interface BaseNodeProps {
+  type: NodeType
+  location: Location
+  errors: HerbError[]
+}
+
+export abstract class Node implements BaseNodeProps {
+  readonly type: NodeType
+  readonly location: Location
+  readonly errors: HerbError[]
+
+  static from(node: SerializedNode): Node {
+    return fromSerializedNode(node)
+  }
+
+  constructor(type: NodeType, location: Location, errors: HerbError[]) {
+    this.type = type
+    this.location = location
+    this.errors = errors
+  }
+
+  toJSON(): SerializedNode {
+    return {
+      type: this.type,
+      location: this.location.toJSON(),
+      errors: this.errors,
+    }
+  }
+
+  inspect(): string {
+    return this.treeInspect(0)
+  }
+
+  abstract treeInspect(indent?: number): string
+  abstract recursiveErrors(): HerbError[]
+  abstract childNodes(): Node[]
+
+  protected inspectArray(
+    array: (Node | HerbError)[] | null | undefined,
+    prefix: string,
+  ): string {
+    if (!array) return "∅\n"
+    if (array.length === 0) return "[]\n"
+
+    let output = `(${array.length} item${array.length == 1 ? "" : "s"})\n`
+
+    array.forEach((item, index) => {
+      const isLast = index === array.length - 1
+
+      if (item instanceof Node || item instanceof HerbError) {
+        output += this.inspectNode(
+          item,
+          prefix,
+          isLast ? "    " : "│   ",
+          isLast,
+          false,
+        )
+      } else {
+        const symbol = isLast ? "└── " : "├── "
+        output += `${prefix}${symbol} ${item}\n`
+      }
+    })
+
+    output += `${prefix}\n`
+
+    return output
+  }
+
+  protected inspectNode(
+    node: Node | HerbError | undefined | null,
+    prefix: string,
+    prefix2: string = "    ",
+    last: boolean = true,
+    trailingNewline: boolean = true,
+  ): string {
+    if (!node) return "∅\n"
+
+    let output = trailingNewline ? "\n" : ""
+    output += `${prefix}`
+
+    output += last ? "└── " : "├── "
+    output += node
+      .treeInspect()
+      .trimStart()
+      .split("\n")
+      .map((line, index) =>
+        index == 0 ? line.trimStart() : `${prefix}${prefix2}${line}`,
+      )
+      .join("\n")
+      .trimStart()
+
+    output += `\n`
+
+    return output
+  }
+}