The Suji Programming Language

Welcome to the Suji Programming Language documentation!

Suji is a dynamically-typed scripting language designed for data manipulation, scripting tasks, and general-purpose programming. It combines the expressiveness of modern scripting languages with powerful features like pattern matching, pipes, and native shell integration.

Why Suji?

Suji is built for developers who need:

• Reliable arithmetic - Decimal number semantics eliminate floating-point surprises
• Data transformation power - First-class pipes and functional programming patterns
• Shell integration - Execute commands naturally, without string escaping hell
• Rapid prototyping - Dynamic typing with strict runtime type checking
• Readable code - Clean syntax inspired by functional languages and modern scripting

Who Is Suji For?

Suji is ideal for:

• Data engineers processing JSON, CSV, YAML, and other formats
• DevOps engineers writing automation scripts and configuration tools
• Backend developers building CLI tools and data pipelines
• Anyone who wants a more expressive alternative to shell scripts

Key Features

One Number Type

There is no int versus float split: every number is a base-10 decimal with 28 digits of precision, so arithmetic behaves the way you would work it out on paper.

import std:println

println(0.1 + 0.2)          # 0.3, not 0.30000000000000004
println(0.1 + 0.2 == 0.3)   # true

Pipes and Method Chains

Transform data left to right, either by chaining methods with :: or by piping values into functions with |>:

import std:println

numbers = [1, 2, 3, 4, 5]

println(numbers::map(|x| x * 2)::filter(|x| x > 5)::sum())  # 24

total = |xs| xs::sum()
println(numbers |> total)  # 15

Pattern Matching

match is Suji’s only conditional construct, in a value form and a condition form:

import std:println

describe = |value| match {
    value == 0 => "zero",
    value < 0 => "negative",
    value < 10 => "single digit",
    _ => "large",
}

println(describe(0))    # zero
println(describe(7))    # single digit
println(describe(900))  # large

Native Shell Integration

Run commands with backtick templates; the result is the command’s output:

import std:println

name = "Suji"

println(`echo Hello from ${name}`)  # Hello from Suji
println(`uname -s`::length() > 0)   # true

String Interpolation

Built-in ${expression} syntax, in every kind of string literal and in shell templates:

import std:println

name = "Alice"
age = 30

println("Hello, ${name}! You are ${age} years old.")
println("Next year: ${age + 1}")

A Small Set of Types

Numbers, booleans, strings, lists, maps, tuples, regular expressions, streams, functions and nil — that is the whole list:

import std:println

user = {
    name: "Alice",
    age: 30,
    tags: ["admin", "developer"],
    email: /^[^@]+@[^@]+$/,
}

println(user:name)                        # Alice
println(user:tags::length())              # 2
println("alice@example.com" ~ user:email) # true

Standard Library

Data formats, filesystem and process access, time, hashing, encoding and more — all explicitly imported:

import std:json
import std:yaml
import std:csv
import std:io
import std:path
import std:time
import std:crypto

Quick Example

Here’s what Suji code looks like:

import std:println
import std:json

# Define a data structure
users = [
    {name: "Alice", age: 30, role: "admin"},
    {name: "Bob", age: 25, role: "user"},
    {name: "Charlie", age: 35, role: "user"},
]

# Transform it with a method chain
adult_admins = users
    ::filter(|u| u:age >= 30)
    ::filter(|u| u:role == "admin")
    ::map(|u| u:name)

println(adult_admins)  # [Alice]

# Convert to JSON
output = json:generate({
    admin_users: adult_admins,
    count: adult_admins::length(),
})

println(output)  # {"admin_users":["Alice"],"count":1}

Philosophy

Suji follows these design principles:

1. Clarity over cleverness - Code should be easy to read and understand
2. Explicit is better than implicit - Imports, types, and control flow are clear
3. Composability - Small, focused functions that work together
4. Practical defaults - Common cases should be easy, edge cases possible
5. Progressive disclosure - Learn the basics quickly, discover advanced features gradually

Language Design covers the concrete decisions these principles led to, and what each one costs.

Language Comparison

Coming from another language? Here’s how Suji compares:

Suji is pre-1.0 (currently version 0.1.22) and is installed by building from source. The two most common surprises for newcomers are that there is no if statement and that runtime errors cannot be caught — see Conditional Logic and Error Handling.

Getting Started

Ready to start? Follow these steps:

1. Installation - Install Suji on your system
2. Quick Start - Write your first programs
3. Hello World - Detailed first program walkthrough
4. CLI & REPL - Master the command-line tools

Documentation Structure

This book is organized into several main sections:

For Beginners

• Getting Started - Installation, first steps, and basic usage
• Language Fundamentals - Core language features and syntax
• Functions and Modules - Structure and organize your code

For Practitioners

• Standard Library Reference - Every module, function and signature
• Cookbook - Practical recipes for common tasks
• Examples - Complete example programs

For Deep Divers

• Advanced Topics - Error handling, pattern matching, shell integration, performance
• Development - Building, testing and contributing
• Appendices - Syntax reference, precedence, error codes, glossary

Community and Support

• GitHub: github.com/suji-lang/suji
• Issues: Report bugs and request features

License

Suji is open source, released under a 3-clause BSD license. See the LICENSE file in the repository for the full text.

Enjoy exploring Suji! We hope you find it as expressive and productive as we do.

Installation

Suji is distributed as source code and built with Cargo. There is no published package yet, so every installation starts with a clone and a build.

Prerequisites

• A Unix-like system (macOS or Linux), or Windows with WSL
• The Rust toolchain, stable channel, 1.85 or newer (the workspace uses Rust edition 2024)
• Git

Suji has no C dependencies: every crate it uses is pure Rust, so you do not need OpenSSL or any other system library.

Build from source

1. Install Rust

If you don’t have Rust, install it from rustup.rs:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

If Rust is already installed, make sure it is current:

rustup update stable
rustc --version

2. Clone the repository

git clone https://github.com/suji-lang/suji.git
cd suji

3. Build the interpreter

cargo build --release

The workspace builds the suji-cli package by default, producing the binary at target/release/suji. The Makefile wraps the same commands:

make build     # debug build, faster to compile
make release   # optimized build

4. Put suji on your PATH (optional)

cargo install --path crates/suji-cli

This installs the suji binary into ~/.cargo/bin, which rustup already adds to your PATH. Alternatively, copy the binary yourself:

sudo cp target/release/suji /usr/local/bin/
# or, without sudo
mkdir -p ~/.local/bin && cp target/release/suji ~/.local/bin/

Verify the installation

Suji has no --version or --help flag, so verify it by running a program. Create hello.si:

import std:println

println("Hello, World!")

Then run it:

suji hello.si

Hello, World!

Starting suji with no file argument opens the REPL:

suji

SUJI Language REPL
Type expressions to evaluate them, or :help for commands
Use Ctrl+C to cancel current input, Ctrl+D or :quit to exit

suji>

Type :quit or press Ctrl+D to leave.

Platform notes

macOS

Install the Xcode Command Line Tools if the linker is missing:

xcode-select --install

Apple Silicon builds natively with the ARM64 toolchain; no extra configuration is needed.

Linux

You need a working linker and C toolchain for Rust itself. On Debian/Ubuntu:

sudo apt update
sudo apt install build-essential

On Fedora/RHEL:

sudo dnf install gcc

Windows

Use WSL 2 and follow the Linux instructions. Suji’s own code is platform-independent, but the shell integration (backtick command templates) and parts of std:os assume a Unix shell, so WSL gives the most predictable behaviour.

Troubleshooting

error: package requires rustc 1.85 or newer — run rustup update stable.

Linking errors — install the platform build tools listed above.

Out of memory while compiling — limit parallelism:

cargo build --release -j 2

suji: command not found — the binary is not on your PATH. Run it by path (./target/release/suji program.si), add the directory to your PATH, or use cargo install --path crates/suji-cli.

Working on Suji itself

cargo build            # debug build
cargo run -- examples/hello.si
make test              # Rust tests + spec suite + examples
make lint              # clippy and formatting checks

See the Contributing chapter for the crate layout and testing conventions.

Uninstalling

cargo uninstall suji-cli        # if installed with cargo install
sudo rm /usr/local/bin/suji     # if copied manually

Then delete the cloned repository.

Next steps

1. Work through the Quick Start
2. Walk through a first program in Hello World
3. Learn the tooling in CLI & REPL
4. Read the Language Overview

See Also

• CLI & REPL
• Contributing

Quick Start

Welcome to Suji! This guide will get you up and running in minutes.

What You’ll Learn

In this quick start, you’ll learn:

• How to write your first Suji program
• Basic syntax and structure
• Core language features
• How to run Suji programs

Prerequisites

Make sure you have Suji installed. If not, see the Installation guide.

Your First Program

Let’s start with the classic “Hello, World!”:

import std:println

"Hello, World!" |> println

Save this in a file called hello.si and run it:

suji hello.si

You should see:

Hello, World!

Variables and Functions

Suji makes it easy to work with variables and functions:

import std:println

# Variables are dynamically typed
name = "Alice"
age = 30

# Functions use the |params| syntax
greet = |person| {
    "Hello, ${person}!"
}

# Call the function
message = greet(name)
println(message)  # Hello, Alice!

Lists and Loops

Working with collections is straightforward:

import std:println

# Create a list
numbers = [1, 2, 3, 4, 5]

# Loop through items
loop through numbers with n {
    println(n)
}

Pattern Matching

Suji has powerful pattern matching for control flow:

import std:println

classify = |n| {
    match n {
        0 => "zero",
        1 | 2 | 3 => "small",
        _ => match {
            n < 10 => "medium",
            _ => "large",
        },
    }
}

println(classify(0))   # zero
println(classify(2))   # small
println(classify(5))   # medium
println(classify(42))  # large

Method Chains and Pipes

Transformations read left to right. Chain methods with :::

import std:println

numbers = [1, 2, 3, 4, 5]

result = numbers::map(|x| x * 2)::filter(|x| x > 5)::sum()

println(result)  # 24

Or feed a value into named functions with the pipe-apply operator |>, which passes the value on the left as the single argument to the function on the right:

import std:println

double_all = |xs| xs::map(|x| x * 2)
big_only = |xs| xs::filter(|x| x > 5)
total = |xs| xs::sum()

result = [1, 2, 3, 4, 5]
    |> double_all
    |> big_only
    |> total

println(result)  # 24

Suji also has a shell-style | pipeline for streaming data between closures and shell commands — see Pipe for the difference between the two.

Data Transformation Example

Here’s a more realistic example showing data transformation:

import std:println
import std:json

# Sample data
users = [
  {name: "Alice", age: 30, role: "admin"},
  {name: "Bob", age: 25, role: "user"},
  {name: "Charlie", age: 35, role: "user"},
  {name: "Diana", age: 28, role: "admin"}
]

# Find adult admins
filtered = users::filter(|u| u:age >= 30)
admins = filtered::filter(|u| u:role == "admin")
adult_admins = admins::map(|u| u:name)

println(adult_admins)  # ["Alice"]

Working with JSON

Suji has excellent support for JSON and other data formats:

import std:println
import std:json

# Parse JSON
data = json:parse("""
{
  "name": "Suji",
  "version": "0.1.0",
  "features": ["pipes", "pattern matching", "shell integration"]
}
""")

println(data:name)     # Suji
println(data:version)  # 0.1.0

# Generate JSON
output = json:generate({
  status: "success",
  count: 42
})

println(output)  # {"count":42,"status":"success"}

json:generate writes object keys in sorted order.

Shell Integration

Execute shell commands directly in your code:

import std:println

# A backtick template runs a command and evaluates to its output
host = `uname -s`
println(host)

# Interpolation works inside the command
name = "Suji"
greeting = `echo Hello from ${name}`
println(greeting)  # Hello from Suji

The result is the command’s standard output with the trailing newline removed. A command that exits non-zero raises a runtime error and stops the program, so guard risky commands (for example `grep x file || true`).

Function Composition

Compose functions for cleaner code:

import std:println

double = |x| x * 2
increment = |x| x + 1

# Compose functions with >>
double_then_increment = double >> increment

result = double_then_increment(5)
println(result)  # 11

Next Steps

Now that you’ve seen the basics, explore more:

• Hello World - Detailed breakdown of your first program
• CLI & REPL - Learn about the command-line interface and REPL
• Language Overview - Understand Suji’s design philosophy
• Data Types - Learn about all available types
• Operators - Master Suji’s operators

Try It Yourself

Experiment with these examples:

1. Modify the greeting: Change the greet function to include the age
2. Filter numbers: Use pipes to find all even numbers in a list
3. Parse data: Load a JSON file and extract specific fields
4. Combine patterns: Use pattern matching inside a loop

Common Beginner Mistakes

• Forgetting imports: nothing is available without an import, not even println, and that applies in the REPL too
• Leaving off the last comma in a match: an arm whose body is a bare expression needs a trailing comma, including the final arm
• Reaching for if: Suji has no if, else, for or while — match and loop cover their jobs
• Missing colons in maps: use key: value, not key = value
• Expecting truthiness: &&, || and ! require real booleans, so value || "default" is a type error

Getting Help

If you get stuck:

• Read the error message — diagnostics point at the offending span and carry a numeric code you can look up in Error Codes
• Use the REPL to experiment interactively
• Refer to the Standard Library reference
• Review the Examples section

Happy coding with Suji!

Hello World

Let’s write your first Suji program and understand it step by step.

Your First Program

Create a file called hello.si:

import std:println
println("Hello, World!")

Run it:

suji hello.si

Output:

Hello, World!

Congratulations! You’ve just written and run your first Suji program!

Breaking It Down

Let’s understand what each part does:

Line 1: Import Statement

import std:println

This line imports the println function from Suji’s standard library. In Suji:

• std is the standard library module
• The colon : is used to access nested modules or functions
• println is a function that prints text followed by a newline

Why do we need to import? Suji keeps the global namespace clean. You explicitly import only what you need.

Line 2: Print Statement

The second line, println("Hello, World!"), calls the println function with the string "Hello, World!" as an argument.

• Strings in Suji are enclosed in double quotes " or single quotes '
• Function calls use parentheses: function_name(arguments)
• println adds a newline character after printing

Variations

Using Single Quotes

import std:println
println('Hello, World!')

Single quotes and double quotes behave identically, including for interpolation.

Using print (No Newline)

import std:print
print("Hello, ")
print("World!")

Output:

Hello, World!

The print function doesn’t add a newline, so both calls print on the same line.

Multiple Imports

import std:print
import std:println

print("Hello, ")
println("World!")

You can import multiple functions with separate import statements.

Adding Variables

Let’s make it more interactive:

import std:println

name = "Alice"
println("Hello, ${name}!")

Output:

Hello, Alice!

What’s new?

• name = "Alice" creates a variable called name
• ${name} is string interpolation - it inserts the value of name into the string
• Interpolation works in single-quoted, double-quoted and triple-quoted strings alike, and ${...} can hold any expression

Creating a Function

Let’s turn our greeting into a reusable function:

import std:println

greet = |name| {
    "Hello, ${name}!"
}

message = greet("Alice")
println(message)

Output:

Hello, Alice!

Understanding the function:

• greet = |name| { ... } defines a function called greet
• |name| declares the parameter list (between pipe characters |)
• The function body is in braces { }
• The last expression in a function is automatically returned
• greet("Alice") calls the function with “Alice” as the argument

A More Complete Example

Here’s a program that demonstrates multiple concepts:

import std:println

# Function to create a greeting
greet = |name, language| {
    match language {
        "english" => "Hello, ${name}!",
        "spanish" => "¡Hola, ${name}!",
        "french" => "Bonjour, ${name}!",
        _ => "Hi, ${name}!",
    }
}

# Use the function
names = ["Alice", "Bob", "Charlie"]

loop through names with name {
    message = greet(name, "english")
    println(message)
}

Output:

Hello, Alice!
Hello, Bob!
Hello, Charlie!

What’s happening?

1. We define a greet function that takes two parameters
2. We use match to choose a greeting based on the language
3. Every arm ends with a comma — including the last one, which is required whenever an arm’s body is a plain expression
4. We create a list of names, loop through it, and print each greeting

Common Beginner Mistakes

Mistake 1: Forgetting to Import

Nothing at all is available without an import — there is no prelude:

# println("Hello")
#
# [401] Error: Undefined variable
#        Variable 'println' is not defined

import std:println

println("Hello")

Mistake 2: Leaving Off the Last Comma in a match

import std:println

# This does NOT parse, because the final arm's body is a bare expression:
#
# label = match 1 {
#     1 => "one",
#     _ => "many"
# }

label = match 1 {
    1 => "one",
    _ => "many",
}

println(label)  # one

An arm whose body is a { ... } block may omit the comma; an arm whose body is an expression may not.

Mistake 3: Missing Quotes

import std:println

# println(Hello)
#
# [401] Error: Undefined variable — `Hello` is read as a variable name

println("Hello")

Mistake 4: Reaching for if

Suji has no if, else, for or while keywords. Conditions are match expressions and iteration is loop:

import std:println

temperature = 30

# if temperature > 25 { ... }   <- not valid Suji

message = match {
    temperature > 25 => "warm",
    _ => "cool",
}

println(message)  # warm

Semicolons Are Optional

Coming from JavaScript or Rust, you may reach for semicolons. They are accepted as statement separators but never required, and a newline does the same job:

import std:println

a = 1; b = 2

println(a + b)  # 3

Try It Yourself

Exercise 1: Personalize It

Modify the program to print your own name:

import std:println

your_name = "YourName"  # Change this
println("Hello, ${your_name}!")

Exercise 2: Multiple Greetings

Print three different greetings:

import std:println

name = "Your Name"
# Add code here to print:
# - Good morning, [name]!
# - Good afternoon, [name]!
# - Good evening, [name]!

import std:println

name = "Alice"
println("Good morning, ${name}!")
println("Good afternoon, ${name}!")
println("Good evening, ${name}!")

Exercise 3: Create a Function

Write a function that takes a name and returns a farewell message:

import std:println

farewell = |name| {
    # Your code here — the last expression in the body is the return value
    ""
}

println(farewell("Alice"))  # your version should print: Goodbye, Alice!

import std:println

farewell = |name| {
    "Goodbye, ${name}!"
}

println(farewell("Alice"))

What’s Next?

Now that you’ve written your first program, learn more:

• CLI & REPL - Master the command-line interface and interactive REPL
• Language Overview - Understand Suji’s design philosophy
• Data Types - Learn about strings, numbers, lists, and more
• Functions - Deep dive into function syntax and features

Quick Reference

Here are the key concepts from this chapter:

Keep experimenting and have fun learning Suji!

CLI & REPL

The suji binary does two things: it runs a program file, or it opens an interactive REPL. This chapter covers both, plus the handful of flags that exist.

Running a program

suji script.si

Create greet.si:

import std:println

println("Hello from Suji!")

Run it:

suji greet.si

Hello from Suji!

Relative imports inside the script resolve against the script’s own directory, so you can run it from anywhere.

Command-line flags

Suji’s CLI is deliberately tiny. There is no --help, --version, -e or -c flag; the complete set of options is:

--print-ast is a development aid rather than something you need day to day.

suji --print-ast greet.si        # inspect the parse tree

Exit status

Suji exits with 0 on success and 1 for any diagnosed failure — lexer, parser or runtime. There are no finer-grained diagnostic codes, and a runtime error always terminates the program, since Suji has no error-handling construct. Two failures skip the diagnostic entirely and abort with a Rust panic instead: numeric overflow exits 101 and a stack overflow exits 134.

if suji script.si; then
    echo "Success"
else
    echo "Failed"
fi

Your program can choose its own status with os:exit, which takes any non-negative integer:

import std:os
import std:println

println("done")
os:exit(0)

Script arguments

Arguments arrive through std:env as a map keyed by strings, where "0" is meant to be the script path and "1" the first argument:

import std:println
import std:env

println(env:args::get("0", "(unknown)"))
println(env:args::get("1", "(none)"))
println(env:args::length())

Run with no arguments, that prints the script’s path, (none) and 1.

Known bug in 0.1.22: positional arguments never make it through. Every argument overwrites key "0", so suji args.si alpha beta leaves env:args as {0: beta} — the last argument, with the script path gone and "1" still missing. Pass input through an environment variable or stdin until this is fixed; see std:env.

Arguments that begin with - are consumed by the interpreter itself and never reach env:args at all, so a script cannot take --flag style options.

Reading standard input

A script can read whatever is piped into it through io:stdin:

import std:println
import std:io

lines = io:stdin::read_lines()

println(lines::length())

printf 'a\nb\nc\n' | suji count.si

3

read_all() returns the whole stream as one string and read_line() reads a single line. All stream reads are eager and blocking.

Executable scripts

# starts a comment in Suji, so a shebang line is valid Suji source:

#!/usr/bin/env suji

import std:println

println("This is a Suji script!")

chmod +x script.si
./script.si

The REPL

Run suji with no arguments:

suji

SUJI Language REPL
Type expressions to evaluate them, or :help for commands
Use Ctrl+C to cancel current input, Ctrl+D or :quit to exit

suji>

How evaluation works

The REPL evaluates each complete input and echoes the value of the last statement unless that value is nil. Bindings persist for the session.

suji> 1 + 1
2
suji> "Hello, " + "World!"
Hello, World!
suji> x = 42
42
suji> x * 2
84

Note that values are printed the way to_string() renders them, so strings appear without surrounding quotes.

Imports are still required

There is no prelude and the REPL adds nothing implicitly — println has to be imported here just as it does in a file:

suji> println("hi")
[401] Error: Undefined variable
suji> import std:println
suji> println("hi")
hi
3

That trailing 3 is not a surprise: println returns the number of bytes it wrote, and the REPL echoes the value of the last statement.

Multi-line input

While braces, brackets or parentheses are unbalanced, the REPL switches to the continuation prompt > and keeps reading:

suji> greet = |name| {
  >     "Hello, ${name}!"
  > }
<function>
suji> greet("Alice")
Hello, Alice!

Input completeness is judged by bracket balance, so an expression that is syntactically incomplete without unbalanced brackets (a trailing +, say) is submitted immediately and reports a parse error.

REPL commands

Those three colon commands are the only ones; there is no :load, :type, :vars or :reset. History lives in memory only and is not written to disk.

Things to try in the REPL

Explore data structures:

suji> users = [{name: "Alice", age: 30}, {name: "Bob", age: 25}]
[{name: Alice, age: 30}, {name: Bob, age: 25}]
suji> users[0]:name
Alice
suji> users::map(|u| u:name)
[Alice, Bob]

Build a pipeline one stage at a time:

suji> numbers = [1, 2, 3, 4, 5]
[1, 2, 3, 4, 5]
suji> numbers::map(|x| x * 2)
[2, 4, 6, 8, 10]
suji> numbers::map(|x| x * 2)::filter(|x| x > 5)
[6, 8, 10]
suji> numbers::map(|x| x * 2)::filter(|x| x > 5)::sum()
24

Check a regular expression:

suji> "user@example.com" ~ /^[^@]+@[^@]+\.[^@]+$/
true
suji> "invalid" ~ /^[^@]+@[^@]+\.[^@]+$/
false

Use it as an exact-decimal calculator:

suji> (42 + 8) * 2
100
suji> 100 / 3
33.333333333333333333333333333
suji> 10 ^ 3
1000

REPL limitations

• State is lost when you exit; nothing is saved between sessions.
• A runtime error aborts the current input only — the session survives — but there is still no way for your code to catch it.
• Long programs are easier to iterate on in a file; the REPL is best for checking one expression at a time.

A typical workflow

Sketch the logic in the REPL, then move it into a file once it works:

import std:println
import std:json

data = json:parse('{"users": [{"name": "Alice", "score": 95}, {"name": "Bob", "score": 87}]}')

high_scorers = data:users
    ::filter(|u| u:score >= 90)
    ::map(|u| u:name)

println(json:generate({
    high_scorers: high_scorers,
    count: high_scorers::length(),
}))

{"count":1,"high_scorers":["Alice"]}

(json:generate writes object keys in sorted order, not insertion order.)

Quick reference

suji                          # start the REPL
suji script.si                # run a program
suji script.si a b            # run with positional arguments
suji --print-ast script.si    # print the parse tree
printf 'x\n' | suji script.si # feed standard input

Next steps

• Language Overview — how the language fits together
• Data Types — the eight value types
• Basic Functions — lambda syntax and returns
• Standard Library Overview — what you can import

See Also

• Installation
• Environment
• I/O and Streams

Language Overview

Suji is a dynamically and strongly typed language designed for simplicity and expressiveness.

Key Features

• Dynamic typing: Variables can hold values of any type
• Strong typing: Type safety enforced at runtime
• Higher-order functions: Functions are first-class values
• Closures: Functions can capture variables from their lexical scope
• Pattern matching: match expressions are the only conditional construct — there is no if, else, while or for
• String interpolation: Built-in ${expression} syntax
• Regular expressions: Native regex support with /pattern/ literals
• Shell integration: Execute commands with backticks
• Decimal arithmetic: A single fixed-precision decimal number type (~28–29 significant digits), so 0.1 + 0.2 == 0.3
• Pipe operators: Both stream pipes (|) and function pipes (|> and <|)

Design Philosophy

Suji is designed to be:

• Simple: Familiar syntax that’s easy to learn
• Expressive: Powerful features that reduce boilerplate
• Practical: Built-in support for common tasks (JSON, YAML, shell commands)
• Type-safe: Runtime type checking prevents common errors
• Functional: First-class functions and transformations (map, filter, fold) that return new collections

Type System

Suji is dynamically typed but strongly typed:

• Variables don’t have type annotations
• Types are checked at runtime
• Type mismatches raise clear runtime errors
• Type checking methods available for runtime validation

Syntax Highlights

Functions

Functions are lambdas bound to a name; there is no fn or def declaration form.

# Function definition
add = |x, y| {
    return x + y
}

# Implicit return (last expression)
multiply = |x, y| {
    x * y
}

# Single expression (braces optional)
square = |x| x * x

Pattern Matching

match is Suji’s only conditional construct — there is no if/else. An arm whose body is a bare expression must be followed by a comma, including the last arm.

import std:println

x = 3

# Value matching
result = match x {
    1 => "one",
    2 | 3 => "small",
    _ => "other",
}

# Conditional matching
status = match {
    x > 10 => "large",
    x > 0 => "positive",
    _ => "zero or negative",
}

println(result)  # small
println(status)  # positive

String Interpolation

name = "Alice"
age = 30
message = "Hello, ${name}! You are ${age} years old."
# Works with both single and double quotes
message2 = 'Hello, ${name}!'

Method Calls

# Method syntax with ::
text = "hello"
length = text::length()
upper = text::upper()

# List methods
numbers = [1, 2, 3]
doubled = numbers::map(|x| x * 2)
sum = numbers::sum()

Pipe Operators

import std:println
import std:io

# Function pipe (|>)
result = 5 |> (|x| x * 2) |> (|x| x + 1)
println(result)  # 11

# Stream pipe (|) — connects closures and shell templates
producer = || {
    println("alpha")
    println("beta")
}

consumer = || {
    lines = io:stdin::read_lines()
    println("kept ${lines::length()}")
}

producer() | `grep a` | consumer()  # kept 2

Standard Library

Suji includes a comprehensive standard library:

• Data formats: JSON, YAML, TOML, CSV parsing and generation
• I/O: File operations, streams, standard input/output
• System: Environment variables, command-line arguments, OS utilities
• Math: Trigonometric functions, logarithms, constants
• Crypto: Hash functions (MD5, SHA-1, SHA-256, SHA-512), HMAC
• Time: Current time, sleep, ISO-8601 parsing and formatting
• UUID: Version 4 and 5 UUID generation
• Encoding: Base64, hex, percent encoding
• Random: Random numbers and string generation
• Path: Cross-platform path utilities
• Dotenv: Loading .env files into the environment

Nothing is available without an import — there is no prelude, so even printing needs import std:println.

File Extension

Suji programs use the .si file extension.

Version

Current version: 0.1.22

See Language Versions for detailed version history.

Next Steps

• Learn about Data Types
• Explore Operators
• Study Control Flow
• Check out Functions

Data Types

Suji provides a rich set of data types for representing different kinds of values.

Overview

Understanding data types is fundamental to writing effective Suji programs. This chapter covers all built-in types, their characteristics, operations, and best practices.

Type System

Suji uses dynamic typing - variables can hold any type of value, and types are checked at runtime. However, the type system is strong - operations between incompatible types raise errors rather than coercing values.

# Dynamic typing - no type declarations needed
name = "Alice"      # String
age = 30            # Number
active = true       # Boolean

# Strong typing - no automatic coercion
# result = "5" + 3  # Error: Can't add string and number

# Explicit conversion required
result = "5"::to_number() + 3  # Works: 8

There is also no truthiness. ! and the right-hand side of &&/|| require an actual boolean — !nil and nil || "default" are type errors — and a conditional match only takes an arm whose test is exactly true. nil, 0 and "" are not “falsy”; they simply are not booleans. See Booleans for the details.

Core Types

Primitive Types

Simple, fundamental types:

• Numbers - A single fixed-precision decimal number type
• Booleans - Logical true/false values
• Strings - Unicode text with interpolation
• Nil - Represents absence of a value

Collection Types

Types for grouping multiple values:

• Lists - Ordered, indexed sequences
• Maps - Key-value dictionaries
• Tuples - Fixed-size, immutable collections

Special Types

Types with unique behaviors:

• Regular Expressions - Pattern matching
• Functions - First-class callable values
• Streams - I/O handles for files and standard streams

Type Characteristics

Immutability

Strings and tuples are immutable. Lists and maps are mutable (some methods modify the value in place).

import std:println

# Lists are mutable
list = [1, 2, 3]
list::push(4)
println(list)  # [1, 2, 3, 4]

# Strings are immutable
text = "hello"
upper = text::upper()
println(text)   # hello (unchanged)
println(upper)  # HELLO

Type Checking

Check types at runtime:

import std:println

value = 42

println(value::is_number())      # true
println(value::is_string())      # false
println(value::is_bool())        # false

text = "hello"
println(text::is_string())       # true

Type Conversion

Explicit conversion between types:

import std:println

# Number to string
num = 42
str = num::to_string()
println(str)  # 42

# String to number
text = "123"
num = text::to_number()
println(num)  # 123

# Tuple to list
tuple = (1, 2, 3)
list = tuple::to_list()
println(list)  # [1, 2, 3]

Choosing the Right Type

Use Numbers For:

• Counting, indexing
• Mathematical calculations
• Measurements, coordinates

Use Strings For:

• Text and messages
• User input/output
• File paths, URLs

Use Booleans For:

• Conditional logic
• Flags and toggles
• Validation results

Use Lists For:

• Ordered collections
• Variable-length sequences
• Data transformations

Use Maps For:

• Structured data
• Key-value associations
• JSON-like objects

Use Tuples For:

• Multiple return values
• Fixed-size groups
• Coordinate pairs

Use Functions For:

• Reusable logic
• Callbacks
• Higher-order operations

Use Regex For:

• Pattern matching
• Text validation
• Data extraction

Type Hierarchy

All Types
├── Primitive
│   ├── Number
│   ├── Boolean
│   ├── String
│   └── Nil
├── Collection
│   ├── List
│   ├── Map
│   └── Tuple
└── Special
    ├── Function
    ├── Regex
    └── Stream

Common Patterns

Type Guards

import std:println

process_value = |value| {
    match {
        value::is_number() => "Number: ${value}",
        value::is_string() => "String: ${value}",
        value::is_bool() => "Boolean: ${value}",
        _ => "Unknown type",
    }
}

println(process_value(42))      # Number: 42
println(process_value("hello")) # String: hello
println(process_value(true))    # Boolean: true

Type-Safe Operations

import std:println

safe_add = |a, b| {
    match { a::is_number() && b::is_number() => a + b, _ => nil, }
}

println(safe_add(5, 3))      # 8
println(safe_add("5", 3))    # nil

Polymorphic Functions

import std:println

length_of = |value| {
    match {
        value::is_string() => value::length(),
        value::is_list() => value::length(),
        value::is_map() => value::length(),
        _ => 0,
    }
}

println(length_of("hello"))        # 5
println(length_of([1, 2, 3]))      # 3
println(length_of({a: 1, b: 2}))   # 2

Performance Considerations

Memory Usage

Different types have different memory characteristics:

• Numbers: Fixed size (a 128-bit decimal)
• Booleans: Fixed size
• Strings: Variable, proportional to length
• Lists: Variable, grows with elements
• Maps: Variable, based on number of keys
• Functions: Small closure overhead

Operation Costs

• Number operations: Decimal arithmetic is done in software, so it is slower than hardware floating point but exact in base 10
• String concatenation: Can be slow for many ops (build a list and ::join() instead)
• String indexing: O(n) — indexes and length() count characters, not bytes
• List access: O(1) by index, O(n) by value
• Map access: O(1) average for lookups
• Function calls: Small overhead (closure capture); there are no tail calls, so deep recursion will overflow the stack

Best Practices

DO:

• Use the most appropriate type for your data
• Check types when accepting external input
• Convert types explicitly
• Document expected types in functions
• Use type-safe helper functions

DON’T:

• Expect implicit type coercion — there is none
• Mix types without validation
• Ignore nil possibilities
• Use strings when numbers are more appropriate
• Assume list and map methods copy: push, pop, merge and delete mutate the value in place

Quick Reference

Mutable types are changed in place by a few methods (list::push, list::pop, map::merge, map::delete) and by index assignment; every other method returns a new value and leaves the receiver alone.

Next Steps

Start with the primitive types to build a solid foundation:

1. Numbers - Learn arithmetic and math operations
2. Strings - Master text manipulation
3. Booleans - Understand logical operations
4. Lists - Work with collections
5. Maps - Handle structured data

Then explore special types for advanced use cases.

See Also

• Language Overview
• Operators
• Type Checking
• Performance Guide

Numbers

Numbers in Suji are represented as fixed-precision decimal numbers (base-10 arithmetic).

Overview

Suji has a single number type: Decimal. All numbers are decimal numbers, whether they have a fractional part or not. Integers are simply decimal numbers with no fractional component.

Key Characteristics

• Single type - All numbers are decimals (no separate integer/float types)
• Decimal arithmetic - Base-10 arithmetic, so 0.1 + 0.2 == 0.3 is true
• Fixed precision - About 28–29 significant digits, with a hard maximum of 79228162514264337593543950335. This is not arbitrary precision: exceeding the range aborts the program.
• No NaN/Infinity - Invalid operations raise runtime errors
• Simple literals - Only decimal digits and an optional . (see below)

When to Use Numbers

Use numbers for:

• Counting and indexing
• Mathematical calculations
• Measurements and quantities
• Coordinates and positions
• Financial calculations (decimal arithmetic provides exact precision)

Syntax

All numbers in Suji are decimal numbers. Whether a number has a fractional part or not, it’s still the same decimal type.

