Atlas

A tiny embedded scripting language implemented in Scala.

Copyright 2018 Dave Gurnell. Licensed Apache 2.

Why?

Atlas is a super-simple scripting language created for use in Cartographer to allow us to define fragments of logic over user-defined data types. It has the following features:

• simple, concise, expression-oriented syntax;
• Scheme-like functional semantics;
• parser and interpreter written in Scala;
• serializable in compiled and uncompiled forms;
• support for "native functions" written in Scala.

Atlas is currently a work-in-progress.

Show me some examples!

Factorials are the "hello world" of scripting languages, right?

let factorial = n ->
  if n <= 1
  then 1
  else n * factorial(n - 1)

factorial(10)

Function bodies are lazily bound allowing letrec-style recursive references:

let even = n ->
  if n == 0 then true else odd(n - 1)

let odd = n ->
  if n == 0 then false else even(n - 1)

even(10)

Quick language reference

Basic literals are Javascript-like:

'foo'      # single-quoted string
"foo"      # double-quoted string
1          # integer
1.2        # double
true       # boolean
null       # null

[a, b]     # array
{a:1, b:2} # object

There are a fixed set of built-in prefix and infix operators. In order of decreasing precedence these are:

!a         # boolean not
-a         # negation
+a         # erm... non-negation

a*b        # multiplication
a/b        # floating point division

a+b        # addition
a-b        # addition

a < b      # comparisons
a > b      # (integer, double, string, or boolean)
a <= b     #
a >= b     #

a == b     # value equality and
a != b     # function reference equality

a && b     # boolean and

a || b     # boolean or

Function literals are written with the -> symbol. Parentheses are optional if there is only one argument:

(a, b) -> a + b
n -> n + 1

In addition to literals, variable references, and infix and prefix operators, there are several types of expression.

Function applications look like Javascript:

max(1, 2)

as do field references:

foo.bar.baz

Conditionals are introduced with the if, then, and else keywords. The else clause is mandatory. The result is the value of the expression in the relevant arm:

if expr then expr else expr

Blocks introduce scopes and allow the definition of intermediate variables. The result is the value of the final expression:

do
  stmt
  stmt
  expr
end

Statements are expressions (evaluated for their side-effects) or declarations, introduced with the let keyword:

let add = (a, b) -> a + b
let ten = add(3, 7)

Function bodies can refer to earlier or later bindings in the block where they are defined, allowing mutually recursive definitions:

let even = n ->
  if n == 0 then true else odd(n - 1)

let odd  = n ->
  if n == 0 then false else even(n - 1)

even(10)

Comments are written with the # symbol and run to the end of the line:

# Calculate a factorial:
let fact = n ->
  if n == 1
  then 1
  else n * fact(n - 1)

Complete programs have the same semantics as blocks but are written without the do and end keywords. If the program ends with a statement, an implicit null expression is added to the end:

let fib = n ->
  if n <= 2
  then 1
  else fib(n - 1) + fib(n - 2)

fib(10)

Interaction with Scala

There are two string interpolators for defining code fragments: expr for expressions and prog for complete programs:

import atlas._
import atlas.syntax._

val anExpression: Expr =
  expr"""
  1 + 2 + 3
  """

val aProgram: Expr =
  prog"""
  let fib = n ->
    if n <= 2
    then 1
    else fib(n - 1) + fib(n - 2)

  fib(10)
  """

Syntax errors raised by the macros result in a Scala compilation error.

You can alternatively use the Parser.expr or Parser.prog methods to parse a regular Scala string: Syntax errors using the parser result in an Either:

val anotherExpression: Either[Parser.Error, Expr] =
  Parser.expr("1 + 2 + 3")

Expressions (and, by extension, programs) can be evaluated using the Eval.apply method. Runtime errors are captured in an Either:

Eval(anExpression) // => Right(IntValue(6))

Eval(aProgram)     // => Right(IntValue(55))

You can optionally pass an Env object to Eval.apply specifying an initial environment:

val program = prog"a + b"
val env = Env.create
  .set("a", 10)
  .set("b", 32)
Eval(program, env) // => Right(IntValue(42))

Although Eval can internally mutate environments to enable mutually recursive function bodies, any environment you pass to Eval.apply should be returned unharmed.

You can implement "native functions" in Scala:

val program = prog"average(10, 5)"
val env = Env.create
  .set("average", native((a: Double, b: Double) => (a + b) / 2))
Eval(program, env) // => Right(DoubleValue(7.5))

Conversion between Atlas and Scala values is implemented using a pair of type classes called ValueEncoder and ValueDecoder. These can be used with the as[A] and asValue extension methods from atlas.syntax:

123.asValue      // => IntValue(123)

IntValue.as[Int] // => Right(123)

Acknowledgements

Thanks to Nic Pereira for naming the project and saving us all from "davescript" :)