Capy-Bearer Documentation

A Capy file contains declarations. Functions, handlers, structs, and type aliases are declarations. Code that performs work belongs inside a function or handler.

A complete source file

// A comment continues to the end of the line.
function RENDER(request : dval) {
    var greeting := "Hello"
    print(greeting, ", Capy!\n")
}

Output

Hello, Capy!

This file has one comment and one handler. Names are case-sensitive, so greeting and Greeting are different names.

Functions

A function declaration has a name, parameters, a result type, and a body:

function add(left : s32, right : s32) s32 {
    -> left + right
}

function RENDER(request : dval) {
    print(add(20, 22), "\n")
}

The -> expression supplies the function result. A function that returns no value has the result type void. Handler declarations omit a result type because handlers write a response instead of returning one.

Statements and expressions

Whitespace separates tokens but does not end an expression. Commas separate arguments and collection items. Most lines do not need a semicolon.

function add(left : s32, right : s32) s32 {
    -> left + right
}

function RENDER(request : dval) {
    var total := add(
        20,
        22
    )
    print(total, "\n")
}

A block starts with { and ends with }. Its expressions run from top to bottom.

Comments

Use // for a line comment:

function RENDER(request : dval) {
    // Explain why the next operation is necessary.
    var retries := 3
    print(retries, "\n")
}

Comments do not change the program. Prefer names that make routine code clear without a comment.

Reserved names

Application code cannot declare host functions. Names that start with __bearer_ are reserved for the standard library. Later chapters introduce the handler names that Bearer calls.

Keep the unit shape simple

Put helper functions near the handler that uses them. Move a helper only when several units share it. This keeps the request flow easy to read.

Use one top-level entry point for each route. Add named handlers only when the route needs separate component, WebSocket, task, or export entry points.

A source file can declare types, structs, functions, and handlers in any order. Prefer the order that helps the next reader: data shapes first, helpers next, and handlers last.

Read syntax errors locally

The compiler reports the source path, line, and column. Look at that location first. If a block misses -> expression, the error points at the value-producing block.

Do not use a newline to end an expression. Newlines are whitespace in normal code. Use braces and explicit block yields to show where a value comes from.