Number Literals

import std:println

# Whole numbers (decimals with no fractional part)
age = 30
count = 100
negative = -42

# Decimal numbers (with fractional part)
pi = 3.14159
temperature = -40.5
tiny = 0.000001

println(age)          # 30
println(negative)     # -42
println(temperature)  # -40.5

A number literal is only a run of decimal digits with an optional . and fractional part. The following forms that other languages accept do not exist in Suji, and each one is a lex or parse error:

Negative numbers are not part of the literal syntax either: -42 is unary minus applied to the literal 42.

Very small magnitudes are also limited: a decimal keeps at most 28 digits after the point, so a value like 6.626e-34 simply cannot be represented. Rescale your units instead of trying to write it.

Note: There’s no distinction between “integers” and “floats” in Suji. Both 42 and 42.0 are decimal numbers. The difference is only whether they have a fractional component.

Trailing Zeros and Scale

Every number carries a scale (the number of digits it keeps after the decimal point), and arithmetic keeps the larger scale of its operands:

import std:println

println(1.50)       # 1.50   (scale preserved)
println(2.50 + 1)   # 3.50
println(1.0)        # 1      (a literal with only zeros normalises)
println(42.0)       # 42

Arithmetic Operations

Basic Operations

import std:println

# Addition
println(5 + 3)        # 8

# Subtraction
println(10 - 4)       # 6

# Multiplication
println(6 * 7)        # 42

# Division (always returns decimal result)
println(15 / 3)       # 5
println(10 / 3)       # 3.3333333333333333333333333333 (rounded at 28 digits)

# Floor division (get integer part)
println((10 / 3)::floor())  # 3

# Modulo (remainder)
println(10 % 3)       # 1

# Exponentiation (the exponent must be a whole number)
println(2 ^ 10)       # 1024

# For roots use the sqrt() method, not a fractional exponent:
# 4 ^ 0.5 is a runtime error, "Power exponent must be an integer"
println(4::sqrt())    # 2

^ is right-associative and binds tighter than unary minus, so 2 ^ 3 ^ 2 is 512 (not 64) and -2 ^ 2 is -4 (not 4).

Compound Assignment

import std:println

x = 10

x += 5   # x is now 15
x -= 3   # x is now 12
x *= 2   # x is now 24
x /= 4   # x is now 6
x %= 4   # x is now 2

println(x)  # 2

# Postfix increment and decrement are statements, not expressions
x++
println(x)  # 3
x--
println(x)  # 2

Operator Precedence

import std:println

# Standard precedence (PEMDAS)
result = 2 + 3 * 4    # 14, not 20
println(result)

# Use parentheses for clarity
result = (2 + 3) * 4  # 20
println(result)

# Exponentiation has highest precedence
result = 2 * 3 ^ 2    # 18 (2 * 9)
println(result)

Comparison Operations

import std:println

# Equality
println(5 == 5)       # true
println(5 == 6)       # false
println(5 != 6)       # true

# Relational
println(5 < 10)       # true
println(5 > 10)       # false
println(5 <= 5)       # true
println(10 >= 10)     # true

Mathematical Functions

Arithmetic that works on a single number is exposed as methods on the number itself. The std:math module contains only the transcendental functions and two constants.

Basic Math (number methods)

import std:println

# Absolute value
println((-5)::abs())      # 5

# Rounding
println(3.7::floor())     # 3
println(3.2::ceil())      # 4
println(3.5::round())     # 4
println(3.4::round())     # 3

# Min/Max (a method on one of the two values)
println(5::min(10))       # 5
println(5::max(10))       # 10

# Power and square root
println(2::pow(10))       # 1024
println(16::sqrt())       # 4

There is no math:abs, math:floor, math:ceil, math:round, math:min, math:max, math:pow, math:sqrt or math:cbrt. Use the methods above. Suji has no cube-root operation at all; 27 ^ (1/3) will not work either because ^ requires a whole-number exponent. If you need one, write a Newton-iteration helper yourself.

sqrt() returns a decimal approximation for non-perfect squares:

import std:println

println(2::sqrt())   # 1.4142135623730950488016887242

pow() requires a non-negative whole-number exponent (2::pow(-1) fails with Negative exponents not supported).

Both ^ and pow() overflow far earlier than plain multiplication does. They work by repeated squaring and square the base once more than the result needs, so the intermediate value exceeds the decimal range long before the answer would:

import std:println

println(10 ^ 15)  # 1000000000000000
println(2 ^ 63)   # 9223372036854775808

10 ^ 16 and 2 ^ 64 both abort the program, even though both results are comfortably inside the decimal range — 1000000000000000 * 10 * 10 computes 100000000000000000 without complaint. Overflow is not a catchable Suji error either: it is a panic that prints Multiplication overflowed and exits with status 101 instead of a framed diagnostic.

Trigonometry

import std:math
import std:println

# Angles in radians
println(math:sin(math:PI / 2))    # 1
println(math:cos(0))              # 1

# Trig results are approximations, so don't expect exact values
println(math:tan(math:PI / 4))    # 0.9999999956815324130588099842

# Inverse functions
println(math:asin(1))      # 1.570796326794897   (π/2)
println(math:acos(1))      # 0
println(math:atan(1))      # 0.785398163397448   (π/4)
println(math:atan2(1, 1))  # 0.785398163397448   (two-argument arctangent)

There are no hyperbolic functions (sinh, cosh, tanh) and no inverse hyperbolics.

Logarithms and Exponentials

import std:math
import std:println

# Natural logarithm
println(math:log(math:E))  # 0.9999999999999999999998942453

# Base 10 logarithm
println(math:log10(100))   # 2

# Exponential
println(math:exp(1))       # 2.7182818261984928651595318263

# Constants (uppercase)
println(math:PI)           # 3.14159265358979323846
println(math:E)            # 2.71828182845904523536

The complete contents of std:math are PI, E, sin, cos, tan, asin, acos, atan, atan2, log, log10 and exp. There is no log2, hypot, sign, clamp, trunc or random (for randomness see std:random).

Number Methods

Type Checking

import std:println

# Check if a number has no fractional part (is an integer)
println(42::is_int())        # true (no fractional part)
println(3.14::is_int())      # false (has fractional part)
println(42.0::is_int())      # true (no fractional part, even with .0)

# Check if a value is a number
println(42::is_number())         # true
println("text"::is_number())    # false

# Note: Suji uses decimal arithmetic, so NaN and Infinity don't exist
# Division by zero raises a runtime error instead

Conversion

import std:println

# To string
println(42::to_string())         # 42
println(3.14::to_string())       # 3.14

# Parse from string
num = "42"::to_number()
println(num)                   # 42

decimal = "3.14"::to_number()
println(decimal)               # 3.14

to_number() raises a runtime error on input that isn’t a number, and Suji has no way to trap a runtime error, so validate the text before converting:

import std:println

parse_or_nil = |text| {
    match {
        text ~ /^-?[0-9]+(\.[0-9]+)?$/ => text::to_number(),
        _ => nil,
    }
}

println(parse_or_nil("42"))     # 42
println(parse_or_nil("abc"))    # nil

Formatting

import std:println

# Rounding methods
num = 3.14159
println(num::round())    # 3
println(num::floor())    # 3
println(num::ceil())     # 4

# Note: number::to_fixed(), to_exponential() and to_precision() do not exist.
# To show a fixed number of decimals, scale, round and divide yourself:
two_dp = |x| (x * 100)::round() / 100
println(two_dp(3.14159))  # 3.14
println(two_dp(2.5))      # 2.50
println(two_dp(2))        # 2

This rounds correctly, but how many decimals get printed still depends on the input’s scale: two_dp(2) shows 2, not 2.00. Suji has no formatting mini-language, so pad the string yourself when you need fixed-width output.

Number Ranges

import std:println

# Range literals (list of numbers)
range1 = 0..5          # [0, 1, 2, 3, 4]
range2 = 0..=5         # [0, 1, 2, 3, 4, 5] (inclusive)
range3 = 5..0          # [5, 4, 3, 2, 1] (descending)

println(range1)

# Note: Suji doesn't support step ranges directly
# Use filter to get evens/odds:
evens = (0..10)::filter(|x| x % 2 == 0)  # [0, 2, 4, 6, 8]
odds = (1..10)::filter(|x| x % 2 == 1)   # [1, 3, 5, 7, 9]

println(evens)

Special Values

Division by Zero

Suji uses decimal arithmetic and raises a runtime error on division by zero:

import std:println

# Division by zero raises a runtime error
# result = 1 / 0  # Runtime error

# Check before dividing
safe_divide = |a, b| {
    match b {
        0 => nil,
        _ => a / b,
    }
}

println(safe_divide(10, 2))  # 5
println(safe_divide(10, 0))  # nil

Note: Suji does not have Infinity or NaN values. Invalid operations raise runtime errors instead.

Common Patterns

Clamping

import std:println

clamp = |value, min_val, max_val| {
    match {
        value < min_val => min_val,
        value > max_val => max_val,
        _ => value,
    }
}

println(clamp(5, 0, 10))      # 5
println(clamp(-5, 0, 10))     # 0
println(clamp(15, 0, 10))     # 10

Linear Interpolation

import std:println

lerp = |a, b, t| {
    a + (b - a) * t
}

# Interpolate between 0 and 100
println(lerp(0, 100, 0.0))    # 0
println(lerp(0, 100, 0.5))    # 50
println(lerp(0, 100, 1.0))    # 100

Range Mapping

import std:println

# Map value from one range to another
map_range = |value, in_min, in_max, out_min, out_max| {
    (value - in_min) * (out_max - out_min) / (in_max - in_min) + out_min
}

# Map 0-100 to 0-1
println(map_range(50, 0, 100, 0, 1))   # 0.50

# Map 0-255 to 0-100 (RGB to percentage)
println(map_range(128, 0, 255, 0, 100)) # 50.196078431372549019607843137

Note the 0.50 in the first result: division keeps the scale of its operands, so round explicitly when the exact number of decimals matters.

Averaging

import std:println

numbers = [1, 2, 3, 4, 5]

# Mean (::average() does the same thing, and returns nil for an empty list)
mean = numbers::sum() / numbers::length()
println(mean)                # 3
println(numbers::average())  # 3

# Median
sorted = numbers::sort()
median = match sorted::length() % 2 {
    0 => {
        mid = sorted::length() / 2
        (sorted[mid - 1] + sorted[mid]) / 2
    },
    _ => {
        mid = (sorted::length() / 2)::floor()
        sorted[mid]
    },
}
println(median)  # 3

Common Pitfalls

Pitfall 1: Decimal Precision

import std:println

# Decimal arithmetic is exact for values that fit in base 10
println(0.1 + 0.2 == 0.3)     # true
println(0.1 + 0.2)            # 0.3

# But precision is finite: repeating divisions are rounded to 28 digits
println(1 / 3)                # 0.3333333333333333333333333333
println((1 / 3) * 3 == 1)     # false

So the familiar 0.1 + 0.2 surprise is gone, but you can still lose digits. Anything that does not terminate in base 10 is rounded, and results larger than 79228162514264337593543950335 abort the program instead of wrapping or becoming infinity.

Pitfall 2: Division by Zero

import std:println

# Division by zero raises a runtime error (not infinity)
# result = 10 / 0  # Runtime error: "Division by zero"

# Check before dividing
divide_safe = |a, b| {
    match b {
        0 => nil,
        _ => a / b,
    }
}

println(divide_safe(10, 2))  # 5
println(divide_safe(10, 0))  # nil

Pitfall 3: Whole Number vs Decimal Division

import std:println

# Suji uses decimal division (always returns decimal result)
println(10 / 3)              # 3.3333333333333333333333333333 (exact decimal)
println((10 / 3)::floor())   # 3 (get whole number part using floor)

# All numbers are decimals, so division always returns a decimal
# Use floor() if you need the whole number part

Pitfall 4: Modulo with Negatives

import std:println

# Result has sign of dividend
println(10 % 3)       # 1
println(-10 % 3)      # -1
println(10 % -3)      # 1

Performance Tips

All Numbers Are Decimals

# All numbers are decimals, so there's no "conversion" between types
count = 0
count = count + 1

# Adding 1.0 is the same as adding 1 (both are decimals)
count = count + 1.0  # Same result

# The only difference is whether the result has a fractional part
whole = 42        # Decimal with no fractional part
decimal = 42.5    # Decimal with fractional part
# Both are the same type: Decimal

Decimal arithmetic is implemented in software rather than by the CPU’s floating-point unit, so it is exact but not free. In hot loops, hoist work that does not depend on the loop variable.

Avoid Repeated Calculations

import std:println

items = [1, 2, 3, 4]

# Recalculates the square root on every iteration
total = 0
loop through items with item {
    total += item / items::length()::sqrt()
}
println(total)  # 5

# Calculate once, outside the loop
sqrt_len = items::length()::sqrt()
total = 0
loop through items with item {
    total += item / sqrt_len
}
println(total)  # 5

Best Practices

DO:

• Handle division by zero before it happens (it raises a runtime error that cannot be caught)
• Use exact decimal comparisons for terminating values (no epsilon needed)
• Round explicitly with round()/floor()/ceil() when a result’s scale matters
• Keep magnitudes well inside the 28–29 significant digit range
• Document units and ranges

DON’T:

• Think of numbers as separate integer/float types (they’re all decimals)
• Assume arbitrary precision — overflow aborts the program
• Ignore division by zero (it raises an error, not infinity)
• Expect NaN or Infinity (invalid operations raise runtime errors)
• Reach for math: for abs/round/sqrt/pow/min/max — those are number methods

Next Steps

• Learn about Booleans for logical values
• Explore the Math Module for trigonometry and logarithms
• Study Operators in detail

See Also

• Booleans
• Math Module
• Arithmetic Operators

Booleans

Booleans represent logical truth values: true or false.

Overview

Booleans are fundamental for control flow, conditionals, and logical operations.

Key Characteristics

• Two values - Only true or false
• Logical operators - &&, ||, ! (there are no and/or/not keywords)
• Comparison results - All comparisons return booleans
• Short-circuit evaluation - Efficient logical operations
• No truthiness - Other types are not “falsy”; !nil and nil || "x" are type errors, and a conditional match only takes an arm that tests true

When to Use Booleans

Use booleans for:

• Conditional logic (match)
• Flags and toggles
• Validation results
• State tracking (enabled/disabled, active/inactive)
• Filter conditions

Syntax

Boolean Literals

import std:println

# The two boolean values
is_valid = true
is_active = false

# In expressions
user_logged_in = true
debug_mode = false

println(is_valid)   # true
println(debug_mode) # false

Logical Operators

AND (&&)

Both operands must be true:

import std:println

println(true && true)     # true
println(true && false)    # false
println(false && true)    # false
println(false && false)   # false

# Short-circuit: second operand not evaluated if first is false
result = false && (10 / 0)  # No error - second part not evaluated

OR (||)

At least one operand must be true:

import std:println

println(true || true)     # true
println(true || false)    # true
println(false || true)    # true
println(false || false)   # false

# Short-circuit: second operand not evaluated if first is true
result = true || (10 / 0)   # No error - second part not evaluated

NOT (!)

Negates a boolean value:

import std:println

println(!true)            # false
println(!false)           # true
println(!!true)           # true (double negation)

Comparison Operators

All comparison operators return booleans:

Equality

import std:println

println(5 == 5)           # true
println(5 == 6)           # false
println(5 != 6)           # true
println("hello" == "hello") # true

Relational

import std:println

println(5 < 10)           # true
println(5 > 10)           # false
println(5 <= 5)           # true
println(10 >= 10)         # true

String Comparison

import std:println

println("apple" < "banana")   # true (lexicographic)
println("zebra" > "aardvark") # true

Compound Conditions

Combining Operators

import std:println

age = 25
has_license = true

# Can drive if adult with license
can_drive = age >= 18 && has_license
println(can_drive)  # true

# Student or senior discount
age = 70
is_student = false
gets_discount = is_student || age >= 65
println(gets_discount)  # true

Operator Precedence

import std:println

# NOT has highest precedence
println(!false && true)          # true  (parsed as (!false) && true)

# AND before OR
println(true || false && false)  # true  (parsed as true || (false && false))

# Use parentheses for clarity
println((true || false) && false)  # false

Short-Circuit Evaluation

AND Short-Circuit

import std:println

# Second expression only evaluated if first is true
check_user = |user| {
    user != nil && user:is_active
}

# Safe - doesn't error on nil user
println(check_user(nil))  # false

OR Short-Circuit

import std:println

# The right side is only evaluated when the left side is not `true`
is_weekend = |day| day == "sat" || day == "sun"

println(is_weekend("sat"))  # true
println(is_weekend("mon"))  # false

# Falling back to a default needs a match: `||` will not accept a non-boolean
get_name = |user| {
    match user != nil && user:name != nil {
        true => user:name,
        false => "Guest",
    }
}

println(get_name(nil))              # Guest
println(get_name({name: "Alice"}))  # Alice

Truthiness

Suji has no truthiness. Only the value true is true, and non-boolean values are never coerced:

• true && expr evaluates expr, which must itself be a boolean
• anything other than true on the left of && behaves like false and short-circuits, without complaining about its type
• a non-boolean on the right of &&/|| is a type error once it is reached: true && 5 fails with Logical AND requires boolean operands, and nil || "default" fails with Logical OR requires boolean operands
• ! always requires a boolean: !nil and !5 are type errors

import std:println

# Only boolean `true` counts as true on the left:
println(true && true)       # true
println(5 && true)          # false
println("hello" && true)    # false

# Use comparisons so both sides are really booleans:
text = "hello"
println(text != "" && true) # true

Because || is strict about its right-hand side, the value || fallback idiom from other languages does not exist in Suji. Use a match or, for maps, map::get(key, default):

import std:println

settings = {"retries": 3}

# NOT: settings:timeout || 30      (type error, and a missing key raises anyway)
timeout = settings::get("timeout", 30)
println(timeout)  # 30

Converting to Boolean

import std:println

# Nil check
value = nil
is_present = value != nil
println(is_present)  # false

# Empty check
list = []
is_empty = list::length() == 0
println(is_empty)  # true

# Non-empty
text = "hello"
has_text = text::length() > 0
println(has_text)  # true

Common Patterns

Validation

import std:println

validate_user = |user| {
    has_name = user:name != nil && user:name::length() > 0
    has_email = user:email != nil && user:email ~ /^[^@]+@[^@]+$/
    is_adult = user:age != nil && user:age >= 18
    
    has_name && has_email && is_adult
}

user = {
    name: "Alice",
    email: "alice@example.com",
    age: 30
}

println(validate_user(user))  # true

Note that user:name raises Key not found if the key is absent, so user:name != nil only guards against an explicit nil value. To tolerate missing keys, read them with user::get("name"), which returns nil instead.

Flags and Toggles

import std:println

# Feature flags
config = {
    dark_mode: true,
    notifications: false,
    beta_features: true
}

# Toggle a flag
config:dark_mode = !config:dark_mode
println(config:dark_mode)  # false (toggled)

Conditional Assignment

import std:println

# Using match
status = true
message = match status {
    true => "Enabled",
    false => "Disabled",
}
println(message)  # Enabled

# Using ternary-style match (note the comma after the last arm)
is_admin = true
role = match { is_admin => "Administrator", _ => "User", }
println(role)  # Administrator

Guard Clauses

import std:println

process_user = |user| {
    # Early returns for validation
    user == nil && return "Error: No user"
    !user:is_active && return "Error: User not active"
    user:age < 18 && return "Error: User must be adult"
    
    # Main logic here
    "User processed successfully"
}

println(process_user(nil))  # Error: No user
println(process_user({is_active: false, age: 25}))  # Error: User not active

Boolean Methods

Type Checking

import std:println

println(true::is_bool())     # true
println(false::is_bool())    # true
println(1::is_bool())        # false
println("true"::is_bool())   # false

Conversion

import std:println

# To string
println(true::to_string())   # true
println(false::to_string())  # false

# Parse from string (simple example)
parse_bool = |s| {
    match s {
        "true" => true,
        "false" => false,
        _ => nil,
    }
}
println(parse_bool("true"))   # true
println(parse_bool("false"))  # false

XOR (Exclusive OR)

XOR is true when operands differ:

import std:println

# Manual XOR
xor = |a, b| {
    (a || b) && !(a && b)
}

println(xor(true, true))       # false
println(xor(true, false))      # true
println(xor(false, true))      # true
println(xor(false, false))     # false

# Simpler: != for booleans
println(true != true)          # false
println(true != false)         # true

Common Pitfalls

Pitfall 1: Comparing with True/False

import std:println

is_valid = true

# Unnecessary comparison
println(match { is_valid == true => "yes", _ => "no", })   # yes

# Use the boolean directly
println(match { is_valid => "yes", _ => "no", })           # yes

# Unnecessary comparison
println(match { is_valid == false => "yes", _ => "no", })  # no

# Use negation
println(match { !is_valid => "yes", _ => "no", })          # no

Pitfall 2: Confusing = and ==

import std:println

# Assignment, not comparison
x = 5
x = 10

# Comparison (use this in conditions)
println(match { x == 10 => "ten", _ => "something else", })  # ten

Pitfall 3: Non-Boolean in Conditionals

import std:println

# A conditional match only takes an arm whose test is exactly `true`.
# Any other value simply fails to match:
text = "hello"
println(match { text => "matched", _ => "fell through", })       # fell through

# Explicit check
println(match { text != "" => "matched", _ => "fell through", }) # matched

# Numbers are not truthy either
count = 0
println(match { count => "matched", _ => "fell through", })      # fell through

# Explicit comparison
println(match { count == 0 => "matched", _ => "fell through", }) # matched

Pitfall 4: Operator Precedence

import std:println

# `!` binds tighter than `&&`, so this is (!false) && true
result = !false && true
println(result)  # true

# If you meant to negate the whole conjunction, use parentheses
result = !(false && true)
println(result)  # true

Examples

All/Any for Lists

Lists have no built-in any() or all(), so write them yourself with a loop and an early return:

import std:println

all = |list, predicate| {
    loop through list with item {
        !predicate(item) && return false
    }
    true
}

any = |list, predicate| {
    loop through list with item {
        predicate(item) && return true
    }
    false
}

numbers = [2, 4, 6, 8]

# All even?
all_even = all(numbers, |x| x % 2 == 0)
println(all_even)  # true

# Any odd?
any_odd = any(numbers, |x| x % 2 == 1)
println(any_odd)  # false

Boolean Algebra

import std:println

# De Morgan's Laws
a = true
b = false

# !(a && b) == !a || !b
println(!(a && b) == (!a || !b))  # true

# !(a || b) == !a && !b
println(!(a || b) == (!a && !b))  # true

State Machine

import std:println

# A map literal with bare identifier keys is parsed as a block when it is the
# whole body of a match arm, so quote the keys here.
traffic_light = |state| {
    match state {
        "red" => {"running": false, "warning": false},
        "yellow" => {"running": true, "warning": true},
        "green" => {"running": true, "warning": false},
        _ => {"running": false, "warning": false},
    }
}

state = traffic_light("yellow")
println("Running: ${state:running}")      # true
println("Warning: ${state:warning}")      # true

Best Practices

DO:

• Use boolean values directly in conditionals
• Use descriptive names (is_active, has_permission)
• Keep conditions simple and readable
• Use short-circuit evaluation for safety
• Prefer early returns for validation

DON’T:

• Compare booleans to true or false
• Create complex nested conditions
• Use non-descriptive names (flag, b, x)
• Rely on implicit truthiness (Suji requires explicit booleans)

Next Steps

• Learn about Conditional Logic
• Explore Pattern Matching with booleans
• Study Logical Operators in depth
• Check out Relational Operators

See Also

• Conditional Logic
• Match Expressions
• Logical Operators
• Relational Operators

Strings

Strings represent text in Suji. They support Unicode, interpolation, and rich manipulation methods.

Overview

Strings are sequences of Unicode characters used for text processing.

Key Characteristics

• UTF-8 encoding - Full Unicode support
• String interpolation - Embed expressions with ${...}
• Immutable - Operations create new strings
• Two quote styles - Single ' or double "
• Multiline support - Triple quotes """..."""

When to Use Strings

Use strings for:

• Text and messages
• User input/output
• File paths and URLs
• Configuration values
• Template generation

Syntax

Single and Double Quotes

import std:println

# Single quotes
name = 'Alice'
path = '/tmp/file.txt'

# Double quotes
greeting = "Hello"
message = "Welcome to Suji"

println("${greeting}, ${name}!")  # Hello, Alice!
println(path)                     # /tmp/file.txt

Both work the same for simple strings. String interpolation works with both quote types.

String Interpolation

Works with both single and double quotes:

import std:println

name = "Alice"
age = 30

# Interpolate variables
println("Hello, ${name}!")  # Hello, Alice!
println('Hello, ${name}!')  # Hello, Alice! (also works with single quotes)

# Interpolate expressions
println("Age: ${age + 1}")  # Age: 31

# Multiple interpolations
println("${name} is ${age} years old")

Multiline Strings

Use triple quotes for multiline text:

import std:println

text = """
This is a
multiline
string
"""

println(text)

Escape Sequences

The supported escapes are exactly \n, \t, \r, \", \', \`, \\ and \$:

import std:println

newline = "Line 1\nLine 2"
tab = "Column 1\tColumn 2"
quote = "He said \"Hello\""
backslash = "Path: C:\\Users\\Alice"
dollar = "Costs \${amount}"   # escape $ to keep it literal

println(newline)
println(tab)
println(quote)
println(backslash)
println(dollar)  # Costs ${amount}

Any other escape is a lex error, including the Unicode escapes you may know from other languages: \u2764, \u{1F600}, \x41, \0 and \e are all rejected with Invalid escape sequence. To put a non-ASCII character in a string, type the character itself — Suji source is UTF-8:

import std:println

heart = "❤"
println(heart)  # ❤

There are also no raw strings; use \\ for a literal backslash.

String Operations

Concatenation

import std:println

first = "Hello"
last = "World"

# Using +
result = first + " " + last
println(result)  # Hello World

# Using interpolation
result = "${first} ${last}"
println(result)  # Hello World

Length

import std:println

text = "Hello"
println(text::length())  # 5

# Counts characters, not bytes
accented = "café"
println(accented::length())  # 4

Indexing

Access characters by position (0-based):

import std:println

text = "Hello"
println(text[0])  # H
println(text[4])  # o

# Negative indices count from end
println(text[-1])  # o
println(text[-2])  # l

Slicing

Extract substrings using semicolon syntax:

import std:println

text = "Hello, World!"

# Range [start;end) - includes start, excludes end
println(text[0;5])    # Hello
println(text[7;12])   # World

# From start
println(text[;7])     # Hello,

# To end
println(text[7;])      # World!

String Methods

Case Conversion

import std:println

text = "Hello World"

println(text::upper())        # HELLO WORLD
println(text::lower())        # hello world

Trimming

import std:println

text = "  hello  "

println(text::trim())         # hello

# Trim specific characters
text = "***hello***"
println(text::trim("*"))      # hello

trim() always trims both ends. There is no trim_start() or trim_end().

Searching

import std:println

text = "Hello, World!"

# Contains
println(text::contains("World"))    # true
println(text::contains("xyz"))      # false

# Starts with / ends with
println(text::starts_with("Hello")) # true
println(text::ends_with("!"))       # true

# Find position
println(text::index_of("World"))    # 7
println(text::index_of("xyz"))      # -1 (not found)

Splitting

import std:println

text = "apple,banana,cherry"

# Split by delimiter
fruits = text::split(",")
println(fruits)  # [apple, banana, cherry]

# Split by space (default separator is `" "`)
text = "one two three"
words = text::split()
println(words)  # [one, two, three]

split() takes a plain string separator only — you cannot split on a regex.

Replacing

import std:println

text = "Hello, World!"

# Replace all occurrences
result = text::replace("World", "Suji")
println(result)  # Hello, Suji!

# Replace in a string with multiple occurrences
text = "foo bar foo"
result = text::replace("foo", "baz")
println(result)  # baz bar baz

Both arguments must be strings. text::replace(/foo/, "baz") is a type error — there is no regex-based replacement in Suji.

Repeating

import std:println

println("*"::repeat(5))      # *****
println("ab"::repeat(3))      # ababab

Reversing

import std:println

text = "Hello"
println(text::reverse())     # olleH

Converting to List

import std:println

text = "hello"
chars = text::to_list()
println(chars)  # [h, e, l, l, o]

to_list() is also how you iterate a string — a string is not directly iterable (see Character Iteration below).

Methods That Do Not Exist

The complete string method list is length, split, to_number, to_list, index_of, contains, starts_with, ends_with, replace, trim, upper, lower, reverse, repeat, to_string (plus the is_* type predicates).

Pattern Matching

With Regular Expressions

import std:println

email = "user@example.com"

# Match operator
is_valid = email ~ /^[^@]+@[^@]+\.[^@]+$/
println(is_valid)  # true

text = "Call me at 555-1234"
words = text::split(" ")
phones = words::filter(|w| w ~ /^\d{3}-\d{4}$/)
match {
    phones::length() > 0 => { println("Found phone: " + phones[0]) },
    _ => println("No phone found"),
}

See Regular Expressions for more details.

Advanced Patterns

Template Strings

import std:println

template = |name, age| {
    """
    Name: ${name}
    Age: ${age}
    Status: ${match { age >= 18 => "Adult", _ => "Minor", }}
    """
}

println(template("Alice", 30))

String Builder Pattern

For building strings efficiently:

import std:println

build_html = |items| {
    html = "<ul>"
    loop through items with item {
        html = html + "<li>${item}</li>"
    }
    html = html + "</ul>"
    html
}

items = ["Apple", "Banana", "Cherry"]
println(build_html(items))

Multi-line with Indentation

import std:println

query = """
    SELECT *
    FROM users
    WHERE age >= 18
      AND status = 'active'
    ORDER BY name
"""

println(query)

Type Conversion

To String

import std:println

# Numbers
println(42::to_string())       # 42

# Booleans
println(true::to_string())     # true

# Lists/Maps
println([1, 2, 3]::to_string())  # [1, 2, 3]

to_string() is required whenever you mix types with +: "n = " + 1 is a type error, while "n = " + 1::to_string() (or just "n = ${1}") works.

From String

import std:println

# Parse number
num = "42"::to_number()
println(num)                   # 42

# Parse boolean
parse_bool = |s| {
    match s {
        "true" => true,
        "false" => false,
        _ => nil,
    }
}
println(parse_bool("true"))    # true

Unicode Support

Unicode Length

String::length() counts Unicode scalar values (Rust chars), not grapheme clusters:

import std:println

text = "Hello World"
println(text::length())         # 11

# Diacritics: a precomposed é is one scalar value
text = "café"
println(text::length())         # 4

# An emoji is usually one scalar value too
text = "👍"
println(text::length())         # 1

Because the unit is the scalar value and not the grapheme cluster, a character written as a base letter plus a combining mark counts as two, and a multi-codepoint emoji (a flag, or a family with zero-width joiners) counts as several. Indexing and length() are therefore O(n) walks over the string.

Character Iteration

A string is not iterable: loop through "Hello" fails with Cannot iterate over string. Convert it to a list of characters first:

import std:println

text = "Hello"
loop through text::to_list() with char {
    println(char)
}
# H
# e
# l
# l
# o

Common Pitfalls

Pitfall 1: Index Out of Bounds

There is no way to catch a runtime error, so check the length before indexing:

import std:println

text = "Hello"

# This would terminate the program:
# char = text[10]  # Runtime error: Index out of bounds

char = match {
    text::length() > 10 => text[10],
    _ => nil,
}
println(char)  # nil

Pitfall 2: Mutability Confusion

import std:println

text = "Hello"
result = text::upper()  # Returns "HELLO", doesn't modify text

# Original unchanged
println(text)    # Hello
println(result)  # HELLO

# Rebind the variable to "modify" it
text = text::upper()
println(text)    # HELLO

Pitfall 3: String Comparison

import std:println

# Case-sensitive by default
println("Hello" == "hello")                        # false

# Case-insensitive comparison
println("Hello"::lower() == "hello"::lower())      # true

# `<` and `>` compare lexicographically, but only between two strings —
# comparing a string with a number is a type error
println("apple" < "banana")                        # true

Performance Considerations

String Concatenation

For many concatenations, collect in list then join:

import std:println

items = ["a", "b", "c"]

# Slow for many items: every + allocates a new string
result = ""
loop through items with item {
    result = result + item + ", "
}
println(result)  # a, b, c,

# Faster, and no trailing separator
println(items::join(", "))  # a, b, c

String Building

import std:println

items = ["Apple", "Banana"]

# Efficient for complex building: collect the pieces, join once
parts = []
loop through items with item {
    parts::push("<li>${item}</li>")
}
html = parts::join("")
println(html)  # <li>Apple</li><li>Banana</li>

Examples

Email Validation

import std:println

validate_email = |email| {
    email ~ /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/
}

println(validate_email("user@example.com"))   # true
println(validate_email("invalid.email"))      # false

Slugify

replace() only accepts strings, so a slug has to be built character by character rather than with a regex substitution:

import std:println

allowed = "abcdefghijklmnopqrstuvwxyz0123456789"

slugify = |text| {
    out = []
    loop through text::lower()::to_list() with ch {
        out::push(match {
            allowed::contains(ch) => ch,
            _ => "-",
        })
    }
    # Collapse runs of "-" and drop the empty leading/trailing pieces
    words = out::join("")::split("-")::filter(|p| p::length() > 0)
    words::join("-")
}

println(slugify("Hello World!"))   # hello-world
println(slugify("  Foo & Bar  "))  # foo-bar

Parse CSV Line

import std:println

parse_csv_line = |line| {
    line::split(",")::map(|s| s::trim())
}

line = "Alice, 30, Engineer"
fields = parse_csv_line(line)
println(fields)  # [Alice, 30, Engineer]

Title Case

import std:println

title_case = |text| {
    words = text::lower()::split()
    result = []
    loop through words with word {
        first = word[0]::upper()
        rest = word[1;]::lower()
        result::push(first + rest)
    }
    result::join(" ")
}

println(title_case("hello world"))     # Hello World
println(title_case("the quick BROWN fox"))  # The Quick Brown Fox

Password Strength

import std:println

