Oak

Oak variables and functions can begin with letters and the "_", "!", "?" characters, and can also contain numbers after the first character. ProductionEnv?, invalidate!, num_attendees, and ___runtime_gc are all valid Oak identifiers.

There are two loosely enforced naming conventions in Oak. First, global constants begin with uppercase letters, but are not written ALL_CAPS. Second, names starting with an underscore, like _bootstrapServer, are considered private to the file and shouldn't be imported into other modules. (However, this isn't currently enforced.)

In Oak, everything is an expression. Function definitions return the defined function; variable declarations and assignments return the new value; conditional expressions evaluate to their final value. Multiple expressions may be grouped into a single "block" with (...) or {...}, which are themselves expressions that evaluate to the last expression in the block.

Oak doesn't have language constructs for looping like for or while, but has robust support for recursion and optimized tail calls, which is the preferred way of expressing loops — after one iteration, the function calls itself again to run the next iteration. For example, the each standard library function is implemented with a recursive sub-function fn sub:

fn each(xs, f) {
    fn sub(i) if i {
        len(xs) -> ?
        _ -> {
            f(xs.(i), i)
            sub(i + 1)
        }
    }
    sub(0)
}

In practice, we rarely write tail-recursive functions by hand for loops, and instead depend on standard library functions like range, map, each, filter, and reduce to express iteration.

Oak uses one construct for control flow -- the if expression. Unlike a traditional if expression, which can only test for truthy and falsy values, Oak's if acts like a sophisticated switch-case, checking the target value in each "branch" until one that deeply equals the original value is reached.

fn pluralize(word, count) if count {
    1 -> word
    2 -> 'a pair of ' + word + 's'
    _ -> word + 's'
}

The true value of Oak's if expressions is its ability to match against complex shapes of data. For example, you might find this snippet in some server code:

if resp {
    { status: :ok, body: _ } -> handleResponse(resp)
    { status: :error, body: 'unknown' } -> handleUnknownError(resp)
    { status: :error, body: _ } -> handleGenericError(resp)
    _ -> pass(resp)
}

The if expression has a few different shorthands. The following pairs of expressions are equivalent — they're syntactic sugar for each other.

if show? -> showDialog()
if show? {
    true -> showDialog()
}

if {
    first?, last? -> counts.push(count)
    _ -> counts.shuffle()
}
if true {
    first? -> counts.push(count)
    last? -> counts.push(count)
    _ -> counts.shuffle()
}

Oak uses lists and objects to organize state and data in programs.

A list is an ordered sequence of values. We can access and update the value of a list anywhere using an integer index, and append to the end of a list using the << operator. However, we can't remove values from the middle of a list — to do so, we'll need to create a new list that doesn't contain the values we don't want.

fruits := [:apple, :orange]
fruits << :pear
fruits.1 := :grapefruit

// fruits = [:apple, :grapefruit, :pear]

An object is an unordered dictionary relating string keys to arbitrary values. We can access and update values, add new values, and delete values by keys, but the values inserted into an object do not remember the order in which they were added — the order in which Oak loops through items in an object may change randomly.

profile := {
    name: 'Linus Lee'
    age: ?
    work: 'Thought & Craft'
    languages: ['Oak', 'Ink', 'JavaScript', 'Go']
}

// access and update values
profile.age := 23
profile.('work') := 'Writer'

// delete values by assigning _
profile.age := _

// get all keys of the object
keys(profile) // ['name', 'work', 'languages']

Accessing an index that is out of bounds in a list, or accessing an object with a key that doesn't exist on that object, will evaluate to ?, the null value.

Besides the normal set of binary and arithmetic operators, Oak has a few strange operators.

The assignment operator := binds values on the right side to names on the left, potentially by destructuring an object or list. For example:

a := 1              // a is 1
[b, c] := [2, 3]    // b is 2, c is 3
d := double(a)      // d is 2

The nonlocal assignment operator <- binds values on the right side to names on the left, but only when those variables already exist. If the variable doesn't exist in the current scope, the operator ascends up parent scopes until it reaches the global scope to find the last scope where that name was bound.

n := 10
m := 20
{
    n <- 30
    m := 40
}
n // 30
m // 20

The push operator << pushes values onto the end of a string or a list, mutating it, and returns the changed string or list.

str := 'Hello '
str << 'World!' // 'Hello World!'

list := [1, 2, 3]
list << 4
list << 5 << 6 // [1, 2, 3, 4, 5, 6]

The pipe operator |> takes a value on the left and makes it the first argument to a function call on the right.

// print 2n for every prime n in range [0, 10)
range(10) |> filter(prime?) |>
    each(double) |> each(println)

// adding numbers
fn add(a, b) a + b
10 |> add(20) |> add(3) // 33

Oak code is organized into "modules". A module is a single source file, described by its name or relative path. To use functions and variables defined in one file from another file, use the import() function.

std := import('std')
std.println('Hello!')

import('./path/to/module') returns an object whose keys are the names of all variables defined at the module's top-level scope, and whose values are the values of those variables. If you're familiar with JavaScript's require() module system, import() works very similarly, except that there is no explicit module.exports variable.

Standard libraries like std, str, and others can be referenced by their name directly in import. Other modules imported from your file system must be referenced by a relative path, beginning with ./, as in utils := import('./utils').

Because callback-based asynchronous concurrency is common in Oak, there's special syntax sugar, the with expression, to help. The with syntax lets you place the last argument to a function (usually a callback function) after the function call itself, like this.

with readFile('./path') fn(file) {
    println(file)
}

// desugars to
readFile('./path', fn(file) {
    println(file)
})

This syntax makes common callback-based patterns easier to read. For example, to read a file:

std := import('std')
fs := import('fs')

with fs.readFile('./file.txt') fn(file) if file {
    ? -> std.println('Could not read file!')
    _ -> print(file)
}