:title
2. Basic syntax

:content
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

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

:output
Hello, Capy!

:content
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:

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

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

:content

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.

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

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

:content

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

## Comments

Use `//` for a line comment:

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

:content

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.

:see-group
guides

:see
capy-03-values-and-types
capy-04-expressions-and-control-flow
handler/render
handler/component
