septima-lang 0.0.7 → 0.0.8

package/src/runtime.ts

@@ -0,0 +1,370 @@
+import { AstNode, show, span, Unit } from './ast-node'
+import { extractMessage } from './extract-message'
+import { failMe } from './fail-me'
+import { shouldNeverHappen } from './should-never-happen'
+import * as Stack from './stack'
+import { switchOn } from './switch-on'
+import { SymbolTable } from './symbol-table'
+import { Value } from './value'
+
+interface Placeholder {
+  destination: undefined | Value
+}
+
+class SymbolFrame implements SymbolTable {
+  constructor(readonly symbol: string, readonly placeholder: Placeholder, private readonly earlier: SymbolTable) {}
+
+  lookup(sym: string): Value {
+    if (this.symbol === sym) {
+      const ret = this.placeholder.destination
+      if (ret === undefined) {
+        throw new Error(`Unresolved definition: ${this.symbol}`)
+      }
+      return ret
+    }
+
+    return this.earlier.lookup(sym)
+  }
+
+  export() {
+    const ret = this.earlier.export()
+    ret[this.symbol] = this.placeholder.destination?.export() ?? failMe(`Unbounded symbol: ${this.symbol}`)
+    return ret
+  }
+
+  exportValue(): Record<string, Value> {
+    const ret = this.earlier.exportValue()
+    ret[this.symbol] = this.placeholder.destination ?? failMe(`Unbounded symbol: ${this.symbol}`)
+    return ret
+  }
+}
+
+class EmptySymbolTable implements SymbolTable {
+  lookup(sym: string): Value {
+    throw new Error(`Symbol ${sym} was not found`)
+  }
+
+  export() {
+    return {}
+  }
+
+  exportValue(): Record<string, Value> {
+    return {}
+  }
+}
+
+export type Verbosity = 'quiet' | 'trace'
+
+export class Runtime {
+  private stack: Stack.T = undefined
+  constructor(
+    private readonly root: AstNode,
+    private readonly verbosity: Verbosity = 'quiet',
+    private readonly preimports: Record<string, Value>,
+    private readonly getAstOf: (fileName: string) => Unit,
+    private readonly args: Record<string, unknown>,
+  ) {}
+
+  private buildInitialSymbolTable(generateTheArgsObject: boolean) {
+    const empty = new EmptySymbolTable()
+
+    const keys = Value.foreign(o => o.keys())
+    const entries = Value.foreign(o => o.entries())
+    const fromEntries = Value.foreign(o => o.fromEntries())
+    let lib = new SymbolFrame('Object', { destination: Value.obj({ keys, entries, fromEntries }) }, empty)
+
+    if (generateTheArgsObject) {
+      lib = new SymbolFrame('args', { destination: Value.from(this.args) }, lib)
+    }
+
+    for (const [importName, importValue] of Object.entries(this.preimports)) {
+      lib = new SymbolFrame(importName, { destination: importValue }, lib)
+    }
+    return lib
+  }
+
+  compute() {
+    try {
+      const value = this.evalNode(this.root, this.buildInitialSymbolTable(true))
+      return { value }
+    } catch (e) {
+      const trace: AstNode[] = []
+      for (let curr = this.stack; curr; curr = curr?.next) {
+        trace.push(curr.ast)
+      }
+      return {
+        expressionTrace: trace,
+        errorMessage: extractMessage(e),
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        stack: (e as { stack?: string[] }).stack,
+      }
+    }
+  }
+
+  private evalNode(ast: AstNode, table: SymbolTable): Value {
+    this.stack = Stack.push(ast, this.stack)
+    let ret = this.evalNodeImpl(ast, table)
+    if (ret.isSink() && !ret.span()) {
+      ret = ret.bindToSpan(span(ast))
+    }
+    switchOn(this.verbosity, {
+      quiet: () => {},
+      trace: () => {
+        // eslint-disable-next-line no-console
+        console.log(`output of <|${show(ast)}|> is ${JSON.stringify(ret)}  // ${ast.tag}`)
+      },
+    })
+    this.stack = Stack.pop(this.stack)
+    return ret
+  }
+
+  private importDefinitions(pathToImportFrom: string): Value {
+    const ast = this.getAstOf(pathToImportFrom)
+    const exp = ast.expression
+    const imports = ast.imports
+    if (
+      exp.tag === 'arrayLiteral' ||
+      exp.tag === 'binaryOperator' ||
+      exp.tag === 'dot' ||
+      exp.tag === 'export*' ||
+      exp.tag === 'functionCall' ||
+      exp.tag === 'ident' ||
+      exp.tag === 'if' ||
+      exp.tag === 'ternary' ||
+      exp.tag === 'indexAccess' ||
+      exp.tag === 'lambda' ||
+      exp.tag === 'literal' ||
+      exp.tag === 'objectLiteral' ||
+      exp.tag === 'unaryOperator' ||
+      exp.tag === 'unit'
+    ) {
+      // TODO(imaman): throw an error on non-exporting unit?
+      return Value.obj({})
+    }
+
+    if (exp.tag === 'topLevelExpression') {
+      const unit: AstNode = {
+        tag: 'unit',
+        imports,
+        expression: { tag: 'topLevelExpression', definitions: exp.definitions, computation: { tag: 'export*' } },
+      }
+      return this.evalNode(unit, this.buildInitialSymbolTable(false))
+    }
+
+    shouldNeverHappen(exp)
+  }
+
+  private evalNodeImpl(ast: AstNode, table: SymbolTable): Value {
+    if (ast.tag === 'unit') {
+      let newTable = table
+      for (const imp of ast.imports) {
+        const o = this.importDefinitions(imp.pathToImportFrom.text)
+        newTable = new SymbolFrame(imp.ident.t.text, { destination: o }, newTable)
+      }
+      return this.evalNode(ast.expression, newTable)
+    }
+    if (ast.tag === 'topLevelExpression') {
+      let newTable = table
+      for (const def of ast.definitions) {
+        const name = def.ident.t.text
+        const placeholder: Placeholder = { destination: undefined }
+        newTable = new SymbolFrame(name, placeholder, newTable)
+        const v = this.evalNode(def.value, newTable)
+        placeholder.destination = v
+      }
+
+      if (ast.computation) {
+        return this.evalNode(ast.computation, newTable)
+      }
+
+      return Value.str('')
+    }
+
+    if (ast.tag === 'export*') {
+      return Value.obj(table.exportValue())
+    }
+
+    if (ast.tag === 'binaryOperator') {
+      const lhs = this.evalNode(ast.lhs, table)
+      if (ast.operator === '||') {
+        return lhs.or(() => this.evalNode(ast.rhs, table))
+      }
+      if (ast.operator === '&&') {
+        return lhs.and(() => this.evalNode(ast.rhs, table))
+      }
+
+      if (ast.operator === '??') {
+        return lhs.unsink(() => this.evalNode(ast.rhs, table))
+      }
+
+      const rhs = this.evalNode(ast.rhs, table)
+      if (ast.operator === '!=') {
+        return lhs.equalsTo(rhs).not()
+      }
+      if (ast.operator === '==') {
+        return lhs.equalsTo(rhs)
+      }
+
+      if (ast.operator === '<=') {
+        const comp = lhs.order(rhs)
+        return comp.isToZero('<=')
+      }
+      if (ast.operator === '<') {
+        const comp = lhs.order(rhs)
+        return comp.isToZero('<')
+      }
+      if (ast.operator === '>=') {
+        const comp = lhs.order(rhs)
+        return comp.isToZero('>=')
+      }
+      if (ast.operator === '>') {
+        const comp = lhs.order(rhs)
+        return comp.isToZero('>')
+      }
+      if (ast.operator === '%') {
+        return lhs.modulo(rhs)
+      }
+      if (ast.operator === '*') {
+        return lhs.times(rhs)
+      }
+      if (ast.operator === '**') {
+        return lhs.power(rhs)
+      }
+      if (ast.operator === '+') {
+        return lhs.plus(rhs)
+      }
+      if (ast.operator === '-') {
+        return lhs.minus(rhs)
+      }
+      if (ast.operator === '/') {
+        return lhs.over(rhs)
+      }
+
+      shouldNeverHappen(ast.operator)
+    }
+
+    if (ast.tag === 'unaryOperator') {
+      const operand = this.evalNode(ast.operand, table)
+      if (ast.operator === '!') {
+        return operand.not()
+      }
+      if (ast.operator === '+') {
+        // We intentionally do <0 + operand> instead of just <operand>. This is due to type-checking: the latter will
+        // evaluate to the operand as-is, making expression such as `+true` dynamically valid (which is not the desired
+        // behavior)
+        return Value.num(0).plus(operand)
+      }
+      if (ast.operator === '-') {
+        return operand.negate()
+      }
+
+      shouldNeverHappen(ast.operator)
+    }
+    if (ast.tag === 'ident') {
+      return table.lookup(ast.t.text)
+    }
+    if (ast.tag === 'literal') {
+      if (ast.type === 'bool') {
+        // TODO(imaman): stricter checking of 'false'
+        return Value.bool(ast.t.text === 'true' ? true : false)
+      }
+      if (ast.type === 'num') {
+        return Value.num(Number(ast.t.text))
+      }
+      if (ast.type === 'sink!!') {
+        return Value.sink(undefined, this.stack, table)
+      }
+      if (ast.type === 'sink!') {
+        return Value.sink(undefined, this.stack)
+      }
+      if (ast.type === 'sink') {
+        return Value.sink()
+      }
+      if (ast.type === 'str') {
+        return Value.str(ast.t.text)
+      }
+      shouldNeverHappen(ast.type)
+    }
+
+    if (ast.tag === 'arrayLiteral') {
+      const arr: Value[] = []
+      for (const curr of ast.parts) {
+        if (curr.tag === 'element') {
+          arr.push(this.evalNode(curr.v, table))
+        } else if (curr.tag === 'spread') {
+          const v = this.evalNode(curr.v, table)
+          arr.push(...v.assertArr())
+        } else {
+          shouldNeverHappen(curr)
+        }
+      }
+
+      return Value.arr(arr)
+    }
+
+    if (ast.tag === 'objectLiteral') {
+      const entries: [string, Value][] = ast.parts.flatMap(at => {
+        if (at.tag === 'hardName') {
+          return [[at.k.t.text, this.evalNode(at.v, table)]]
+        }
+        if (at.tag === 'computedName') {
+          return [[this.evalNode(at.k, table).assertStr(), this.evalNode(at.v, table)]]
+        }
+        if (at.tag === 'spread') {
+          const o = this.evalNode(at.o, table)
+          return Object.entries(o.assertObj())
+        }
+
+        shouldNeverHappen(at)
+      })
+
+      // TODO(imaman): verify type of all keys (strings, maybe also numbers)
+      return Value.obj(Object.fromEntries(entries))
+    }
+
+    if (ast.tag === 'lambda') {
+      return Value.lambda(ast, table)
+    }
+
+    if (ast.tag === 'functionCall') {
+      const argValues = ast.actualArgs.map(a => this.evalNode(a, table))
+      const callee = this.evalNode(ast.callee, table)
+
+      return this.call(callee, argValues)
+    }
+
+    if (ast.tag === 'if' || ast.tag === 'ternary') {
+      const c = this.evalNode(ast.condition, table)
+      return c.ifElse(
+        () => this.evalNode(ast.positive, table),
+        () => this.evalNode(ast.negative, table),
+      )
+    }
+
+    if (ast.tag === 'dot') {
+      const rec = this.evalNode(ast.receiver, table)
+      if (rec === undefined || rec === null) {
+        throw new Error(`Cannot access attribute .${ast.ident.t.text} of ${rec}`)
+      }
+      return rec.access(ast.ident.t.text, (callee, args) => this.call(callee, args))
+    }
+
+    if (ast.tag === 'indexAccess') {
+      const rec = this.evalNode(ast.receiver, table)
+      const index = this.evalNode(ast.index, table)
+      return rec.access(index, (callee, args) => this.call(callee, args))
+    }
+
+    shouldNeverHappen(ast)
+  }
+
+  call(callee: Value, argValues: Value[]) {
+    return callee.call(argValues, (names, body, lambdaTable: SymbolTable) => {
+      if (names.length > argValues.length) {
+        throw new Error(`Arg list length mismatch: expected ${names.length} but got ${argValues.length}`)
+      }
+      const newTable = names.reduce((t, n, i) => new SymbolFrame(n, { destination: argValues[i] }, t), lambdaTable)
+      return this.evalNode(body, newTable)
+    })
+  }
+}

