The Elo Language

Types

Elo has a simple type system with the following types. Use typeOf() to inspect types at runtime.

Note: Use null for absent values. Use isNull() to check for null, and the | operator to provide defaults: x | 'default'.

typeOf(42) == 'Int' and typeOf(P1D) == 'Duration'

Literals

Elo supports numbers, booleans, strings, dates, and durations as first-class values.

Numbers

42 + 3.14

Booleans

true and not false

Strings

'hello world'

Dates & Times

D2025-12-25

TODAY < NOW

SOY <= TODAY and TODAY <= EOY

TODAY in BOT ... EOT

Durations

P1Y2M3D

PT2H30M

Data Paths

.user.address.city

Type Selectors

Literal syntax (like 42 or 'hello') is shorthand for type selectors. Type selectors validate and convert values to specific types. They throw an error if parsing fails.

Int('123')

String(42) + ' items'

Date('2024-12-25')

Data('{"name": "Alice"}').name

Available: Int(), Float(), Bool(), String(), Null(), Date(), Datetime(), Duration(), Data().

Note: Type selectors can be combined into Data Schemas for validating complex data structures.

Operators

Elo provides arithmetic, comparison, and logical operators.

Arithmetic

(10 + 5) * 2 - 8 / 4

2 ^ 10 + 17 % 5

TODAY + P7D

Comparison

10 > 5 and 3 <= 3

Logical

(5 > 3 and 2 < 4) or not (1 == 2)

Pipe Operator

'  hello world  ' |> trim |> upper

'42' |> padStart(5, '0')

Alternative Operator

indexOf('hello', 'x') | indexOf('hello', 'l') | -1

Tuples

Elo tuples are collections of named values. They use JSON-like syntax with key-value pairs and compile to native structures in each target language.

{name: 'Alice', age: 30}

{budget: 1500}.budget

let t = {x: 10, y: 20} in t.x + t.y

Note: Tuples look like JavaScript objects but Elo uses relational terminology. In SQL, they compile to PostgreSQL JSONB using jsonb_build_object().

Lists

Elo lists are ordered sequences using JSON-like array syntax. Lists are heterogeneous and compile to native arrays.

[1, 2, 3]

[1, 'two', true, null]

[[1, 2], [3, 4]]

Note: Lists look like JavaScript arrays but Elo uses relational terminology. In SQL, they compile to PostgreSQL ARRAY[...] syntax.

Lambdas

Elo provides anonymous functions using lambdas:

• Lambdas: fn( params ~> body ) or x ~> body (sugar)

Lambda Expressions

fn( x ~> x * 2 )

fn( x, y ~> x + y )

[1, 2, 3] |> map(x ~> x * 2)

Invoking Lambdas

let double = fn( x ~> x * 2 ) in double(5)

Note: Lambdas compile to JavaScript and Ruby only. SQL does not support function expressions.

Local Variables

Use let ... in expressions to bind local variables.

let x = 10 in x * 2

let width = 5, height = 3 in width * height

Conditionals

Use if ... then ... else expressions to branch based on conditions.

if 5 > 3 then 'yes' else 'no'

let x = 10 in if x > 5 then 'big' else 'small'

Range Membership

Check if a value falls within a range using the in operator.

5 in 1..10

5 in 1...10

TODAY in SOY..EOY

Data Selector

The Data() selector parses JSON strings into Elo values. This is useful when receiving data as text from external sources.

Data('{"name": "Alice", "age": 30}')

Data('[1, 2, 3]')

Data('{"user": {"name": "Bob"}}').user.name

Note: See Type Selectors for all available selectors. For validating and transforming complex JSON structures, see Data Schemas.

Input Data

Every Elo program has access to external input via the special _ variable. When an expression uses _, the compiled output becomes a function that takes input data as a parameter.

_ * 2

_.price * _.quantity

_.budget * 1.21

Note: When using the CLI, use elo with JSON input: elo -e "_.x + _.y" -d '{"x": 1, "y": 2}'

Data Paths

Data paths are syntactic sugar for lists of strings and integers. They provide a concise way to describe locations within nested data structures.

.name

.user.address.city

.items.0.name

Navigating Data

Use fetch() to retrieve values and patch() to update them immutably.

fetch({user: {name: 'Alice'}}, .user.name)

fetch({a: 1, b: 2}, {x: .a, y: .b})

fetch({a: 1, b: 2}, [.a, .b])

patch({user: {name: 'Alice'}}, .user.name, 'Bob')

Note: Since data paths are lists, typeOf(.name) returns 'List'. The stdlib uses "DataPath" as a conceptual name in function signatures.

Data Schemas

Data schemas let you validate and transform complex data structures like JSON. Define schemas using uppercase let bindings with type selectors, then apply them with the pipe operator.

Note: Data schemas compile to JavaScript and Ruby only. SQL is not supported.

Basic Types

All type selectors can be used as schema types: Int, Float, Bool, String, Null, Date, Datetime, Duration, Data. Use . (dot) for any value.

let T = Int in '42' |> T

let T = . in 'anything' |> T

Tuple Types

let Person = { name: String, age: Int } in
{ name: 'Alice', age: '30' } |> Person

let T = { name: String, age :? Int } in
{ name: 'Bob' } |> T

let T = { name: String, ... } in
{ name: 'Eve', extra: 42 } |> T

Array Types

let Numbers = [Int] in ['1', '2', '3'] |> Numbers

