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()
{
	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()
{
	print(add(20, 22), "\n")
}

Output

42

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()
{
	var total := add(20, 22)
	print(total, "\n")
}

Output

42

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

Comments

Use // for a line comment:

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

Output

3

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.

These words are keywords: function, struct, type, var, return, if, else, try, while, for, break, continue, and none. Do not use them as names.

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.