septima-lang 0.0.21 → 0.2.0

package/src/septima.ts

@@ -0,0 +1,218 @@
+import * as path from 'path'
+
+import { Unit, UnitId } from './ast-node'
+import { failMe } from './fail-me'
+import { Parser } from './parser'
+import { formatTrace, Result, ResultSink } from './result'
+import { Outputter, Runtime, Verbosity } from './runtime'
+import { Scanner } from './scanner'
+import { shouldNeverHappen } from './should-never-happen'
+import { SourceCode } from './source-code'
+
+interface Options {
+  /**
+   * A callback function to be invoked when the Septima program evaluated to `sink`. Allows the caller to determine
+   * which value will be returned in that case. For instance, passing `() => undefined` will translate a `sink` value
+   * to `undefined`. The default behavior is to throw an error.
+   */
+  onSink?: (res: ResultSink) => unknown
+  /**
+   * A custom output function that will receive the values that are passed to console.log() calls in the septima code.
+   */
+  consoleLog?: Outputter
+}
+
+export interface Executable {
+  execute(args: Record<string, unknown>): Result
+}
+
+type SyncCodeReader = (resolvePath: string) => string | undefined
+type CodeReader = (resolvePath: string) => Promise<string | undefined>
+
+export interface SourceUnit {
+  sourceCode: SourceCode
+  unit: Unit
+}
+
+export class Septima {
+  /**
+   * Runs a Septima program and returns the value it evaluates to. If it evaluates to `sink`, returns the value computed
+   * by `options.onSink()` - if present, or throws an error - otherwise.
+   *
+   * This method is the simplest way to evaluate a Septima program, and it fits many common use cases. One can also use
+   * `.compute()` to get additional details about the execution.
+   *
+   * @param input the source code of the Septima program
+   * @param options
+   * @returns the value that `input` evaluates to
+   */
+  static run(input: string, options?: Options, args: Record<string, unknown> = {}): unknown {
+    const onSink =
+      options?.onSink ??
+      ((r: ResultSink) => {
+        throw new Error(r.message)
+      })
+
+    const fileName = '<inline>'
+    const contentRec: Record<string, string> = { [fileName]: input }
+    const readFile = (m: string) => contentRec[m]
+    const res = new Septima(undefined, options?.consoleLog).compileSync(fileName, readFile).execute(args)
+    if (res.tag === 'ok') {
+      return res.value
+    }
+
+    if (res.tag === 'sink') {
+      return onSink(res)
+    }
+
+    shouldNeverHappen(res)
+  }
+
+  private readonly unitByUnitId = new Map<UnitId, SourceUnit>()
+
+  constructor(private readonly sourceRoot = '', private readonly consoleLog?: Outputter) {}
+
+  compileSync(fileName: string, readFile: SyncCodeReader) {
+    fileName = this.relativize(fileName)
+    const acc = [fileName]
+    this.pumpSync(acc, readFile)
+    return this.getExecutableFor(fileName)
+  }
+
+  async compile(fileName: string, readFile: CodeReader) {
+    fileName = this.relativize(fileName)
+    const acc = [fileName]
+    await this.pump(acc, readFile)
+    return this.getExecutableFor(fileName)
+  }
+
+  private relativize(fileName: string) {
+    if (path.isAbsolute(fileName)) {
+      return path.relative(this.sourceRoot, fileName)
+    }
+
+    return fileName
+  }
+
+  private getExecutableFor(fileName: string): Executable {
+    // Verify that a unit for the main file exists
+    this.unitOf(undefined, fileName)
+
+    return {
+      execute: (args: Record<string, unknown>) => {
+        const value = this.execute(fileName, 'quiet', args)
+        const ret: Result = { value: value.export(), tag: 'ok' }
+        return ret
+      },
+    }
+  }
+
+  private execute(fileName: string, verbosity: Verbosity, args: Record<string, unknown>) {
+    const runtime = new Runtime(
+      this.unitOf(undefined, fileName),
+      verbosity,
+      (a, b) => this.unitOf(a, b),
+      args,
+      this.consoleLog,
+    )
+    const c = runtime.compute()
+
+    if (c.value) {
+      return c.value
+    }
+
+    const formatted = formatTrace(c.expressionTrace, this.unitByUnitId)
+    throw new Error(`${c.errorMessage} when evaluating:\n${formatted}`)
+  }
+
+  /**
+   * Translates the filename into a resolved path (to be read) if it has not been read yet. If it has been read,
+   * returns undefined
+   */
+  private computeResolvedPathToRead(fileName: string) {
+    const pathFromSourceRoot = this.getPathFromSourceRoot(undefined, fileName)
+    if (this.unitByUnitId.has(pathFromSourceRoot)) {
+      return undefined
+    }
+    return path.join(this.sourceRoot, pathFromSourceRoot)
+  }
+
+  private loadFileContent(resolvedPath: string | undefined, content: string | undefined, acc: string[]) {
+    if (resolvedPath === undefined) {
+      return
+    }
+    const pathFromSourceRoot = path.relative(this.sourceRoot, resolvedPath)
+    if (content === undefined) {
+      throw new Error(`Cannot find file '${path.join(this.sourceRoot, pathFromSourceRoot)}'`)
+    }
+    const sourceCode = new SourceCode(content, pathFromSourceRoot)
+    const scanner = new Scanner(sourceCode)
+    const parser = new Parser(scanner)
+    const unit = parser.parse()
+
+    this.unitByUnitId.set(pathFromSourceRoot, { unit, sourceCode })
+    acc.push(...unit.imports.map(at => this.getPathFromSourceRoot(pathFromSourceRoot, at.pathToImportFrom.text)))
+  }
+
+  private unitOf(importerPathFromSourceRoot: string | undefined, relativePath: string) {
+    const p = this.getPathFromSourceRoot(importerPathFromSourceRoot, relativePath)
+    const { unit } =
+      this.unitByUnitId.get(p) ?? failMe(`Encluntered a file which has not been loaded (file name: ${p})`)
+    return unit
+  }
+
+  private getPathFromSourceRoot(startingPoint: string | undefined, relativePath: string) {
+    if (path.isAbsolute(relativePath)) {
+      throw new Error(`An absolute path is not allowed in import (got: ${relativePath})`)
+    }
+    const joined = startingPoint === undefined ? relativePath : path.join(path.dirname(startingPoint), relativePath)
+    const ret = path.normalize(joined)
+    if (ret.startsWith('.')) {
+      throw new Error(
+        `resolved path (${path.join(this.sourceRoot, ret)}) is pointing outside of source root (${this.sourceRoot})`,
+      )
+    }
+    return ret
+  }
+
+  // loadSync() need to be kept in sync with load(), ditto pumpSync() w/ pump(). There is deep testing coverage for the
+  // sync variant but only partial coverage for the async variant.
+  // An extra effort was taken in order to reduce the duplication between the two variants. This attempt achieved its
+  // goal (to some extent) but resulted in a somewhat unnatural code (like using an "acc" parameter to collect items,
+  // instead of returning an array, having an external "pump" logic instead of a plain recursion). Perhaps a better
+  // approach is to have a contract test and run it twice thus equally testing the two variants.
+
+  private loadSync(fileName: string, readFile: SyncCodeReader, acc: string[]) {
+    const p = this.computeResolvedPathToRead(fileName)
+    const content = p && readFile(p)
+    this.loadFileContent(p, content, acc)
+  }
+
+  private async load(fileName: string, readFile: CodeReader, acc: string[]): Promise<void> {
+    const p = this.computeResolvedPathToRead(fileName)
+    const content = p && (await readFile(p))
+    this.loadFileContent(p, content, acc)
+  }
+
+  private pumpSync(acc: string[], readFile: SyncCodeReader) {
+    while (true) {
+      const curr = acc.pop()
+      if (!curr) {
+        return
+      }
+
+      this.loadSync(curr, readFile, acc)
+    }
+  }
+
+  private async pump(acc: string[], readFile: CodeReader) {
+    while (true) {
+      const curr = acc.pop()
+      if (!curr) {
+        return
+      }
+
+      await this.load(curr, readFile, acc)
+    }
+  }
+}

