Introduction

Welcome to The Halcyon Book, the official documentation for the Halcyon programming language. Halcyon is a compiled, strongly typed, functional programming language. It is compiled to WebAssembly, a portable binary format that can run in the browser.

Installation

IDE Setup

Visual Studio Code

TODO

Helix

In your Helix config folder (~/.config/helix/ by default), create languages.toml if it does not already exist. Add a grammar and language entry for Halcyon:

[[grammar]]
name = "halcyon"
source = { git = "https://git.lgatlin.dev/logan/tree-sitter-halcyon.git", rev = "main" }

[[language]]
name = "halcyon"
scope = "source.hc"
file-types = ["hc"]
grammar = "halcyon"
comment-tokens = ["--"]
block-comment-tokens = { start = "(*", end = "*)" }

Next, fetch and build the grammar. If this is your first time building grammars this will take several minutes.

helix -g fetch
helix -g build

Finally, download the highlight queries to your runtime directory:

mkdir -p ~/.config/helix/runtime/queries/halcyon
wget https://git.lgatlin.dev/logan/tree-sitter-halcyon/raw/branch/main/queries/highlights.scm \
  -O ~/.config/helix/runtime/queries/halcyon/highlights.scm

Hello World

Time to write your first Halcyon program. Create a file named main.hc containing the following:

<span class='hljs-keyword'>module</span> hello_world =
  <span class='hljs-keyword'>do</span> <span class='hljs-title class_'>std</span><span class='hljs-punctuation'>::</span><span class='hljs-title function_'>println</span> <span class='hljs-string'>"Hello World!"</span>
<span class='hljs-keyword'>end</span>

Langauge Reference

Here you will find a description of the major features of the Halcyon langauge.

Anatomy of a program

Lets examine a Halcyon program piece by piece. Here is a Fizz Buzz program:

<span class='hljs-keyword'>module</span> example =
  <span class='hljs-keyword'>let</span> fizzbuzz = <span class='hljs-keyword'>fn</span> <span class='hljs-params'>number</span> <span class='hljs-params'>max</span> <span class='hljs-keyword'>=&gt;</span>
    <span class='hljs-punctuation'>(</span><span class='hljs-keyword'>match</span> <span class='hljs-punctuation'>(</span>number <span class='hljs-operator'>%</span> <span class='hljs-variable constant_'>3</span><span class='hljs-punctuation'>,</span> number <span class='hljs-operator'>%</span> <span class='hljs-variable constant_'>5</span><span class='hljs-punctuation'>)</span> <span class='hljs-keyword'>with</span>
      | <span class='hljs-punctuation'>(</span><span class='hljs-variable constant_'>0</span><span class='hljs-punctuation'>,</span> <span class='hljs-variable constant_'>0</span><span class='hljs-punctuation'>)</span> <span class='hljs-keyword'>=&gt;</span> <span class='hljs-string'>"FizzBuzz"</span>
      | <span class='hljs-punctuation'>(</span><span class='hljs-variable constant_'>0</span><span class='hljs-punctuation'>,</span> _<span class='hljs-punctuation'>)</span> <span class='hljs-keyword'>=&gt;</span> <span class='hljs-string'>"Fizz"</span>
      | <span class='hljs-punctuation'>(</span>_<span class='hljs-punctuation'>,</span> <span class='hljs-variable constant_'>0</span><span class='hljs-punctuation'>)</span> <span class='hljs-keyword'>=&gt;</span> <span class='hljs-string'>"Buzz"</span>
      | <span class='hljs-punctuation'>(</span>_<span class='hljs-punctuation'>,</span> _<span class='hljs-punctuation'>)</span> <span class='hljs-keyword'>=&gt;</span> <span class='hljs-title class_'>format</span><span class='hljs-punctuation'>::</span><span class='hljs-title function_'>integer</span> number<span class='hljs-punctuation'>)</span>
	<span class='hljs-operator'>|&gt;</span> <span class='hljs-title class_'>std</span><span class='hljs-punctuation'>::</span><span class='hljs-title function_'>println</span><span class='hljs-punctuation'>;</span>
    <span class='hljs-keyword'>if</span> number <span class='hljs-operator'>&lt;</span> max <span class='hljs-keyword'>then</span>
      <span class='hljs-title function_'>fizzbuzz</span> <span class='hljs-punctuation'>(</span>number <span class='hljs-operator'>+</span> <span class='hljs-variable constant_'>1</span><span class='hljs-punctuation'>)</span> max
    <span class='hljs-keyword'>else</span>
      <span class='hljs-punctuation'>(</span><span class='hljs-punctuation'>)</span>

  <span class='hljs-keyword'>do</span> <span class='hljs-title function_'>fizzbuzz</span> <span class='hljs-variable constant_'>1</span> <span class='hljs-variable constant_'>30</span>
<span class='hljs-keyword'>end</span>

Modules

A Halcyon source file contains one or more modules.

<span class='hljs-keyword'>module</span> example =
<span class='hljs-comment'>(* ... *)</span>
<span class='hljs-keyword'>end</span>

