A first program

The project

One command will create a ready-to-build project (command names may change before launch):

ael init hello

ael init will create a folder named hello with three files at its root. It will never overwrite files that already exist.

hello/
  main.ael        # the program's entry point
  pack.ael        # the packages the project uses; none yet
  metadata.ael    # the project's name and settings

metadata.ael will record the name you gave:

metadata {
    schema = 1;
    name = "hello";
}

pack.ael will start with no packages. It will stay in the project even when it is empty:

pack {
    schema = 1;
    dependencies = [];
}

A project name will be an AEL identifier: letters, digits and _, not starting with a digit, not a keyword, and at most 64 characters.

The entry point

Every program will start in main.ael, which will declare exactly one main:

# main.ael
main main() {
    print("Hello from AEL");
}

A main without a result type will return nothing, and the program will exit successfully when main finishes. A comment will start with # and run to the end of the line.

A helper function

A function declared with fn will be a helper function. It will be private to the file that declares it and that file's extension files: no other file will be able to call it.

# main.ael
main main() {
    let price: i64 = 1200;
    let total: i64 = with_tax(price);
    print(total);
}

fn with_tax(amount: i64) -> i64 {
    return amount + amount / 5;
}

• let will bind a name to a value; here each binding writes its type after the name. A binding will not change unless it is declared with let mut.
• i64 will be a 64-bit signed integer. Integers will have fixed widths, and AEL will never convert between them silently.
• Arithmetic will be checked: if amount + amount / 5 overflowed, AEL will report the overflow, never silently ignore it.

To share a function between files, you will write it as a global or a reusable function in a file of its own. Project layout describes both.

Checking and running

From inside the hello folder, you will check and run the program:

ael check
ael run

ael check will check the whole project without running anything. Its diagnostics will point at the exact place in your source, and ael check --json will report them in a machine-readable form.

ael run will check, build and run the program in one step.

Building

To build the program without running it, choose a target:

ael build --target <target> -o build/hello

<target> names what the program will run on: an operating system and processor, or a microcontroller board. Planned targets lists the targets planned for Beta 0.0.1.

For a desktop or server target, the result will be a self-contained native executable, with no interpreter or virtual machine to run and nothing else to install on the machine that runs it. Building a program describes every build option.

Formatting

ael fmt will format every source file the same way, and ael fmt --check will list the files it would change without changing them:

ael fmt

Next

• A first agent adds a system prompt, a node and an agent.
• Project layout shows the files of a larger project.
• How it works describes the four steps from source to a running program.