Standard library

Primitive types

String, methods

List<T>

Mutable homogeneous list. Construct with the literal [a, b, c] or by push on a let/var. Cross-statement inference: let xs = [] infers the type from the first push.

Index access: xs[i] (no bounds checking; use get(i) for safe access).

Range expressions

a..b (exclusive of b) and a..=b (inclusive) produce a List<Int> materialised from the half-open / closed integer range. Both endpoints must be Int. Float endpoints are deliberately excluded.

for i in 0..10            // 0, 1, 2, ..., 9
    stdio.println("${i}")

for i in 1..=5            // 1, 2, 3, 4, 5
    stdio.println("${i}")

let n = 4
let xs = (n - 1)..(n * 2) // 3..8, arithmetic endpoints

let evens = (0..10).filter(fun (x: Int) -> Bool => x % 2 == 0)
                              // ranges support the full List API

Range precedence sits between addition and comparison, so 1+2..5+3 parses as (1+2)..(5+3) and a..b == c..d as (a..b) == (c..d). Range itself is non-associative; a..b..c is a syntax error.

Map<K, V>

Hash map. Construct via new_map() with a required type annotation.

let m: Map<String, Int> = new_map()
m.set("a", 1)
match m.get("a")
    Some(n) -> stdio.println("a = ${n}")
    None -> stdio.println("not found")

Set<T>

Set of unique elements. Construct via new_set() with a type annotation.

Option<T>

Built-in sum type:

type Option<T> =
    Some(T)
    None

Result<T, E>

Built-in sum type for error handling:

type Result<T, E> =
    Ok(T)
    Err(E)

The ? operator automatically propagates Err in functions that return Result:

fun read_and_process(fs: Fs) -> Result<Int, IoError>
    let content = fs.read("x.txt")?  // if Err, returns immediately
    return Ok(content.length())

JsonValue

Built-in sum type for JSON representation:

type JsonValue =
    JNull
    JBool(Bool)
    JNum(Float)
    JStr(String)
    JArr(List<JsonValue>)
    JObj(Map<String, JsonValue>)

Extraction methods

Top-level functions

Built-in conversion functions

Capa has no implicit numeric coercion: Float + Int is a type error. Use to_float / to_int at the call site to make the conversion explicit:

fun avg(sum: Float, count: Int) -> Float
    return sum / to_float(count)

Python interoperability

The two functions below cross the Capa/Python trust boundary. Both require the Unsafe capability as the first argument.

fun square_root(unsafe: Unsafe, x: Float) -> Float
    let math = py_import(unsafe, "math")
    return py_invoke(unsafe, math.sqrt, [x])

Crossing this boundary loses Capa's static guarantees: the Python value can do anything its type allows, with full ambient authority. The --manifest output marks functions with an Unsafe parameter via has_unsafe: true, so audit tooling can flag them for separate review.

Capabilities

Stdio

Fs

Env

Clock

Random

Net

A Net received from main is unrestricted; restrictions accumulate through restrict_to. The result of restrict_to is a fresh capability instance and is bindable in a let/var; Capa relaxes the "no capabilities in locals" rule specifically for method-call results (which are necessarily fresh, not aliases of an existing capability).

fun fetch(net: Net) -> Result<String, IoError>
    return net.get("https://api.example.com/users")

fun main(net: Net, stdio: Stdio)
    let api = net.restrict_to("api.example.com")
    match fetch(api)
        Ok(body) -> stdio.println(body)
        Err(e)   -> stdio.eprintln("${e}")

See examples/net_attenuation.capa for a fuller demonstration, including the monotonic-narrowing property (chaining two disjoint restrictions yields a Net that allows nothing).

Unsafe

Marker capability for crossing the Python boundary. Has no methods, its only role is to gate py_import and py_invoke (see the Python interoperability section above).

User-defined capabilities

Libraries can declare their own capabilities with the capability keyword. The declaration registers the name in the capability discipline; any type that implements the capability becomes a valid implementor.

capability SendEmail
    fun send(self, to: String, subject: String, body: String) -> Result<Unit, IoError>

type SmtpMailer {
    server: String,
    net: Net          // built-in cap as a field, allowed because
                      // SmtpMailer implements a user-defined cap
}

impl SendEmail for SmtpMailer
    fun send(self, to: String, subject: String, body: String) -> Result<Unit, IoError>
        // delegate to self.net under the hood
        return Ok(())

// Factory that consumes the underlying built-in cap and produces the
// higher-level capability. Allowed return type even though SmtpMailer
// carries authority.
fun make_smtp_mailer(net: Net, server: String) -> SmtpMailer
    return SmtpMailer { server: server, net: net.restrict_to(server) }

// Caller side: receive the capability by parameter (subtyping accepts
// SmtpMailer where SendEmail is expected because of the impl).
fun send_welcome(mailer: SendEmail, to: String) -> Result<Unit, IoError>
    return mailer.send(to, "Welcome", "Hello!")

The discipline still applies: a let dup = mailer (plain identifier alias of a cap-bearing value) is rejected; only call/method-call right-hand sides produce fresh capability instances that can be bound. See examples/user_capabilities.capa for a complete example.

The IoError type

Opaque type representing I/O errors. Available as a type parameter in Result<T, IoError> and in pattern matching:

match fs.read("x.txt")
    Ok(content) -> stdio.println(content)
    Err(e) -> stdio.eprintln("error: ${e}")

IoError's string representation is human-readable, but its internal contents are private.