package/src/should-never-happen.ts

@@ -0,0 +1,4 @@
+export function shouldNeverHappen(n: never): never {
+  // This following line never gets executed. It is here just to make the compiler happy.
+  throw new Error(`This should never happen ${n}`)
+}

package/src/source-code.ts

@@ -0,0 +1,101 @@
+import { AstNode, span } from './ast-node'
+import { Location, Location2d, Span } from './location'
+
+export class SourceCode {
+  constructor(readonly input: string, readonly pathFromSourceRoot: string) {}
+
+  formatTrace(trace: AstNode[]): string {
+    const spacer = '  '
+
+    const formatted = trace
+      .map(ast => this.sourceRef(span(ast)))
+      .reverse()
+      .join(`\n${spacer}`)
+    return `${spacer}${formatted}`
+  }
+
+  formatAst(ast: AstNode): string {
+    return this.sourceRef(span(ast))
+  }
+
+  sourceRef(span: Span | undefined) {
+    if (!span) {
+      return `at <unknown location>`
+    }
+    return `at (${this.pathFromSourceRoot}:${this.formatSpan(span)}) ${this.interestingPart(span)}`
+  }
+
+  private formatSpan(span: Span) {
+    const f = this.resolveLocation(span.from)
+    const t = this.resolveLocation(span.to)
+    if (f.line === t.line) {
+      return `${f.line + 1}:${f.col + 1}..${t.col + 1}`
+    }
+
+    return `${f.line + 1}:${f.col + 1}..${t.line + 1}:${t.col + 1}`
+  }
+
+  private interestingPart(span: Span) {
+    const f = this.resolveLocation(span.from)
+    const t = this.resolveLocation(span.to)
+
+    const strip = (s: string) => s.replace(/^[\n]*/, '').replace(/[\n]*$/, '')
+    const limit = 80
+
+    const lineAtFrom = this.lineAt(span.from)
+    if (f.line !== t.line) {
+      return `${strip(lineAtFrom).substring(0, limit)}...`
+    }
+
+    const stripped = strip(lineAtFrom.substring(f.col, t.col + 1))
+    if (stripped.length <= limit) {
+      return stripped
+    }
+    return `${stripped.substring(0, limit)}...`
+  }
+
+  private resolveLocation(loc: Location): Location2d {
+    const prefix = this.input.slice(0, loc.offset)
+    let line = 0
+    for (let i = 0; i < prefix.length; ++i) {
+      const ch = prefix[i]
+      if (ch === '\n') {
+        line += 1
+      }
+    }
+
+    let col = 0
+    for (let i = prefix.length - 1; i >= 0; --i, ++col) {
+      const ch = prefix[i]
+      if (ch === '\n') {
+        break
+      }
+    }
+
+    return { line, col }
+  }
+
+  /**
+   * Returns a span starting a the given input location that runs all the way to the end of the line. Specifically, the
+   * returned span's `.to` location will point at the character (in the same line as `loc`) that is immediately before
+   * the terminating newline character.
+   */
+  expandToEndOfLine(loc: Location): Span {
+    let endOfLine = this.input.indexOf('\n', loc.offset)
+    if (endOfLine < 0) {
+      endOfLine = this.input.length - 1
+    }
+    return { from: loc, to: { offset: endOfLine } }
+  }
+
+  private lineAt(loc: Location) {
+    const precedingNewline = this.input.lastIndexOf('\n', loc.offset)
+    // add a + 1 to skip over the '\n' character (it is not part of the line). Also works if precedingNewLine is -1 (no
+    // preceding newline exists)
+    const startOfLine = precedingNewline + 1
+    const endOfLine = this.expandToEndOfLine(loc).to
+
+    const ret = this.input.substring(startOfLine, endOfLine.offset + 1)
+    return ret
+  }
+}

package/src/stack.ts

@@ -0,0 +1,18 @@
+import { AstNode } from './ast-node'
+export type T = { ast: AstNode; next: T } | undefined
+
+export function push(ast: AstNode, s: T) {
+  return { ast, next: s }
+}
+
+export function pop(s: T) {
+  if (typeof s === 'undefined') {
+    throw new Error(`Cannot pop from an empty stack`)
+  }
+
+  return s.next
+}
+
+export function empty(): T {
+  return undefined
+}

package/src/switch-on.ts

@@ -0,0 +1,4 @@
+export function switchOn<G, K extends string>(selector: K, cases: Record<K, () => G>): G {
+  const f = cases[selector]
+  return f()
+}

package/src/symbol-table.ts

@@ -0,0 +1,9 @@
+import { Value } from './value'
+
+export type Visibility = 'EXPORTED' | 'INTERNAL'
+
+export interface SymbolTable {
+  lookup(sym: string): Value
+  export(): Record<string, unknown>
+  exportValue(): Record<string, Value>
+}