A first program

This tutorial teaches heff by writing it. Each chapter builds on the one before; by the end you will have written a program with effects of its own and tested it.

Installing

heff is young and changes quickly, so install a release rather than building from source. Download the archive for your platform from the release and unpack it into ~/.heff/:

mkdir -p ~/.heff
tar xzf heff-0.4.0-macos-arm64.tar.gz -C ~/.heff --strip-components=1

Then put ~/.heff/bin on your PATH. heff builds native programs with zig, so install zig too.

A new project

heff init hello
cd hello

This makes a project with one module, one program, and one test:

File	What it is
package.hf	the package: its name and the heff it is for
src/hello/greeting.hf	a module, hello.greeting
app/hello/main.hf	a program
app/hello/build.hf	how that program is built
test/greeting.hf	a test

Running it

$ heff run app/hello/main.hf
Hello, world!

The module

Open src/hello/greeting.hf:

module hello.greeting

-- | a greeting, of `name`
-- | >>> greeting "heff"
-- | "Hello, heff!"
greeting : String -> String
greeting name = "Hello, " ^ name ^ "!"

The first line names the module. A definition is a type signature, greeting : String -> String, followed by its equations. ^ joins strings.

The -- | lines above it are its documentation, and they are also a test. The line after >>> is an expression, and the line after that is the value it should have. heff test checks it.

The program

Open app/hello/main.hf:

module app.hello.main

import co
import hello.greeting
import std.io

main : Co stdio Unit
main = do
  print (greeting "world")

import hello.greeting brings in the module above. A module’s name is its path under src/.

main’s type says what it does: it is a computation (Co stdio Unit) in the world of the standard streams (stdio), and nothing else, so it can print. Chapter 3 explains worlds, and computations that run in any world that has what they need.

Testing it

$ heff test
ok    src/hello/greeting.hf  1/1
  ok    greeting
ok    test/greeting.hf  0/0, tests 1/1
1/1 expectations hold, 1/1 tests hold, 2/2 files check as they should

heff test checks the doc tests in src/, and runs the tests in test/. Chapter 6 covers tests in full.