let People = [{ name: String }] in
[{ name: 'A' }, { name: 'B' }] |> People

Union Types

let T = Int|String in 'hello' |> T

let T = [Int|String] in ['42', 'hello'] |> T

Subtype Constraints

let Positive = Int(i | i > 0) in '42' |> Positive

let Adult = { age: Int(a | a >= 18) } in
{ age: '25' } |> Adult

let PosEven = Int(i | positive: i > 0, even: i % 2 == 0) in
'42' |> PosEven

let Adult = Int(a | 'must be 18 or older': a >= 18) in
'25' |> Adult

Named Type Aliases

let
  Age = Int(a | a >= 0),
  Person = { name: String, age: Age }
in { name: 'Alice', age: '30' } |> Person

Data Formats

The CLI and playground support multiple input and output formats. Input data is parsed and made available as the _ variable. Results can be formatted for different use cases.

JSON Format

JSON is the default format. Values map directly to Elo types:

upper(_.name) + ' is ' + String(_.age)

CSV Format

CSV input is parsed as a list of tuples. The first row provides field names (headers), and subsequent rows become tuple values. All values are strings.

name,age
Alice,30
Bob,25

[
  {name: 'Alice', age: '30'},
  {name: 'Bob', age: '25'}
]

Since CSV values are strings, you can convert them manually:

_ |> map(r ~> {name: r.name, age: Int(r.age)})

Better approach: Use data schemas to declare a schema. This validates structure and converts types in one step:

let Person = {name: String, age: Int}
in _ |> map(p ~> p |> Person)

Output Formats

Results can be formatted as:

• JSON — Standard JSON serialization (default)
• Elo — Elo code syntax (readable, can be copy-pasted)
• CSV — For lists of tuples (spreadsheet-compatible)

CLI Usage

# JSON input (default)
elo -e "_.x + _.y" -d '{"x": 1, "y": 2}'

# CSV input from file (format auto-detected from .csv extension)
elo -e "map(_, r ~> r.name)" -d @data.csv

# Explicit CSV format
elo -e "map(_, r ~> r.name)" -d @data.txt -f csv

# Output as CSV
elo -e "[{a: 1}, {a: 2}]" -o csv

# Output as Elo code
elo -e "{name: 'test'}" -o elo

Custom Format Adapters

The format system is pluggable. You can provide custom adapters for formats like XLSX using libraries such as PapaParse or SheetJS. See the FormatAdapter interface in src/formats.ts.

Assertions

Use assert() to validate conditions at runtime.

assert(2 + 2 == 4)

indexOf('hello', 'x') | fail('character not found')

Guards

Guards validate conditions before returning a value. Use guard for preconditions and check for postconditions.

guard 5 > 0 in 5 * 2

guard positive: 10 > 0 in 10

guard 10 > 0, 10 < 100 in 10

Let with Guard

let x = 5 guard x > 0 in x * 2

let x = 10 check x > 0 in x + 5

Pipe-Style Guards

5 |> guard(x | x > 0)

Note: Guards compile to JavaScript and Ruby only. Use --strip-guards to remove guards in production builds.

Get Started

Ready to use Elo on your computer? Here's how to get started.

Try Online First

The easiest way to explore Elo is the online playground — no installation needed.

Install the CLI

To run Elo locally, install the command-line tools via npm:

npm install -g @enspirit/elo

This gives you two commands:

• elo — Evaluate Elo expressions and see results immediately
• eloc — Compile Elo to JavaScript, Ruby, or SQL

Quick Examples

# Evaluate an expression
elo -e "2 + 3 * 4"          # => 14

# Evaluate from a file
echo "upper('hello')" > hello.elo
elo hello.elo               # => HELLO

# Compile to JavaScript
eloc -e "2 + 3"             # => (function(_) { return 2 + 3; })

What's Next?

• Learning Elo? Start with the Learn tutorial
• Building an app? See the JavaScript API below
• Need a function? Browse the Standard Library

JavaScript API

For Node.js or browser projects, install the library:

npm install @enspirit/elo

compile()

Every Elo expression compiles to a function that takes _ (the implicit input) as parameter.

import { compile } from '@enspirit/elo';
import { DateTime, Duration } from 'luxon';

const double = compile('_ * 2', { runtime: { DateTime, Duration } });
double(21); // => 42

Lower-Level API

import { parse, compileToJavaScript, compileToRuby, compileToSQL } from '@enspirit/elo';

const ast = parse('2 + 3 * 4');
compileToJavaScript(ast); // => "2 + 3 * 4"
compileToRuby(ast);       // => "2 + 3 * 4"
compileToSQL(ast);        // => "2 + 3 * 4"

Command Line

Elo provides two CLI tools: eloc (compiler) and elo (evaluator).

Evaluator (elo)

Quickly evaluate Elo expressions:

# Evaluate an expression
elo -e "2 + 3 * 4"     # => 14

# Evaluate with input data
elo -e "_.x + _.y" -d '{"x": 1, "y": 2}'   # => 3

# Evaluate from file
elo expressions.elo

Compiler (eloc)

Compile Elo to other languages:

# Compile to JavaScript (default)
eloc -e "2 + 3 * 4"

# Compile to Ruby
eloc -e "2 + 3 * 4" -t ruby

# Compile to SQL
eloc -e "2 + 3 * 4" -t sql

# Include runtime prelude
eloc -e "NOW + PT2H" -t ruby -p