package/src/scanner.ts

@@ -0,0 +1,106 @@
+import { Location } from './location'
+import { SourceCode } from './source-code'
+
+export interface Token {
+  readonly text: string
+  readonly location: Location
+}
+
+export class Scanner {
+  constructor(readonly sourceCode: SourceCode, private offset = 0) {
+    if (this.offset === 0) {
+      this.eatWhitespace()
+    }
+  }
+
+  get sourceRef() {
+    return this.sourceCode.sourceRef(this.sourceCode.expandToEndOfLine({ offset: this.offset }))
+  }
+
+  private curr() {
+    return this.sourceCode.input.substring(this.offset)
+  }
+
+  private eatWhitespace() {
+    while (true) {
+      if (this.consumeIf(/\s*/, false)) {
+        continue
+      }
+      if (this.consumeIf('//', false)) {
+        this.consume(/[^\n]*/, false)
+        continue
+      }
+
+      return
+    }
+  }
+
+  eof(): boolean {
+    return this.offset >= this.sourceCode.input.length
+  }
+
+  synopsis() {
+    const c = this.curr()
+    let lookingAt = c.substring(0, 20)
+    if (lookingAt.length !== c.length) {
+      lookingAt = `${lookingAt}...`
+    }
+
+    return {
+      position: this.offset,
+      lookingAt,
+    }
+  }
+
+  headMatches(...patterns: (RegExp | string)[]): boolean {
+    const alt = new Scanner(this.sourceCode, this.offset)
+    for (const p of patterns) {
+      const t = alt.consumeIf(p, true)
+      if (t === undefined) {
+        return false
+      }
+    }
+
+    return true
+  }
+
+  consume(r: RegExp | string, eatWhitespace = true): Token {
+    const text = this.match(r)
+    if (text === undefined) {
+      throw new Error(`Expected ${r} ${this.sourceRef}`)
+    }
+
+    const offset = this.offset
+    this.offset += text.length
+
+    if (eatWhitespace) {
+      this.eatWhitespace()
+    }
+    return { location: { offset }, text }
+  }
+
+  consumeIf(r: RegExp | string, eatWhitespace = true): Token | undefined {
+    const ret = this.match(r)
+    if (!ret) {
+      return undefined
+    }
+
+    return this.consume(r, eatWhitespace)
+  }
+
+  private match(r: RegExp | string): string | undefined {
+    if (typeof r === 'string') {
+      if (this.curr().startsWith(r)) {
+        return r
+      }
+      return undefined
+    }
+
+    const m = this.curr().match(r)
+    if (m && m.index === 0) {
+      return m[0]
+    }
+
+    return undefined
+  }
+}

