Acord/CORDIAL_GUIDE.md

Cordial Language Reference Guide

Cordial is a simple, expression-based programming language embedded in Swiftly. This guide documents every working feature.

Evaluation Prefix

All evaluation in the editor uses the /= prefix:

/= 2 + 3

Output:

5

Types

Cordial has five value types:

• number: floating-point numbers (internally f64). Displayed as integers when they have no fractional part.
• bool: true or false
• str: strings in double quotes, with escape sequences (\n, \t, \\, \")
• array: ordered collections of values
• void: the value returned by statements with no explicit value

Variables

Declaration

Use let to declare and initialize a variable:

let x = 5
/= x

Output:

5

Type Annotations

Optionally annotate the type after the variable name:

let x: int = 3.7
/= x

Output:

3

Supported type annotations:

• int: truncates numbers to integers
• float: accepts any number (no coercion)
• bool: converts 0 to false, 1 to true; rejects other numbers
• str: only accepts strings

let b: bool = 1
/= b

Output:

true

Assignment

Reassign an existing variable without let:

let x = 5
x = 10
/= x

Output:

10

Operators

Arithmetic

• +: addition or string concatenation
• -: subtraction
• *: multiplication
• /: division (errors on division by zero)
• %: modulo
• ^: exponentiation (right-associative)

/= 2 ^ 3 ^ 2

Output:

512

(Evaluated as 2 ^ (3 ^ 2) = 2 ^ 9 = 512)

Comparison

All comparison operators return booleans:

• <: less than
• >: greater than
• <=: less than or equal
• >=: greater than or equal
• ==: equality
• !=: inequality

/= 5 > 3

Output:

true

Logical

• &&: logical AND (short-circuits)
• ||: logical OR (short-circuits)
• !: logical NOT

/= true && false

Output:

false

/= !true

Output:

false

Operator Precedence

From lowest to highest:

1. ||
2. &&
3. ==, !=, <, >, <=, >=
4. +, -
5. *, /, %
6. ^ (right-associative)
7. unary -, !
8. function calls, array literals

Strings

String literals use double quotes:

/= "hello"

Output:

hello

Escape sequences:

• \n: newline
• \t: tab
• \\: backslash
• \": double quote

String Concatenation

Strings concatenate with the + operator. Numbers and booleans are automatically converted:

/= "value: " + 42

Output:

value: 42

/= 100 + " items"

Output:

100 items

Arrays

Literals

Create arrays with square brackets:

/= [1, 2, 3]

Output:

[1, 2, 3]

Arrays can contain mixed types:

/= [1, "two", true]

Output:

[1, "two", true]

Empty arrays:

/= []

Output:

[]

Indexing

Access elements by index (zero-based):

let arr = [10, 20, 30]
/= arr[1]

Output:

20

Negative indices count from the end:

/= [10, 20, 30][-1]

Output:

30

Out-of-bounds access returns an error.

String Indexing

Strings support the same index syntax, returning individual characters:

/= "hello"[0]

Output:

h

Functions

Definition

Define functions with the fn keyword:

fn add(a, b) {
    a + b
}

The last expression in the function body is returned implicitly. An explicit return statement is also available for early exit.

fn square(x) {
    x * x
}
/= square(5)

Output:

25

Scope

Function parameters are local to the function. The function saves and restores the variable scope:

let x = 10
fn modify() {
    x = 5
}
modify()
/= x

Output:

10

(x inside the function is a separate variable; the outer x is unchanged)

Recursion

Functions can call themselves recursively, up to a maximum call depth of 256:

fn fib(n) {
    let a = 0
    let b = 1
    let i = 0
    while (i < n) {
        let tmp = b
        b = a + b
        a = tmp
        i = i + 1
    }
    a
}
/= fib(10)

Output:

55

Control Flow

While Loops

Loop while a condition is truthy:

let i = 0
let sum = 0
while (i < 10) {
    sum = sum + i
    i = i + 1
}
/= sum

Output:

45

Parentheses around the condition are optional (but recommended for clarity).

Loop safety: while loops are limited to 10,000 iterations to prevent infinite loops.

If/Else

Conditional branching with optional else clause:

let x = 10
if x > 5 {
    x = 1
} else {
    x = 0
}
/= x

Output:

1

Parentheses around the condition are optional. Else-if chaining works:

let grade = 85
let letter = "F"
if grade >= 90 {
    letter = "A"
} else if grade >= 80 {
    letter = "B"
} else if grade >= 70 {
    letter = "C"
}
/= letter

Output:

B

For Loops

Iterate over arrays or ranges:

let sum = 0
for x in [1, 2, 3, 4, 5] {
    sum = sum + x
}
/= sum

Output:

15

Using a range expression (start..end, exclusive of end):

let sum = 0
for i in 0..5 {
    sum = sum + i
}
/= sum

Output:

10

The range(start, end) builtin function also works:

let sum = 0
for i in range(1, 6) {
    sum = sum + i
}
/= sum

Output:

15

For loops are limited to 10,000 iterations.

Return Statements

Use return for early exit from functions:

fn abs_val(x) {
    if x < 0 {
        return -x
    }
    x
}
/= abs_val(-7)

Output:

7

Bare return (with no value) returns false.

Builtin Functions

Math Functions

All math functions accept a single number and return a number:

• sin(x): sine
• cos(x): cosine
• tan(x): tangent
• asin(x): arc sine
• acos(x): arc cosine
• atan(x): arc tangent
• sqrt(x): square root
• abs(x): absolute value
• floor(x): round down
• ceil(x): round up
• round(x): round to nearest integer
• ln(x): natural logarithm
• log(x): base-10 logarithm

/= sqrt(16)

Output:

4

/= abs(-5)

Output:

5

/= floor(3.7)

Output:

3

Range Function

range(start, end) returns an array of numbers from start to end (exclusive):

/= range(0, 5)

Output:

[0, 1, 2, 3, 4]

Length Function

len() returns the length of a string or array:

/= len("hello")

Output:

5

/= len([1, 2, 3])

Output:

3

Truthiness

In boolean contexts (conditions, logical operators), values are truthy or falsy:

• bool: true is truthy, false is falsy
• number: 0 is falsy, all other numbers are truthy
• string: empty string is falsy, all other strings are truthy
• array: empty array is falsy, all other arrays are truthy
• void: falsy
• error: falsy

Truthiness matters for if, while, for conditions and &&/|| operators.

Ranges

The .. operator creates an array from start to end (exclusive):

/= 0..5

Output:

[0, 1, 2, 3, 4]

Ranges are primarily useful with for loops and can be stored in variables.

Negative Numbers

Negative number literals are recognized in appropriate contexts:

/= -5

Output:

-5

/= 10 + -3

Output:

7

The unary minus operator also works:

/= -(5 + 3)

Output:

-8

Error Handling

Errors are propagated as error values and displayed with an error: prefix:

/= undefined_var

Output:

error: undefined variable 'undefined_var'

/= 1 / 0

Output:

error: division by zero

Multiple statements execute in sequence, and errors in one statement don't prevent subsequent statements from executing.

Comments

Single-line comments use //:

// This is a comment
let x = 5
/= x

Comments can appear at the end of lines too.

Examples

Multi-step Calculation

let principal = 1000
let rate = 0.05
let years = 10
let amount = principal * (1 + rate) ^ years
/= amount

Output:

1628.89462382...

Fibonacci

fn fib(n) {
    let a = 0
    let b = 1
    let i = 0
    while (i < n) {
        let tmp = b
        b = a + b
        a = tmp
        i = i + 1
    }
    a
}
/= fib(15)

Output:

610

String Building

let greeting = "Hello"
let name = "World"
/= greeting + ", " + name + "!"

Output:

Hello, World!

Display Formats

Inline (default)

The standard /= prefix displays the result as a single value on the right edge of the editor:

let x = 42
/= x

Result appears as: → 42

Arrays display inline:

/= [1, 2, 3]

Result: → [1, 2, 3]

Table (/=|)

The /=| prefix renders a 2D array (array of arrays) as a visual table overlay:

let data = [["Name", "Age"], ["Alice", 30], ["Bob", 25]]
/=| data

The first row is treated as the header (rendered bold). Each subsequent row becomes a table row. Non-array values fall back to inline display.

Works with any 2D array:

let matrix = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
/=| matrix

Tree (/=\)

The /=\ prefix renders nested data as an indented tree overlay:

let tree = [1, [2, 3], [4, [5, 6]]]
/=\ tree

Nested arrays are expanded with tree-drawing characters showing depth. Leaf values display inline. The root shows the total element count.

Limitations

• No array mutation: Arrays cannot be modified after creation (no arr[i] = val)
• No mutable references: Variable reassignment creates new bindings in the current scope
• Maximum call depth: 256 function calls deep
• Maximum loop iterations: 10,000 iterations per while/for loop
• No user-defined types or structs
• No imports or modules
• No pattern matching or destructuring
• No closures or lambdas