check_password_strength = |password| {
    has_length = password::length() >= 8
    has_upper = password ~ /[A-Z]/
    has_lower = password ~ /[a-z]/
    has_digit = password ~ /[0-9]/
    has_special = password ~ /[!@#$%^&*]/
    
    checks = [has_length, has_upper, has_lower, has_digit, has_special]
    score = checks::filter(|x| x)::length()
    
    match score {
        5 => "Strong",
        _ => match score >= 3 {
            true => "Medium",
            false => "Weak",
        },
    }
}

println(check_password_strength("abc123"))           # Weak
println(check_password_strength("Abc123"))           # Medium
println(check_password_strength("Abc123!@"))         # Strong

Best Practices

DO:

• Use string interpolation with ${...} (works with both single and double quotes)
• Use triple quotes for multiline text
• Use method chaining with :: syntax
• Use meaningful variable names
• Handle Unicode correctly

DON’T:

• Concatenate in loops (use join instead)
• Forget strings are immutable
• Ignore Unicode edge cases
• Hard-code strings that should be configurable

Next Steps

• Learn about Lists for collections of strings
• Explore Regular Expressions for pattern matching
• Study String Interpolation in depth
• Check out Text Encoding in the stdlib

See Also

• Regular Expressions
• String Interpolation
• Text Encoding
• Pattern Matching

Lists

Lists are ordered, indexed collections that can hold any type of values.

Overview

Lists are one of the most commonly used data types in Suji for storing sequences of items.

Key Characteristics

• Ordered - Items maintain insertion order
• Indexed - Zero-based integer indexing
• Heterogeneous - Can contain mixed types
• Growable - Can add/remove items
• Functional - Rich methods for transformation

When to Use Lists

Use lists for:

• Sequences of items
• Collections that need ordering
• Data pipelines and transformations
• Iterating over elements
• Stack/queue operations

Syntax

Creating Lists

import std:println

# Empty list
items = []

# With initial values
numbers = [1, 2, 3, 4, 5]
names = ["Alice", "Bob", "Charlie"]

# Mixed types
mixed = [1, "two", 3.0, true, nil]

# Nested lists
matrix = [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
]

println(items)   # []
println(names)   # [Alice, Bob, Charlie]
println(mixed)   # [1, two, 3, true, nil]
println(matrix)  # [[1, 2, 3], [4, 5, 6], [7, 8, 9]]

Note that printing a list shows its elements without quotes: strings inside a list are not re-quoted by println.

Range Literals

Create lists using range syntax. A range is evaluated immediately into a real list — it is not lazy, so 0..1000000 allocates a million elements.

import std:println

# Exclusive range (includes start, excludes end)
println(0..10)     # [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

# Inclusive range (includes both start and end)
println(0..=10)    # [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

# Descending range
println(10..5)     # [10, 9, 8, 7, 6]

# Descending inclusive
println(10..=5)    # [10, 9, 8, 7, 6, 5]

# Negative numbers
println(-2..2)     # [-2, -1, 0, 1]

There is no step syntax; use filter to skip elements.

Accessing Elements

import std:println

numbers = [10, 20, 30, 40, 50]

# By index (0-based)
println(numbers[0])     # 10
println(numbers[2])     # 30

# Negative indices (from end)
println(numbers[-1])    # 50 (last)
println(numbers[-2])   # 40 (second to last)

Slicing

Extract sublists using semicolon syntax:

import std:println

numbers = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

# Range [start;end) - includes start, excludes end
println(numbers[1;3])    # [1, 2]

# From start
println(numbers[;2])     # [0, 1]

# To end
println(numbers[2;])     # [2, 3, 4, 5, 6, 7, 8, 9]

# Negative indices
println(numbers[-2;])    # [8, 9]

Assigning Elements

import std:println

xs = [10, 20, 30]
xs[1] = 99     # xs is now [10, 99, 30]
xs[-1] = 0     # xs is now [10, 99, 0]
println(xs)    # [10, 99, 0]

List Methods

Length

import std:println

numbers = [1, 2, 3, 4, 5]
println(numbers::length())    # 5

empty = []
println(empty::length())      # 0

Adding Elements

import std:println

# Push (add to end)
list = [1, 2, 3]
list::push(4)
println(list)  # [1, 2, 3, 4]

# Multiple pushes
list::push(5)
list::push(6)
println(list)  # [1, 2, 3, 4, 5, 6]

# Concatenate lists
list1 = [1, 2]
list2 = [3, 4]
combined = list1 + list2
println(combined)  # [1, 2, 3, 4]

Removing Elements

import std:println

# Pop (remove from end)
list = [1, 2, 3, 4]
last = list::pop()
println(list)  # [1, 2, 3]
println(last)  # 4

Joining

import std:println

# Join with default separator (space)
words = ["hello", "world"]
println(words::join())  # hello world

# Join with custom separator
numbers = [1, 2, 3]
println(numbers::join(","))  # 1,2,3

Functional Methods

Map

Transform each element:

import std:println

numbers = [1, 2, 3, 4, 5]

# Double each number
doubled = numbers::map(|x| x * 2)
println(doubled)  # [2, 4, 6, 8, 10]

# Convert to strings (println shows them unquoted)
strings = numbers::map(|x| x::to_string())
println(strings)  # [1, 2, 3, 4, 5]

Filter

Keep only elements that match a condition:

import std:println

numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

# Only even numbers
evens = numbers::filter(|x| x % 2 == 0)
println(evens)  # [2, 4, 6, 8, 10]

# Only numbers > 5
large = numbers::filter(|x| x > 5)
println(large)  # [6, 7, 8, 9, 10]

Fold

Combine elements into a single value:

import std:println

numbers = [1, 2, 3, 4, 5]

# Sum
sum = numbers::fold(0, |acc, x| acc + x)
println(sum)  # 15

# Product
product = numbers::fold(1, |acc, x| acc * x)
println(product)  # 120

Sum and Product

Convenient shortcuts for fold:

import std:println

numbers = [1, 2, 3, 4, 5]
println(numbers::sum())      # 15
println(numbers::product())  # 120

Chain Operations

Combine multiple operations:

import std:println

numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

# Filter evens, square them, filter > 20, sum
result = numbers
  ::filter(|x| x % 2 == 0)      # [2, 4, 6, 8, 10]
  ::map(|x| x * x)              # [4, 16, 36, 64, 100]
  ::filter(|x| x > 20)          # [36, 64, 100]
  ::sum()                       # 200

println(result)  # 200

Searching Methods

Contains

import std:println

fruits = ["apple", "banana", "cherry"]

println(fruits::contains("banana"))   # true
println(fruits::contains("grape"))    # false

Index Of

Find position of element:

import std:println

fruits = ["apple", "banana", "cherry"]

println(fruits::index_of("banana"))  # 1
println(fruits::index_of("grape"))   # -1 (not found)

Sorting and Reversing

Sort

import std:println

# Sort numbers
numbers = [3, 1, 4, 1, 5, 9, 2, 6]
sorted = numbers::sort()
println(sorted)  # [1, 1, 2, 3, 4, 5, 6, 9]

# Sort strings
fruits = ["cherry", "apple", "banana"]
sorted = fruits::sort()
println(sorted)  # [apple, banana, cherry]

sort() takes no arguments: there is no sort_by() and no comparator. To sort by a derived key, build a list of "key|value" strings, sort that, and map back — or sort a list of the keys and look values up in a map.

Reverse

import std:println

list = [1, 2, 3, 4, 5]
reversed = list::reverse()
println(reversed)  # [5, 4, 3, 2, 1]
println(list)      # [1, 2, 3, 4, 5] (original unchanged)

Min, Max, and Average

Min and Max

import std:println

scores = [85, 92, 78, 96, 88]
println(scores::min())  # 78
println(scores::max())  # 96

Average

import std:println

numbers = [1, 2, 3, 4]
println(numbers::average())   # 2.50

empty = []
println(empty::average())    # nil

min(), max(), sum(), product() and average() require numeric elements. average() is the only one that returns nil for an empty list.

First and Last

import std:println

items = ["first", "middle", "last"]
println(items::first())  # first
println(items::last())   # last

# With default values
empty = []
println(empty::first("n/a"))  # n/a
println(empty::last(0))        # 0

Methods That Do Not Exist

The complete list method set is push, pop, length, join, index_of, filter, map, fold, sum, product, average, contains, reverse, sort, min, max, first, last, to_string (plus the is_* predicates). Familiar names from other languages are missing; here is what to use instead:

Common Patterns

Building Lists

import std:println

# Range literals
numbers = 0..10     # [0, 1, 2, ..., 9]
inclusive = 0..=10  # [0, 1, 2, ..., 10]

# List comprehension style using map
squares = (0..10)::map(|x| x * x)
println(squares)  # [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

Processing with Loops

import std:println

numbers = [1, 2, 3, 4, 5]
doubled = []

loop through numbers with n {
    doubled::push(n * 2)
}

println(doubled)  # [2, 4, 6, 8, 10]

Common Pitfalls

Pitfall 1: Index Out of Bounds

import std:println

list = [1, 2, 3]

# This would terminate the program:
# item = list[10]  # Runtime error: Index out of bounds

# Check first
item = match {
    list::length() > 10 => list[10],
    _ => nil,
}
println(item)  # nil

# Or use first/last with defaults
println(list::first(nil))  # 1

Pitfall 2: Modifying While Iterating

import std:println

# Don't grow a list while iterating it
list = [1, 2, 3, 4, 5]
loop through list with item {
    # list::push(item)  # Dangerous! Keeps extending what you iterate
    continue
}

# Build a new list instead
new_list = []
loop through list with item {
    new_list::push(item * 2)
}
println(new_list)  # [2, 4, 6, 8, 10]

Pitfall 3: Methods Return New Lists

import std:println

list = [1, 2, 3]
reversed = list::reverse()  # Returns a new list

# Original unchanged
println(list)      # [1, 2, 3]
println(reversed)  # [3, 2, 1]

# push() modifies the list
list::push(4)
println(list)  # [1, 2, 3, 4]

Pitfall 4: Empty List Edge Cases

import std:println

empty = []

# Error on empty
# first = empty[0]  # Runtime error

# Check first (note the comma after the final arm)
first = match empty::length() {
    0 => nil,
    _ => empty[0],
}
println(first)  # nil

# The same check on one line
last = match empty::length() { 0 => nil, _ => empty[-1], }
println(last)  # nil

# Or let first()/last() supply the default
println(empty::first("n/a"))  # n/a

There is no is_empty() method — compare length() with 0.

Performance Considerations

Every one of map, filter and fold is eager and allocates a fresh list, so a long chain walks the data once per stage. Ranges are materialised too: 0..1000000 really does build a list of a million numbers.

Method Chaining

import std:println

list = [3, -1, 4, -5, 9]

# Readable - methods can be chained across lines
result = list
  ::filter(|x| x > 0)
  ::map(|x| x * 2)
  ::sum()

println(result)  # 32

Avoid Repeated Concatenation

import std:println

items = [1, 2, 3]

# Slow for many items (O(n²)) - builds a new list on every iteration
result = []
loop through items with item {
    result = result + [item]
}
println(result)  # [1, 2, 3]

# Use push (amortised O(1) per item)
result = []
loop through items with item {
    result::push(item)
}
println(result)  # [1, 2, 3]

Examples

Remove Duplicates Preserving Order

There is no unique() method, so track what you have seen in a map:

import std:println

remove_duplicates = |list| {
    seen = {}
    result = []

    loop through list with item {
        seen::contains(item) && continue
        seen[item] = true
        result::push(item)
    }

    result
}

numbers = [1, 2, 2, 3, 1, 4, 3, 5]
println(remove_duplicates(numbers))  # [1, 2, 3, 4, 5]

Moving Average

import std:println

moving_average = |values, window| {
    result = []
    
    loop through 0..(values::length() - window + 1) with i {
        window_values = values[i;i + window]
        avg = window_values::sum() / window
        result::push(avg)
    }
    
    result
}

data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
averages = moving_average(data, 3)
println(averages)  # [2, 3, 4, 5, 6, 7, 8, 9]

Transpose Matrix

import std:println

transpose = |matrix| {
    match matrix::length() {
        0 => [],
        _ => {
            cols = matrix[0]::length()
            # Bind the range first: a line starting with "(" would otherwise be
            # read as a call on the previous line's value.
            indices = 0..cols
            indices::map(|col| matrix::map(|row| row[col]))
        }
    }
}

matrix = [
    [1, 2, 3],
    [4, 5, 6]
]

transposed = transpose(matrix)
println(transposed)  # [[1, 4], [2, 5], [3, 6]]

Best Practices

DO:

• Use functional methods (map, filter, fold)
• Use range literals (0..10) for sequences
• Check list length before accessing indices
• Use meaningful variable names
• Use first() and last() with defaults for safe access

DON’T:

• Modify lists while iterating
• Ignore index out of bounds errors
• Use repeated concatenation in loops
• Forget that most methods return new lists (except push/pop)

Next Steps

• Learn about Maps for key-value collections
• Explore Tuples for fixed-size collections
• Study Functional Programming patterns
• Check out Data Transformation recipes

See Also

• Maps
• Tuples
• Higher-Order Functions
• Pipe Operators

Maps

Maps are insertion-ordered key-value collections, perfect for structured data and JSON-like objects.

Overview

Maps associate keys with values, providing fast lookups and flexible data structures.

Key Characteristics

• Key-value pairs - Associate data with unique keys
• Insertion-ordered - keys(), values(), to_list() and loop through all visit entries in the order they were inserted
• Keys are strings, numbers or booleans - not lists, maps or nil
• Nested access - Convenient syntax for deep properties, and those chains are assignable
• Missing keys raise - m:absent is a runtime error, not nil; use m::get(k, default) or m::contains(k)
• JSON-compatible - Natural mapping to JSON objects

When to Use Maps

Use maps for:

• Structured data (user profiles, configuration)
• JSON-like data structures
• Key-based lookups
• Dictionaries and associations
• Optional/sparse data

Syntax

Creating Maps

import std:println

# Empty map
empty = {}

# With initial data
user = {
    name: "Alice",
    age: 30,
    email: "alice@example.com"
}

# Nested maps
config = {
    database: {
        host: "localhost",
        port: 5432
    },
    features: {
        dark_mode: true,
        notifications: false
    }
}

println(empty)            # {}
println(user)             # {name: Alice, age: 30, email: alice@example.com}
println(config:database)  # {host: localhost, port: 5432}

Bare identifier keys (name:) and quoted keys ("name":) mean the same thing. Bare keys are only recognised where a map is expected, though: as the entire body of a match arm or a lambda, { name: "x" } is parsed as a block and fails. Quote the keys or wrap the literal in parentheses in those positions.

Accessing Values

import std:println

user = {name: "Alice", age: 30}

# Colon notation (preferred)
println(user:name)    # Alice
println(user:age)     # 30

# Bracket notation
println(user["name"]) # Alice

# Nested access
config = {db: {host: "localhost"}}
println(config:db:host)  # localhost

# A missing key is a runtime error, not nil:
# println(user:phone)  # Error: Key not found: Key 'phone' not found in map

Use ::get() (below) whenever a key might be absent — Suji has no way to recover from the Key not found error once it happens.

Setting Values

import std:println

user = {name: "Alice"}

# Add/update with direct assignment
user["age"] = 30
user["email"] = "alice@example.com"

println(user)
# {name: Alice, age: 30, email: alice@example.com}

# Multiple updates
user["age"] = 31
user["city"] = "Boston"
println(user)
# {name: Alice, age: 31, email: alice@example.com, city: Boston}

# Nested chains are assignable too
profile = {user: {name: "Alice"}}
profile:user:name = "Bob"
println(profile)  # {user: {name: Bob}}

There is no map::set(key, value) method — assignment is the only way to write a key.

Map Methods

Get Value

import std:println

user = {name: "Alice", age: 30}

# Get with default
email = user::get("email", "no-email@example.com")
println(email)  # no-email@example.com

# Returns nil if not found and no default
phone = user::get("phone")
println(phone)  # nil

Check if Key Exists

import std:println

user = {name: "Alice", age: 30}

println(user::contains("name"))    # true
println(user::contains("email"))   # false

The method is contains(), not has().

Keys and Values

import std:println

user = {name: "Alice", age: 30, city: "Boston"}

# Get all keys, in insertion order
keys = user::keys()
println(keys)  # [name, age, city]

# Get all values, in the same order
values = user::values()
println(values)  # [Alice, 30, Boston]

# Get key-value pairs as a list of tuples
entries = user::to_list()
println(entries)  # [(name, Alice), (age, 30), (city, Boston)]

to_list() is the pair-list accessor; there is no entries(). Remember that the pairs are tuples, so unpack them by destructuring (k, v = pair) rather than indexing — see Tuples.

Size

import std:println

user = {name: "Alice", age: 30}
println(user::length())  # 2

empty = {}
println(empty::length())  # 0

There is no is_empty(); compare length() with 0.

Remove Key

import std:println

user = {name: "Alice", age: 30, email: "alice@example.com"}

# Remove a key (mutates the map, returns true if the key was present)
println(user::delete("email"))  # true
println(user)  # {name: Alice, age: 30}

The method is delete(), not remove().

Merge Maps

import std:println

defaults = {theme: "light", lang: "en"}
user_prefs = {theme: "dark"}

# Merge (user_prefs overwrites defaults)
defaults::merge(user_prefs)
println(defaults)  # {theme: dark, lang: en}

merge() mutates the receiver and returns nil, so merged = a::merge(b) would leave merged as nil. Merge into the map you want to end up with.

Functional Operations

Maps have no map(), filter() or each() methods — those exist only on lists. Iterate with loop through m with k, v and build a new map yourself.

Map Values

Transform all values:

import std:println

prices = {apple: 1.00, banana: 0.50, cherry: 2.00}

# Double all prices (manual transformation)
doubled = {}
loop through prices with key, value {
    doubled[key] = value * 2
}
println(doubled)  # {apple: 2, banana: 1, cherry: 4}

Two bindings after with only work for maps: loop through some_list with a, b is a runtime error.

Filter

Keep only entries matching condition:

import std:println

users = {
    alice: {age: 30, active: true},
    bob: {age: 25, active: false},
    charlie: {age: 35, active: true}
}

# Only active users (manual filtering)
active = {}
loop through users with key, val {
    match { val:active => { active[key] = val } }
}
println(active)
# {alice: {age: 30, active: true}, charlie: {age: 35, active: true}}

A conditional match with no matching arm evaluates to nil and does nothing, which is why the single-armed match above works as a filter.

Common Patterns

Default Values

import std:println

get_config = |key, default| {
    config = {timeout: 30, retries: 3}
    config::get(key, default)
}

println(get_config("timeout", 60))    # 30
println(get_config("max_size", 100))  # 100 (default)

Nested Access with Safety

import std:println

safe_get = |m, path| {
    result = m
    loop through path with key {
        match {
            result::is_map() => { result = result::get(key) }
            _ => { result = nil }
        }
    }
    result
}

data = {user: {profile: {name: "Alice"}}}

# Safe deep access
name = safe_get(data, ["user", "profile", "name"])
println(name)  # Alice

# Returns nil for missing paths
missing = safe_get(data, ["user", "settings", "theme"])
println(missing)  # nil

Building Maps

import std:println

# From lists of pairs
pairs = [["a", 1], ["b", 2], ["c", 3]]
map = {}
loop through pairs with pair {
    map[pair[0]] = pair[1]
}
println(map)  # {a: 1, b: 2, c: 3}


# From keys and values
keys = ["name", "age", "city"]
values = ["Alice", 30, "Boston"]
user = {}
limit = keys::length()
match { values::length() < limit => { limit = values::length() } }
loop through (0..limit) with i {
    user[keys[i]] = values[i]
}
println(user)  # {name: Alice, age: 30, city: Boston}

Grouping

import std:println

users = [
    {name: "Alice", role: "admin"},
    {name: "Bob", role: "user"},
    {name: "Charlie", role: "admin"}
]

# Group by role
by_role = {}
loop through users with u {
    role = u:role
    group = by_role::get(role, [])
    group::push(u)
    by_role[role] = group
}
println(by_role)
# {admin: [{name: Alice, role: admin}, {name: Charlie, role: admin}], user: [{name: Bob, role: user}]}

get(role, []) gives a fresh default list, so the pattern above works even for the first user in each group. Note that lists have no group_by() method — this loop is the idiom.

JSON Integration

Maps work naturally with JSON:

import std:json
import std:println

# Map to JSON (json:generate sorts the keys)
user = {name: "Alice", age: 30, active: true}
json_str = json:generate(user)
println(json_str)  # {"active":true,"age":30,"name":"Alice"}

# JSON to Map
data = json:parse("""
{
    "users": [
        {"name": "Alice", "age": 30},
        {"name": "Bob", "age": 25}
    ]
}
""")

# Access like a map
println(data:users[0]:name)  # Alice

Common Pitfalls

Pitfall 1: Missing Keys Raise an Error

This is the most common surprise for people coming from other languages: reading an absent key does not give you nil, it terminates the program with Key not found.

import std:println

user = {name: "Alice"}

# This would abort the script:
# age = user:age       # Error: Key not found: Key 'age' not found in map

# Use get() with a default
println(user::get("age", 0))  # 0

# get() with no default yields nil
println(user::get("age"))     # nil

# Or check first
age = match user::contains("age") {
    true => user:age,
    false => 0,
}
println(age)  # 0

Pitfall 2: Key Types

import std:println

# Keys may be strings, numbers or booleans
map = {1: "one", 2: "two"}
println(map[1])    # one

# A number key and a string key are different keys
map["1"] = "string one"
println(map::length())  # 3

# Lists, maps and nil cannot be keys (Invalid key type)

Be consistent: mixing 1 and "1" in one map is legal and almost always a bug.

Pitfall 3: Nested Updates

import std:println

user = {profile: {name: "Alice"}}

# Access chains are assignable, so you can update in place
user:profile:name = "Bob"
println(user)  # {profile: {name: Bob}}

# Bracket form works the same way
user["profile"]["name"] = "Carol"
println(user)  # {profile: {name: Carol}}

Every key along the chain must already exist, though — assigning through a missing intermediate key raises Key not found.

Pitfall 4: Iteration Order

Maps preserve insertion order, so iteration is deterministic — but insertion order is rarely the order you want to display. Sort the keys when presentation matters:

import std:println

map = {c: 3, a: 1, b: 2}

# Insertion order
println(map::keys())  # [c, a, b]

# Sorted order
loop through map::keys()::sort() with key {
    println("${key}: ${map[key]}")
}
# a: 1
# b: 2
# c: 3

Note that json:generate() sorts keys, so a round-trip through JSON does not preserve insertion order.

Performance Considerations

Lookups are Fast

Map lookups are O(1) average case - very fast even for large maps:

import std:println

# Build a map with 1000 entries
large_map = {}
loop through 0..1000 with i {
    large_map[i] = i * i
}

# Lookup cost does not grow with the map
println(large_map[999])            # 998001
println(large_map::get(5000, nil)) # nil

Choose Right Data Structure

import std:println

# Use a map for key-based lookup
user_by_id = {
    123: {name: "Alice"},
    456: {name: "Bob"}
}
println(user_by_id[456]:name)  # Bob

# A list needs a scan for the same question
users_list = [{id: 123, name: "Alice"}, {id: 456, name: "Bob"}]
found = users_list::filter(|u| u:id == 456)::first(nil)
println(found:name)  # Bob

Examples

Configuration Merging

import std:println

# merge() mutates `defaults`, so return it explicitly rather than the nil
# that merge() itself gives back.
merge_config = |defaults, user_config| {
    defaults::merge(user_config)
    defaults
}

defaults = {
    theme: "light",
    lang: "en",
    notifications: true,
    timeout: 30
}

user = {
    theme: "dark",
    lang: "es"
}

final = merge_config(defaults, user)
println(final)
# {theme: dark, lang: es, notifications: true, timeout: 30}

Object Transformation

import std:println

# Transform user object. The keys are quoted because a map literal that is the
# whole body of a lambda would otherwise be read as a block.
transform_user = |user| {
    {
        "full_name": "${user:first_name} ${user:last_name}",
        "contact": user:email,
        "is_adult": user:age >= 18,
    }
}

user = {
    first_name: "Alice",
    last_name: "Smith",
    age: 30,
    email: "alice@example.com"
}

transformed = transform_user(user)
println(transformed)
# {full_name: Alice Smith, contact: alice@example.com, is_adult: true}

Counting Occurrences

import std:println

count_occurrences = |items| {
    counts = {}
    loop through items with item {
        current = counts::get(item, 0)
        counts[item] = current + 1
    }
    counts
}

words = ["apple", "banana", "apple", "cherry", "banana", "apple"]
result = count_occurrences(words)
println(result)  # {apple: 3, banana: 2, cherry: 1}

Index By Key

import std:println

index_by = |list, key| {
    result = {}
    loop through list with item {
        id = item[key]
        result[id] = item
    }
    result
}

users = [
    {id: 1, name: "Alice"},
    {id: 2, name: "Bob"},
    {id: 3, name: "Charlie"}
]

by_id = index_by(users, "id")
println(by_id[2])  # {id: 2, name: Bob}

Methods That Do Not Exist

The complete map method set is keys, values, to_list, get, contains, delete, length, merge, to_string (plus the is_* predicates).

Best Practices

DO:

• Use consistent key types (usually strings)
• Read possibly-absent keys with get(key, default) — direct access raises
• Use contains(key) before writing through a nested chain
• Use maps for structured data
• Leverage JSON integration

DON’T:

• Assume a missing key gives you nil
• Expect merge() or delete() to return a new map — they mutate in place
• Rely on insertion order surviving a JSON round-trip
• Mix different conventions for key naming

Next Steps

• Learn about Tuples for fixed-size collections
• Explore JSON for data serialization
• Study Pattern Matching with maps
• Check out Data Transformation recipes

See Also

• Tuples
• Lists
• JSON Module
• YAML Module

Tuples

Tuples are immutable, fixed-size collections that group heterogeneous values together.

Overview

Tuples let you package multiple values into a single compound value, perfect for returning multiple results or grouping related data.

Key Characteristics

• Fixed size - Cannot add/remove elements
• Immutable - Cannot change after creation
• Heterogeneous - Can contain different types
• Not indexable - t[0] is a type error; there is no get, first or second either
• Destructuring - a, b = t is the way to get the elements out

When to Use Tuples

Use tuples for:

• Multiple return values from functions
• Grouping related but different types
• Temporary data bundling
• Coordinate pairs or triples
• Fixed-size records

Syntax

Creating Tuples

import std:println

# Empty tuple
empty = ()

# With values
pair = (1, 2)
triple = (1, "two", 3.0)
nested = (1, (2, 3), 4)

# Single element tuple (note the comma)
single = (42,)

println(empty)   # ()
println(pair)    # (1, 2)
println(triple)  # (1, two, 3)
println(nested)  # (1, (2, 3), 4)
println(single)  # (42,)

Accessing Elements

Tuples are not indexable. t[0] fails with Cannot index tuple, and there are no get(), first() or second() methods — the only tuple methods are length(), to_list() and to_string(). Get at the elements by destructuring, or convert to a list first:

import std:println

point = (10, 20, 30)

# This does NOT work:
# println(point[0])   # Error: Type error: Cannot index tuple

# Destructure instead
x, y, z = point
println(x)  # 10
println(z)  # 30

# Or convert to a list, which *is* indexable
coords = point::to_list()
println(coords[0])   # 10
println(coords[-1])  # 30

Destructuring

The most powerful feature of tuples. Write the targets without parentheses — (x, y) = point is not destructuring syntax and will not work:

import std:println

# Unpack tuple into variables
point = (10, 20)
x, y = point
println("x: ${x}, y: ${y}")  # x: 10, y: 20

# Ignore values with underscore
triple = (1, 2, 3)
first, _, third = triple
println("${first}, ${third}")  # 1, 3

Destructuring is one level deep: a nested tuple comes out as a tuple that you unpack in a second step.

import std:println

data = (1, (2, 3), 4)

a, inner, d = data
println(inner)  # (2, 3)

b, c = inner
println("${a}, ${b}, ${c}, ${d}")  # 1, 2, 3, 4

The number of targets must match the tuple exactly — a, b = (1, 2, 3) fails with Destructuring arity mismatch: expected 2, got 3.

Multiple Return Values

Tuples excel at returning multiple values:

import std:println

# Function returning tuple
# Use an explicit `return` for the tuple: a line that begins with "(" would
# otherwise be read as a call on the previous line's value.
divide_with_remainder = |a, b| {
    quotient = (a / b)::floor()
    remainder = a % b
    return (quotient, remainder)
}

# Destructure the result
q, r = divide_with_remainder(17, 5)
println("17 ÷ 5 = ${q} remainder ${r}")  # 17 ÷ 5 = 3 remainder 2

return a, b also builds a tuple, so an explicit early return can carry two values:

import std:println

split_sign = |n| {
    n < 0 && return ("negative", n::abs())
    return ("non-negative", n)
}

label, magnitude = split_sign(-7)
println("${label} ${magnitude}")  # negative 7

Real-World Example

import std:println

# Parse name into parts
parse_name = |full_name| {
    parts = full_name::split()
    match parts::length() {
        0 => (nil, nil),
        1 => (parts[0], nil),
        _ => (parts[0], parts[1;]::join(" ")),
    }
}

first, last = parse_name("Alice Smith")
println("First: ${first}, Last: ${last}")
# First: Alice, Last: Smith

first, last = parse_name("Bob")
println("First: ${first}, Last: ${last}")
# First: Bob, Last: nil

Tuple Methods

Length

import std:println

triple = (1, 2, 3)
println(triple::length())  # 3

Conversion

import std:println

# Tuple to list
triple = (1, 2, 3)
as_list = triple::to_list()
println(as_list)  # [1, 2, 3]

# There is no automatic list-to-tuple conversion; construct a tuple explicitly
# when you know the length
values = [4, 5, 6]
rebuilt = (values[0], values[1], values[2])
println(rebuilt)  # (4, 5, 6)

# to_string() renders the same text println shows
println(triple::to_string())  # (1, 2, 3)

Comparison

Tuples support equality, which compares element by element:

import std:println

println((1, 2) == (1, 2))   # true
println((1, 2) == (1, 3))   # false
println((1, 2) != (1, 3))   # true

There is no ordering for tuples: (1, 2) < (1, 3) fails with Cannot compare tuple and tuple. If you need to sort pairs, destructure them and compare the components yourself.

Common Patterns

Coordinate Pairs

import std:println

# 2D point
point = (10, 20)
x, y = point

# Distance from origin
distance = ((x ^ 2) + (y ^ 2))::sqrt()
println(distance)  # 22.360679774997896964091736688

# 3D point
point3d = (10, 20, 30)
x, y, z = point3d
println("${x}, ${y}, ${z}")  # 10, 20, 30

Min/Max with Index

import std:println

# `loop through list with a, b` is a runtime error - two bindings are for maps
# only - so iterate the indices when you need a counter.
find_min_with_index = |numbers| {
    min_val = numbers[0]
    min_idx = 0

    loop through 0..numbers::length() with idx {
        match { numbers[idx] < min_val => {
            min_val = numbers[idx]
            min_idx = idx
        } }
    }

    (min_val, min_idx)
}

numbers = [5, 2, 8, 1, 9]
min_value, min_index = find_min_with_index(numbers)
println("Min ${min_value} at index ${min_index}")
# Min 1 at index 3

Success/Error Results

Suji has no exceptions and no Result type, so a (value, error) tuple is the usual way to report failure from a function:

import std:println

safe_divide = |a, b| {
    match b {
        0 => (nil, "Division by zero"),
        _ => (a / b, nil),
    }
}

result, error = safe_divide(10, 2)
match error {
    nil => println("Result: ${result}"),
    _ => println("Error: ${error}"),
}
# Result: 5

result, error = safe_divide(10, 0)
match error {
    nil => println("Result: ${result}"),
    _ => println("Error: ${error}"),
}
# Error: Division by zero

Note the _ in the second arm. A bare identifier in a pattern is treated as a string literal, so an arm written err => … would only match the literal string "err"; it would not bind the error.

Swapping Values

import std:println

a = 10
b = 20

# Swap using tuple destructuring - the right side must be a real tuple,
# so the parentheses here are required
a, b = (b, a)

println("a: ${a}, b: ${b}")  # a: 20, b: 10

Tuples vs Lists

When to Use Tuples

import std:println

# Fixed, known structure
rgb = (255, 0, 128)

# Different types
user = ("Alice", 30, true)  # name, age, active

# Multiple returns
try_parse = |text| {
    match {
        text ~ /^[0-9]+$/ => (true, text::to_number()),
        _ => (false, nil),
    }
}

ok, value = try_parse("42")
println("${ok} ${value}")  # true 42

println(rgb)   # (255, 0, 128)
println(user)  # (Alice, 30, true)

When to Use Lists

import std:println

# Variable number of items
numbers = [1, 2, 3, 4, 5]  # Could be any length

# Same type collection
names = ["Alice", "Bob", "Charlie"]

# Need to add/remove items
items = [1, 2, 3]
items::push(4)  # Grows dynamically

println(numbers::length())  # 5
println(names::join(", "))  # Alice, Bob, Charlie
println(items)              # [1, 2, 3, 4]

Common Pitfalls

Pitfall 1: Forgetting Comma for Single Element

import std:println

# Not a tuple - just a number in parentheses
not_tuple = (42)
println(not_tuple::is_tuple())  # false

# Single-element tuple needs trailing comma
one_tuple = (42,)
println(one_tuple::is_tuple())  # true
println(one_tuple::length())    # 1

Pitfall 2: Trying to Modify or Index

import std:println

triple = (1, 2, 3)

# Neither of these works:
# triple[0] = 10   # Error: Type error: Cannot assign index on tuple
# println(triple[0])  # Error: Type error: Cannot index tuple

# Destructure, then build a new tuple
a, b, c = triple
updated = (10, b, c)
println(updated)  # (10, 2, 3)

Pitfall 3: Wrong Number of Variables

import std:println

triple = (1, 2, 3)

# Too few targets:
# a, b = triple  # Error: Destructuring arity mismatch: expected 2, got 3

# Match the count
a, b, c = triple
println("${a}${b}${c}")  # 123

# Or use underscore for unwanted values
a, _, c = triple
println("${a}${c}")  # 13

Pitfall 4: Confusion with Function Calls

import std:println

calculate = |a, b| a * b

# Parentheses for grouping
println((5 + 3) * 2)   # 16

# Parentheses for a function call
println(calculate(5, 3))  # 15

# Tuple (note the comma!)
coords = (5, 3)
println(coords)  # (5, 3)

Advanced Usage

Tuple Unpacking in Loops

A loop binds one variable per element. loop through points with x, y is a runtime error — two bindings only work for maps — so destructure inside the body:

import std:println

# List of tuples
points = [(1, 2), (3, 4), (5, 6)]

loop through points with point {
    x, y = point
    println("Point: (${x}, ${y})")
}
# Point: (1, 2)
# Point: (3, 4)
# Point: (5, 6)

Maps are the exception, and map::to_list() gives you exactly this shape:

import std:println

scores = {alice: 3, bob: 5}

loop through scores with name, score {
    println("${name} scored ${score}")
}
# alice scored 3
# bob scored 5

Nested Destructuring

Destructuring does not recurse. Unpack one level at a time:

import std:println

# Complex nested structure
data = (1, (2, 3, (4, 5)), 6)

a, middle, f = data
b, c, innermost = middle
d, e = innermost

println("${a}, ${b}, ${c}, ${d}, ${e}, ${f}")
# 1, 2, 3, 4, 5, 6

Pattern Matching with Tuples

Tuple patterns work, and _ is a wildcard inside them. What does not work is binding: patterns cannot introduce variables, and a bare identifier in a pattern is read as a string literal. So use _ for “anything” and fall through to a conditional match when you need to look at the values.

import std:println

classify_point = |point| {
    match point {
        (0, 0) => "origin",
        (0, _) => "on y-axis",
        (_, 0) => "on x-axis",
        _ => {
            x, y = point
            match { x == y => "on diagonal", _ => "elsewhere", }
        }
    }
}

println(classify_point((0, 0)))    # origin
println(classify_point((0, 5)))    # on y-axis
println(classify_point((3, 0)))    # on x-axis
println(classify_point((4, 4)))    # on diagonal
println(classify_point((2, 3)))    # elsewhere

Examples

RGB to HSV Conversion

import std:println

rgb_to_hsv = |r, g, b| {
    r = r / 255
    g = g / 255
    b = b / 255
    
    max_val = match {
        r >= g && r >= b => r,
        g >= b => g,
        _ => b,
    }
    min_val = match {
        r <= g && r <= b => r,
        g <= b => g,
        _ => b,
    }
    delta = max_val - min_val
    
    # Calculate hue
    h = match {
        delta == 0 => 0,
        max_val == r => 60 * (((g - b) / delta) % 6),
        max_val == g => 60 * (((b - r) / delta) + 2),
        _ => 60 * (((r - g) / delta) + 4),
    }
    
    # Calculate saturation
    s = match max_val {
        0 => 0,
        _ => delta / max_val,
    }
    
    v = max_val
    
    return (h, s, v)
}

h, s, v = rgb_to_hsv(255, 0, 0)  # Red
println("H: ${h}, S: ${s}, V: ${v}")  # H: 0, S: 1, V: 1

Statistics

import std:println

calculate_stats = |numbers| {
    total = numbers::sum()
    count = numbers::length()
    mean = total / count

    sorted = numbers::sort()
    mid = (count / 2)::floor()
    median = match count % 2 {
        0 => (sorted[mid - 1] + sorted[mid]) / 2,
        _ => sorted[mid],
    }

    return (mean, median, total, count)
}

data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
mean, median, sum, count = calculate_stats(data)

println("Mean: ${mean}")      # Mean: 5.50
println("Median: ${median}")  # Median: 5.50
println("Sum: ${sum}")        # Sum: 55
println("Count: ${count}")    # Count: 10

Best Practices

DO:

• Use for multiple return values
• Destructure immediately when possible
• Use underscore for unused values
• Keep tuples small (2-4 elements ideal)
• Document tuple structure in function names

DON’T:

• Try to index a tuple (t[0]) or reach for get/first/second — destructure, or call to_list() if you really need positional access
• Wrap destructuring targets in parentheses ((a, b) = t is not destructuring)
• Order tuples with </> — only == and != are defined
• Use tuples for large collections
• Create deeply nested tuples (use maps instead)
• Forget trailing comma for single-element tuples

Next Steps

• Learn about Pattern Matching with tuples
• Explore Functions returning tuples
• Study Destructuring patterns
• Check out Lists for variable-size collections

See Also

• Lists
• Maps
• Multiple Return Values
• Pattern Matching

Functions

Functions are first-class values in Suji that can be passed around, stored, and returned.

Overview

Functions encapsulate reusable logic and are treated as values like numbers or strings. This page covers functions as a data type: how to create them, what a function value can do, and how they interact with the rest of the language. For deeper treatment of individual topics see Higher-Order Functions, Closures, Recursion and Multiple Return Values.

Key Characteristics

• Lambda syntax only - name = |a, b| …. There is no fn, def, func or function keyword; a function is just a value you bind to a variable.
• First-class - Functions can be stored in lists and maps, passed as arguments, and returned from other functions
• Closures - Capture the enclosing scope by reference, and can mutate what they capture
• Default parameter values - |a, b = 10| …
• Multiple return values - Using tuples
• No variadics, no keyword arguments - Take a list or a map instead

When to Use Functions

Use functions for:

• Reusable logic
• Abstraction and composition
• Callbacks and event handlers
• Data transformations
• Building DSLs

Syntax

Function Definition

A function value is written with pipes around the parameter list, followed by either a single expression or a { … } block.

import std:println

# Basic function
greet = |name| {
    "Hello, ${name}!"
}

# Multiple parameters
add = |a, b| {
    a + b
}

# No parameters
answer = || {
    42
}

# Single expression (no braces needed)
double = |x| x * 2

println(greet("Alice"))  # Hello, Alice!
println(add(2, 3))       # 5
println(answer())        # 42
println(double(21))      # 42

Because a function is an ordinary value, it has the usual type predicate and can be stored anywhere:

import std:println

double = |x| x * 2

println(double::is_function())  # true

# Functions in a map, used as a dispatch table
ops = {"double": double, "negate": |x| 0 - x}
println(ops:double(7))  # 14
println(ops:negate(7))  # -7

Function Calls

import std:println

greet = |name| "Hello, ${name}!"

# Call function
message = greet("Alice")
println(message)  # Hello, Alice!

# Direct call
println(greet("Bob"))  # Hello, Bob!

Arity is checked at call time: passing the wrong number of arguments raises Arity mismatch: Function expects N arguments, got M and stops the program.

There are two pipe-apply operators for feeding a value into a function, which often reads better than nesting calls — see Pipe Apply:

import std:println

double = |x| x * 2

println(5 |> double)   # 10  (forward)
println(double <| 5)   # 10  (backward)

Parameters

Required Parameters

import std:println

calculate = |x, y, operation| {
    match operation {
        "add" => x + y,
        "subtract" => x - y,
        "multiply" => x * y,
        "divide" => x / y,
        _ => 0,
    }
}

println(calculate(10, 5, "add"))       # 15
println(calculate(10, 5, "multiply"))  # 50

Default Values

A parameter can declare a default, which applies when the argument is omitted:

import std:println

greet = |name, title = "Mr./Ms."| "${title} ${name}"

println(greet("Alice", "Dr."))  # Dr. Alice
println(greet("Bob"))           # Mr./Ms. Bob

Defaults only fill in missing arguments. Passing nil explicitly passes nil; if you want nil to mean “use the default”, check for it in the body.

Variable Arguments

Suji has no variadic parameters and no keyword arguments. Accept a list when the count varies, or a map when you want named options:

import std:println

# Using a list for a variable number of values
sum_all = |numbers| numbers::fold(0, |acc, x| acc + x)
println(sum_all([1, 2, 3, 4, 5]))  # 15

# Using a map for named options, with get() supplying defaults
render = |text, options| {
    prefix = options::get("prefix", "- ")
    upper = options::get("upper", false)
    body = match upper {
        true => text::upper(),
        _ => text,
    }
    "${prefix}${body}"
}

println(render("hello", {}))                # - hello
println(render("hello", {"upper": true}))   # - HELLO

Return Values

Explicit Return

import std:println

find_first = |list, predicate| {
    loop through list with item {
        predicate(item) && return item  # Early return
    }
    nil  # Default return
}

numbers = [1, 2, 3, 4, 5]
println(find_first(numbers, |x| x > 3))  # 4

Implicit Return

Last expression is returned:

import std:println

add = |a, b| {
    a + b  # Returned automatically
}

println(add(3, 4))  # 7

Multiple Return Values

Use tuples:

import std:println

divide_with_remainder = |a, b| {
    quotient = (a / b)::floor()
    remainder = a % b
    return (quotient, remainder)
}

q, r = divide_with_remainder(17, 5)
println("${q} remainder ${r}")  # 3 remainder 2

Two details worth remembering: destructuring targets are written without parentheses (q, r = …), and the tuple is returned with an explicit return because a line that starts with ( would otherwise be parsed as a call on the previous line’s value. return a, b builds the tuple for you as well.

Closures

Functions capture variables from their surrounding scope:

import std:println

make_adder = |x| {
    |y| x + y  # Captures x
}

add_5 = make_adder(5)
add_10 = make_adder(10)

println(add_5(3))   # 8 (5 + 3)
println(add_10(3))  # 13 (10 + 3)

Closure Example

Captured variables are shared by reference, so a closure can keep mutable state. Note the explicit return: a line beginning with || would otherwise be read as a logical-or continuing the previous line.

import std:println

make_counter = || {
    count = 0
    return || {
        count = count + 1
        count
    }
}

counter = make_counter()
println(counter())  # 1
println(counter())  # 2
println(counter())  # 3

Higher-Order Functions

Functions that accept or return functions:

Functions as Parameters

import std:println

apply_twice = |fn, x| {
    fn(fn(x))
}

double = |x| x * 2
println(apply_twice(double, 3))  # 12 (double(double(3)))

increment = |x| x + 1
println(apply_twice(increment, 5))  # 7

Functions as Return Values

import std:println

multiplier = |factor| {
    |x| x * factor
}

times_2 = multiplier(2)
times_10 = multiplier(10)

println(times_2(5))   # 10
println(times_10(5))  # 50

Common Patterns

Partial Application

There is no partial-application syntax; return a lambda from a lambda instead:

import std:println

greet_with = |greeting| {
    |name| "${greeting}, ${name}!"
}

hello = greet_with("Hello")
hi = greet_with("Hi")

println(hello("Alice"))  # Hello, Alice!
println(hi("Bob"))       # Hi, Bob!

Function Composition

import std:println

compose = |f, g| {
    |x| f(g(x))
}

add_1 = |x| x + 1
times_2 = |x| x * 2

# (x + 1) * 2
add_then_multiply = compose(times_2, add_1)
println(add_then_multiply(5))  # 12

# (x * 2) + 1
multiply_then_add = compose(add_1, times_2)
println(multiply_then_add(5))  # 11

Suji also has built-in composition operators, so you rarely need to write compose yourself: f >> g is “f then g” and f << g is “g then f”. See Composition Operators.

import std:println

add_1 = |x| x + 1
times_2 = |x| x * 2

println((add_1 >> times_2)(5))  # 12
println((add_1 << times_2)(5))  # 11

Currying

import std:println

# Curried function
curry_add = |a| |b| |c| a + b + c

# Partial application
add_1 = curry_add(1)
add_1_2 = add_1(2)
result = add_1_2(3)

println(result)  # 6

# Or all at once
println(curry_add(1)(2)(3))  # 6

Memoization

import std:println

memoize = |fn| {
    cache = {}
    return |arg| {
        match cache::contains(arg) {
            true => cache::get(arg),
            false => {
                result = fn(arg)
                cache[arg] = result
                result
            }
        }
    }
}

# Example: memoize a function and avoid repeating work
calls = 0
slow_square = |n| {
    calls = calls + 1
    n * n
}

fast_square = memoize(slow_square)
println(fast_square(5))  # 25
println(fast_square(5))  # 25
println(calls)           # 1

Recursion

Functions can call themselves:

import std:println

# Factorial
factorial = |n| {
    match n {
        0 => 1,
        _ => n * factorial(n - 1),
    }
}

println(factorial(5))  # 120

# Fibonacci
fib = |n| {
    match n {
        0 => 0,
        1 => 1,
        _ => fib(n - 1) + fib(n - 2),
    }
}

println(fib(10))  # 55

Recursion Depth

Suji does not optimise tail calls. Every recursive call is a real stack frame, and somewhere around 600–700 frames deep the process aborts with a stack overflow. Writing a call in tail position does not change that:

import std:println

# "Tail-recursive" in shape, but still one frame per call
factorial = |n| {
    helper = |n, acc| {
        match n {
            0 => acc,
            _ => helper(n - 1, n * acc),
        }
    }
    helper(n, 1)
}

println(factorial(5))  # 120

For anything that could run deep, use a loop instead of recursion:

import std:println

sum_to = |n| {
    total = 0
    loop through 1..=n with i {
        total += i
    }
    total
}

println(sum_to(100000))  # 5000050000

Lambda Expressions

Short anonymous functions:

import std:println

# In map
numbers = [1, 2, 3, 4, 5]
squares = numbers::map(|x| x * x)
println(squares)  # [1, 4, 9, 16, 25]

# In filter
evens = numbers::filter(|x| x % 2 == 0)
println(evens)  # [2, 4]

# In fold (the method is fold, not reduce)
sum = numbers::fold(0, |acc, x| acc + x)
println(sum)  # 15

Common Pitfalls

Pitfall 1: Forgetting to Call Function

import std:println

greet = |name| "Hello, ${name}!"

# This is the function value, not the result
result = greet
println(result::is_function())  # true

# Call the function
result = greet("Alice")
println(result)  # Hello, Alice!

Pitfall 2: Closure Variable Capture

Closures capture the enclosing scope by reference, so later changes to a captured variable are visible inside the closure:

import std:println

factor = 2
scale = |x| x * factor

println(scale(5))  # 10

# Reassigning the captured variable changes what the closure computes
factor = 10
println(scale(5))  # 50

Loop bindings, on the other hand, are fresh each iteration, so closures created in a loop each keep their own value — the “all my callbacks see the last index” bug from other languages does not happen here:

import std:println

functions = []
loop through [1, 2, 3] with i {
    functions::push(|| i)
}

println(functions::first()())  # 1
println(functions::last()())   # 3

Pitfall 3: Missing Base Case

There is no way to catch a stack overflow, so a runaway recursion kills the process:

import std:println

# No base case - would abort with a stack overflow:
# countdown = |n| {
#     println(n)
#     countdown(n - 1)
# }

# Always have a base case
countdown = |n| {
    n <= 0 && return nil
    println(n)
    countdown(n - 1)
}

countdown(3)
# 3
# 2
# 1

Best Practices

DO:

• Use descriptive function names (verbs)
• Keep functions small and focused
• Use lambdas for simple transformations
• Leverage closures when appropriate
• Document complex functions

DON’T:

• Create overly long functions
• Mix concerns in one function
• Forget base cases in recursion
• Capture mutable state carelessly
• Ignore function return values

Examples

Map-Filter-Fold Pipeline

import std:println

numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

result = numbers
  ::filter(|x| x % 2 == 0)       # [2, 4, 6, 8, 10]
  ::map(|x| x * x)               # [4, 16, 36, 64, 100]
  ::fold(0, |acc, x| acc + x)    # 220

println(result)

Function Builder

import std:println

operation = |op| {
    match op {
        "add" => |a, b| a + b,
        "subtract" => |a, b| a - b,
        "multiply" => |a, b| a * b,
        "divide" => |a, b| a / b,
        _ => |a, b| 0,
    }
}

add = operation("add")
multiply = operation("multiply")

println(add(5, 3))       # 8
println(multiply(5, 3))  # 15

Retry Logic

import std:println

retry = |fn, max_attempts| {
    attempt = 1
    loop {
        result = fn()
        # Bind the condition first: a line starting with "(" would be parsed
        # as a call on the previous line's value.
        done = result != nil || attempt >= max_attempts
        done && return result
        attempt++
    }
}

# Simulated flaky function: fails twice, then succeeds
tries = 0
flaky = || {
    tries++
    match {
        tries < 3 => nil,
        _ => "ok",
    }
}

println(retry(flaky, 5))  # ok
println(tries)            # 3

loop always evaluates to nil and break <value> is not supported, so an explicit return from inside the loop is how you hand a result back.

Next Steps

• Learn about Higher-Order Functions
• Explore Closures in detail
• Study Composition Operators
• Check out Recursion patterns

See Also

• Function Basics
• Higher-Order Functions
• Closures
• Multiple Return Values
• Composition Operators
• Pipe Apply
• Pattern Matching

Regular Expressions

Regular expressions (regex) are patterns for matching text.

Overview

In this repository, regexes are used for:

• Validating formats (emails, URLs, IDs)
• Filtering text (pick only lines that match)
• Branching with match based on whether a string matches a pattern

Matching is all a regex can do in Suji. There is no way to:

• Extract capture groups — there is no ::match(), ::captures() or ::find(), and parentheses in a pattern only group for the matcher’s own purposes
• Replace with a regex — "abc"::replace(/b/, "B") is a type error, because replace() takes two strings
• Split with a regex — split() also takes a plain string separator
• Interpolate a pattern — /${word}/ is compiled literally and fails as an invalid pattern; build the check some other way (see Building patterns at runtime)

Syntax

Regex literals use slashes, and evaluate to a regex value you can store in a variable:

import std:println

email = /^[^@]+@[^@]+\.[^@]+$/

println(email::is_regex())            # true
println("user@example.com" ~ email)   # true

The pattern is compiled by Rust’s regex engine, so you can use inline modifiers like (?i):

import std:println

case_insensitive = /(?i)hello/
println("HeLLo there" ~ case_insensitive)  # true

Matching

Match operator (~)

import std:println

email = "user@example.com"
println(email ~ /^[^@]+@[^@]+\.[^@]+$/)  # true

Negative match (!~)

import std:println

text = "hello world"
println(text !~ /goodbye/)  # true

Using regex in match

You can use a regex literal as a match pattern:

import std:println

line = "[WARN] disk is almost full"
match line {
    /^\[ERROR\]/ => println("error"),
    /^\[WARN\]/ => println("warn"),
    _ => println("other"),
}

Common patterns

Email validation

import std:println

is_email = |s| s ~ /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/

println(is_email("user@example.com"))  # true
println(is_email("nope"))              # false

URL detection

import std:println

is_url = |s| s ~ /^https?:\/\/.+$/

println(is_url("https://example.com"))  # true
println(is_url("example.com"))          # false

Filtering lines

import std:println

lines = [
    "INFO startup ok",
    "WARN slow request",
    "ERROR database down"
]

errors = lines::filter(|line| line ~ /^ERROR\b/)
println(errors::length())  # 1

Building patterns at runtime

A regex literal is fixed at parse time — /${prefix}/ does not interpolate. When the thing you are looking for is only known at runtime, use the string methods instead of a regex:

import std:println

word = "cat"
text = "the cat sat"

# Instead of /${word}/
println(text::contains(word))     # true
println(text::starts_with(word))  # false
println(text::index_of(word))     # 4

Extracting values without capture groups

Since there are no capture groups, validate with a regex and then pull the pieces out with string operations:

import std:println

parse_pair = |text| {
    match {
        text ~ /^[a-z_]+=[0-9]+$/ => {
            parts = text::split("=")
            return (parts[0], parts[1]::to_number())
        }
        _ => (nil, nil),
    }
}

key, value = parse_pair("retries=3")
println("${key} -> ${value}")  # retries -> 3

key, value = parse_pair("garbage")
println("${key} -> ${value}")  # nil -> nil

See Also

• Strings
• Matching Operators

Streams

Streams represent readable/writable handles (files, stdin/stdout/stderr).

All stream reads are eager and blocking: read_all() and read_lines() return the whole contents as a string or a list of strings. There are no lazy iterators, and a stream is not itself iterable — loop through some_stream fails with a runtime error. Iterate stream::read_lines() instead.

Getting streams

import std:io
import std:println

stdin = io:stdin
stdout = io:stdout
stderr = io:stderr

println(stdout::is_stream())  # true

Open a file. io:open(path, create = false, truncate = false) raises a runtime error if the file does not exist and create is false:

import std:io
import std:println

path = `mktemp`

# create = true, truncate = true
f = io:open(path, true, true)
f::close()

# Now it exists, so a plain open works
f = io:open(path)
println(f::read_all())  # (empty file)
f::close()

`rm -f ${path}`

Methods

Streams support:

• stream::read(chunk_kb=8) → String | nil
• stream::read_line() → String | nil
• stream::read_all() → String
• stream::read_lines() → List[String]
• stream::write(text) → Number (bytes written)
• stream::is_terminal() → boolean
• stream::close() → nil
• stream::to_string() → String

That is the complete list. There is no seek, no flush, no each_line, and no io:read_file / io:write_file convenience function.

Examples

Write a file

import std:io
import std:println

path = `mktemp`

out = io:open(path, true, true)
println(out::write("Report\n"))  # 7 (bytes written)
out::write("======\n")
out::close()

`rm -f ${path}`

Read line by line

read_lines() reads the whole file up front and gives you a list, which you then loop over:

import std:io
import std:println

path = `mktemp`
out = io:open(path, true, true)
out::write("first\n\nsecond\n")
out::close()

f = io:open(path)
loop through f::read_lines() with line {
    match { line::trim()::length() > 0 => println(line), _ => nil, }
}
f::close()
# first
# second

`rm -f ${path}`

Note the comma after the final _ => nil arm: a match arm whose body is a bare expression always needs a trailing comma, including the last one.

Writing to stderr

std:print and std:println take an optional stream as their second argument:

import std:io
import std:println

println("this goes to stderr", io:stderr)
println("this goes to stdout")

See Also

• Strings
• io Module
• Shell Integration

Nil

nil represents the absence of a value.

It is its own type with a single value. println(nil) prints nil, and it interpolates as nil inside a string. The only methods it has are to_string() and the is_* type predicates — and note that there is no is_nil(), so test for nil with == nil.

Checking for nil

Use equality and conditional match / guards:

import std:println

value = nil

match { value == nil => { println("Value is nil") } }
match { value != nil => { println("Value exists") } }
# Value is nil

nil is not “falsy”: !nil is a type error (Cannot apply logical NOT to nil), and nil || "default" is a type error too. Comparing is the only test.

Returning nil for “not found”

Because there is no exception mechanism, returning nil is the normal way to say “nothing here”:

import std:println

# The keys are quoted: a map literal that is the whole body of a match arm would
# otherwise be parsed as a block.
get_user = |id| match id {
    1 => {"name": "Alice", "age": 30},
    2 => {"name": "Bob", "age": 25},
    _ => nil,
}

user = get_user(1)
match { user != nil => println("Found: ${user:name}"), _ => println("User not found"), }
# Found: Alice

user = get_user(9)
match { user != nil => println("Found: ${user:name}"), _ => println("User not found"), }
# User not found

A match that has no matching arm also evaluates to nil, so an incomplete match yields nil rather than raising.

Nil in collections

Lists

import std:println

items = [1, nil, 3, nil, 5]
non_nil = items::filter(|x| x != nil)
println(non_nil)  # [1, 3, 5]

Maps

A missing key does not read as nil — it raises Key not found and terminates the program. Use ::get() when the key may be absent:

import std:println

user = {name: "Alice", age: 30}

# This would abort the script:
# email = user:email   # Error: Key not found: Key 'email' not found in map

email = user::get("email")
println(email)  # nil

match { email != nil => println("Email: ${email}"), _ => println("No email provided"), }
# No email provided

get() accepts a default as its second argument, which is usually clearer than checking for nil afterwards:

import std:println

user = {name: "Alice"}
println(user::get("email", "none"))  # none

Note that a key whose stored value really is nil is indistinguishable from a missing key when you use get() with no default — use ::contains() if that distinction matters.

Default values

Use match for defaults. There is no || fallback idiom, because || requires boolean operands:

import std:println

title = nil
title = match { title != nil => title, _ => "Mr./Ms.", }
println(title)  # Mr./Ms.

See Also

• Booleans
• Maps
• Match Expressions
• Error Handling

Operators

Operators are special symbols that perform operations on values and expressions.

Overview

Suji provides a rich set of operators for arithmetic, comparison, logic, pattern matching, and data flow.

Operator Categories

Arithmetic Operators

Perform mathematical calculations:

import std:println

a = 10
b = 3

println(a + b)    # 13 (addition)
println(a - b)    # 7 (subtraction)
println(a * b)    # 30 (multiplication)
println(a / b)    # 3.3333333333333333333333333333 (division)
println((a / b)::floor())   # 3 (integer division via floor)
println(a % b)    # 1 (modulo/remainder)
println(a ^ b)    # 1000 (exponentiation)
println(-a)       # -10 (negation)

Learn more about Arithmetic Operators →

Relational Operators

Compare values and return booleans:

import std:println

x = 5
y = 10

println(x == y)   # false (equal to)
println(x != y)   # true (not equal to)
println(x < y)    # true (less than)
println(x <= y)   # true (less than or equal)
println(x > y)    # false (greater than)
println(x >= y)   # false (greater than or equal)

Learn more about Relational Operators →

Logical Operators

Combine boolean expressions. Both operands must already be booleans — Suji has no truthiness, and there are no and / or / not keywords:

import std:println

a = true
b = false

println(a && b)   # false (AND)
println(a || b)   # true (OR)
println(!a)       # false (NOT)

Learn more about Logical Operators →

Assignment Operators

Assign and update variables:

import std:println

x = 10

# Basic assignment
x = 20

# Compound assignment
x = x + 5    # or: x += 5
x = x - 3    # or: x -= 3
x = x * 2    # or: x *= 2
x = x / 4    # or: x /= 4
x = x % 3    # or: x %= 3

println(x)

Learn more about Assignment Operators →

Matching Operators

Test patterns with regular expressions:

import std:println

text = "user@example.com"

# Match operator
is_email = text ~ /^[^@]+@[^@]+$/
println(is_email)  # true

# Negative match
not_number = text !~ /^\d+$/
println(not_number)  # true

Learn more about Matching Operators →

Pipe and Composition Operators

Suji has three distinct pipe-ish operators plus two composition operators. They are easy to confuse, so keep them straight:

There is no |< operator.

import std:println

double = |x| x * 2
inc = |x| x + 1

# Pipe-apply passes a value into a function
println(5 |> double)          # 10
println(double <| 5)          # 10
println(5 |> double |> inc)   # 11

# Composition builds a new function instead of calling one
then_inc = double >> inc
println(then_inc(5))          # 11

inc_first = double << inc
println(inc_first(5))         # 12

Learn more about the Pipeline Operator → · Pipe Apply → · Function Composition →

Operator Precedence

Operators are evaluated in a specific order. The full table, lowest to highest precedence:

1. Assignment (=, including destructuring a, b = …)
2. Compound assignment (+=, -=, *=, /=, %=)
3. Backward pipe-apply (<|, right-associative)
4. Forward pipe-apply (|>)
5. Pipeline (|)
6. Function composition (>>, <<)
7. Logical OR (||)
8. Logical AND (&&)
9. Regex match (~, !~)
10. Equality (==, !=)
11. Ordering (<, <=, >, >=)
12. Range (.., ..=)
13. Addition, Subtraction (+, -)
14. Multiplication, Division, Modulo (*, /, %)
15. Unary (-, !)
16. Exponentiation (^, right-associative)
17. Postfix ((), [], ::, :, ++, --)

Note that || binds less tightly than &&, and both bind less tightly than the regex operators — which in turn bind less tightly than ==. There is no . member access operator: :: calls a method and : reads a map key.

Precedence Examples

import std:println

# Without parentheses
result = 2 + 3 * 4
println(result)  # 14 (multiplication first)

# With parentheses
result = (2 + 3) * 4
println(result)  # 20 (addition first)

# Exponentiation before multiplication
result = 2 * 3 ^ 2
println(result)  # 18 (3^2 = 9, then 2*9)

# Comparison before logical
result = 5 > 3 && 10 < 20
println(result)  # true (comparisons first, then &&)

Associativity

When operators have the same precedence, associativity determines evaluation order:

Left-Associative

Most operators evaluate left to right:

import std:println

# Left to right: (10 - 3) - 2
result = 10 - 3 - 2
println(result)  # 5

# Left to right: (12 / 3) / 2
result = 12 / 3 / 2
println(result)  # 2

Right-Associative

Exponentiation and assignment evaluate right to left:

import std:println

# Right to left: 2 ^ (3 ^ 2)
result = 2 ^ 3 ^ 2
println(result)  # 512 (2^9)

# Assignment chains (right to left)
a = b = c = 10
println(a)  # 10

Overloading

Some operators work differently based on operand types:

Addition (+)

+ works on two numbers, two strings, or two lists. It never mixes types:

import std:println

# Numbers: arithmetic addition
println(5 + 3)  # 8

# Strings: concatenation
println("Hello" + " " + "World")  # Hello World

# Lists: concatenation
println([1, 2] + [3, 4])  # [1, 2, 3, 4]

# Mixing types is a type error:
#   "a" + 1     ->  Type error: Cannot add string and number
# Convert or interpolate instead:
println("a" + 1::to_string())  # a1
println("a${1}")               # a1

Multiplication (*)

* is numbers-only. Unlike some scripting languages, Suji has no string or list repetition operator:

import std:println

# Numbers: arithmetic multiplication
println(5 * 3)  # 15

# "Ha" * 3   ->  Type error: Cannot multiply string and number
# [1, 2] * 3 ->  Type error: Cannot multiply list and number

# Use the repeat() method for strings:
println("Ha"::repeat(3))  # HaHaHa

Short-Circuit Evaluation

Logical operators use short-circuit evaluation:

AND (&&)

If left side is false, right side is not evaluated:

import std:println

# Right side not evaluated, so no division-by-zero error
result = false && (10 / 0)
println(result)  # false

OR (||)

If left side is true, right side is not evaluated:

import std:println

# Right side not evaluated
result = true || (10 / 0)
println(result)  # true

This is useful for safe operations:

import std:println

# Safe property access
user = nil
name_present = user != nil && user:name != nil
println(name_present)  # false (no error accessing nil)

Because && and || require boolean operands, there is no x || "default" idiom in Suji — nil || "default" is a type error. Use match (or map::get(key, default)) instead:

import std:println

user_setting = nil

config_value = match user_setting {
    nil => "default",
    _ => user_setting,
}
println(config_value)  # default

# For maps, get() already takes a default
settings = {theme: "dark"}
println(settings::get("lang", "en"))  # en

Best Practices

DO:

• Use parentheses for clarity in complex expressions
• Understand precedence to avoid bugs
• Leverage short-circuit evaluation for safety
• Use pipes for readable data transformations
• Keep expressions simple and readable

DON’T:

• Write deeply nested expressions without parentheses
• Rely on obscure precedence rules
• Ignore short-circuit evaluation opportunities
• Chain too many operations in one expression
• Sacrifice readability for brevity

Quick Reference

Next Steps

Explore each operator category in detail:

1. Arithmetic Operators - Mathematical operations
2. Relational Operators - Equality and ordering
3. Logical Operators - Boolean logic
4. Assignment Operators - Variable assignment
5. Matching Operators - Regex matching
6. Pipeline Operator - stdin/stdout pipelines
7. Pipe Apply - Applying a value to a function
8. Function Composition - Building functions from functions

See Also

• Operator Precedence Table
• Expression Syntax
• Pattern Matching
• Functions

Assignment Operators

Assignment operators set or update variable values.

Overview

Assignment is how you store values in variables and update them over time.

Basic Assignment (=)

The simplest and most common operator:

import std:println

# Assign a value to a variable
x = 42
name = "Alice"
active = true

println(x)     # 42
println(name)  # Alice

Compound Assignment

Combine an operation with assignment for concise updates:

Addition Assignment (+=)

import std:println

x = 10
x += 5  # same as: x = x + 5

println(x)  # 15

Subtraction Assignment (-=)

import std:println

x = 20
x -= 3  # same as: x = x - 3

println(x)  # 17

Multiplication Assignment (*=)

import std:println

x = 5
x *= 4  # same as: x = x * 4

println(x)  # 20

Division Assignment (/=)

import std:println

x = 100
x /= 4  # same as: x = x / 4

println(x)  # 25

Modulo Assignment (%=)

import std:println

x = 17
x %= 5  # same as: x = x % 5

println(x)  # 2

Increment and Decrement (++, --)

++ and -- are postfix operators that mutate the variable in place. There are no prefix forms — ++x fails with Increment (++) can only be applied to variables. Note that unlike C, x++ evaluates to the value after the increment:

import std:println

count = 0
count++
count++
println(count)  # 2

count--
println(count)  # 1

x = 1
y = x++
println(y)  # 2 (the incremented value, not 1)

Assignment Semantics

Rebinding

Assignment in Suji rebinds the variable to a new value:

import std:println

x = 10
println(x)  # 10

x = 20  # Rebind x to new value
println(x)  # 20

x = "hello"  # Can change type
println(x)  # hello

Immutability

Strings and tuples are immutable. Lists and maps are mutable (some methods modify the value in place):

import std:println

list = [1, 2, 3]
list::push(4)
println(list)  # [1, 2, 3, 4]

Destructuring Assignment

Tuple Destructuring

Unpack tuple values into variables. The target list is a bare comma-separated list of names — do not wrap it in parentheses. (x, y) = (10, 20) fails with Invalid assignment target:

import std:println

# Basic destructuring
x, y = (10, 20)
println("x: ${x}, y: ${y}")  # x: 10, y: 20

# Any number of targets, as long as the arity matches
a, b, c, d = (1, 2, 3, 4)
println("${a}, ${b}, ${c}, ${d}")  # 1, 2, 3, 4

# Ignore values with underscore
first, _, third = (1, 2, 3)
println("${first}, ${third}")  # 1, 3

Nested destructuring is not supported. a, (b, c), d = … is a parse error; unpack in two steps instead:

import std:println

outer, inner = (1, (2, 3))
p, q = inner

println("${outer}, ${p}, ${q}")  # 1, 2, 3

Multiple Return Values

return a, b returns a tuple, which the caller can destructure:

import std:println

divide_with_remainder = |a, b| {
    return (a / b)::floor(), a % b
}

quotient, remainder = divide_with_remainder(17, 5)
println("${quotient} remainder ${remainder}")  # 3 remainder 2

Assignment vs Equality

Don’t confuse assignment (=) with equality (==):

import std:println

x = 5  # Assignment: set x to 5

# Equality check
match x == 5 {
    true => println("x is 5"),
    false => {},
}

# Assignment in condition would be an error
# match x = 5 {  # Error: Assignment not allowed in condition
#     ...
# }

Chained Assignment

Assign the same value to multiple variables:

import std:println

# Right-to-left evaluation
a = b = c = 10

println(a)  # 10
println(b)  # 10
println(c)  # 10

Common Patterns

Accumulator

import std:println

numbers = [1, 2, 3, 4, 5]
sum = 0

loop through numbers with num {
    sum += num
}

println(sum)  # 15

Counter

import std:println

items = [3, -1, 7, 0, 12]
count = 0

loop through items with item {
    match { item > 0 => { count++ } }
}

println("${count} valid items")  # 3 valid items

Swap Values

import std:println

a = 10
b = 20

# Swap using tuple destructuring
a, b = (b, a)

println("a: ${a}, b: ${b}")  # a: 20, b: 10

Update Configuration

import std:println

config = {
    theme: "light",
    lang: "en",
    notifications: true
}

# Update single value
config["theme"] = "dark"

# Update multiple values
config["lang"] = "es"
config["notifications"] = false

println(config)  # {theme: dark, lang: es, notifications: false}

Common Pitfalls

Pitfall 1: Forgetting Immutability

list = [1, 2, 3]

# push() modifies the list, but returns nil
result = list::push(4)
# list is now [1, 2, 3, 4], and result is nil

Pitfall 2: Assignment in Conditions

x = 5

# Typo: assignment instead of comparison
# match x = 10 {  # Error
#     ...
# }

# Correct: equality check
match x == 10 {
    true => {
        # ...
    },
    false => {},
}

Pitfall 3: Shadowing vs Mutation

import std:println

x = 10

# This creates a new binding in inner scope
{
    x = 20  # Rebinds x
    println(x)  # 20
}

# x is now 20 (not shadowing in Suji, actual rebinding)
println(x)  # 20

Pitfall 4: Compound Assignment Type Changes

import std:println

x = "10"

# This would be an error, so it is commented out:
#   x += 5   ->  Type error: Cannot add string and number

# Convert first
x = x::to_number()
x += 5

println(x)  # 15

Best Practices

DO:

• Use compound assignment for concise updates
• Use destructuring for multiple return values
• Choose descriptive variable names
• Initialize variables before use
• Keep assignments simple and clear

DON’T:

• Confuse = with ==
• Forget that operations return new values
• Use overly complex chained assignments
• Mutate external state unexpectedly
• Reuse variable names for different purposes

Examples

Running Total

import std:println

prices = [10.50, 25.00, 15.75, 30.00]
total = 0.0

loop through prices with price {
    total = total + price
    println("Subtotal: $${total}")
}

println("Final total: $${total}")

State Machine

import std:println

state = "idle"

process_event = |event| {
    state = match (state, event) {
        ("idle", "start") => "running",
        ("running", "pause") => "paused",
        ("paused", "resume") => "running",
        ("running", "stop") => "idle",
        _ => state,
    }
}

process_event("start")
println(state)  # running

Note the wildcard arm: a bare identifier in a pattern position is treated as a string literal, not a binding, so (s, _) => s would try to match the literal tuple ("s", "_"). Use _ and refer to the outer variable instead.

Fibonacci Sequence

import std:println

a = 0
b = 1

loop through (0..10) {
    println(a)
    a, b = (b, a + b)  # Tuple swap and update
}

Build Configuration

import std:println

config = {}

# Build up configuration
config["env"] = "production"
config["debug"] = false
config["port"] = 8080
config["host"] = "0.0.0.0"

println(config)  # {env: production, debug: false, port: 8080, host: 0.0.0.0}

Next Steps

• Learn about Arithmetic Operators
• Explore Language Overview
• Study Destructuring

See Also

• Language Overview
• Arithmetic Operators
• Tuples
• Destructuring

Arithmetic Operators

Arithmetic operators perform mathematical calculations on numeric values.

Overview

Suji provides all standard arithmetic operators for working with numbers.

Basic Operations

Addition (+)

Add two numbers:

import std:println

println(5 + 3)       # 8
println(10.5 + 2.3)  # 12.8
println(-5 + 10)     # 5

+ also concatenates two strings or two lists, but it never mixes types: "a" + 1 is a type error. Use ::to_string() or string interpolation instead.

import std:println

# String concatenation
println("Hello" + " " + "World")  # Hello World

# List concatenation
println([1, 2] + [3, 4])  # [1, 2, 3, 4]

# Mixing types is a type error, so convert or interpolate:
println("count: " + 3::to_string())  # count: 3
println("count: ${3}")               # count: 3

Subtraction (-)

Subtract one number from another:

import std:println

println(10 - 3)      # 7
println(20.5 - 5.5)  # 15
println(5 - 10)      # -5

Multiplication (*)

Multiply two numbers:

import std:println

println(5 * 3)       # 15
println(2.5 * 4)     # 10
println(-3 * 4)      # -12

* is numbers only. There is no repetition operator for strings or lists — "Ha" * 3 and [1, 2] * 3 are both type errors. Use ::repeat(n) for strings:

import std:println

println("Ha"::repeat(3))  # HaHaHa

# "Ha" * 3   ->  Type error: Cannot multiply string and number
# [1, 2] * 3 ->  Type error: Cannot multiply list and number

Lists have no repeat method; build one with a loop if you need it:

import std:println

repeated = []
loop through 0..3 {
    repeated = repeated + [1, 2]
}

println(repeated)  # [1, 2, 1, 2, 1, 2]

Division (/)

Divide one number by another. Suji has a single decimal number type, so division is always decimal division. Non-terminating results are rounded to 28 significant digits:

import std:println

println(10 / 2)      # 5
println(10 / 3)      # 3.3333333333333333333333333333
println(15.0 / 4.0)  # 3.75

Dividing by zero is a runtime error that terminates the program — there is no Infinity and no way to catch it, so check the divisor first.

Integer Division

Suji uses decimal division. To get integer division, use the floor() method:

import std:println

println((10 / 3)::floor())     # 3
println((17 / 5)::floor())     # 3
println((-10 / 3)::floor())    # -4 (rounds down)

There is no // integer-division operator; floor() is the idiom.

Modulo (%)

Get remainder after division:

import std:println

println(10 % 3)      # 1
println(17 % 5)      # 2
println(20 % 4)      # 0 (evenly divisible)

# Useful for checking even/odd
println(7 % 2 == 0)  # false (odd)
println(8 % 2 == 0)  # true (even)

Exponentiation (^)

Raise a number to a power. The exponent must be a non-negative integer:

import std:println

println(2 ^ 3)       # 8 (2³)
println(10 ^ 2)      # 100 (10²)
println(2 ^ 10)      # 1024

Fractional and negative exponents are rejected:

• 4 ^ 0.5 → Invalid operation: Power exponent must be an integer
• 2 ^ (0 - 1) → Invalid operation: Negative exponents not supported

Use ::sqrt() for square roots and division for reciprocals:

import std:println

println(16::sqrt())  # 4
println(1 / 2 ^ 1)   # 0.50

Also note that ^ binds tighter than unary minus, so -2 ^ 2 is -(2 ^ 2):

import std:println

println(-2 ^ 2)      # -4
println((-2) ^ 2)    # 4

Negation (-)

Negate a number (unary operator):

import std:println

x = 5
println(-x)          # -5
println(-(-x))       # 5 (double negation)

y = -10
println(-y)          # 10

Compound Assignment

Arithmetic operations combined with assignment:

import std:println

x = 10

x += 5      # same as: x = x + 5
println(x)  # 15

x -= 3      # same as: x = x - 3
println(x)  # 12

x *= 2      # same as: x = x * 2
println(x)  # 24

x /= 4      # same as: x = x / 4
println(x)  # 6

x %= 5      # same as: x = x % 5
println(x)  # 1

Operator Precedence

The arithmetic slice of the precedence table, lowest to highest:

1. Addition, Subtraction (+, -)
2. Multiplication, Division, Modulo (*, /, %)
3. Unary negation and not (-, !)
4. Exponentiation (^, right-associative)

Parentheses override all of it. Note that ^ binds tighter than unary -, which differs from the usual PEMDAS reading — see the -2 ^ 2 example above. The full table for all operators is in the operators overview.

Examples

import std:println

# Multiplication before addition
println(2 + 3 * 4)       # 14 (not 20)

# Exponentiation before multiplication
println(2 * 3 ^ 2)       # 18 (2 * 9, not 6²)

# Use parentheses to override
println((2 + 3) * 4)     # 20
println((2 * 3) ^ 2)     # 36

# Complex expression
println(10 + 2 * 3 ^ 2 - 4 / 2)  # 26
# Breakdown: 10 + 2*9 - 2 = 10 + 18 - 2 = 26

Associativity

Most arithmetic operators are left-associative:

import std:println

# Left to right: (10 - 3) - 2
println(10 - 3 - 2)  # 5

# Left to right: (20 / 4) / 2
println(20 / 4 / 2)  # 2.50

(Scale is preserved through division, which is why this prints 2.50 rather than 2.5.)

Exponentiation is right-associative:

import std:println

# Right to left: 2 ^ (3 ^ 2)
println(2 ^ 3 ^ 2)   # 512 (2^9, not 8^2)

Common Patterns

Increment/Decrement

import std:println

count = 0
count++            # Increment (also: count += 1)
println(count)     # 1

count--            # Decrement (also: count -= 1)
println(count)     # 0

Averaging

import std:println

numbers = [10, 20, 30, 40, 50]
sum = numbers::fold(0, |acc, x| acc + x)
average = sum / numbers::length()
println(average)  # 30

Scaling

import std:println

# Scale value to percentage
value = 75
max_value = 200
percentage = (value / max_value) * 100
println("${percentage}%")  # 37.500%

Rounding

Rounding lives on the number type, not in std:math — there is no math:round, math:floor, math:ceil, math:abs or math:sqrt:

import std:println

value = 3.14159

# Round to 2 decimal places
rounded = (value * 100)::round() / 100
println(rounded)  # 3.14

Wrapping (Circular)

import std:println

# Wrap index in circular buffer
index = 15
buffer_size = 10
wrapped = index % buffer_size
println(wrapped)  # 5

Common Pitfalls

Pitfall 1: Division by Zero

Division by zero terminates the program, and there is no try/catch, so the only option is to check first:

import std:println

# result = 10 / 0   ->  Runtime error: Division by zero (process exits)

# Check before dividing
safe_divide = |a, b| {
    match b {
        0 => nil,
        _ => a / b,
    }
}

println(safe_divide(10, 0))  # nil
println(safe_divide(10, 4))  # 2.50

Pitfall 2: Integer Division Confusion

import std:println

# Regular division always returns decimal
println(10 / 3)   # 3.3333333333333333333333333333

# Integer division using floor method
println((10 / 3)::floor())  # 3

# Be explicit about intent
total = 10
count = 4
println(total / count)              # 2.50 - when you want decimal
println((total / count)::floor())   # 2    - when you want an integer

Suji has no // operator. Writing a // b starts a regex literal and produces a lexer error, not integer division.

Pitfall 3: Modulo with Negatives

import std:println

# Result has sign of dividend (left operand)
println(10 % 3)    # 1
println(-10 % 3)   # -1 (not 2)
println(10 % -3)   # 1

Pitfall 4: Assuming Binary Floating Point

Suji’s single number type is a fixed-precision decimal, not a binary float, so the classic 0.1 + 0.2 surprise does not happen here:

import std:println

println(0.1 + 0.2)         # 0.3
println(0.1 + 0.2 == 0.3)  # true

What does bite is the precision limit: results are rounded to about 28 significant digits, and exceeding the maximum value (79228162514264337593543950335) aborts the process rather than producing an approximation. Decimals are not big integers.

Pitfall 5: Operator Precedence Confusion

import std:println

# Unclear intent
result = 2 + 3 * 4 ^ 2 - 5

# Use parentheses for clarity
result = 2 + (3 * (4 ^ 2)) - 5
println(result)  # 45

Best Practices

DO:

• Use parentheses for clarity in complex expressions
• Check for division by zero before dividing — there is no way to recover after
• Be aware of the 28-significant-digit precision limit
• Use (a / b)::floor() when you need integer division
• Consider modulo sign behavior with negatives

DON’T:

• Rely on obscure precedence rules (^ binds tighter than unary -)
• Ignore division by zero possibilities
• Reach for //, **, "x" * 3 or math:sqrt — none of them exist
• Assume modulo always returns positive

Examples

Distance Between Points

std:math has no sqrt — square roots are a number method:

import std:println

distance = |x1, y1, x2, y2| {
    dx = x2 - x1
    dy = y2 - y1
    sum_of_squares = (dx ^ 2) + (dy ^ 2)
    sum_of_squares::sqrt()
}

println(distance(0, 0, 3, 4))  # 5

Temperature Conversion

import std:println

celsius_to_fahrenheit = |c| {
    (c * 9 / 5) + 32
}

fahrenheit_to_celsius = |f| {
    (f - 32) * 5 / 9
}

println(celsius_to_fahrenheit(0))    # 32
println(celsius_to_fahrenheit(100))  # 212
println(fahrenheit_to_celsius(32))   # 0

Compound Interest

import std:println

compound_interest = |principal, rate, time| {
    principal * ((1 + rate) ^ time)
}

# $1000 at 5% for 10 years
final = compound_interest(1000, 0.05, 10)
println("$${final::round()}")  # $1629

Digit Sum

import std:println

digit_sum = |n| {
    sum = 0
    num = n::abs()
    
    loop {
        num == 0 && break
        sum = sum + (num % 10)
        num = (num / 10)::floor()
    }
    
    sum
}

println(digit_sum(12345))  # 15 (1+2+3+4+5)

Next Steps

• Learn about Relational Operators
• Explore Math Module for trigonometry, logs and PI/E
• Study Operator Precedence in detail
• Check out Number Data Type

See Also

• Numbers
• Math Module
• Operator Precedence
• Assignment Operators

Relational Operators

Relational operators compare values and return boolean results.

Overview

Relational (comparison) operators test relationships between values. They’re essential for conditional logic, sorting, and filtering operations.

This page covers both equality (==, !=) and ordering (<, <=, >, >=). The two behave differently across types: equality between mismatched types simply returns false, while ordering between mismatched types is a runtime type error.

Operators

Equal To (==)

Tests if two values are equal.

import std:println

println(5 == 5)       # true
println(5 == 3)       # false
println("a" == "a")   # true
println("a" == "A")   # false
println(true == true) # true

Works with: every type. Lists, maps and tuples compare by value.

Type-strict: 5 == "5" is false (number ≠ string) — comparing different types is never an error, it is just false.

Not Equal To (!=)

Tests if two values are not equal.

import std:println

println(5 != 3)       # true
println(5 != 5)       # false
println("a" != "b")   # true
println("a" != "a")   # false

Equivalent to: !(a == b)

Less Than (<)

Tests if left value is less than right value.

import std:println

println(3 < 5)      # true
println(5 < 3)      # false
println(5 < 5)      # false
println("a" < "b")  # true (lexicographic)

Works with: Numbers, strings (lexicographic comparison). Anything else — including two booleans, two lists, or a number and a string — is a runtime type error.

Less Than or Equal (<=)

Tests if left value is less than or equal to right value.

import std:println

println(3 <= 5)     # true
println(5 <= 5)     # true
println(7 <= 5)     # false
println("a" <= "a") # true

Greater Than (>)

Tests if left value is greater than right value.

import std:println

println(5 > 3)      # true
println(3 > 5)      # false
println(5 > 5)      # false
println("b" > "a")  # true (lexicographic)

Works with: Numbers, strings (lexicographic comparison)

Greater Than or Equal (>=)

Tests if left value is greater than or equal to right value.

import std:println

println(5 >= 3)     # true
println(5 >= 5)     # true
println(3 >= 5)     # false
println("b" >= "b") # true

Type Compatibility

Numbers

All relational operators work with numbers:

import std:println

println(3.14 < 3.15)   # true
println(100 >= 50)     # true
println(42 == 42.0)    # true (there is only one number type)
println(0 != -0)       # false (both zero)

Strings

Strings use lexicographic (dictionary) ordering:

import std:println

println("a" < "b")      # true
println("apple" < "banana")  # true
println("A" < "a")      # true (uppercase before lowercase)
println("10" < "2")     # true (string comparison, not numeric)

Note: String comparison is case-sensitive and uses Unicode code points.

Booleans

Booleans can be compared for equality:

import std:println

println(true == true)   # true
println(true == false)  # false
println(true != false)  # true

Note: Order comparisons are not supported for booleans — true < false fails with Type error: Cannot compare boolean and boolean.

Nil

Nil can be compared for equality:

import std:println

println(nil == nil)     # true
println(nil != nil)     # false
println(5 == nil)       # false
println("text" != nil)  # true

Collections

Lists, maps and tuples support equality only. They are compared element by element (maps by key/value pairs):

import std:println

println([1, 2] == [1, 2])        # true
println([1, 2] == [2, 1])        # false
println([1, 2] == [1, 2, 3])     # false
println((1, 2) == (1, 2))        # true
println({a: 1} == {a: 1})        # true

There is no ordering for collections: [1, 2] < [1, 3] fails with Type error: Cannot compare list and list. To sort a list of lists you would have to compare a derived scalar (e.g. an element or a length) yourself.

Common Patterns

Range Checking

import std:println

age = 25

match { age >= 18 && age < 65 => { println("Working age") } }

# Numeric ranges
score = 85
match { score >= 80 && score < 90 => { println("Grade: B") } }

Boundary Validation

import std:println

validate_percentage = |value| {
    match { value < 0 || value > 100 => {
        println("Error: Must be between 0 and 100")
        return false
    } }
    true
}

println(validate_percentage(50))   # true
println(validate_percentage(150))  # prints the error, then false

Sorting

import std:println

numbers = [5, 2, 8, 1, 9]

sorted = numbers::sort()
println(sorted)  # [1, 2, 5, 8, 9]

Finding Min/Max

import std:println

find_min = |list| {
    list::length() == 0 && return nil
    
    min = list[0]
    loop through list with item {
        match { item < min => { min = item } }
    }
    min
}

numbers = [5, 2, 8, 1, 9]
println(find_min(numbers))  # 1

Filtering

import std:println

numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

# Filter by comparison
evens = numbers::filter(|x| x % 2 == 0)
large = numbers::filter(|x| x > 5)
range = numbers::filter(|x| x >= 3 && x <= 7)

println(evens)  # [2, 4, 6, 8, 10]
println(large)  # [6, 7, 8, 9, 10]
println(range)  # [3, 4, 5, 6, 7]

Conditional Logic

import std:println

classify = |temp| {
    match {
        temp < 0 => "Freezing",
        temp < 15 => "Cold",
        temp < 25 => "Comfortable",
        _ => "Hot",
    }
}

println(classify(-5))   # Freezing
println(classify(20))   # Comfortable
println(classify(30))   # Hot

String Comparison Details

Lexicographic Order

Strings are compared character by character using Unicode values:

import std:println

# Character-by-character comparison
println("abc" < "abd")      # true ('c' < 'd')
println("abc" < "abcd")     # true (shorter is less if prefix matches)

# Case sensitivity
println("ABC" < "abc")      # true (uppercase < lowercase in Unicode)
println("apple" < "Apple")  # false

# Numbers as strings
println("10" < "2")         # true ("1" < "2" as strings)
println("10" < "9")         # true ("1" < "9" as strings)

Case-Insensitive Comparison

For case-insensitive comparison, normalize first:

import std:println

compare_ignore_case = |a, b| {
    a::lower() == b::lower()
}

println(compare_ignore_case("Hello", "hello"))  # true
println(compare_ignore_case("Apple", "APPLE"))  # true

Chaining Comparisons

You can chain comparisons with logical operators:

import std:println

x = 5

# Multiple conditions
match { x > 0 && x < 10 => { println("x is between 0 and 10") } }

# Range check
in_range = x >= 1 && x <= 100
println(in_range)  # true

Best Practices

DO:

• Use == for equality, not = (assignment)
• Compare same types (number with number, string with string)
• Use parentheses for clarity in complex conditions
• Normalize strings before case-insensitive comparison
• Check for nil before comparing

DON’T:

• Compare different types (5 == “5” is always false)
• Use = in conditions (syntax error)
• Forget that string comparison is case-sensitive
• Chain operators without logical connectors (a < b < c doesn’t work)
• Assume order comparison works for all types

Examples

Temperature Converter with Validation

import std:println

celsius_to_fahrenheit = |c| {
    below_absolute_zero = c < -273.15
    match below_absolute_zero {
        true => {
            println("Error: Below absolute zero")
            return nil
        }
        _ => nil,
    }
    result = (c * 9 / 5) + 32
    result
}

f = celsius_to_fahrenheit(100)
match f {
    nil => {},
    _ => println("${f}°F"),
}

Note the local variable before (c * 9 / 5): a line that starts with ( continues the previous expression, so it would otherwise be parsed as a call on the match result.

Grade Calculator

import std:println

get_grade = |score| {
    (score < 0 || score > 100) && return "Invalid score"
    
    match {
        score >= 90 => "A",
        score >= 80 => "B",
        score >= 70 => "C",
        score >= 60 => "D",
        _ => "F",
    }
}

println(get_grade(85))   # B
println(get_grade(92))   # A
println(get_grade(105))  # Invalid score

List Deduplication

import std:println

deduplicate = |list| {
    unique = []
    
    loop through list with item {
        found = false
        loop through unique with existing {
            match { existing == item => {
                found = true
                break
            } }
        }
        
        match { !found => { unique::push(item) } }
    }
    
    unique
}

numbers = [1, 2, 2, 3, 3, 3, 4, 5, 5]
result = deduplicate(numbers)
println(result)  # [1, 2, 3, 4, 5]

Binary Search

import std:println

binary_search = |sorted_list, target| {
    left = 0
    right = sorted_list::length() - 1
    
    loop {
        left > right && return nil  # Not found
        
        mid = ((left + right) / 2)::floor()
        mid_val = sorted_list[mid]
        
        match {
            mid_val == target => return mid,
            mid_val < target => left = mid + 1,
            _ => right = mid - 1,
        }
    }
}

numbers = [1, 3, 5, 7, 9, 11, 13]
index = binary_search(numbers, 7)
println(index)  # 3

Operator Summary

See Also

• Logical Operators - AND, OR, NOT
• Arithmetic Operators - Math operations
• Matching Operators - Regex matching
• Control Flow - conditionals, loops, match

Logical Operators

Logical operators combine boolean expressions and short-circuit.

Suji does not have general truthiness: only true counts as true in boolean contexts. The operators are &&, || and ! — the words and, or and not are not keywords in Suji and using them produces an Undefined variable error.

Crucially, && and || always evaluate to a boolean, never to one of their operands. That means the x || "default" idiom from other languages does not exist here: nil || "default" fails with Type error: Logical OR requires boolean operands. See Default Values below for what to write instead.

Overview

Logical operators are essential for building complex conditions in match expressions, loops, and filters.

The Three Logical Operators

AND (&&)

Returns true only if both operands are true:

import std:println

println(true && true)    # true
println(true && false)   # false
println(false && true)   # false
println(false && false)  # false

OR (||)

Returns true if at least one operand is true:

import std:println

println(true || true)    # true
println(true || false)   # true
println(false || true)   # true
println(false || false)  # false

NOT (!)

Negates a boolean value:

import std:println

println(!true)           # false
println(!false)          # true
println(!!true)          # true (double negation)

Short-Circuit Evaluation

Logical operators use short-circuit evaluation for efficiency and safety.

AND Short-Circuit

If the left side is false, the right side is NOT evaluated:

import std:println

# Right side never evaluated (no error!)
result = false && (10 / 0)
println(result)  # false

# This is useful for safe operations
user = nil
is_admin = user != nil && user:is_admin == true
println(is_admin)  # false - no error accessing nil, because user != nil is false

OR Short-Circuit

If the left side is true, the right side is NOT evaluated:

import std:println

# Right side never evaluated
result = true || (10 / 0)
println(result)  # true

# `||` short-circuits on boolean `true`, and its result is always a boolean.
#
# If you want a default when a value may be `nil`, use `match`:
maybe_timeout_ms = nil
timeout_ms = match maybe_timeout_ms {
    nil => 1000,
    _ => maybe_timeout_ms,
}
println(timeout_ms)  # 1000

Note the _ arm rather than a binding: patterns cannot bind variables in Suji, and a bare identifier in a pattern is treated as a string literal.

Combining Conditions

Multiple AND

All conditions must be true:

import std:println

age = 25
has_license = true
has_insurance = true

can_drive = age >= 18 && has_license && has_insurance
println(can_drive)  # true

Multiple OR

At least one condition must be true:

import std:println

day = "Sunday"
is_national_holiday = false
is_regional_holiday = false

is_weekend = day == "Saturday" || day == "Sunday"
is_holiday = is_national_holiday || is_regional_holiday

day_off = is_weekend || is_holiday
println(day_off)  # true

Mixed AND/OR

import std:println

# Must be adult AND (have license OR have permit)
age = 17
has_license = false
has_permit = true

can_drive = age >= 18 && (has_license || has_permit)
println(can_drive)  # false (not adult)

age = 18
can_drive = age >= 18 && (has_license || has_permit)
println(can_drive)  # true (adult with permit)

Operator Precedence

Lowest to highest:

1. OR (||) - lowest
2. AND (&&)
3. NOT (!) - highest (it sits with the other unary operators, above *// and below ^)

All three bind less tightly than the comparison and regex operators, so a == b && c > d groups the way you would expect without parentheses.

import std:println

# NOT first, then AND, then OR
result = true || false && !false
# Parsed as: true || (false && (!false))
println(result)  # true

# Use parentheses for clarity
result = (true || false) && (!false)
println(result)  # true

Common Patterns

Validation

Reading a missing map key raises Key not found, so user:name != nil is only safe when the key is known to exist. Use ::get(key, default) to read defensively:

import std:println

validate_user = |user| {
    name = user::get("name", "")
    email = user::get("email", "")
    age = user::get("age", 0)

    has_name = name::length() > 0
    has_email = email ~ /^[^@]+@[^@]+$/
    is_adult = age >= 18

    has_name && has_email && is_adult
}

println(validate_user({name: "Alice", email: "alice@example.com", age: 30}))  # true
println(validate_user({name: "Bob"}))                                        # false

Range Checking

import std:println

in_range = |value, min_val, max_val| {
    value >= min_val && value <= max_val
}

println(in_range(5, 0, 10))   # true
println(in_range(15, 0, 10))  # false

Default Values

There is no || fallback and no ?? operator. Use map::get(key, default) for maps, and match for anything else:

import std:println

get_name = |user| {
    preferred = user::get("preferred_name", nil)
    first = user::get("first_name", nil)

    match {
        preferred != nil => preferred,
        first != nil => first,
        _ => "Anonymous",
    }
}

println(get_name({preferred_name: "Ada"}))  # Ada
println(get_name({first_name: "Grace"}))    # Grace
println(get_name({}))                       # Anonymous

Or, when a single default suffices, let get do the work:

import std:println

user = {}
println(user::get("first_name", "Anonymous"))  # Anonymous

Guard Clauses

import std:println

process_user = |user| {
    # Early returns with logical checks (guard clauses)
    invalid = user == nil || !user::get("is_active", false)
    invalid && return "Invalid user"

    unauthorized = user::get("age", 0) < 18 || !user::get("has_consent", false)
    unauthorized && return "Unauthorized"

    "Processing user..."
}

println(process_user(nil))                                            # Invalid user
println(process_user({is_active: true, age: 12}))                     # Unauthorized
println(process_user({is_active: true, age: 30, has_consent: true}))  # Processing user...

Access Control

import std:println

can_edit = |user, document| {
    is_owner = user:id == document:owner_id
    is_admin = user:role == "admin"
    is_collaborator = document:collaborators::contains(user:id)

    is_owner || is_admin || is_collaborator
}

alice = {id: 1, role: "member"}
doc = {owner_id: 2, collaborators: [1, 5]}
println(can_edit(alice, doc))  # true (collaborator)

De Morgan’s Laws

Useful equivalences for simplifying logical expressions:

NOT (A AND B) = (NOT A) OR (NOT B)

import std:println

a = true
b = false

# These are equivalent:
result1 = !(a && b)
result2 = !a || !b

println(result1 == result2)  # true

NOT (A OR B) = (NOT A) AND (NOT B)

import std:println

a = true
b = false

# These are equivalent:
result1 = !(a || b)
result2 = !a && !b

println(result1 == result2)  # true

Truth Tables

AND (&&)

OR (||)

NOT (!)

Common Pitfalls

Pitfall 1: Confusing && with ,

import std:println

age = 20
has_license = true

# Wrong - this is a tuple of two booleans, not a logical AND
conditions = (age >= 18, has_license)
println(conditions)  # (true, true)

# Correct - logical AND
can_drive = age >= 18 && has_license
println(can_drive)  # true

Pitfall 2: Unnecessary Comparisons

is_valid = true

# Redundant comparison
match is_valid == true {
    true => {
        # ...
    },
    false => {},
}

# Use directly
match is_valid {
    true => {
        # ...
    },
    false => {},
}

Pitfall 3: Incorrect Negation

is_valid = true

# Wrong (redundant comparison)
match is_valid == false {
    true => {
        # ...
    },
    false => {},
}

# Correct (use negation)
match !is_valid {
    true => {
        # ...
    },
    false => {},
}

Pitfall 4: Complex Conditions Without Parentheses

import std:println

a = true
b = false
c = true
d = true
e = false

# Hard to read
match (a && b) || (c && d) || e {
    true => println("matched"),
    false => {},
}

# Clear with parentheses (same as above, but explicit)
match ((a && b) || (c && d) || e) {
    true => println("matched"),
    false => {},
}

Pitfall 5: Side Effects in Conditions

import std:println

# Don't rely on side effects: with short-circuiting, whether the right-hand side
# runs at all depends on the left-hand side.

# Separate side effects from conditions
counter = 0
limit = 5

counter++
match counter <= limit {
    true => println("within limit"),
    false => {},
}

Best Practices

DO:

• Use parentheses for complex conditions
• Leverage short-circuit evaluation for safety
• Keep conditions simple and readable
• Use meaningful boolean variable names
• Extract complex logic into named variables

DON’T:

• Compare booleans to true/false
• Create deeply nested logical expressions
• Put side effects in conditional expressions
• Forget operator precedence
• Mix too many conditions without structure

Examples

Permission System

import std:println

has_permission = |user, resource, action| {
    # Admin can do anything
    user:role == "admin" && return true
    
    # Owner can do anything with their resource
    resource:owner_id == user:id && return true
    
    # Check specific permissions
    permission_key = "${resource:type}:${action}"
    user:permissions::contains(permission_key)
}

editor = {role: "editor", id: 7, permissions: ["post:read", "post:write"]}
post = {type: "post", owner_id: 99}

println(has_permission(editor, post, "write"))   # true
println(has_permission(editor, post, "delete"))  # false

Input Validation

import std:println

validate_password = |password| {
    long_enough = password::length() >= 8
    has_upper = password ~ /[A-Z]/
    has_lower = password ~ /[a-z]/
    has_digit = password ~ /[0-9]/
    has_special = password ~ /[!@#$%^&*]/
    
    # All conditions must be true
    long_enough && has_upper && has_lower && has_digit && has_special
}

println(validate_password("Passw0rd!"))  # true
println(validate_password("password"))   # false

Feature Flags

import std:println

global_features = {dark_mode: true, beta_search: false}

is_feature_enabled = |feature_name, user| {
    # Check global flag, defaulting to off
    global_enabled = global_features::get(feature_name, false)

    # Check user-specific override
    user_enabled = user:feature_flags::get(feature_name, nil)

    # User override takes precedence
    match user_enabled {
        nil => global_enabled,
        _ => user_enabled,
    }
}

user = {feature_flags: {beta_search: true}}

println(is_feature_enabled("dark_mode", user))    # true (global)
println(is_feature_enabled("beta_search", user))  # true (user override)
println(is_feature_enabled("unknown", user))      # false (default)

Eligibility Check

import std:println

is_eligible_for_loan = |applicant| {
    # Must meet all criteria
    age_ok = applicant:age >= 21 && applicant:age <= 65
    income_ok = applicant:annual_income >= 30000
    credit_ok = applicant:credit_score >= 650
    employed = applicant:employment_status == "employed"
    
    # No disqualifying factors
    no_bankruptcy = !applicant:has_bankruptcy
    no_defaults = !applicant:has_loan_defaults
    
    # All positive criteria AND no negative factors
    age_ok && income_ok && credit_ok && employed && no_bankruptcy && no_defaults
}

applicant = {
    age: 34,
    annual_income: 52000,
    credit_score: 710,
    employment_status: "employed",
    has_bankruptcy: false,
    has_loan_defaults: false,
}

println(is_eligible_for_loan(applicant))  # true

Next Steps

• Learn about Relational Operators to create conditions
• Explore Conditional Logic
• Study Boolean Data Type
• Check out Pattern Matching

See Also

• Booleans
• Relational Operators
• Conditional Logic
• Match Expressions

Matching Operators

Matching operators test if strings match regular expression patterns.

Overview

Suji provides two operators for testing strings against regular expressions, making text validation concise and readable.

The operators are ~ and !~ — there is no =~. Both yield only a boolean. Suji’s regex support is deliberately match-only:

• no capture groups (::captures(), ::match(), ::find() do not exist)
• no regex replace — ::replace(old, new) takes strings only
• no regex split — ::split(sep) takes a string separator
• regex literals are not interpolated: /${var}/ is passed to the engine literally and fails to compile

Regex values are first class: you can store one in a variable and use it as a match arm pattern.

Match Operator (~)

Tests if a string matches a regex pattern:

import std:println

text = "user@example.com"
pattern = /^[^@]+@[^@]+\.[^@]+$/

# Returns true if matches
is_email = text ~ pattern
println(is_email)  # true

Basic Matching

import std:println

# Check if string contains pattern
println("hello world" ~ /world/)      # true
println("hello world" ~ /goodbye/)    # false

# Case-sensitive by default
println("Hello" ~ /hello/)            # false
println("Hello" ~ /(?i)hello/)        # true (case-insensitive)

Negative Match Operator (!~)

Tests if a string does NOT match a pattern:

import std:println

text = "hello123"

println(text !~ /world/)      # true (doesn't contain "world")
println(text !~ /hello/)      # false (contains "hello")

# Useful for validation
username = "alice_123"
is_valid_username = username !~ /[^a-zA-Z0-9_]/
println(is_valid_username)    # true - contains NO invalid characters

Common Patterns

Email Validation

import std:println

validate_email = |email| {
    email ~ /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/
}

println(validate_email("user@example.com"))    # true
println(validate_email("invalid.email"))        # false

URL Validation

import std:println

validate_url = |url| {
    url ~ /^https?:\/\/[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}(\/.*)?$/
}

println(validate_url("https://example.com"))       # true
println(validate_url("http://site.co.uk/path"))    # true
println(validate_url("not-a-url"))                 # false

Phone Number

import std:println

validate_phone = |phone| {
    phone ~ /^\d{3}-\d{3}-\d{4}$/
}

println(validate_phone("555-123-4567"))  # true
println(validate_phone("555-1234"))      # false
println(validate_phone("5551234567"))    # false

Contains Digits

import std:println

has_digits = |text| {
    text ~ /\d/
}

println(has_digits("hello123"))  # true
println(has_digits("hello"))     # false

Starts/Ends With

import std:println

# Starts with "http"
println("http://example.com" ~ /^http/)    # true
println("https://example.com" ~ /^http/)   # true
println("ftp://example.com" ~ /^http/)     # false

# Ends with ".com"
println("example.com" ~ /\.com$/)          # true
println("example.org" ~ /\.com$/)          # false

In Conditionals

Matching operators work well with match expressions:

import std:println

username = "alice_123"

match username ~ /^[a-zA-Z0-9_]+$/ {
    true => println("Valid username"),
    false => println("Invalid username: contains special characters"),
}

In Filters

Use matching to filter lists:

import std:println

emails = [
    "valid@example.com",
    "invalid.email",
    "another@test.org",
    "bad@"
]

pattern = /^[^@]+@[^@]+\.[^@]+$/
valid_emails = emails::filter(|e| e ~ pattern)

println(valid_emails)
# [valid@example.com, another@test.org]

Pattern Matching with Match

Combine with match for branching on patterns:

import std:println

text = "Call me at 555-1234"

words = text::split(" ")
phones = words::filter(|w| w ~ /^\d{3}-\d{4}$/)

match {
    phones::length() > 0 => println("Phone: " + phones[0]),
    _ => println("No phone found"),
}

A regex literal can also be used directly as a match arm pattern, which is often tidier than a chain of ~ tests:

import std:println

classify = |token| {
    match token {
        /^\d+$/ => "number",
        /^[a-z]+$/ => "word",
        _ => "mixed",
    }
}

println(classify("42"))       # number
println(classify("hello"))    # word
println(classify("h3llo"))    # mixed

Because regex values are ordinary values, you can name them and reuse them:

import std:println

digits_only = /^\d+$/

println("123" ~ digits_only)  # true
println("12a" ~ digits_only)  # false

What you cannot do is build a pattern dynamically. Regex literals are not interpolated, so /${some_var}/ is handed to the engine verbatim and fails with a Regex error, and there is no function that turns a string into a regex. Patterns must be written out literally in the source.

Negation Patterns

Use !~ to check absence of patterns:

import std:println

# Check password doesn't contain spaces
password = "MyP@ssw0rd"
no_spaces = password !~ /\s/
println(no_spaces)  # true

# Check username has no special chars
username = "alice_123"
only_alphanumeric = username !~ /[^a-zA-Z0-9_]/
println(only_alphanumeric)  # true

Combining with Logical Operators

import std:println

validate_password = |password| {
    # All these conditions must be true
    long_enough = password::length() >= 8
    has_upper = password ~ /[A-Z]/
    has_lower = password ~ /[a-z]/
    has_digit = password ~ /[0-9]/
    has_special = password ~ /[!@#$%^&*]/
    
    long_enough && has_upper && has_lower && has_digit && has_special
}

println(validate_password("Passw0rd!"))  # true
println(validate_password("password"))   # false

Inline Regex Modes

The regex engine supports inline mode modifiers like (?i) (case-insensitive) and (?m) (multiline).

import std:println

text = "Hello World"

# Case-insensitive
println(text ~ /(?i)hello/)       # true

# Multiline
multiline = "line1\nline2"
println(multiline ~ /(?m)^line2/) # true

Common Pitfalls

Pitfall 1: Not Escaping Special Characters

import std:println

# Unescaped dot matches any character
println("axb" ~ /a.b/)   # true  - the dot matched "x"
println("a.b" ~ /a.b/)   # true  - and it matches a literal dot too

# Escape the dot to match only a literal dot
println("axb" ~ /a\.b/)  # false
println("a.b" ~ /a\.b/)  # true

Pitfall 2: Forgetting Anchors

import std:println

# Partial match (finds "123" anywhere)
println("hello123world" ~ /\d+/)  # true

# Anchored (entire string must be digits)
println("hello123world" ~ /^\d+$/)  # false
println("123" ~ /^\d+$/)            # true

Pitfall 3: Case Sensitivity

import std:println

# Case-sensitive by default
println("Hello" ~ /hello/)   # false

# Use inline case-insensitive mode
println("Hello" ~ /(?i)hello/)  # true

Pitfall 4: Expecting Greediness to Matter

Greedy and non-greedy quantifiers are both accepted, but since ~ returns only “did it match”, the difference is invisible — you never get to see what matched:

import std:println

text = "<tag>content</tag>"

println(text ~ /<.*>/)   # true
println(text ~ /<.*?>/)  # true - same answer

If you need the matched text, regex will not help you: use string methods such as ::index_of(), ::split() and slicing (s[1;4]) to carve the value out yourself.

Best Practices

DO:

• Use anchors (^, $) for exact matches
• Escape special regex characters
• Reach for ::contains(), ::starts_with() and ::ends_with() when a plain substring test will do
• Test patterns thoroughly
• Add comments for complex regex

DON’T:

• Expect captured groups, regex replace or regex split — none exist
• Write =~; the operator is ~
• Try to interpolate a pattern (/${var}/ is a regex error)
• Forget case sensitivity
• Use regex to parse HTML/XML

Examples

Username Validation

import std:println

validate_username = |username| {
    # 3-20 characters, alphanumeric and underscore only
    valid_format = username ~ /^[a-zA-Z0-9_]{3,20}$/
    no_double_underscore = username !~ /__/
    not_starts_with_number = username !~ /^[0-9]/
    
    valid_format && no_double_underscore && not_starts_with_number
}

println(validate_username("alice_123"))    # true
println(validate_username("ab"))           # false (too short)
println(validate_username("alice__bob"))   # false (double underscore)
println(validate_username("123alice"))     # false (starts with number)

Extract Domain from URL

import std:println

get_domain = |url| {
    url !~ /^https?:\/\// && return nil

    parts = url::split("://")
    parts::length() < 2 && return nil

    host_and_path = parts[1]
    host_parts = host_and_path::split("/")
    host_parts[0]
}

println(get_domain("https://example.com/path"))  # example.com
println(get_domain("http://site.org"))           # site.org
println(get_domain("ftp://site.org"))            # nil

Sanitize Input

There is no regex replace, so filtering has to be done character by character. Note that strings are not iterable — loop through text is a runtime error, so convert with ::to_list() first:

import std:println

sanitize = |text| {
    # Keep only alphanumerics, spaces, hyphens and underscores
    result = ""
    loop through text::to_list() with char {
        match { char ~ /[a-zA-Z0-9 _-]/ => { result = result + char } }
    }
    result
}

println(sanitize("Hello, World!"))      # Hello World
println(sanitize("Test@#$%123"))        # Test123

Password Strength Checker

import std:println

check_password_strength = |password| {
    score = 0
    
    match { password::length() >= 8 => { score = score + 1 } }
    match { password::length() >= 12 => { score = score + 1 } }
    match { password ~ /[A-Z]/ => { score = score + 1 } }
    match { password ~ /[a-z]/ => { score = score + 1 } }
    match { password ~ /[0-9]/ => { score = score + 1 } }
    match { password ~ /[!@#$%^&*]/ => { score = score + 1 } }
    
    match {
        score >= 5 => "Strong",
        score >= 3 => "Medium",
        _ => "Weak",
    }
}

println(check_password_strength("abc123"))          # Weak
println(check_password_strength("Abc123"))          # Medium
println(check_password_strength("Abc123!@"))        # Strong

File Extension Check

import std:println

is_image = |filename| {
    filename ~ /(?i)\.(jpg|jpeg|png|gif|webp)$/
}

is_document = |filename| {
    filename ~ /(?i)\.(pdf|doc|docx|txt)$/
}

println(is_image("photo.jpg"))        # true
println(is_image("document.pdf"))     # false
println(is_document("report.pdf"))    # true

Next Steps

• Learn about Regular Expressions in detail
• Explore String Methods
• Study Pattern Matching
• Check out Text Processing

See Also

• Regular Expressions
• Strings
• Pattern Matching
• Match Expression

Pipe (|)

The pipe operator | builds pipelines where the stdout of one stage becomes the stdin of the next.

This is different from pipe-apply (|> / <|), which passes values as function arguments. Note that |< is not an operator in Suji; the backward pipe-apply is spelled <|.

What can appear in a pipeline?

In this repository, each stage must be either:

• A function invocation (e.g. stage() or stage(arg)), or
• A backtick command template (e.g. `cat file.txt`)

Stages communicate via stdin/stdout (not via return values). A bare function name is not a valid stage — you must call it.

Example: shell → Suji → shell

import std:io

# Read all input from stdin, uppercase it, write to stdout
upper = || {
    text = io:stdin::read_all()
    io:stdout::write(text::upper())
}

`printf "hello\n"` | upper() | `wc -c`

The value of a pipeline

A pipeline expression evaluates to the captured stdout of its last stage, with the trailing newline trimmed (the same rule as a plain backtick template). Nothing is printed automatically when the last stage is a backtick command, so assign it if you want to see it:

import std:io
import std:println

upper = || {
    text = io:stdin::read_all()
    io:stdout::write(text::upper())
}

bytes = `printf "hello\n"` | upper() | `wc -c`
println("bytes: ${bytes::trim()}")  # bytes: 6

Example: processing lines

Reading a stream is eager: read_lines() returns the whole input as a list of lines. This example creates its own input file so it runs anywhere:

import std:io
import std:println

path = `mktemp`
`printf 'alpha\n\nbeta\n\ngamma\n' > ${path}`

only_non_empty = || {
    lines = io:stdin::read_lines()
    loop through lines with line {
        match { line::trim()::length() > 0 => { io:stdout::write(line + "\n") } }
    }
}

kept = `cat ${path}` | only_non_empty() | `head -n 2`
println(kept)  # alpha, then beta on the next line

`rm ${path}`

Notes

• | is implemented by redirecting std:io streams for each stage and capturing stdout between stages.
• A stage whose command exits non-zero raises a runtime error that terminates the script — there is no way to trap it. Defensive tricks such as `cmd || true` keep the shell happy.
• | sits between |> and >> in the precedence table: lower than composition, higher than the pipe-apply operators.
• If you want to pass values through a chain (not stdin/stdout), use list/string methods (::map, ::filter, …) or pipe-apply (|> / <|).

See Also

• Pipe Apply (|> and <|)
• Function Composition (>> and <<)
• Operators overview

Pipe Apply (|> and <|)

Pipe-apply operators call functions with one argument, but let you choose a convenient reading order.

Overview

• value |> f is equivalent to f(value)
• f <| value is equivalent to f(value)

Both operators require the function side to evaluate to a function value; anything else raises Pipe apply (|>) requires a function on the right-hand side (or the matching left-hand-side error for <|).

There is no |< operator — the backward form is <|.

Forward apply (|>)

Read left-to-right:

import std:println

trim = |s| s::trim()
upper = |s| s::upper()

result = "  hello  " |> trim |> upper
println(result)  # HELLO

Backward apply (<|)

Read right-to-left. <| is right-associative, so the parentheses are optional:

import std:println

trim = |s| s::trim()
upper = |s| s::upper()

println <| upper <| trim <| "  hello  "   # HELLO

Precedence

<| has the lowest precedence of the two, just above assignment; |> binds slightly tighter, and both bind looser than arithmetic. That means the arithmetic on the left is evaluated before the value is piped:

import std:println

inc = |x| x + 1

println(1 + 2 |> inc)  # 4 - the same as (1 + 2) |> inc

Notes

• |> / <| always apply one argument. They do not “insert into a parameter list”, and there is no partial application syntax — write a lambda returning a lambda if you need that.
• If you want to transform collections, prefer list methods:

import std:println

numbers = [1, 2, 3, 4, 5]
result = numbers::filter(|x| x % 2 == 0)::map(|x| x * x)::sum()

println(result)  # 20

• If you want to build a reusable function instead of calling one right away, use the composition operators >> / << (see Function Composition).
• If you want stdin/stdout piping between stages, use the | operator (see Pipe).

See Also

• Pipe (|)
• Function Composition (>> and <<)
• Operators overview

Function Composition

Function composition operators combine functions to create new functions.

Overview

Composition creates a new function by chaining two functions together, where the output of one becomes the input of the next. Suji provides two composition operators: >> (compose right) and << (compose left).

Both sit at the same precedence level, between the pipeline operator | and ||. They are distinct from the pipe-apply operators |> / <|, which call a function immediately rather than building a new one.

Operators

Compose Right (>>)

Chains functions left-to-right: f >> g means “first apply f, then apply g to the result”.

import std:println

# Define simple functions
add2 = |x| x + 2
mul3 = |x| x * 3

# Compose: add 2, then multiply by 3
f = add2 >> mul3

println(f(5))  # (5 + 2) * 3 = 21

Syntax: function1 >> function2

Evaluation: (f >> g)(x) is equivalent to g(f(x))

Compose Left (<<)

Chains functions right-to-left: f << g means “first apply g, then apply f to the result”.

import std:println

# Define simple functions
add2 = |x| x + 2
mul3 = |x| x * 3

# Compose: multiply by 3, then add 2
f = add2 << mul3

println(f(5))  # (5 * 3) + 2 = 17

Syntax: function1 << function2

Evaluation: (f << g)(x) is equivalent to f(g(x))

Comparison

import std:println

add2 = |x| x + 2
mul3 = |x| x * 3

# Left-to-right (>>)
f1 = add2 >> mul3
println(f1(5))  # (5 + 2) * 3 = 21

# Right-to-left (<<)
f2 = add2 << mul3
println(f2(5))  # (5 * 3) + 2 = 17

# Equivalence
f3 = mul3 << add2
println(f3(5))  # Same as f1: (5 + 2) * 3 = 21

Relationship: f >> g is equivalent to g << f

Common Use Cases

Data Transformation Pipelines

import std:println

# Processing functions
trim = |s| s::trim()
upper = |s| s::upper()
exclaim = |s| "${s}!"

# Compose processing pipeline
process = trim >> upper >> exclaim

println(process("  hello  "))  # HELLO!

Number Processing

import std:println

# Math operations
square = |x| x * x
negate = |x| -x
add10 = |x| x + 10

# Complex transformation
transform = square >> negate >> add10

println(transform(3))  # -(3^2) + 10 = -9 + 10 = 1

Validation and Transformation

import std:println

# Validators
is_positive = |x| x > 0
is_even = |x| x % 2 == 0

# Transformers
double = |x| x * 2
add5 = |x| x + 5

# Combined pipeline
safe_transform = |x| {
    match (is_positive(x) && is_even(x)) {
        true => {
            pipeline = double >> add5
            pipeline(x)
        },
        false => nil,
    }
}

println(safe_transform(4))   # (4 * 2) + 5 = 13
println(safe_transform(3))   # nil (not even)
println(safe_transform(-2))  # nil (not positive)

Function Factories

import std:println

# Create composable operations
make_adder = |n| { |x| x + n }
make_multiplier = |n| { |x| x * n }

# Build complex functions
add10 = make_adder(10)
mul2 = make_multiplier(2)

# Compose dynamically
transform = add10 >> mul2

println(transform(5))  # (5 + 10) * 2 = 30

Chaining Compositions

Composition is associative, allowing natural chaining:

import std:println

f = |x| x + 1
g = |x| x * 2
h = |x| x * x

# All equivalent:
pipeline1 = (f >> g) >> h
pipeline2 = f >> (g >> h)
pipeline3 = f >> g >> h

println(pipeline1(3))  # 64
println(pipeline2(3))  # 64
println(pipeline3(3))  # 64

# Calculation: ((3 + 1) * 2)^2 = (8)^2 = 64

Composition vs Pipe Apply

Composition creates a new function, while pipe apply executes immediately:

import std:println

add2 = |x| x + 2
mul3 = |x| x * 3

# Composition: creates a function
composed = add2 >> mul3
result1 = composed(5)     # Call the composed function
println(result1)  # 21

# Pipe apply: executes immediately
result2 = 5 |> add2 |> mul3
println(result2)  # 21

# Key difference: composition is reusable
println(composed(10))  # 36
println(composed(15))  # 51

With Higher-Order Functions

Composition works elegantly with map, filter, etc.:

import std:println

add1 = |x| x + 1
double = |x| x * 2

# Compose transformation
transform = add1 >> double

# Apply to list
numbers = [1, 2, 3, 4, 5]
result = numbers::map(transform)

println(result)  # [4, 6, 8, 10, 12]

Pattern: Method Chain Composition

import std:println

# String processing pipeline
process_text = 
    (|s| s::trim()) >>
    (|s| s::lower()) >>
    (|s| s::split(" "))

text = "  HELLO WORLD  "
words = process_text(text)
println(words)  # [hello, world]

Advanced Patterns

Conditional Composition

import std:println

safe_divide = |divisor| {
    |x| {
        match divisor != 0 {
            true => x / divisor,
            false => nil,
        }
    }
}

# Compose with safe operations
add10 = |x| x + 10
divide_by_2 = safe_divide(2)

pipeline = add10 >> divide_by_2

println(pipeline(5))  # 7.50 - (5 + 10) / 2

N-ary Function Composition

import std:println

# Compose functions that take multiple arguments
add = |a, b| a + b
multiply_by_3 = |x| x * 3

# Suji has no partial-application syntax, so wrap the call in a one-argument lambda
add5 = |x| add(x, 5)
transform = add5 >> multiply_by_3

println(transform(10))  # (10 + 5) * 3 = 45

Best Practices

DO:

• Use >> for left-to-right reading (more intuitive)
• Compose pure functions (no side effects)
• Create reusable function pipelines
• Name composed functions descriptively
• Keep composed functions simple and focused

DON’T:

• Compose functions with side effects (unpredictable)
• Create overly complex compositions (hard to debug)
• Forget that composition creates new functions
• Mix composition with imperative code
• Ignore function signatures (ensure types match)

Composition Equivalences

These are identities, not runnable Suji (≡ is not an operator):

f >> g  ≡  |x| g(f(x))
f << g  ≡  |x| f(g(x))

Associativity:
(f >> g) >> h  ≡  f >> (g >> h)
(f << g) << h  ≡  f << (g << h)

Relationship:
f >> g  ≡  g << f

And here they are as executable checks:

import std:println

f = |x| x + 1
g = |x| x * 2

println((f >> g)(5) == g(f(5)))  # true
println((f << g)(5) == f(g(5)))  # true
println((f >> g)(5) == (g << f)(5))  # true

Examples

URL Builder

import std:println

# Component functions
add_protocol = |url| "https://${url}"
add_path = |url| "${url}/api"
add_version = |url| "${url}/v1"

# Compose URL builder
build_api_url = add_protocol >> add_path >> add_version

url = build_api_url("example.com")
println(url)  # https://example.com/api/v1

Data Sanitization

import std:println

# Sanitization steps. There is no regex replace, so stripping unwanted characters
# means filtering them out one at a time (strings need ::to_list() to be iterable).
remove_whitespace = |s| s::trim()
remove_special_chars = |s| {
    kept = ""
    loop through s::to_list() with ch {
        match { ch ~ /[A-Za-z0-9]/ => { kept = kept + ch } }
    }
    kept
}
to_lowercase = |s| s::lower()

# Compose sanitizer
sanitize = remove_whitespace >> remove_special_chars >> to_lowercase

raw = "  Hello@World!  "
clean = sanitize(raw)
println(clean)  # helloworld

Numeric Transformation

import std:println

# Math operations. Note `^` requires an integer exponent, so `x ^ 0.5` is an error —
# square roots use the number method `::sqrt()`.
abs_val = |x| x::abs()
square = |x| x * x
root = |x| x::sqrt()

# Compose distance calculation
distance = abs_val >> square >> root

println(distance(-5))  # 5 - abs(-5) = 5, 5^2 = 25, sqrt(25) = 5

See Also

• Pipe Apply Operators - Execute pipelines immediately
• Higher-Order Functions - Functions that work with functions
• Function Basics - Function fundamentals
• Pipe Operator - Stream composition

Control Flow

Control flow determines the order in which code executes based on conditions and iteration needs.

Overview

Suji provides two control flow constructs: loop (with break and continue) and match expressions. There is no if, else, while or for, and no try/catch. Guard clauses using logical operators enable early returns.

One rule catches almost everybody: in a match, an arm whose body is a bare expression must be followed by a comma, including the final arm. Only arms with { … } block bodies may omit it.

Control Flow Constructs

Conditional Logic

Suji does not have if or else statements. Use match expressions for all conditional logic:

Match for Conditionals

import std:println

age = 25

# Match on boolean condition
match age >= 18 {
    true => println("Adult"),
    false => println("Minor"),
}

Multiple Conditions

import std:println

score = 85

# Use conditional match for ranges
match {
    score >= 90 => println("A"),
    score >= 80 => println("B"),
    score >= 70 => println("C"),
    score >= 60 => println("D"),
    _ => println("F"),
}

Learn more about Conditional Logic →

Loops

Repeat code multiple times:

Infinite Loop

import std:println

count = 0
loop {
    count = count + 1
    count > 5 && break
    println(count)
}

Loop Through Lists

import std:println

fruits = ["apple", "banana", "cherry"]

loop through fruits with fruit {
    println(fruit)
}

# Lists have no index binding — keep a counter or iterate the indices
loop through 0..fruits::length() with index {
    println("${index}: ${fruits[index]}")
}

Loop Through Maps

Two bindings are for maps only:

import std:println

config = {port: 8080, host: "localhost"}

loop through config with key, value {
    println("${key} = ${value}")
}

Learn more about Loops →

Pattern Matching

Match values against patterns:

import std:println

grade = |score| {
    match {
        score >= 90 => "A",
        score >= 80 => "B",
        score >= 70 => "C",
        score >= 60 => "D",
        _ => "F",
    }
}

println(grade(85))  # B

With Tuple Patterns

Tuple patterns compare element by element. Elements are literals or _ — they do not bind, so use a destructuring assignment when you need the parts:

import std:println

point = (10, 20)

match point {
    (0, 0) => println("Origin"),
    (0, _) => println("On the Y-axis"),
    (_, 0) => println("On the X-axis"),
    _ => println("Elsewhere"),
}

x, y = point
println("Point at ${x}, ${y}")

With Regex

import std:println

text = "Call 555-1234"

match text {
    /\d{3}-\d{4}/ => {
        words = text::split(" ")
        phones = words::filter(|w| w ~ /^\d{3}-\d{4}$/)
        match { phones::length() > 0 => { println("Phone: " + phones[0]) } }
    },
    _ => println("No phone found"),
}

Learn more about Pattern Matching →

Guard Clauses

Early returns using logical operators:

import std:println

process_user = |user| {
    # Guard: return early if nil
    user == nil && return "Error: No user"

    # Guard: return early if inactive (::get avoids a "Key not found" error)
    user::get("is_active", false) == false && return "Error: Inactive user"

    # Main logic
    "User ${user::get("name", "?")} processed"
}

println(process_user(nil))                              # Error: No user
println(process_user({name: "Ada"}))                    # Error: Inactive user
println(process_user({name: "Ada", is_active: true}))   # User Ada processed

Guards are the only way to deal with failure: a runtime error terminates the program and cannot be caught, so validate before acting.

Learn more about Guard Clauses →

Control Flow Comparison

When to Use Each Construct

Common Patterns

Early Return Pattern

import std:println

transform = |xs| xs::map(|n| n * 2)

process_data = |data| {
    # Validate and return early on failure
    data == nil && return nil
    data::length() == 0 && return nil

    # Main processing logic
    transform(data)
}

println(process_data(nil))        # nil
println(process_data([]))         # nil
println(process_data([1, 2, 3]))  # [2, 4, 6]

Switch-Style Match

import std:println

handle_command = |cmd| {
    match cmd {
        "start" => println("Starting..."),
        "stop" => println("Stopping..."),
        "restart" => println("Restarting..."),
        "status" => println("Running"),
        _ => println("Unknown command"),
    }
}

handle_command("stop")    # Stopping...
handle_command("deploy")  # Unknown command

Iterator Pattern

import std:println

items = ["skip me", "a", "b", "c"]
index = 0

loop through items with item {
    index = index + 1

    index == 1 && continue  # Skip first

    index > 3 && break  # Stop after the third

    println(item)
}

State Machine

import std:println

state = "idle"

process_event = |event| {
    state = match (state, event) {
        ("idle", "start") => "running",
        ("running", "pause") => "paused",
        ("paused", "resume") => "running",
        ("running", "stop") => "idle",
        _ => state,  # No change
    }
}

process_event("start")
println(state)  # running

process_event("bogus")
println(state)  # running

Nested Control Flow

Nested Conditions

import std:println

check_access = |user, resource| {
    # Use guards for early returns
    user == nil && return false
    user::get("is_active", false) == false && return false
    user::get("permissions", [])::contains(resource)
}

println(check_access(nil, "reports"))                                       # false
println(check_access({is_active: true, permissions: ["logs"]}, "reports"))  # false
println(check_access({is_active: true, permissions: ["reports"]}, "reports"))  # true

Nested Loops

import std:println

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

loop through matrix with row {
    loop through row with cell {
        println(cell)
    }
}

Match with Nested Conditions

import std:println

categorize = |value| {
    match {
        value::is_number() => {
            match {
                value < 0 => "negative",
                value == 0 => "zero",
                _ => "positive",
            }
        },
        value::is_string() => "text",
        _ => "unknown",
    }
}

println(categorize(-4))     # negative
println(categorize("hi"))   # text
println(categorize(nil))    # unknown

Best Practices

DO:

• Use guard clauses for early validation
• Prefer match for all conditional logic
• Use loop through for collections
• Keep nesting shallow (max 2-3 levels)
• Use meaningful condition names

DON’T:

• Try to use if statements (they don’t exist in Suji)
• Forget the trailing comma after the last expression arm of a match
• Assume a bare identifier pattern binds — it is a string literal
• Create deeply nested match expressions
• Use loops where functional methods work better
• Ignore break/continue for complex loop logic
• Write long match expressions (extract to functions)
• Forget the default case (_) in match

Common Pitfalls

Pitfall 1: Missing Comma After the Last Arm

This is the most common parse error in Suji code. Expression arms need commas, last arm included:

match value { 1 => "one", 2 => "two" }    # [201] Error: Unexpected token

import std:println

value = 2

println(match value { 1 => "one", 2 => "two", })  # two

Pitfall 2: Missing Default Case

A match that matches nothing evaluates to nil rather than raising, so a missing _ arm shows up as an unexpected nil later:

import std:println

value = 3

# No default case
println(match value {
    1 => "one",
    2 => "two",
})  # nil

# Always have a default when nil is not the answer you want
println(match value {
    1 => "one",
    2 => "two",
    _ => "other",
})  # other

Pitfall 3: Infinite Loops

import std:println

count = 0
done = || count >= 3

# No exit condition
# loop {
#     println("forever")   # Never breaks!
# }

# Have clear exit
loop {
    done() && break
    count = count + 1
    println(count)
}

Pitfall 4: Binding Patterns That Do Not Exist

Patterns cannot introduce variables. n below is the string "n", so nothing matches and the result is nil:

import std:println

println(match 5 { n => n * 2, })  # nil

n = 5
println(match { n > 0 => n * 2, _ => 0, })  # 10

Performance Considerations

Match Arms Are Tested in Order

There is no jump table: the interpreter walks the arms top to bottom, so put the cheapest and most likely conditions first.

import std:println

handle = |key| {
    match key {
        "a" => "handled a",
        "b" => "handled b",
        "c" => "handled c",
        _ => "handled default",
    }
}

println(handle("b"))  # handled b
println(handle("z"))  # handled default

Loop vs Functional Methods

import std:println

numbers = [1, 2, 3, 4, 5, 6]

# Loop with state mutation
total = 0
loop through numbers with n {
    match { n % 2 == 0 => { total = total + n } }
}
println(total)  # 12

# Functional pipeline (shorter, though it allocates an intermediate list)
total = numbers::filter(|n| n % 2 == 0)::sum()
println(total)  # 12

Next Steps

Explore each control flow construct in detail:

1. Conditional Logic - Using match for conditionals
2. Loops - Iteration and repetition
3. Match - Pattern matching
4. Guards - Early returns and validation

See Also

• Operators
• Functions
• Pattern Matching
• Error Handling

Conditional Logic

Suji has no if, else or elif, no ternary operator, and no and/or/not keywords. match is the only conditional construct, in two forms; logical operators (&&, ||, !) combine boolean conditions and drive guard clauses for early returns.

Using Match for Conditionals

match is Suji’s only conditional construct, and it comes in two forms:

• the subject form, match value { pattern => body, … }, which compares patterns against a value
• the condition-only form, match { condition => body, … }, where every arm is a boolean expression evaluated in order

Both are expressions: they evaluate to the body of the first matching arm, or to nil if no arm matches. Every arm whose body is a bare expression needs a trailing comma, including the last one — see Match Expressions for the full rule.

Basic Conditional

import std:println

age = 25

# Match on boolean condition
match age >= 18 {
    true => println("Adult"),
    false => println("Minor"),
}

Multiple Conditions

import std:println

score = 85

# Use conditional match for ranges
status = match {
    score >= 90 => "A",
    score >= 80 => "B",
    score >= 70 => "C",
    score >= 60 => "D",
    _ => "F",
}

println(status)  # B

Match as Expression

Match expressions return values:

import std:println

age = 25
status = match age >= 18 {
    true => "adult",
    false => "minor",
}

println(status)  # adult

Nested Conditions

import std:println

user = {is_active: true, is_admin: false}

# Use nested match or combine conditions
match user:is_active {
    true => match user:is_admin {
        true => println("Active admin"),
        false => println("Active user"),
    },
    false => println("Inactive user"),
}

# Or combine conditions
match {
    user:is_active && user:is_admin => println("Active admin"),
    user:is_active => println("Active user"),
    _ => println("Inactive user"),
}

Guard Clauses

Use logical operators (&& and ||) for early returns. Read a possibly-missing map key with ::get(key, default) — a plain user:name on a map that lacks the key raises Key not found and terminates the program:

import std:println

validate_user = |user| {
    # Guard: return early if nil
    user == nil && return "User is required"

    # Guard: return early if name is missing or empty
    name = user::get("name", "")
    name::length() == 0 && return "Name is required"

    # Guard: return early if too young
    user::get("age", 0) < 18 && return "Must be 18 or older"

    # All guards passed
    "Valid"
}

println(validate_user({name: "Alice", age: 30}))  # Valid
println(validate_user({age: 30}))                 # Name is required
println(validate_user(nil))                       # User is required

Guard Pattern Explained

Guard clauses use short-circuit evaluation:

• condition && return value - returns if condition is true
• condition || return value - returns if condition is false

The condition must be a real boolean. There is no truthiness in Suji, so write x == nil or name::length() == 0 rather than relying on the value itself, and note that x || "default" is a type error rather than a defaulting idiom.

import std:println

process = |x| {
    # Return early if x is nil
    x == nil && return "nil"
    
    # Return early if x is negative
    x < 0 && return "negative"
    
    # Main logic
    "positive: ${x}"
}

println(process(5))   # positive: 5
println(process(-1))  # negative
println(process(nil)) # nil

Common Patterns

Range Checking

import std:println

temperature = 25

status = match {
    temperature < 0 => "Freezing",
    temperature < 20 => "Cold",
    temperature < 30 => "Comfortable",
    _ => "Hot",
}

println(status)  # Comfortable

Checking Before Acting

Runtime errors cannot be caught, so a conditional is how you avoid them. Test the dangerous condition first and pick a safe branch:

import std:println

divide = |a, b| {
    match {
        b == 0 => nil,
        _ => a / b,
    }
}

println(divide(10, 2))  # 5
println(divide(10, 0))  # nil

Type Checking

import std:println

process_value = |value| {
    match {
        value::is_number() => println("Number: ${value}"),
        value::is_string() => println("String: ${value}"),
        value::is_bool() => println("Boolean: ${value}"),
        _ => println("Unknown type"),
    }
}

process_value(42)      # Number: 42
process_value("hello") # String: hello
process_value(true)    # Boolean: true

Ternary-Style

For simple true/false conditionals:

import std:println

age = 25
status = match age >= 18 {
    true => "adult",
    false => "minor",
}

println(status)  # adult

Best Practices

DO:

• Use match for all conditional logic
• Use guard clauses (&& return) for early validation
• Use conditional match (match { condition => ... }) for multiple conditions
• Keep match expressions readable
• Use pattern alternation (|) for multiple matching values

DON’T:

• Try to use if, else, elif or a ternary operator (none of them exist in Suji)
• Write and, or or not — the operators are &&, || and !
• Rely on truthiness: x || "default" is a type error, not a default
• Nest match expressions too deeply (extract to functions)
• Forget the default case (_) in match, unless nil is the answer you want
• Omit the trailing comma after the last expression arm
• Use complex boolean expressions in guards (extract to variables)

Comparison with Other Languages

If you’re coming from languages with if statements:

See Also

• Match Expressions - Complete guide to pattern matching
• Guard Clauses - Using logical operators for early returns
• Logical Operators - Understanding && and ||
• Loops - Iteration and repetition

Loops

Loops repeat code multiple times until a condition is met. loop is the only looping keyword — there is no while and no for. The five forms are:

loop { … }                      # infinite; needs break
loop as outer { … }             # labeled infinite loop
loop through xs { … }           # iterate without a binding
loop through xs with x { … }    # bind each element (or each map key)
loop through m with k, v { … }  # bind key and value — maps only

A loop is a statement, never a value: break takes no operand (there is no break <value>) and a loop expression always evaluates to nil.

Infinite Loop

import std:println

count = 0
loop {
    count = count + 1
    println(count)
    
    match count >= 5 {
        true => break,
        false => {},
    }
}

Loop Through Lists

import std:println

fruits = ["apple", "banana", "cherry"]

# Basic iteration
loop through fruits with fruit {
    println(fruit)
}

# Iterate a fixed number of times without binding anything
count = 0
loop through fruits {
    count = count + 1
}
println(count)  # 3

There Is No Index Binding for Lists

Two bindings are for maps only. Writing loop through fruits with fruit, index fails at runtime with Type error: Cannot iterate over list. Keep your own counter, or iterate an index range:

import std:println

fruits = ["apple", "banana", "cherry"]

# Manual counter
index = 0
loop through fruits with fruit {
    println("${index}: ${fruit}")
    index = index + 1
}

# Or iterate the indices directly
loop through 0..fruits::length() with i {
    println("${i} -> ${fruits[i]}")
}

Loop Through Maps

Only maps support two bindings, one for the key and one for the value. Iterating a map with k alone binds just the key.

import std:println

config = {
    host: "localhost",
    port: 8080,
    debug: true
}

loop through config with key, value {
    println("${key} = ${value}")
}

Loop Through Ranges

A range is not a lazy iterator — a..b evaluates immediately to a plain list, so loop through 1..11 is exactly loop through [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]. Very large ranges therefore allocate very large lists.

import std:println

# Using range literal (exclusive)
loop through 1..11 with n {
    println(n)  # 1 to 10
}

# Inclusive range
loop through 1..=10 with n {
    println(n)  # 1 to 10
}

# Descending range
loop through 10..5 with n {
    println(n)  # 10, 9, 8, 7, 6
}

What You Cannot Iterate

Only lists (including ranges) and maps are iterable. A string or a stream must be converted first, otherwise you get Type error: Cannot iterate over string / over stream:

import std:println

word = "hi"

# loop through word with c { … }   # runtime error
loop through word::to_list() with c {
    println(c)
}

Streams are the same story: read them into a list with read_lines() first, then loop through that list.

Labeled Loops

Label an infinite loop with as name to break or continue an outer loop from inside a nested one. The label goes on the plain loop form; loop as name through … is a parse error.

import std:println

i = 0
loop as outer {
    i = i + 1
    i > 3 && break outer

    loop through [1, 2, 3] with j {
        j == 2 && continue outer
        println("${i},${j}")
    }
}

Break and Continue

Break

Exit the loop immediately:

import std:println

numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

loop through numbers with n {
    n > 5 && break  # Stop when n > 5 (short-circuit)
    println(n)
}
# Prints: 1, 2, 3, 4, 5

Continue

Skip to next iteration:

import std:println

numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

loop through numbers with n {
    n % 2 == 0 && continue  # Skip even numbers (short-circuit)
    println(n)
}
# Prints: 1, 3, 5, 7, 9

Return from Loop

Since break cannot carry a value, a loop that needs to produce a result lives inside a function and uses return:

import std:println

find_first = |list, predicate| {
    loop through list with item {
        predicate(item) && return item  # Return from function (short-circuit)
    }
    nil  # Not found
}

println(find_first([1, 3, 8, 5], |n| n % 2 == 0))  # 8
println(find_first([1, 3, 5], |n| n % 2 == 0))     # nil

Common Patterns

Accumulator

import std:println

numbers = [1, 2, 3, 4, 5]
sum = 0

loop through numbers with n {
    sum = sum + n
}

println(sum)  # 15

Search

import std:println

names = ["Alice", "Bob", "Charlie"]
target = "Bob"
found = false

loop through names with name {
    match { name == target => {
        found = true
        break
    } }
}

println(found)  # true

Transformation

import std:println

numbers = [1, 2, 3, 4, 5]
doubled = []

loop through numbers with n {
    doubled::push(n * 2)
}

println(doubled)  # [2, 4, 6, 8, 10]

Nested Loops

import std:println

# Multiplication table
loop through 1..11 with i {
    loop through 1..11 with j {
        println("${i} x ${j} = ${i * j}")
    }
}

Loops vs Functional Methods

Often functional methods are more concise:

import std:println

numbers = [1, 2, 3, 4, 5]

# Loop (verbose)
doubled = []
loop through numbers with n {
    doubled::push(n * 2)
}

# Map (concise)
doubled = numbers::map(|n| n * 2)

println(doubled)  # [2, 4, 6, 8, 10]

When to use each:

• Use loops for: complex logic, early exits, state management
• Use functional methods for: transformations, filtering, aggregation

Best Practices

DO:

• Use loop through for collections
• Provide clear exit conditions
• Use break for early exit
• Use continue to skip iterations
• Label the outer loop when a nested loop needs to break out of it
• Consider functional methods for simple transformations

DON’T:

• Create infinite loops without break
• Expect break to return a value, or a loop to evaluate to anything but nil
• Use two bindings on a list — that form is for maps only
• Iterate a string or stream directly; convert with to_list() / read_lines()
• Modify collection while iterating
• Nest loops more than 2-3 levels
• Use loops where functional methods are clearer

See Also

• Lists
• Maps
• Higher-Order Functions
• Streams

Match Expressions

Pattern matching allows you to match values against patterns and execute corresponding code.

Basic Match

import std:println

day = "Monday"

match day {
    "Monday" => println("Start of week"),
    "Friday" => println("End of week"),
    "Saturday" | "Sunday" => println("Weekend"),
    _ => println("Midweek"),
}

The Comma Rule

This is the single easiest thing to get wrong. An arm whose body is a bare expression must be followed by a comma — including the final arm. Only an arm whose body is a { … } block may omit the comma.

Correct — every expression arm ends with a comma:

import std:println

x = 1

println(match x { 1 => "one", _ => "other", })

Incorrect — the last arm has no comma, so the program fails to parse with [201] Error: Unexpected token pointing at the closing brace:

match x { 1 => "one", _ => "other" }

Block bodies are the exception, and they may be written with or without commas:

import std:println

x = 1

match x {
    1 => { println("one") }
    _ => { println("other") }
}

Match as Expression

Match expressions return values:

import std:println

grade = |score| {
    match {
        score >= 90 => "A",
        score >= 80 => "B",
        score >= 70 => "C",
        score >= 60 => "D",
        _ => "F",
    }
}

println(grade(85))  # B

Pattern Types

Patterns are deliberately limited. The complete list is:

• number literals, including negative ones (-3)
• string literals ("Monday")
• boolean literals (true, false) and nil
• regex literals (/\d+/)
• tuple patterns whose elements are themselves patterns ((0, 1), (10, _))
• alternations with | (1 | 2 | 3)
• the wildcard _

There are no variable-binding patterns, no list patterns ([a, b]), no map patterns, no range patterns (1..10 =>) and no if guards. For anything that needs a computed test, use the condition-only form of match described below.

Literal Matching

import std:println

value = 2

result = match value {
    0 => "zero",
    1 => "one",
    2 => "two",
    _ => "other",
}

println(result)  # two

Bare Identifiers Are String Literals — Not Bindings

A bare identifier on the left of => is not a binding; it is parsed as a string literal. So this looks like it doubles the subject but actually compares 5 against the string "n", matches nothing, and evaluates to nil:

import std:println

println(match 5 { n => n * 2, })  # nil

If you need the subject inside an arm body, refer to the original variable instead:

import std:println

n = 5

println(match { n > 0 => n * 2, _ => 0, })  # 10

No Match Means nil

A match with no arm that matches is not an error — it evaluates to nil:

import std:println

println(match 99 { 1 => "one", 2 => "two", })  # nil

That is why an explicit _ arm matters whenever nil would be a surprising result.

Conditional Match (No Scrutinee)

Use match { ... } without an expression for conditional matching:

import std:println

categorize = |n| {
    match {
        n < 0 => "negative",
        n == 0 => "zero",
        n < 10 => "single digit",
        n < 100 => "double digit",
        _ => "large",
    }
}

println(categorize(42))  # double digit

Tuple Patterns

A tuple pattern matches element by element, and each element is itself a pattern — a literal or _, never a binding:

import std:println

point = (10, 0)

match point {
    (0, 0) => println("Origin"),
    (0, _) => println("On the Y-axis"),
    (_, 0) => println("On the X-axis"),
    _ => println("Somewhere else"),
}

To use the components of a tuple, destructure it with an assignment first — the match arms can then test the parts:

import std:println

point = (10, 20)
x, y = point

quadrant = match {
    x > 0 && y > 0 => "I",
    x < 0 && y > 0 => "II",
    x < 0 && y < 0 => "III",
    x > 0 && y < 0 => "IV",
    _ => "on an axis",
}

println("(${x}, ${y}) is in quadrant ${quadrant}")  # (10, 20) is in quadrant I

Regex Patterns

A regex literal as a pattern matches when the subject string matches it. Regex matching is boolean only — there are no capture groups, so an arm body cannot pull pieces out of the subject:

import std:println

text = "Call me at 555-1234"

match text {
    /\d{3}-\d{4}/ => {
        words = text::split(" ")
        phones = words::filter(|w| w ~ /^\d{3}-\d{4}$/)
        match { phones::length() > 0 => { println("Phone: " + phones[0]) } }
    }
    /[a-z]+@[a-z]+\.[a-z]+/ => println("Email found"),
    _ => println("No pattern matched"),
}

Type Matching

import std:println

process = |value| {
    match {
        value::is_number() => "Number: ${value}",
        value::is_string() => "String: ${value}",
        value::is_bool() => "Boolean: ${value}",
        value::is_list() => "List with ${value::length()} items",
        _ => "Unknown type",
    }
}

println(process(42))        # Number: 42
println(process("hello"))   # String: hello
println(process([1, 2, 3])) # List with 3 items

Multiple Patterns (Alternation)

Use | to match multiple patterns:

import std:println

value = 5

match value {
    1 | 2 | 3 => println("Small"),
    4 | 5 | 6 => println("Medium"),
    7 | 8 | 9 => println("Large"),
    _ => println("Out of range"),
}

Wildcard Pattern (_)

Matches anything (catch-all):

import std:println

value = "something"

match value {
    "specific" => println("Matched specific"),
    _ => println("Matched anything else"),
}

Nested Match

import std:println

process = |value| {
    match {
        value::is_number() => {
            match {
                value < 0 => "Negative",
                value == 0 => "Zero",
                value < 10 => "Small positive",
                _ => "Large positive",
            }
        },
        value::is_string() => "Text",
        _ => "Other",
    }
}

println(process(-5))      # Negative
println(process(5))       # Small positive
println(process("hi"))    # Text

Common Patterns

Command Handler

import std:println

start_service = || println("starting")
stop_service = || println("stopping")
check_status = || println("running")

handle_command = |cmd| {
    match cmd {
        "start" => start_service(),
        "stop" => stop_service(),
        "status" => check_status(),
        _ => println("Unknown command: ${cmd}"),
    }
}

handle_command("start")   # starting
handle_command("deploy")  # Unknown command: deploy

State Machine

import std:println

next_state = |current, event| {
    match (current, event) {
        ("idle", "start") => "running",
        ("running", "pause") => "paused",
        ("paused", "resume") => "running",
        ("running", "stop") => "idle",
        ("paused", "stop") => "idle",
        _ => current,  # No transition
    }
}

println(next_state("idle", "start"))  # running
println(next_state("idle", "pause"))  # idle

Note the last arm: it is _ (a wildcard pattern) with the body current (an ordinary variable reference). Writing (state, _) => state would not work, because state in a pattern means the string "state".

Value-and-Error Tuples

Suji has no Result or Option type and no exceptions, so functions that can fail conventionally return a (value, error) tuple. Destructure the tuple first, then branch on the error with the condition form:

import std:println

parse_port = |text| {
    match text {
        /^\d+$/ => (text::to_number(), nil),
        _ => (nil, "not a number"),
    }
}

report = |text| {
    value, error = parse_port(text)
    match {
        error == nil => println("Port: ${value}"),
        _ => println("Error: ${error}"),
    }
}

report("8080")  # Port: 8080
report("http")  # Error: not a number

Ranges Are Not Patterns

1..10 is a range expression that evaluates to a list; it cannot appear on the left of =>. Use the condition form for interval logic:

import std:println

categorize_age = |age| {
    match {
        age < 0 => "Invalid",
        age < 13 => "Child",
        age < 20 => "Teenager",
        age < 65 => "Adult",
        _ => "Senior",
    }
}

println(categorize_age(25))  # Adult

Match vs Conditional Logic

When to Use Match:

• Multiple distinct literal values
• Regex or tuple shape testing
• Type-based dispatch (via is_number(), is_string() and friends)
• Interval and comparison logic, using the condition form
• Anywhere another language would use if/else

When to Use Short-Circuit Operators:

• Simple boolean conditions with early returns
• Guard clauses: condition && return value
• Early exits: condition || break

Both operands of && and || must be real booleans — there is no truthiness, so write x == nil or xs::length() == 0 rather than relying on a bare value.

Best Practices

DO:

• Always include a wildcard case (_) unless nil is the result you want
• Remember the trailing comma on every expression arm, last one included
• Use the condition form (match { … }) for ranges and computed tests
• Destructure a tuple before matching when you need its parts
• Keep match arms simple (extract complex logic)
• Order patterns from specific to general

DON’T:

• Forget the wildcard/default case
• Expect a bare identifier pattern to bind — it is a string literal
• Reach for list, map, range or if-guard patterns; they do not exist
• Have unreachable patterns
• Mix unrelated match criteria

See Also

• Pattern Matching
• Regular Expressions
• Tuples
• Conditional Logic

Guard Clauses

Guard clauses use logical operators (&& and ||) for early returns and short-circuit control flow.

Overview

Guard clauses improve code readability by handling edge cases and validation upfront, avoiding deep nesting. Suji uses logical operators for short-circuit evaluation to enable early returns.

They matter more in Suji than in most languages, because there is no error handling construct at all — no try, no catch, no throw, no Result type. A runtime error prints a diagnostic and terminates the process with exit code 1, and nothing can intercept it. The only way to survive a bad input is to check for it before performing the operation that would fail.

Both operands of && and || must be real booleans. There is no truthiness, so a guard condition is always an explicit comparison such as x == nil, xs::length() == 0 or m::contains("k").

Basic Guard Clause

import std:println

process_user = |user| {
    # Guard: return early if nil
    user == nil && return "Error: No user provided"
    
    # Main logic
    "Processing ${user:name}"
}

println(process_user(nil))  # Error: No user provided

Multiple Guards

Read possibly-missing map keys with ::get(key, default). A plain order:items on a map without that key raises Key not found and ends the program, which defeats the purpose of a guard:

import std:println

validate_order = |order| {
    # Guard 1: nil check
    order == nil && return "Order is required"

    # Guard 2: empty items
    order::get("items", [])::length() == 0 && return "Order must have items"

    # Guard 3: invalid total
    order::get("total", 0) <= 0 && return "Order total must be positive"

    # All guards passed - main logic
    "Order ${order::get("id", "?")} is valid"
}

println(validate_order(nil))                                     # Order is required
println(validate_order({items: []}))                             # Order must have items
println(validate_order({id: 7, items: ["book"], total: 0}))      # Order total must be positive
println(validate_order({id: 7, items: ["book"], total: 12.50}))  # Order 7 is valid

Guard Pattern Explained

Instead of nested conditions, use guard clauses for flat, readable code:

import std:println

# Guards (clear and flat)
process = |user| {
    # Guard clauses - return early on failure
    user == nil && return "No user"
    user::get("is_active", false) == false && return "User inactive"
    user::get("permissions", [])::contains("edit") == false && return "No permission"

    # Main logic (not nested)
    "Success"
}

println(process(nil))                                            # No user
println(process({is_active: false}))                             # User inactive
println(process({is_active: true, permissions: ["read"]}))       # No permission
println(process({is_active: true, permissions: ["read", "edit"]}))  # Success

Guards in Loops

import std:println

items = [
    {name: "a", valid: true},
    {name: "b", valid: false},
    {name: "c", valid: true},
]

loop through items with item {
    # Skip invalid items
    item:valid == false && continue

    # Process valid item
    println("processing ${item:name}")
}

break and continue also work with a label on an enclosing loop as name { … }, so a guard deep inside nested loops can abandon the outer one.

Logical Operators for Guards

Short-Circuit AND (&&)

Use && to return early when condition is true:

import std:println

# Return early if condition is true
validate = |x| {
    x == nil && return "nil"
    x < 0 && return "negative"
    "valid: ${x}"
}

println(validate(5))   # valid: 5
println(validate(-1))  # negative
println(validate(nil)) # nil

Short-Circuit OR (||)

Use || to return early when condition is false:

import std:println

# Return early if condition is false
process = |x| {
    x != nil || return "nil required"
    x > 0 || return "must be positive"
    "processing ${x}"
}

println(process(5))   # processing 5
println(process(0))   # must be positive
println(process(nil)) # nil required

Watch the Precedence

&& binds tighter than ||, so an alternative-condition guard needs parentheses. Written without them, i < 0 || i >= xs::length() && return nil groups as i < 0 || (i >= … && return nil) and never returns when i is negative:

import std:println

at = |xs, i| {
    (i < 0 || i >= xs::length()) && return nil
    xs[i]
}

println(at([1, 2, 3], 1))  # 2
println(at([1, 2, 3], 7))  # nil

Guarding Against Runtime Errors

These are the operations that terminate a program, and the check that prevents each one.

import std:println

# Division by zero: test the divisor
safe_divide = |a, b| {
    b == 0 && return nil
    a / b
}

println(safe_divide(10, 2))  # 5
println(safe_divide(10, 0))  # nil

# Missing map key: ::get with a default, or ::contains to test
config = {host: "localhost"}
println(config::get("port", 8080))  # 8080
println(config::contains("port"))   # false

# Empty collection: check length before averaging
scores = []
println(match { scores::length() == 0 => "no scores", _ => scores::average(), })  # no scores

# Unparseable number: validate with a regex before converting
to_number_or = |text, default| {
    !(text ~ /^-?\d+(\.\d+)?$/) && return default
    text::to_number()
}

println(to_number_or("42", 0))   # 42
println(to_number_or("abc", 0))  # 0

Index access is the same idea: xs[5] on a two-element list raises Index out of bounds, so compare against xs::length() first, as in the precedence example above.

Default Values Pattern

There is no x || default idiom — || requires booleans, so nil || "Guest" is a type error. Use ::get on maps, or a match when the value is already in hand:

import std:println

get_name = |user| {
    preferred = user::get("preferred_name", nil)
    preferred != nil && return preferred

    user::get("first_name", "Guest")
}

user1 = {preferred_name: "Alice"}
user2 = {first_name: "Bob"}
user3 = {}

println(get_name(user1))  # Alice
println(get_name(user2))  # Bob
println(get_name(user3))  # Guest

Common Patterns

Validation Function

Because a failure cannot be raised, report it as a value. A (ok, error) tuple is the usual shape; return a, b returns a tuple and a, b = f() destructures it:

import std:println

validate_user = |user| {
    user::get("name", "")::length() == 0 && return false, "Name is required"
    !(user::get("email", "") ~ /^[^@]+@[^@]+$/) && return false, "Valid email is required"
    user::get("age", 0) < 18 && return false, "Must be 18 or older"

    return true, nil
}

valid, error = validate_user({name: "Alice", email: "alice@example.com", age: 30})
match {
    error == nil => println("Valid"),
    _ => println("Error: ${error}"),
}

valid2, error2 = validate_user({name: "Bob", email: "nope", age: 30})
println("${valid2}: ${error2}")  # false: Valid email is required

Resource Access

import std:println

can_access = |user, resource| {
    # Guard: no user
    user == nil && return false

    # Guard: inactive user
    user::get("is_active", false) == false && return false

    # Guard: no resource
    resource == nil && return false

    # Check permissions
    user::get("permissions", [])::contains(resource::get("type", ""))
}

alice = {is_active: true, permissions: ["report"]}

println(can_access(nil, nil))                     # false
println(can_access(alice, {type: "invoice"}))     # false
println(can_access(alice, {type: "report"}))      # true

Data Processing

import std:println

process_data = |data| {
    # Guard: nil
    data == nil && return []

    # Guard: wrong type
    data::is_list() == false && return []

    # Guard: empty
    data::length() == 0 && return []

    # Process valid data
    data::filter(|n| n > 0)::map(|n| n * 10)
}

println(process_data(nil))              # []
println(process_data("not a list"))     # []
println(process_data([1, -2, 3]))       # [10, 30]

Command Handler

import std:println

known = ["start", "stop", "status"]

handle_command = |cmd, user| {
    # Guard: no command
    cmd == nil && return "Command required"
    cmd::length() == 0 && return "Command required"

    # Guard: unauthorized
    user == nil && return "Not authenticated"
    user::get("is_authenticated", false) == false && return "Not authenticated"

    # Guard: unknown command
    known::contains(cmd) == false && return "Unknown command: ${cmd}"

    "Running ${cmd}"
}

session = {is_authenticated: true}

println(handle_command("", session))         # Command required
println(handle_command("start", nil))        # Not authenticated
println(handle_command("deploy", session))   # Unknown command: deploy
println(handle_command("start", session))    # Running start

Guards vs Match

Use guards for early returns, match for branching:

import std:println

# Guards for validation
process = |x| {
    x == nil && return "nil"
    x < 0 && return "negative"
    
    # Match for branching logic
    match {
        x > 100 => "very large",
        x > 10 => "large",
        _ => "small",
    }
}

println(process(nil))  # nil
println(process(-1))   # negative
println(process(500))  # very large

Guards Instead of Exceptions

Suji has no exceptions to catch, so validation has to happen up front and failures travel back as ordinary return values:

import std:println

safe_divide = |a, b| {
    b == 0 && return nil, "Division by zero"
    return a / b, nil
}

result, error = safe_divide(10, 0)
match {
    error == nil => println("Result: ${result}"),
    _ => println("Error: ${error}"),
}

result2, error2 = safe_divide(10, 2)
println("${result2} ${error2}")  # 5 nil

Note what is not possible: you cannot write a / b first and recover afterwards. Once Division by zero is raised the process is gone.

Best Practices

DO:

• Put guards at the start of functions
• Return early on failure cases
• Check for nil before accessing properties
• Prefer m::get(k, default) and m::contains(k) over a direct m:k that can raise
• Use guards to avoid deep nesting
• Make error messages descriptive
• Use && return for positive conditions (return if true)
• Use || return for negative conditions (return if false)
• Parenthesize mixed &&/|| conditions

DON’T:

• Put guards after main logic
• Expect to recover from a runtime error — there is no try/catch
• Rely on truthiness; compare explicitly (x == nil, flag == false)
• Use x || "default" as a defaulting idiom — it is a type error
• Create overly defensive guards
• Use guards for normal branching logic (use match instead)
• Forget to return from guards
• Have guards with complex conditions (extract to variables)
• Mix guard patterns inconsistently

When to Use Guards

Use Guards For:

• Input validation
• Nil checks
• Permission checks
• Precondition verification
• Preventing operations that would raise (division by zero, missing keys, out-of-range indices)
• Early returns

Don’t Use Guards For:

• Normal branching logic (use match instead)
• Complex decision trees (use match instead)
• Multiple related conditions (use conditional match)

Examples

API Handler

Map literals with bare identifier keys are only recognised where a map is expected, so quote the keys when a map is the whole body of a return:

import std:println

handle_request = |request| {
    # Validate request with guards
    request == nil && return {"status": 400, "error": "No request"}
    !(request::get("method", "") ~ /^(GET|POST|PUT|DELETE)$/) && return {"status": 405, "error": "Invalid method"}
    request::contains("path") == false && return {"status": 400, "error": "Path required"}

    # Process request
    {"status": 200, "path": request:path}
}

println(handle_request(nil))                            # {status: 400, error: No request}
println(handle_request({method: "TRACE", path: "/"}))   # {status: 405, error: Invalid method}
println(handle_request({method: "GET"}))                # {status: 400, error: Path required}
println(handle_request({method: "GET", path: "/ok"}))   # {status: 200, path: /ok}

Form Validation

Collect every problem instead of returning on the first one:

import std:println

validate_form = |form| {
    errors = []

    username = form::get("username", "")
    match { username::length() < 3 => { errors::push("Username too short") } }

    password = form::get("password", "")
    match { password::length() < 8 => { errors::push("Password too short") } }

    email = form::get("email", "")
    match { !(email ~ /^[^@]+@[^@]+$/) => { errors::push("Invalid email") } }

    errors
}

println(validate_form({username: "al", password: "secret", email: "nope"}))
println(validate_form({username: "alice", password: "supersecret", email: "alice@example.com"}))

See Also

• Match Expressions - Pattern matching for branching logic
• Logical Operators - Understanding && and ||
• Loops - Using guards in loops
• Functions - Guard clauses in functions

Functions

Functions are first-class values in Suji that encapsulate reusable logic and enable functional programming patterns.

Overview

In Suji, functions are treated as values just like numbers or strings. You can pass them as arguments, return them from other functions, and store them in data structures.

Function Basics

Defining Functions

Every function in Suji is a lambda assigned to a name — there is no fn, def or function declaration keyword:

import std:println

# Basic function
greet = |name| {
    "Hello, ${name}!"
}

# Multiple parameters
add = |a, b| {
    a + b
}

# No parameters
get_pi = || {
    3.14159
}

# Single expression (implicit return)
double = |x| x * 2

# Default parameter value
increment = |x, step = 1| x + step

Calling Functions

import std:println

greet = |name| "Hello, ${name}!"

# Call the function
message = greet("Alice")
println(message)  # Hello, Alice!

# Direct call
println(greet("Bob"))  # Hello, Bob!

Learn more about Function Basics →

Closures

Functions capture variables from their surrounding scope:

import std:println

make_counter = || {
    count = 0
    increment = || {
        count = count + 1
        count
    }
    increment
}

counter = make_counter()
println(counter())  # 1
println(counter())  # 2
println(counter())  # 3

The returned closure is bound to a name (increment) before it is returned. A line that begins with | would otherwise be read as the pipeline operator continuing the previous statement.

Learn more about Closures →

Higher-Order Functions

Functions that take functions as parameters or return functions:

import std:println

# Takes a function as parameter
apply_twice = |fn, x| {
    fn(fn(x))
}

double = |x| x * 2
println(apply_twice(double, 5))  # 20

# Returns a function
multiplier = |factor| {
    |x| x * factor
}

times_3 = multiplier(3)
println(times_3(5))  # 15

Learn more about Higher-Order Functions →

Function Composition

Combine functions to create new functions:

import std:println

add_1 = |x| x + 1
times_2 = |x| x * 2

# Compose: (x + 1) * 2
composed = add_1 >> times_2
println(composed(5))  # 12

# Reverse: (x * 2) + 1
reversed = add_1 << times_2
println(reversed(5))  # 11

Learn more about Function Composition →

Recursion

Functions that call themselves. Note that every match arm whose body is a bare expression needs a trailing comma, including the last one:

import std:println

# Factorial
factorial = |n| {
    match n {
        0 => 1,
        _ => n * factorial(n - 1),
    }
}

println(factorial(5))  # 120

# Accumulator version — the same depth of recursion, just a different shape
factorial_acc = |n| {
    helper = |n, acc| {
        match n {
            0 => acc,
            _ => helper(n - 1, n * acc),
        }
    }
    helper(n, 1)
}

println(factorial_acc(5))  # 120

Suji has no tail-call optimisation, so recursion is limited by the native stack — see Recursion for the depth you can rely on.

Learn more about Recursion →

Multiple Return Values

Use tuples to return multiple values:

import std:println

divide_with_remainder = |a, b| {
    quotient = (a / b)::floor()
    return quotient, a % b
}

q, r = divide_with_remainder(17, 5)
println("${q} remainder ${r}")  # 3 remainder 2

Destructuring targets are written without parentheses (q, r = …); a line that starts with ( is read as a call on the previous expression.

Learn more about Multiple Returns →

Common Patterns

Partial Application

There is no partial-application operator; return a lambda from a lambda instead:

import std:println

greet_with = |greeting| {
    |name| "${greeting}, ${name}!"
}

hello = greet_with("Hello")
hi = greet_with("Hi")

println(hello("Alice"))  # Hello, Alice!
println(hi("Bob"))       # Hi, Bob!

Currying

import std:println

# Curried function
curry_add = |a| |b| |c| a + b + c

# Partial application
add_1 = curry_add(1)
add_1_2 = add_1(2)
result = add_1_2(3)

println(result)  # 6

Function Pipeline

import std:println

validate = |data| data::filter(|x| x != nil)
transform = |data| data::map(|x| x * 2)
enrich = |data| data + [0]

process_data = |data| {
    validated = validate(data)
    transformed = transform(validated)
    enrich(transformed)
}

println(process_data([1, nil, 3]))  # [2, 6, 0]

Memoization

A closure over a cache map turns an expensive recursive function into a fast one:

import std:println

fib_cache = {0: 0, 1: 1}

fib = |n| {
    fib_cache::contains(n) && return fib_cache[n]
    result = fib(n - 1) + fib(n - 2)
    fib_cache[n] = result
    result
}

println(fib(60))  # 1548008755920

Function Types

Pure Functions

No side effects, same input always produces same output:

# Pure: depends only on parameters
add = |a, b| a + b

# Pure: deterministic
double = |x| x * 2

Impure Functions

Have side effects or depend on external state:

import std:println

# Impure: side effect (printing)
log = |message| {
    println(message)
}

# Impure: depends on external state
counter = 0
increment = || {
    counter = counter + 1
    counter
}

Anonymous Functions (Lambdas)

Inline functions without names:

import std:println

numbers = [1, 2, 3, 4, 5]

# Anonymous function in map
doubled = numbers::map(|x| x * 2)

# Anonymous function in filter
evens = numbers::filter(|x| x % 2 == 0)

Best Practices

DO:

• Keep functions small and focused (single responsibility)
• Use descriptive names (verbs for actions)
• Prefer pure functions when possible
• Use closures for encapsulation
• Leverage higher-order functions for abstraction

DON’T:

• Create functions with too many parameters (>4)
• Mix concerns in a single function
• Forget to handle edge cases
• Create deeply nested functions
• Ignore function return values

Performance Considerations

Function Call Overhead

Every call still walks the interpreter, so inlining simple arithmetic is cheaper than routing it through two closures:

import std:println

double = |x| x * 2
add_1 = |x| x + 1

x = 5
result1 = x * 2 + 1
result2 = add_1(double(x))

println(result1 == result2)  # true

Closure Capture

A closure keeps a reference to the scope it was created in, so captured variables stay live (and stay writable) for as long as the closure does:

make_adder = |x| {
    |y| x + y
}

Recursion Depth

There is no tail-call optimisation: a tail-recursive shape uses exactly as much stack as any other recursion, and a few hundred nested calls will overflow the native stack and abort the process. Use a loop when the depth depends on input size:

import std:println

# Recursive: one stack frame per element
sum_recursive = |n| {
    match n {
        0 => 0,
        _ => n + sum_recursive(n - 1),
    }
}

# Iterative: constant stack, any size
sum_iterative = |n| {
    total = 0
    loop through 1..=n with i {
        total = total + i
    }
    total
}

println(sum_recursive(100))   # 5050
println(sum_iterative(10000)) # 50005000

Common Use Cases

Callbacks

import std:println

read_config = |path, callback| {
    contents = `cat ${path}`
    callback(contents)
}

path = `mktemp`
`printf 'debug=true' > ${path}`

read_config(path, |data| {
    println("Received: ${data}")  # Received: debug=true
})

Event Handlers

Store handlers in a map and call them when the event happens:

import std:println

handlers = {}

on = |event, handler| {
    handlers[event] = handler
}

emit = |event| {
    handler = handlers::get(event)
    match { handler != nil => { handler() } }
}

on("click", || println("Button clicked!"))
emit("click")   # Button clicked!
emit("scroll")  # nothing registered, nothing happens

Factory Functions

import std:println

create_user = |name, age| {
    user = {
        name: name,
        age: age,
        greet: || "Hello, I'm ${name}",
        is_adult: || age >= 18,
    }
    user
}

user = create_user("Alice", 30)
println(user:greet())     # Hello, I'm Alice
println(user:is_adult())  # true

The map is bound to a name before being returned: a { … } in statement position is parsed as a block, not as a map literal.

Middleware Pattern

import std:println

# Middleware function
with_logging = |handler| {
    |request| {
        println("Request: ${request}")
        result = handler(request)
        println("Response: ${result}")
        result
    }
}

# Base handler
handle_request = |request| {
    "Processed: ${request}"
}

# Wrapped handler
logged_handler = with_logging(handle_request)
println(logged_handler("GET /"))
# Request: GET /
# Response: Processed: GET /
# Processed: GET /

Quick Reference

Next Steps

Dive deep into each function concept:

1. Function Basics - Parameters, returns, calling
2. Closures - Variable capture, scope
3. Higher-Order Functions - Functions as values
4. Recursion - Self-referential functions
5. Multiple Returns - Returning tuples
6. Function Composition - Combining functions with >> and <<

See Also

• Operators
• Control Flow
• Data Types
• Modules

Function Basics

Learn the fundamentals of defining, calling, and using functions in Suji.

Defining Functions

Functions are created with the pipe syntax |parameters| { body } and bound to a name with =. There is no separate declaration keyword:

import std:println
import std:time

# Basic function
greet = |name| {
    "Hello, ${name}!"
}

# Multiple parameters
add = |a, b| {
    a + b
}

# No parameters
get_timestamp = || {
    time:now():epoch_ms
}

# Single expression (no braces needed)
double = |x| x * 2
square = |x| x * x

Calling Functions

import std:println

greet = |name| "Hello, ${name}!"
add = |a, b| a + b
double = |x| x * 2

# Direct call
println(greet("Alice"))  # Hello, Alice!

# Store result
message = greet("Bob")
println(message)  # Hello, Bob!

# Chain calls
result = double(add(3, 4))
println(result)  # 14

Parameters

Required Parameters

Every parameter without a default must be provided. Arity is checked at call time, so a missing argument is a runtime error, not nil:

import std:println

calculate = |x, y, operation| {
    match operation {
        "add" => x + y,
        "subtract" => x - y,
        "multiply" => x * y,
        "divide" => x / y,
        _ => 0,
    }
}

println(calculate(10, 5, "add"))  # 15

# calculate(10, 5)
# => Arity mismatch: Function expects 3 arguments, got 2

Default Values

Give a parameter a default with = in the parameter list. The default is used when the argument is omitted:

import std:println

greet = |name, title = "Mr./Ms."| "${title} ${name}"

println(greet("Alice", "Dr."))  # Dr. Alice
println(greet("Bob"))           # Mr./Ms. Bob

Passing nil explicitly passes nil — it does not fall back to the default. Handle that case with match if callers may supply nil:

import std:println

greet = |name, title| {
    label = match title {
        nil => "Mr./Ms.",
        _ => title,
    }
    "${label} ${name}"
}

println(greet("Alice", "Dr."))  # Dr. Alice
println(greet("Bob", nil))      # Mr./Ms. Bob

A bare identifier in a match pattern is a string literal, not a binding, so the fallback arm has to be _ and read the parameter directly.

Variable Arguments Pattern

There are no variadic parameters. Accept a list instead:

import std:println

sum_all = |numbers| {
    numbers::fold(0, |acc, x| acc + x)
}

println(sum_all([1, 2, 3]))       # 6
println(sum_all([1, 2, 3, 4, 5])) # 15

Return Values

Implicit Return

Last expression is automatically returned:

import std:println

add = |a, b| {
    a + b  # Returned automatically
}

println(add(3, 4))  # 7

Explicit Return

Use return for early exit:

import std:println

find_first = |list, predicate| {
    loop through list with item {
        predicate(item) && return item  # Early return
    }
    nil  # Not found
}

numbers = [1, 2, 3, 4, 5]
println(find_first(numbers, |x| x > 3))  # 4

Multiple Return Values

Return several values with return a, b, and destructure them without parentheses:

import std:println

divide_with_remainder = |a, b| {
    return (a / b)::floor(), a % b
}

quotient, remainder = divide_with_remainder(17, 5)
println("${quotient} remainder ${remainder}")  # 3 remainder 2

No Return Value

Functions can perform side effects without returning:

import std:println

log_message = |message| {
    println("[LOG] ${message}")
    # No explicit return (returns nil implicitly)
}

log_message("Application started")

Function Scope

Local Variables

Variables defined in functions are local:

import std:println

calculate = |x| {
    temp = x * 2
    result = temp + 10
    result
}

println(calculate(5))  # 20
# temp and result are not accessible here

Capturing Outer Variables

Functions can access variables from outer scope:

import std:println

multiplier = 10

scale = |x| {
    x * multiplier  # Accesses outer variable
}

println(scale(5))  # 50

Function as Values

Functions are first-class values:

import std:println

# Store in variable
double = |x| x * 2

# Store in list
operations = [
    |x| x + 1,
    |x| x * 2,
    |x| x ^ 2,
]

times_2 = operations[1]
println(times_2(5))  # 10 (second function)

# Store in map
math_ops = {
    add: |a, b| a + b,
    sub: |a, b| a - b,
    mul: |a, b| a * b,
}

println(math_ops:add(3, 4))  # 7

Common Patterns

Predicate Functions

Return boolean:

import std:println

is_even = |x| x % 2 == 0
is_positive = |x| x > 0
is_adult = |age| age >= 18

println(is_even(4))      # true
println(is_positive(-5)) # false
println(is_adult(25))    # true

Transformer Functions

Transform input to output:

import std:println

to_upper = |text| text::upper()
trim_and_lower = |text| text::trim()::lower()
add_prefix = |text| "PREFIX_${text}"

println(to_upper("hello"))  # HELLO

Validator Functions

Validate and return result:

import std:println

validate_email = |email| {
    missing = email == nil || email::length() == 0
    missing && return false, "Email is required"
    !(email ~ /^[^@]+@[^@]+$/) && return false, "Invalid email format"

    return true, nil
}

valid, error = validate_email("test@example.com")
println(valid)  # true

ok, why = validate_email("not-an-email")
println(why)  # Invalid email format

Note the explicit return true, nil at the end: a line starting with ( would be parsed as a call on the previous line’s value.

Best Practices

DO:

• Use descriptive verb names (calculate, validate, transform)
• Keep functions small and focused
• Document complex behavior
• Handle edge cases
• Return consistent types

DON’T:

• Create functions with too many parameters
• Mix different concerns
• Use cryptic abbreviations
• Ignore error cases
• Create side effects unexpectedly

See Also

• Closures
• Higher-Order Functions
• Multiple Returns
• Recursion

Closures

Closures are functions that capture and remember variables from their surrounding scope.

Overview

A closure “closes over” variables from its outer scope, allowing the function to access those variables even after the outer scope has finished executing.

Basic Closure

import std:println

outer = || {
    message = "Hello"
    
    # Inner function captures 'message'
    inner = || {
        println(message)
    }
    
    inner
}

fn = outer()
fn()  # Prints: Hello

Capturing Variables

import std:println

make_greeter = |greeting| {
    # Returns function that captures 'greeting'
    |name| "${greeting}, ${name}!"
}

hello = make_greeter("Hello")
hi = make_greeter("Hi")

println(hello("Alice"))  # Hello, Alice!
println(hi("Bob"))       # Hi, Bob!

Counter Example

Classic closure use case:

import std:println

make_counter = || {
    count = 0
    increment = || {
        count = count + 1
        count
    }
    increment
}

counter1 = make_counter()
counter2 = make_counter()

println(counter1())  # 1
println(counter1())  # 2
println(counter2())  # 1 (separate counter)
println(counter1())  # 3

The inner closure is bound to increment before being returned. A statement that begins with | is read as the pipeline operator continuing the previous statement, so a returned lambda always needs a name (or has to be the first thing in the body).

Multiple Closures Sharing State

import std:println

make_account = |initial_balance| {
    balance = initial_balance

    account = {
        deposit: |amount| {
            balance = balance + amount
            balance
        },
        withdraw: |amount| {
            match {
                amount <= balance => {
                    balance = balance - amount
                    balance
                },
                _ => nil,
            }
        },
        get_balance: || balance,
    }
    account
}

account = make_account(100)
println(account:deposit(50))     # 150
println(account:withdraw(30))    # 120
println(account:get_balance())   # 120

All three closures share the same balance, and the map has to be bound to a name before it is returned — a { … } in statement position is parsed as a block.

Partial Application

Use closures for partial application:

import std:println

multiply = |a, b| a * b

# Create specialized function
double = |x| multiply(2, x)
triple = |x| multiply(3, x)

println(double(5))  # 10
println(triple(5))  # 15

# Or with closure
make_multiplier = |factor| {
    |x| multiply(factor, x)
}

times_10 = make_multiplier(10)
println(times_10(5))  # 50

Configuration Pattern

import std:println

create_formatter = |config| {
    prefix = config::get("prefix", "")
    suffix = config::get("suffix", "")
    uppercase = config::get("uppercase", false)

    format = |text| {
        result = text
        match { uppercase => { result = result::upper() } }
        "${prefix}${result}${suffix}"
    }
    format
}

formatter = create_formatter({
    prefix: "[",
    suffix: "]",
    uppercase: true,
})

println(formatter("hello"))  # [HELLO]

Closure Scope Chain

Closures can access multiple levels of scope:

import std:println

outer = |x| {
    middle = |y| {
        inner = |z| {
            # Accesses all three scopes
            x + y + z
        }
        inner
    }
    middle
}

fn = outer(1)(2)
println(fn(3))  # 6

Memoization with Closures

import std:println

memoize = |fn| {
    cache = {}
    cached = |arg| {
        cache::contains(arg) && return cache[arg]
        println("Computing for ${arg}")
        result = fn(arg)
        cache[arg] = result
        result
    }
    cached
}

expensive = |n| {
    # Simulate expensive computation
    n * n
}

fast = memoize(expensive)
println(fast(5))  # Computing for 5, then 25
println(fast(5))  # 25 straight from the cache

Event Handlers

import std:println

create_button = |label| {
    click_count = 0

    button = {
        label: label,
        on_click: || {
            click_count = click_count + 1
            println("${label} clicked ${click_count} times")
        },
    }
    button
}

button = create_button("Submit")
button:on_click()  # Submit clicked 1 times
button:on_click()  # Submit clicked 2 times

Common Patterns

Factory Function

import std:println

create_validator = |rules| {
    check = |value| {
        loop through rules with rule {
            !rule(value) && return false
        }
        true
    }
    check
}

is_valid_password = create_validator([
    |p| p::length() >= 8,
    |p| p ~ /[A-Z]/,
    |p| p ~ /[0-9]/,
])

println(is_valid_password("Abc123"))    # false
println(is_valid_password("Abc12345")) # true

Module Pattern

import std:println

create_module = || {
    # Private state
    private_data = "secret"

    # Public interface
    api = {
        get_public: || "public data",
        process: |input| {
            # Can access private_data
            "${input} + ${private_data}"
        },
    }
    api
}

module = create_module()
println(module:get_public())      # public data
println(module:process("test"))   # test + secret
# private_data is not accessible

Performance Considerations

Closure Creation Cost

Creating a closure only records the current scope, so factories are cheap to call:

make_adder = |x| {
    |y| x + y
}

A lambda that is the first thing in the body does not need a name — it is only a statement after another expression that would be misread as a pipeline.

Shared Scope

A closure holds a reference to the whole scope it was created in, not a copy of individual variables. Everything defined in that scope stays alive as long as the closure does, and writes are visible in both directions:

import std:println

outer = || {
    shared = "first"
    read = || shared
    shared = "second"
    read
}

read = outer()
println(read())  # second

Best Practices

DO:

• Use closures for encapsulation
• Return closures for configuration
• Use for event handlers and callbacks
• Create factory functions with closures
• Bind a returned closure to a name before returning it

DON’T:

• Keep large values alive in a captured scope longer than needed
• Create deeply nested closures
• Use closures for simple operations
• Forget captured variables are shared
• Mutate captured state unexpectedly

See Also

• Function Basics
• Higher-Order Functions
• Function Composition

Higher-Order Functions

Higher-order functions are functions that take other functions as parameters or return functions as results.

Overview

Higher-order functions enable powerful abstraction and code reuse by treating functions as first-class values.

Functions as Parameters

Basic Example

import std:println

apply_twice = |fn, x| {
    fn(fn(x))
}

double = |x| x * 2
increment = |x| x + 1

println(apply_twice(double, 3))     # 12 (double(double(3)))
println(apply_twice(increment, 5))  # 7 (increment(increment(5)))

Map

Transform each element in a collection:

import std:println

numbers = [1, 2, 3, 4, 5]
squared = numbers::map(|x| x * x)
println(squared)  # [1, 4, 9, 16, 25]

Filter

Keep only elements that match a predicate:

import std:println

numbers = [1, 2, 3, 4, 5, 6]
evens = numbers::filter(|x| x % 2 == 0)
println(evens)  # [2, 4, 6]

Fold

Combine elements into a single value with fold(initial, fn). This is the only reducing method — there is no list::reduce():

import std:println

numbers = [1, 2, 3, 4, 5]
sum = numbers::fold(0, |acc, x| acc + x)
product = numbers::fold(1, |acc, x| acc * x)

println(sum)      # 15
println(product)  # 120

map, filter and fold are the built-in higher-order list methods. Anything else (each, find, any, all, sort_by, group_by, …) you write yourself with a loop through, as shown below.

Functions as Return Values

Function Factories

import std:println

make_multiplier = |factor| {
    |x| x * factor
}

times_2 = make_multiplier(2)
times_10 = make_multiplier(10)

println(times_2(5))   # 10
println(times_10(5))  # 50

Configurable Functions

import std:println

create_validator = |min_length, pattern| {
    check = |input| {
        long_enough = input::length() >= min_length
        matches = input ~ pattern
        long_enough && matches
    }
    check
}

validate_username = create_validator(3, /^[a-zA-Z0-9_]+$/)
validate_password = create_validator(8, /^.*[A-Z].*[0-9].*$/)

println(validate_username("abc"))    # true
println(validate_password("Pass1")) # false (too short)

Common Higher-Order Functions

ForEach

There is no list::each(); loop through is the way to run a function for every element, and it wraps up neatly as a helper:

import std:println

for_each = |list, fn| {
    loop through list with item {
        fn(item)
    }
}

names = ["Alice", "Bob", "Charlie"]
for_each(names, |name| println("Hello, ${name}!"))

Find

list::find() does not exist either. Write it with an early return:

import std:println

find = |list, predicate| {
    loop through list with item {
        predicate(item) && return item
    }
    nil
}

numbers = [1, 3, 5, 8, 10]
first_even = find(numbers, |x| x % 2 == 0)
println(first_even)  # 8

Any / All

Same again — any and all are helpers you define, not methods:

import std:println

any = |list, predicate| {
    loop through list with item {
        predicate(item) && return true
    }
    false
}

all = |list, predicate| {
    loop through list with item {
        !predicate(item) && return false
    }
    true
}

numbers = [2, 4, 6, 8]
println(any(numbers, |x| x > 5))        # true
println(all(numbers, |x| x % 2 == 0))  # true

Sort By

There is no built-in list::sort_by(). If you need ordering by a key, write a small helper.

import std:println

insert_sorted = |list, item, key_fn| {
    out = []
    inserted = false
    loop through list with existing {
        match { !inserted && key_fn(item) < key_fn(existing) => {
            out::push(item)
            inserted = true
        } }
        out::push(existing)
    }
    match { inserted == false => { out::push(item) } }
    out
}

sort_by = |list, key_fn| {
    result = []
    loop through list with item {
        result = insert_sorted(result, item, key_fn)
    }
    result
}

users = [
    {name: "Alice", age: 30},
    {name: "Bob", age: 25},
    {name: "Charlie", age: 35},
]

by_age = sort_by(users, |u| u:age)
println(by_age[0]:name)  # Bob (youngest)

list::sort() sorts numbers and strings directly; the helper above is only needed when you sort by a derived key.

Group By

Group elements by key function:

import std:println

group_by = |list, key_fn| {
    result = {}
    loop through list with item {
        key = key_fn(item)
        group = result::get(key, [])
        group::push(item)
        result[key] = group
    }
    result
}

users = [
    {name: "Alice", role: "admin"},
    {name: "Bob", role: "user"},
    {name: "Charlie", role: "admin"},
]

by_role = group_by(users, |u| u:role)
println(by_role:admin::length())  # 2

Function Combinators

Compose

Combine two functions. Suji has built-in composition operators (>> and <<), but writing compose by hand shows what they do:

import std:println

compose = |f, g| {
    |x| f(g(x))
}

add_1 = |x| x + 1
times_2 = |x| x * 2

# (x + 1) * 2
add_then_multiply = compose(times_2, add_1)
println(add_then_multiply(5))  # 12

# The same thing with the operator
println((add_1 >> times_2)(5))  # 12

Pipe

Apply value through functions:

import std:println

pipe = |x, functions| {
    result = x
    loop through functions with fn {
        result = fn(result)
    }
    result
}

result = pipe(5, [
    |x| x + 1,
    |x| x * 2,
    |x| x ^ 2,
])
println(result)  # 144

Partial

There are no variadic parameters, so a generic partial is not expressible. Bind the known arguments in a closure with the arity you actually need:

import std:println

add_three = |a, b, c| a + b + c

partial_1 = |fn, first| {
    rest = |b, c| fn(first, b, c)
    rest
}

add_5_and = partial_1(add_three, 5)
println(add_5_and(3, 7))  # 15

Practical Examples

Data Pipeline

import std:println

process_data = |data, transformers| {
    result = data
    loop through transformers with transform {
        result = transform(result)
    }
    result
}

data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

result = process_data(data, [
    |nums| nums::filter(|x| x % 2 == 0),
    |nums| nums::map(|x| x * x),
    |nums| nums::fold(0, |acc, x| acc + x)
])

println(result)  # 220

Validation Pipeline

import std:println

validate_all = |value, validators| {
    loop through validators with validator {
        valid, error = validator(value)
        !valid && return false, error
    }
    return true, nil
}

valid, error = validate_all("test@example.com", [
    |v| match { v != nil => (true, nil), _ => (false, "Required"), },
    |v| match { v::length() > 0 => (true, nil), _ => (false, "Not empty"), },
    |v| match { v ~ /@/ => (true, nil), _ => (false, "Invalid email"), },
])

println(valid)  # true
println(error)  # nil

Retry Logic

A function that returns a (value, error) pair can be retried by a higher-order wrapper. Suji has no exceptions, so the wrapped function reports failure in its return value rather than raising:

import std:println

retry = |fn, max_attempts| {
    attempt = 1
    loop {
        result, error = fn()
        done = error == nil || attempt >= max_attempts
        done && return result, error
        attempt = attempt + 1
    }
}

# A call that fails the first two times
attempts = 0
flaky = || {
    attempts = attempts + 1
    match {
        attempts < 3 => (nil, "temporary failure"),
        _ => ("payload", nil),
    }
}

result, error = retry(flaky, 5)
println(result)   # payload
println(attempts) # 3

Best Practices

DO:

• Use higher-order functions for abstraction
• Prefer the built-in methods (map, filter, fold) over hand-written loops
• Name function parameters descriptively
• Keep functions pure when possible
• Use lambdas for simple transformations

DON’T:

• Overuse higher-order functions
• Create deeply nested function calls
• Ignore performance implications
• Make functions too abstract
• Forget about readability

See Also

• Function Basics
• Closures
• Function Composition
• Lists

Recursion

Recursion occurs when a function calls itself to solve a problem by breaking it into smaller sub-problems.

A function recurses through the name it is assigned to, and every match arm whose body is a bare expression needs a trailing comma — including the last arm.

Depth limit: Suji has no tail-call optimisation. Each call consumes a native stack frame, and a few hundred nested calls overflow the stack and abort the process. The exact ceiling depends on how much each frame holds — a simple 1 + f(n - 1) recursion survives 600 levels but not 700, and a two-argument accumulator survives 700 but not 900. Recursion is for bounded, shallow work; use a loop when the depth grows with the size of the input.

Basic Recursion

import std:println

# Factorial
factorial = |n| {
    match n {
        0 => 1,
        _ => n * factorial(n - 1),
    }
}

println(factorial(5))  # 120

Fibonacci Sequence

import std:println

fib = |n| {
    match n {
        0 => 0,
        1 => 1,
        _ => fib(n - 1) + fib(n - 2),
    }
}

println(fib(10))  # 55

Accumulator Recursion

Passing an accumulator keeps the intermediate result in a parameter instead of in the pending multiplications:

import std:println

factorial = |n| {
    helper = |n, acc| {
        match n {
            0 => acc,
            _ => helper(n - 1, n * acc),
        }
    }
    helper(n, 1)
}

println(factorial(5))  # 120

This is often called tail recursion, but Suji does not optimise it: the accumulator version uses exactly as many stack frames as the version above. Its only advantage here is that the result is complete as soon as the base case is reached.

Recursion vs Iteration

Recursive Sum

import std:println

sum_recursive = |list| {
    match list::length() {
        0 => 0,
        _ => list[0] + sum_recursive(list[1;]),
    }
}

println(sum_recursive([1, 2, 3, 4, 5]))  # 15

Iterative Sum

import std:println

sum_iterative = |list| {
    total = 0
    loop through list with n {
        total = total + n
    }
    total
}

println(sum_iterative([1, 2, 3, 4, 5]))  # 15

Both print the same answer, but only the iterative version survives a long list: sum_recursive needs one stack frame per element, so it aborts somewhere past a few hundred elements.

Common Recursive Patterns

List Processing

import std:println

# Recursive map
map_recursive = |list, fn| {
    match list::length() {
        0 => [],
        _ => [fn(list[0])] + map_recursive(list[1;], fn),
    }
}

numbers = [1, 2, 3, 4, 5]
doubled = map_recursive(numbers, |x| x * 2)
println(doubled)  # [2, 4, 6, 8, 10]

Tree Traversal

import std:println

# Sum all values in tree
sum_tree = |node| {
    match node {
        nil => 0,
        _ => node:value + sum_tree(node:left) + sum_tree(node:right),
    }
}

tree = {
    value: 10,
    left: {value: 5, left: nil, right: nil},
    right: {value: 15, left: nil, right: nil},
}

println(sum_tree(tree))  # 30

Patterns cannot bind values: a bare identifier in a match pattern is a string literal, so the recursive arm is _ and reads node directly.

Path Finding

import std:println

find_path = |graph, start, goal, visited| {
    seen = match visited {
        nil => [],
        _ => visited,
    }

    start == goal && return [goal]
    seen::contains(start) && return nil

    seen::push(start)
    neighbors = graph::get(start, [])

    loop through neighbors with neighbor {
        path = find_path(graph, neighbor, goal, seen)
        path != nil && return [start] + path
    }

    nil
}

graph = {
    a: ["b", "c"],
    b: ["d"],
    c: ["d"],
    d: [],
}

println(find_path(graph, "a", "d", nil))  # [a, b, d]
println(find_path(graph, "d", "a", nil))  # nil

Recursive Data Structures

Linked List

import std:println

# Count elements
count_list = |node| {
    match node {
        nil => 0,
        _ => 1 + count_list(node:next),
    }
}

list = {value: 1, next: {value: 2, next: {value: 3, next: nil}}}
println(count_list(list))  # 3

Directory Tree

import std:println

# Count all files
count_files = |entry| {
    match entry:type {
        "file" => 1,
        "directory" => {
            total = 0
            loop through entry:children with child {
                total = total + count_files(child)
            }
            total
        }
        _ => 0,
    }
}

tree = {
    type: "directory",
    children: [
        {type: "file"},
        {type: "directory", children: [{type: "file"}, {type: "file"}]},
    ],
}

println(count_files(tree))  # 3

The _ => 0 arm matters: a match with no matching arm evaluates to nil, which would break the total + … addition on the next level up.

Mutual Recursion

Functions that call each other:

import std:println

is_even = |n| {
    match n {
        0 => true,
        _ => is_odd(n - 1),
    }
}

is_odd = |n| {
    match n {
        0 => false,
        _ => is_even(n - 1),
    }
}

println(is_even(4))  # true
println(is_odd(5))   # true

is_even may refer to is_odd before it is defined, because the name is looked up when the call happens, not when the lambda is created.

Performance Optimization

Memoization

Cache results to avoid recomputation. The cache has to be consulted inside the recursive function, so that every sub-call benefits:

import std:println

fib_cache = {0: 0, 1: 1}

fib = |n| {
    fib_cache::contains(n) && return fib_cache[n]
    result = fib(n - 1) + fib(n - 2)
    fib_cache[n] = result
    result
}

println(fib(60))  # 1548008755920

Without the cache, fib(60) would make more calls than you have patience for; with it, each value is computed once. Note that the recursion still goes 60 frames deep, so this trick makes the function faster, not deeper.

A generic wrapper is also possible, but it only caches repeated calls at the top level — the recursive calls inside fib_slow still go to the unmemoized function:

import std:println

memoize = |fn| {
    cache = {}
    cached = |arg| {
        cache::contains(arg) && return cache[arg]
        result = fn(arg)
        cache[arg] = result
        result
    }
    cached
}

fib_slow = |n| {
    match n {
        0 => 0,
        1 => 1,
        _ => fib_slow(n - 1) + fib_slow(n - 2),
    }
}

fib_fast = memoize(fib_slow)
println(fib_fast(20))  # 6765 (computed)
println(fib_fast(20))  # 6765 (from the cache)

No Tail-Call Optimization

Suji does not optimise tail calls. Both functions below use one stack frame per element, so both overflow on a long list — the accumulator version is not a way to recurse deeper:

import std:println

# Tail-recursive in shape, but not optimised
sum_tail = |list, acc| {
    match list::length() {
        0 => acc,
        _ => sum_tail(list[1;], acc + list[0]),
    }
}

# Plainly recursive
sum_regular = |list| {
    match list::length() {
        0 => 0,
        _ => list[0] + sum_regular(list[1;]),
    }
}

small = 1..=50
println(sum_tail(small, 0))    # 1275
println(sum_regular(small))    # 1275

# sum_tail(1..=5000, 0)
# => aborts with "thread 'main' has overflowed its stack"

When the depth follows the size of the input, use list::fold() or a loop:

import std:println

big = 1..=10000
println(big::fold(0, |acc, x| acc + x))  # 50005000

When to Use Recursion

Good Use Cases:

• Tree/graph traversal
• Divide-and-conquer algorithms
• Parsing nested structures
• Mathematical sequences
• Backtracking algorithms

Avoid Recursion For:

• Simple list iteration (use loops)
• Deep recursion (stack overflow risk)
• When iterative solution is clearer
• Performance-critical hot paths

Best Practices

DO:

• Always have base case
• Keep the depth bounded and small (a few hundred frames at most)
• Consider memoization for expensive recursion
• Document recursive logic
• Test with edge cases (empty, single element)

DON’T:

• Forget the base case
• Create infinite recursion — there is no trampolining, it aborts the process
• Use recursion for simple loops
• Expect tail calls to be optimised
• Over-complicate with recursion

Examples

Flatten Nested Lists

import std:println

flatten = |list| {
    result = []
    loop through list with item {
        match {
            item::is_list() => { result = result + flatten(item) },
            _ => result::push(item),
        }
    }
    result
}

nested = [1, [2, 3], [4, [5, 6]], 7]
println(flatten(nested))  # [1, 2, 3, 4, 5, 6, 7]

Quick Sort

import std:println

quicksort = |list| {
    match list::length() {
        0 => [],
        1 => list,
        _ => {
            pivot = list[0]
            rest = list[1;]

            less = rest::filter(|x| x < pivot)
            greater = rest::filter(|x| x >= pivot)

            quicksort(less) + [pivot] + quicksort(greater)
        },
    }
}

unsorted = [3, 1, 4, 1, 5, 9, 2, 6, 5]
println(quicksort(unsorted))  # [1, 1, 2, 3, 4, 5, 5, 6, 9]

Generate Permutations

import std:println

permutations = |list| {
    match list::length() {
        0 => [[]],
        _ => {
            result = []
            i = 0
            loop through list with item {
                rest = list[0;i] + list[i + 1;]
                loop through permutations(rest) with perm {
                    result::push([item] + perm)
                }
                i = i + 1
            }
            result
        }
    }
}

println(permutations([1, 2, 3]))
# [[1, 2, 3], [1, 3, 2], [2, 1, 3], [2, 3, 1], [3, 1, 2], [3, 2, 1]]

loop through over a list binds one variable, the element. Track the index with a counter, as above; the two-binding form (with k, v) is for maps only.

See Also

• Function Basics
• Higher-Order Functions
• Loops
• Pattern Matching

Multiple Return Values

Functions can return multiple values using tuples, enabling elegant error handling and complex result patterns.

Two rules apply throughout this chapter:

• Return several values with return a, b, which builds a tuple.
• Destructure without parentheses: a, b = f(). A line that begins with ( is parsed as a call on the previous expression, so (a, b) = f() does not destructure.

Basic Multiple Returns

import std:println

divide_with_remainder = |a, b| {
    quotient = (a / b)::floor()
    return quotient, a % b
}

q, r = divide_with_remainder(17, 5)
println("${q} remainder ${r}")  # 3 remainder 2

Destructuring Returns

Basic Destructuring

import std:println

get_coordinates = || (10, 20, 30)

x, y, z = get_coordinates()
println("x:${x}, y:${y}, z:${z}")  # x:10, y:20, z:30

Ignoring Values

Use underscore to ignore unwanted values:

import std:println

# total, average, min, max
get_stats = || (100, 50, 25, 10)

total, avg, _, _ = get_stats()
println("Total: ${total}, Average: ${avg}")  # Total: 100, Average: 50

Result/Error Pattern

Common pattern for error handling:

import std:println

safe_divide = |a, b| {
    match { b == 0 => (nil, "Division by zero"), _ => (a / b, nil), }
}

result, error = safe_divide(10, 2)
match error {
    nil => println("Result: ${result}"),   # Result: 5
    _ => println("Error: ${error}"),
}

failed, why = safe_divide(10, 0)
println(why)  # Division by zero

Patterns do not bind, so the second arm is _ and reads error directly. This is the only way to react to a failure: a real division by zero terminates the program, so the check has to happen before the operation.

Validation Results

import std:println

validate_user = |user| {
    # Check multiple conditions
    user:name == nil && return false, "Name is required"
    user:name::length() < 3 && return false, "Name too short"
    user:age < 18 && return false, "Must be 18+"

    return true, nil
}

valid, error = validate_user({name: "Alice", age: 30})
match { valid => println("User is valid"), _ => println("Validation error: ${error}"), }
# User is valid

ok, problem = validate_user({name: "Al", age: 30})
println(problem)  # Name too short

Parsing Results

import std:println

parse_int = |text| {
    # Validate before converting: to_number() on junk is a runtime error
    match { text ~ /^\d+$/ => (text::to_number(), nil), _ => (nil, "Invalid integer format"), }
}

value, error = parse_int("123")
match error {
    nil => println("Parsed: ${value}"),   # Parsed: 123
    _ => println("Error: ${error}"),
}

bad, why = parse_int("12x")
println(why)  # Invalid integer format

Multiple Validation Results

import std:println

validate_form = |form| {
    errors = []
    warnings = []

    # Collect errors — get() avoids the "Key not found" error on absent keys
    email = form::get("email")
    phone = form::get("phone")

    match { email == nil => errors::push("Email required"), _ => nil, }
    match { email != nil && !(email ~ /@/) => errors::push("Invalid email"), _ => nil, }

    # Collect warnings
    match { phone == nil => warnings::push("Phone recommended"), _ => nil, }

    return errors, warnings
}

errors, warnings = validate_form({email: "test@example.com"})
println("Errors: ${errors::length()}")      # Errors: 0
println("Warnings: ${warnings::length()}")  # Warnings: 1

Complex State Returns

import std:println

process_transaction = |account, amount| {
    old_balance = account:balance
    new_balance = old_balance + amount

    status = match {
        new_balance < 0 => "overdrawn",
        new_balance < 100 => "low",
        _ => "ok",
    }

    return new_balance, old_balance, status
}

new_bal, old_bal, status = process_transaction({balance: 150}, -75)

println("Old: ${old_bal}, New: ${new_bal}, Status: ${status}")
# Old: 150, New: 75, Status: low

Option Pattern

Represent optional values:

import std:println

find_user = |id| {
    users = {
        1: {name: "Alice", age: 30},
        2: {name: "Bob", age: 25},
    }

    user = users::get(id)
    match user {
        nil => (nil, false),
        _ => (user, true),
    }
}

user, found = find_user(1)
match { found => println("Found: ${user:name}"), _ => println("User not found"), }
# Found: Alice

missing, was_found = find_user(99)
println(was_found)  # false

Suji has no Option type; a (value, found) pair is the idiom, and map::get(key) returns nil instead of raising when the key is absent.

Tuples of Structures

Tuple elements can be any value, including maps:

import std:println

get_user_with_address = || {
    person = {name: "Alice", age: 30}
    address = {city: "Boston", zip: "02101"}
    return person, address
}

user, address = get_user_with_address()
println("${user:name} lives in ${address:city}")  # Alice lives in Boston

Common Patterns

Success/Failure

import std:println

try_operation = |input| {
    success = input != nil

    match {
        success => (input::upper(), nil),
        _ => (nil, "no input given"),
    }
}

data, error = try_operation("payload")
println(data)  # PAYLOAD

nothing, problem = try_operation(nil)
println(problem)  # no input given

Before/After State

import std:println

update_counter = |current| {
    before = current
    after = current + 1
    return before, after
}

old, new = update_counter(5)
println("Changed from ${old} to ${new}")  # Changed from 5 to 6

Min/Max Pair

import std:println

get_range = |list| {
    match list::length() {
        0 => (nil, nil),
        _ => (list::min(), list::max()),
    }
}

lowest, highest = get_range([3, 1, 4, 1, 5, 9])
println("Min: ${lowest}, Max: ${highest}")  # Min: 1, Max: 9

Split Result

import std:println

partition_by_predicate = |list, pred| {
    matching = []
    non_matching = []

    loop through list with item {
        match pred(item) {
            true => { matching::push(item) },
            false => { non_matching::push(item) },
        }
    }

    return matching, non_matching
}

numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
evens, odds = partition_by_predicate(numbers, |x| x % 2 == 0)

println("Evens: ${evens}")  # [2, 4, 6, 8, 10]
println("Odds: ${odds}")    # [1, 3, 5, 7, 9]

Best Practices

DO:

• Use tuples for multiple related values
• Use (value, error) pattern for operations that can fail
• Destructure immediately when possible
• Use underscore for unwanted values
• Keep tuple size reasonable (2-4 elements)

DON’T:

• Return large tuples (use maps instead)
• Mix unrelated values in tuples
• Forget to check error values
• Overuse tuples when single value suffices
• Create deeply nested tuples

Tuples Are Not Indexable

Destructuring is the only cheap way into a tuple. t[0] is a type error, and there is no t::get(0) or t::first(); the fallback is to_list(), which copies:

import std:println

function_returning_tuple = || (1, 2)

# Preferred
a, b = function_returning_tuple()
println("${a} ${b}")  # 1 2

# Works, but allocates a list
values = function_returning_tuple()::to_list()
println(values[0])  # 1

# values = function_returning_tuple()
# values[0]
# => Type error: Cannot index tuple

Tuples also support length() and to_string().

Examples

HTTP Response Pattern

import std:println

fetch_data = |url| {
    # Simulated HTTP response
    status = 200
    data = {users: ["Alice", "Bob"]}

    return status, data, nil
}

status, data, error = fetch_data("https://api.example.com")

match status {
    200 => println("Success: ${data}"),
    _ => println("Error: ${error}"),
}
# Success: {users: [Alice, Bob]}

Database Query Result

import std:println

query_users = |conditions| {
    # Simulated query
    rows = [{id: 1, name: "Alice"}, {id: 2, name: "Bob"}]

    return rows, rows::length(), false
}

users, total, has_more = query_users({active: true})
println("Found ${total} users")  # Found 2 users

Parser Result

import std:println

parse_command = |input| {
    parts = input::split()

    match parts::length() {
        0 => (nil, nil, "Empty command"),
        1 => (parts[0], [], nil),
        _ => (parts[0], parts[1;], nil),
    }
}

cmd, args, error = parse_command("git commit -m message")
println(cmd)   # git
println(args)  # [commit, -m, message]

See Also

• Tuples
• Function Basics
• Error Handling
• Pattern Matching

Modules

Modules in Suji are values loaded from files and directories. Most modules are maps (key/value objects), and importing a module brings that exported value into scope.

Quick example

Two files in the same directory. math.si:

export {
    PI: 3.14159,
    add: |a, b| a + b,
}

main.si:

import std:println
import math

println(math:add(math:PI, 2))  # 5.14159

Run it with suji main.si.

Imports

Import a module (the value exported by a file or directory). The path is a bare identifier path, never a string — import "./my_module.si" is a parse error:

import my_module

Import a specific item from a module (colon-separated path):

import std:json
import std:json:parse

Alias an imported item:

import std:json:parse as parse_json

Notes:

• Imports are one per statement (no import a:b, c).
• Aliases apply to item imports (paths with at least one :); import my_module as m is a parse error.

Exports

Each .si file may contain exactly one export statement:

• Map export (module): export { key: expr, ... }
• Expression export (leaf): export <expr>

See:

• Imports
• Exports
• Module Resolution
• Standard Library Structure

Imports

Imports bring modules (and items inside module maps) into the current scope.

Syntax

import <name>
import <name>:<segment>:...:<item>
import <name>:<segment>:...:<item> as <alias>

Where each <name>/<segment>/<item>/<alias> is an identifier. Paths are never quoted: import "./math.si" and import "math" are parse errors.

Examples

Import a module value (the file math.si next to the importing file):

import math

Import a nested item:

import std:json:parse
import std:json:generate

Alias an imported item:

import std:json:parse as parse_json

The name that is bound is always the last segment of the path (or the alias), so import std:json:parse gives you parse, not json:parse.

Notes

• Imports are one per statement (write multiple import lines).
• There is no grouped import syntax like import std:json:parse, generate.
• An alias needs a path of two or more segments. import math as m is a parse error; write import lib:math as m, or import normally and rebind with m = math.
• Importing something that does not resolve is an error at import time, not at first use.

Exports

Exports define what a .si file provides to importers.

Rules

• Each file may contain exactly one export statement. A second one is a parse error: Multiple export statements found.
• A file with no export can still be run directly; it just has nothing to import.
• Exports are either:
  • Map export: export { name: expr, ... }
  • Expression export: export <expr>

Map export (module)

export {
    add: |a, b| a + b,
    PI: 3.14159,
}

This file exports a map. Importers can take the whole module (import util, then util:add(…)) or a single key (import util:add, then add(…)).

Expression export (leaf)

answer = 42
export answer

If this file is answer.si, then import answer binds the number 42 itself. Only map exports can be indexed with : or imported key by key.

Exporting computed modules

make = || {
    return {
        inc: |x| x + 1,
        double: |x| x * 2,
    }
}

export make()

The export expression is evaluated once, when the module is first imported, and the resulting value is cached for every later import.

See Also

• Imports
• Module Resolution

Module Resolution

This chapter describes how import paths are resolved in this repository.

Standard library (std)

std is a special, built-in module root. For example:

import std:println
import std:json

Files and directories

Non-std imports are resolved relative to the importing file’s directory. Path segments are identifiers separated by :, and the .si extension is always omitted: the file lib/util.si is imported as lib:util.

Importing a single segment: import one