package/src/septima.ts

@@ -0,0 +1,121 @@
+import { Unit } from './ast-node'
+import { Parser } from './parser'
+import { Result, ResultSink, ResultSinkImpl } from './result'
+import { Runtime, Verbosity } from './runtime'
+import { Scanner } from './scanner'
+import { shouldNeverHappen } from './should-never-happen'
+import { SourceCode } from './source-code'
+import { Value } from './value'
+
+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
+}
+
+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 res = new Septima().compute(input, {}, 'quiet', args)
+    if (res.tag === 'ok') {
+      return res.value
+    }
+
+    if (res.tag === 'sink') {
+      return onSink(res)
+    }
+
+    shouldNeverHappen(res)
+  }
+
+  constructor() {}
+
+  computeModule(moduleName: string, moduleReader: (m: string) => string, args: Record<string, unknown>): Result {
+    const input = moduleReader(moduleName)
+    const sourceCode = new SourceCode(input)
+    const value = this.computeImpl(sourceCode, 'quiet', {}, moduleReader, args)
+    if (!value.isSink()) {
+      return { value: value.export(), tag: 'ok' }
+    }
+    return new ResultSinkImpl(value, sourceCode)
+  }
+
+  compute(
+    input: string,
+    preimports: Record<string, string> = {},
+    verbosity: Verbosity = 'quiet',
+    args: Record<string, unknown>,
+  ): Result {
+    const lib: Record<string, Value> = {}
+    for (const [importName, importCode] of Object.entries(preimports)) {
+      const sourceCode = new SourceCode(importCode)
+      const value = this.computeImpl(sourceCode, verbosity, {}, undefined, {})
+      if (value.isSink()) {
+        // TODO(imaman): cover!
+        const r = new ResultSinkImpl(value, sourceCode)
+        throw new Error(`preimport (${importName}) evaluated to sink: ${r.message}`)
+      }
+      lib[importName] = value
+    }
+
+    const sourceCode = new SourceCode(input)
+    const value = this.computeImpl(sourceCode, verbosity, lib, undefined, args)
+    if (!value.isSink()) {
+      return { value: value.export(), tag: 'ok' }
+    }
+    return new ResultSinkImpl(value, sourceCode)
+  }
+
+  private computeImpl(
+    sourceCode: SourceCode,
+    verbosity: Verbosity,
+    lib: Record<string, Value>,
+    moduleReader: undefined | ((m: string) => string),
+    args: Record<string, unknown>,
+  ) {
+    const scanner = new Scanner(sourceCode)
+    const parser = new Parser(scanner)
+    const ast = parse(parser)
+
+    const getAstOf = (fileName: string) => {
+      if (!moduleReader) {
+        throw new Error(`cannot read modules`)
+      }
+      return parse(moduleReader(fileName))
+    }
+
+    const runtime = new Runtime(ast, verbosity, lib, getAstOf, args)
+    const c = runtime.compute()
+
+    if (c.value) {
+      return c.value
+    }
+
+    const runtimeErrorMessage = `${c.errorMessage} when evaluating:\n${sourceCode.formatTrace(c.expressionTrace)}`
+    throw new Error(runtimeErrorMessage)
+  }
+}
+
+export function parse(arg: string | Parser): Unit {
+  const parser = typeof arg === 'string' ? new Parser(new Scanner(new SourceCode(arg))) : arg
+  const ast = parser.parse()
+  return ast
+}

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) {}
+
+  formatTrace(trace: AstNode[]): string {
+    const spacer = '  '
+
+    const formatted = trace
+      .map(ast => this.sourceRef(span(ast)))
+      .reverse()
+      .join(`\n${spacer}`)
+    return `${spacer}${formatted}`
+  }
+
+  sourceRefOfLocation(loc: Location) {
+    return this.sourceRef(this.expandToEndOfLine(loc))
+  }
+
+  sourceRef(span: Span | undefined) {
+    if (!span) {
+      return `at <unknown location>`
+    }
+    return `at ${this.formatSpan(span)} ${this.interestingPart(span)}`
+  }
+
+  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)}...`
+  }
+
+  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 } }
+  }
+
+  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
+  }
+}