Modules contain four kinds of statements:

let defines a variable
do executes an expression (like a main function)
type defines a new type, or type alias (described later)
import imports a function from another language, such as JavaScript or C

Note

Statements do not require whitespace or semicolons to separate them.

A module acts as a namespace. To access a value or type from another module, the :: symbol is used. For example, std::println refers to the println function in the std module.

Functions

Functions are a kind of expression. They are defined using the syntax fn [parameters] => [body]. Here, a function is defined with two parameters number and max.

<span class='hljs-keyword'>let</span> fizzbuzz = <span class='hljs-keyword'>fn</span> <span class='hljs-params'>number</span> <span class='hljs-params'>max</span> <span class='hljs-keyword'>=&gt;</span>

The body of a function is a single expression after the => operator. The functions return value is the value of this expression, there is no return keyword.

The syntax for function calls is significantly different from other languages. If the argument to a function is a literal (numbers, strings, booleans, arrays, structures, etc), no parenthesis are required.

<span class='hljs-keyword'>do</span> <span class='hljs-title class_'>std</span><span class='hljs-punctuation'>::</span><span class='hljs-title function_'>println</span> <span class='hljs-string'>"Hello World!"</span>

If an argument is an expression, it must be wrapped in parenthesis.

<span class='hljs-keyword'>do</span> <span class='hljs-title function_'>add_integers</span> <span class='hljs-punctuation'>(</span><span class='hljs-variable constant_'>5</span> <span class='hljs-operator'>-</span> <span class='hljs-variable constant_'>1</span><span class='hljs-punctuation'>)</span> <span class='hljs-variable constant_'>4</span>

An alternative way to call a function is with the |> operator. This operator calls a function on the right with an argument on the left.

<span class='hljs-keyword'>do</span> <span class='hljs-string'>"Hello World!"</span> <span class='hljs-operator'>|&gt;</span> <span class='hljs-title class_'>std</span><span class='hljs-punctuation'>::</span><span class='hljs-title function_'>println</span>

It is even possible to combine both syntax. The |> operator has a lower precedence than a regular function call, so the argument to the left of it will come last.

<span class='hljs-keyword'>do</span> <span class='hljs-string'>"World!"</span>
  <span class='hljs-operator'>|&gt;</span> <span class='hljs-title class_'>string</span><span class='hljs-punctuation'>::</span><span class='hljs-title function_'>concatenate</span> <span class='hljs-string'>"Hello "</span>
  <span class='hljs-comment'>(* Equivalent to:
   * string::concatenate "Hello " "World!" *)</span>
  <span class='hljs-operator'>|&gt;</span> <span class='hljs-title class_'>std</span><span class='hljs-punctuation'>::</span><span class='hljs-title function_'>println</span>
  <span class='hljs-comment'>(* Prints "Hello World!" *)</span>

Match expressions

The match expression is the most important control flow in Halcyon. It is similar to, but much more powerful than switch statements in other languages. A match expression consists of an expression to match on (the discriminant), and a list of cases. Here, the program is matching on the tuple (number % 3, number % 5):

<span class='hljs-punctuation'>(</span><span class='hljs-keyword'>match</span> <span class='hljs-punctuation'>(</span>number <span class='hljs-operator'>%</span> <span class='hljs-variable constant_'>3</span><span class='hljs-punctuation'>,</span> number <span class='hljs-operator'>%</span> <span class='hljs-variable constant_'>5</span><span class='hljs-punctuation'>)</span> <span class='hljs-keyword'>with</span>
      | <span class='hljs-punctuation'>(</span><span class='hljs-variable constant_'>0</span><span class='hljs-punctuation'>,</span> <span class='hljs-variable constant_'>0</span><span class='hljs-punctuation'>)</span> <span class='hljs-keyword'>=&gt;</span> "FizzBuzz"
      | <span class='hljs-punctuation'>(</span><span class='hljs-variable constant_'>0</span><span class='hljs-punctuation'>,</span> _<span class='hljs-punctuation'>)</span> <span class='hljs-keyword'>=&gt;</span> "Fizz"
      | <span class='hljs-punctuation'>(</span>_<span class='hljs-punctuation'>,</span> <span class='hljs-variable constant_'>0</span><span class='hljs-punctuation'>)</span> <span class='hljs-keyword'>=&gt;</span> "Buzz"
      | <span class='hljs-punctuation'>(</span>_<span class='hljs-punctuation'>,</span> _<span class='hljs-punctuation'>)</span> <span class='hljs-keyword'>=&gt;</span> format<span class='hljs-punctuation'>::</span>integer number<span class='hljs-punctuation'>)</span>

A match case has the syntax | [pattern] => [expression]. The discriminant is compared with each pattern in order. The entire expression evaluates to the case of the first pattern matched. For example, consider the case:

| <span class='hljs-punctuation'>(</span><span class='hljs-variable constant_'>0</span><span class='hljs-punctuation'>,</span> <span class='hljs-variable constant_'>0</span><span class='hljs-punctuation'>)</span> <span class='hljs-keyword'>=&gt;</span> "FizzBuzz"

The pattern (0, 0) is matched only when the discriminant is equal to (0, 0). However, this pattern:

| <span class='hljs-punctuation'>(</span><span class='hljs-variable constant_'>0</span><span class='hljs-punctuation'>,</span> _<span class='hljs-punctuation'>)</span> <span class='hljs-keyword'>=&gt;</span> "Fizz"

only requires the first value in the tuple to be 0. The _ symbol, or any identifier, is a 'wildcard' that matches anything.

This match expression evaluates to "FizzBuzz" if number is a multiple of 3, and 5, "Fizz" if number is only a multiple of 3, "Buzz" if number is only a multiple of 5, and format::integer number otherwise. This is string is then printed.

<span class='hljs-operator'>|&gt;</span> std<span class='hljs-punctuation'>::</span>println<span class='hljs-punctuation'>;</span>

Note

The ; symbol is an operator like in bash. Its purpose is to join together two expressions.

If expressions

The if expression works exactly the same as in other lanuguages, with the exception that the else clause is mandatory. This is because if is an expression, not a statement, and so it must evaluate to something in either case. Here, the program recursively calls fizz_buzz if number is less than max. Otherwise, the function returns () (similar to void or None in other languages).

if number <span class='hljs-operator'>&lt;</span> max <span class='hljs-keyword'>then</span>
      fizzbuzz <span class='hljs-punctuation'>(</span>number <span class='hljs-operator'>+</span> <span class='hljs-variable constant_'>1</span><span class='hljs-punctuation'>)</span> max
    <span class='hljs-keyword'>else</span>
      <span class='hljs-punctuation'>(</span><span class='hljs-punctuation'>)</span>

Comments

There are two kinds of comments, single line and block. A single line comments begin with two dashes --. Block comments begin with (* and end in *), and may be nested inside other block comments. It is conventional to begin every line of a block comment with *, but this is not required.

<span class='hljs-comment'>-- This is a line comment</span>
<span class='hljs-comment'>(*
 * This is a block comment,
 * it can span multiple lines<span class='hljs-comment'>
   (*
    * This is a nested block comment
   *)</span>
*)</span>

Non-features

Mutable variables

Every variable in Halcyon is constant. Once a variable is defined, it cannot be changed.

Loops

Halcyon does not have for or while loops. Instead, all looping is done through recursion. The compiler performs tail call optimization to convert recursive functions into simple loops. This means that your program will not overflow its stack no matter how deeply it recurses.

Warning

Tail call optimizization is only possible in certain circumstances. It is only done when the recursive call is the last operation performed in the function. The fizzbuzz example is tail recursive.

Exceptions and null

Halcyon does not have exceptions or null. Functions that may fail instead return an opt or result. These are covered more in-depth in their respective doc pages.

Operators Reference

The following is the full list of operators in Halcyon, in order of their precedence:

Symbol	Description
(unary) `-` `-.`	arithmetic negation
(unary) `not`	logical negation
`` `.`	multiplication
`/` `/.`	division
`%`	modulus
`+` `+.`	addition
`-` `-.`	subtraction
(function call)
`>>` `<<`	function composition
`xor`	logical XOR
`or`	logical OR
`\|>`	function pipe
`==` `!=` `<=` `>=` `<` `>`	comparison
`and`	logical AND
`;`

Warning

Currently, the comparison operators are only defined for primitive types. Comparing other data types will cause a crash.

Operators are regular functions that are defined in the std module. An operator's function can be accessed by surrounding it in parenthesis, like ( + ) 1 2 == 1 + 2

Warning

Always put whitespace around an operator when it is in parenthesis. (*) is parsed as the beginning of a comment, while ( * ) is the multiplication operator.

Integer and Real Operators

Because operators are functions, the operators for integers and reals are different.

Integers	Reals
`+`	`+.`
`-`	`-.`
`*`	`*.`
`/`	`/.`
`%`

The `;` Operator

The ; simply returns the value to the right. It is useful for chaining together function calls with side effects.

Halcyon type	C type
`()` or `unit`	`void`
`integer`	`int` or `long`
`real`	`double`
`boolean`	`bool`
`glyph`	`wchar_t`
`string`	`wchar_t[]`

Literal	Representation
`9_999`	Decimal number
`0b1111`	Binary number (prefixed with 0b)
`0o777`	Octal number (prefixed with 0o)
`0xFF`	Hexadecimal number (prefixed with 0x)

Escape Sequence	Name
\n	new line
\r	carriage return
\t	tab
\b	back space
\	backslash
\"	double quote
\'	single quote
\x7F	Byte character code (2 hex digits)
\w7FFF	Word character code (4 hex digits)

Function	Condition
assert_eq	Equal
assert_ne	Not Equal
assert_ge	Greater or Equal
assert_le	Less or Equal
assert_gt	Greater
assert_lt	Less

Keyboard shortcuts

The Halcyon Book