# haku reference manual haku is a dynamically typed, pure functional programming language, used for programming brushes in rakugaki. For the layperson, it can be thought of a beefed up calculator. It has roots in ordinary school algebra, but has a much more powerful set of features, with the special ability of being able to edit images. ## Overview haku programs are called _brushes_. The purpose of a brush is to produce instructions for rakugaki on how the user may interact with the wall (via _reticles_), and what things should be drawn on the wall as a result of those interactions (via _scribbles_). Collectively, reticles and scribbles are what we call _effects_. A brush's task is to compute (or in simpler terms, calculate) an effect that rakugaki will then _perform_. In case of reticles, rakugaki will allow the user to interact with the wall, and then ask haku for another effect to perform afterwards (a _continuation_). In case of scribbles, rakugaki will draw the scribble onto the wall, without asking haku for more. Once rakugaki runs through all effects, we say that the brush has _finished executing_. ## Lexical elements ### Comments haku's most basic lexical element is the _comment_. ``` -- This is a comment. -- こんにちは！ ``` Comments introduce human-readable remarks into a brush's code. Their only purpose is documentation. They serve no semantic meaning, and thus do not affect the result of the brush whatsoever. Comments begin with `--`, and span until the end of the current line of text. Once the line ends, the comment does, too. Comments do not necessarily have to appear at the beginning of a line. ```haku magnitude: \v -> -- calculate the magnitude of a vector hypot vecX.v vecY.v ``` ### Literals Literals represent _literal values_ that are input into the brush. haku has a few types of literals, but not all literals are purely lexical elements (some of them can nest)---which is why the different types of literals are covered under the [Expressions](#Expressions) section. ### Identifiers Identifiers are used for naming values inside a brush. New names are introduced using [defs](#Structure-of-a-brush) and [lets](#Let-expression). Once a name is introduced, it may be referenced using its identifier in its corresponding scope---the whole brush for defs, and the following expression in lets. An identifier starts with a *lowercase* ASCII letter---`a`--`z` or an underscore---`_`, and is followed by zero or more ASCII letters of any case---`a`--`z`, `A`--`Z`, digits---`0`--`9`, and underscores---`_`. This then may be followed by an arbitrary number of _suffix characters_ prime symbols---`'` and question marks---`?`. By convention, prime symbols are used in the same way they are used in math notation---for introducing a distinct variable of the same name as another variable, usually derived from the previous. For example, given a variable named `position`, an _updated_ position may be named `position'`. The question mark suffix is conventionally used for [boolean](#Boolean-type) variables, as well as boolean-returning functions. By convention, only one question mark is always used. Identifiers starting with *uppercase* ASCII letters---`A`--`Z` are not identifiers, but rather [tags](#tag-literal), and therefore cannot be used as def and let names. The following identifiers are reserved as _keywords_, and have special meaning assigned within the language syntax. - `if` --- Introduces an [`if` expression](#if-expression). - `else` --- Introduces the `else` clause in an [`if` expression](#if-expression). Additionally, the following identifiers are reserved for future use, and may not be used for naming defs and lets. - `and` - `or` By convention, a prime symbol `'` suffix can be used to work around this restriction. For example, instead of naming a variable `if`, try naming it `if'` (read as _if prime_, "_the other if_"). ### Operators and punctuation Operators and punctuation share a section in this part of the reference due to their lexical similarity. [Operators](#operators) serve as a terse syntax for calling a small set of built-in functions within the program (described in detail in the [system reference documentation](system.html)), while punctuation serves the purpose of syntactic delimiters. The following symbols are operators: ``` + - * / == != < <= > >= ! ``` And the following symbols are punctuation: ``` ( ) [ ] , = : . | \ -> ``` `` is literally written down as a line break in programs, which would be invisible in this reference. ## Structure of a brush A brush is structured like so: ```haku def1: expr1 def2: expr2 def3: expr3 -- ... effectExpr ``` That is, there are two parts to a brush: its _defs_, followed by the resulting effect [expression](#Expressions). The effect produced by this expression is the effect performed by rakugaki when the user interacts with the wall (clicks on it, touches it, starts a pen stroke). Defs introduce names for values that are available across the entire program. They are most commonly used to name constants and functions. Example: ```haku -- Constant definition pi: 3.14159265 -- Function definition magnitude: \v -> hypot vecX.v vecY.v ``` ## Expressions haku is a strictly expression-oriented language. There is no idea of statements, as would be the case in lower-level languages like C++ or JavaScript. This comes from the fact that haku is a _pure_ functional language, which means there aren't any expressions whose result you would want to discard, only for their side effects. ### Nil An empty parenthesis represents a _nil_ value---that is, literally a value that means "no value." ```haku () ``` It is one of the only values considered [_false_](#Truth) by the language, other than the [`False` boolean](#Tags). ### Numbers Numbers in haku are written down as a sequence of ASCII digits---`0`--`9`, followed by an optional decimal point `.` with a decimal part. ```haku 0 123 3.14159265 ``` Internally, they are represented by 32-bit floating point numbers. This means that they have [fairly limited precision](https://float.exposed/0x42f60000), and do not always behave exactly like math on real numbers. For example, there are magical values for ∞ and -∞ (which _can_ exist and can be operated upon), as well as a value called NaN (not a number), which are produced as results of certain operations that aren't well-defined in math (most commonly division by zero). ### Tags Tags are similar to [identifiers](#Identifiers), but start with an *uppercase* rather than a lowercase ASCII letter (that is, `A`--`Z`). They are values which represent _names_. This concept may feel a bit alien. As an example, consider how haku implements record types. From the perspective of the user, a record type acts like a [function](#Functions) which accepts a tag as an argument---with the tag being the name of the record field. ```haku withDotter \d -> stroke 8 #000 (line d.From d.To) ---- -- these are tags ``` There are also two special tags, `True` and `False`, which are used to represent Boolean logic. The boolean `False` is the only [_false_](#Truth) value in the language, other than [nil](#Nil). ### Colors haku has a literal for representing RGBA colors. It takes one of the following four forms, from most explicit to least explicit: ```haku #RRGGBBAA #RRGGBB #RGBA #RGB ``` Each character in a color literal is a hexadecimal digit, with the digits `0`--`9` representing digits 0 to 9, and letters `a`--`f` representing digits 10 to 16 (case insensitive.) For `#RGB` and `#RGBA`, the digits are repeated twice implicitly---that is, `#1234` is the same as `#11223344`. This syntax is designed to be convenient for working with colors coming from external programs. For example, you may pick a color from an online palette, and paste its hex code straight into your brush code. Example (rakugaki logo colors): ```haku white: #FFF peach: #FFA6A6 raspberry: #F44096 ``` ### Lists Lists are fixed-length sequences of values. They are written down by listing out a sequence of comma `,` or newline-separated items, enclosed in square brackets `[]`. ```haku six: [1, 2, 3, 4, 5, 6] four: [ 1 2 3 4 ] ``` Lists are allowed to nest, as the values may be of any type---including lists themselves. Lists are most commonly used to compose scribbles. A list is also a scribble, which draws the scribbles it contains within itself, from first to last. ### Operators Operators in haku are used mostly for basic mathematical operations. They are either unary, written in prefix form `!x`, or binary, written in infix form `a + b`. While order of operations in case of unary operators is unambiguous (innermost to outermost), infix operators are not as simple. Certain infix operators have _precedence_ over others. This precedence depends on the operator used, as well as the spacing around it. Spacing _only_ matters for infix operators; prefix operators may have any amount of spaces around them, though conventionally they are glued to the expression on the right, like `(-1)`, or `vec -1 0`. Infix operators with spaces around them are classified as _loose_, and those without spaces around them are _tight_. An unequal amount of spaces around an infix operator is considered an error (or is parsed as a prefix operator, depending on context). Based on these two groups, the precedence of operators is defined as follows: 1. Prefix operators: `-a`, `!a` 1. Tight 1. Dot: `a.b` 1. Arithmetic: `a+b`, `a-b`, `a*b`, `a/b` 1. Comparisons: `a==b`, `a!=b`, `ab`, `a>=b` 1. Function calls: `a b` 1. Loose 1. Dot: `a . b` 1. Arithmetic: `a + b`, `a - b`, `a * b`, `a / b`, `a |b` 1. Comparisons: `a == b`, `a != b` 1. Variables: `a: b`, `a = b` The operators `+`, `-`, `*`, `/`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `!`, are used for calling functions built into the haku [system library](system.html). Other infix tokens listed above have other semantic meaning. - `a b`, `.`, and `|` --- Used for calling [functions](#Functions). - `:` --- Used for introducing [defs](#Structure-of-a-brush). - `=` --- Used for introducing [lets](#Let-expression). Examples of how these precedence rules work in practice: ```haku 2 + 2 * 2 == 8 -- left to right 2 + 2*2 == 6 -- 2*2 goes first 2+2 * 2 == 8 -- 2+2 goes first 2+2*2 == 8 -- left to right sin 2 * pi * x == (sin 2) * pi * x -- function call goes first sin 2*pi*x == sin (2 * pi * x) -- argument goes first -- unintuitive for users of C-likes: -- prefix `-` has higher precedence than `.` -vecX.v == (-vecX).v ``` One thing that should be noted about haku's operator precedence is that, unlike math notation and most other programming languages, `+`, `-`, `*`, and `/`, are evaluated from left to right. This is because otherwise they would interact unintuitively with the pipe `|` operator, which is effectively used as an operator that turns any function infix. It is not obvious where `|` would sit in the precedence hierarchy if arithmetic was split into separate precedence levels for `+` and `-`, and `*` and `/`, whereas with haku's solution, all arithmetic expressions are simply read from left to right. ### Parentheses In case the tight-loose system is not expressive enough, parentheses can be used as an escape hatch for grouping expressions. ```haku 2 + (2 * 2) == 2 + 2*2 ``` ### Functions Functions in haku follow the definition of mathematical functions: given a set of _arguments_, the arguments are substituted into the function's _parameter variables_, and a result is computed from the resulting expression. A function literal is written down like `\params -> result`, where `params` is a comma-separated list of parameters, and `result` is the function's resulting expression. ```haku square: \x -> x * x ``` A newline is permitted after the arrow `->`, which should be preferred for most functions. ```haku magnitude: \v -> hypot vecX.v vecY.v normalize: \v -> l = magnitude v v / vec l l ``` Note that there must be at least one parameter. In case you need a function with no parameters, you almost always want a constant value instead. Functions can be used by _calling_ them with space-separated arguments. Note that space-separated function calls have higher precedence than most arithmetic operators, which means you have to use parentheses or tighten the expression to pass more complicated expressions. ```haku normalize (vec 4 4) ``` Note that a call must pass in _exactly_ the amount of arguments defined by the function. Calling the above-defined `normalize` with more than one argument will not work: ```haku normalize (vec 4 4) (vec 5 5) ``` In places where a call with space-separated arguments is inconvenient, there are two alternative syntaxes for calling a function. The first is by using the `.` operator, which, when used tightly, can be used to do a function call with higher operator precedence than an ordinary space-separated call would have. ```haku f x == f.x ``` Combined with [records](#Records) and [tags](#Tags), it mimics the record field access syntax found in C-like programming languages. ```haku withDotter \d -> stroke 8 #000 (line d.From d.To) ------ ---- ``` The other alternative syntax is the _pipe_ `|` operator. It calls the function on the right with the argument on the left. ```haku 2 |sqrt ``` When a space-separated function call is found on the right, the `|` operator instead inserts the value from the left as the first argument of the function call. ```haku x |mod 2 == mod x 2 ``` The spacing convention around `|` is a bit unusual, but the above example demonstrates why: the `|` operator effectively turns an arbitrary function into an infix operator on par with built-in arithmetic operators. Therefore, the function name is glued to the pipe, like `|mod`, to appear as one word visually. Certain functions are _built-in_, and implement core functionality that cannot be implemented in haku alone (at all, or in a performant manner). The [haku system library](system.html) is what defines all the built-in functions. Due to temporary limitations of the implementation, built-in functions cannot be referenced like regular functions. They always have to appear in a call. If you'd like to reference a built-in function to e.g. pass it to a list-transforming function, you will have to wrap it in a function of your own: ```haku add: \x, y -> x + y sum: [1, 2, 3] |reduce 0 sum sin': \x -> sin x sines: [0, pi*1/2, pi*2/2, pi*3/2] |map sin' ``` ### `if` expressions `if` expressions allow for choosing between two different results based on a condition. ```haku if (cond) a else b ``` When `cond` is [_true_](#Truth), `a` will be computed and returned as the result. Otherwise, `b` will be computed and returned as the result. Note that in both cases, only one of the two expressions is computed. This allows for implementing bounded recursion to achieve repetition. ```haku -- Fibonacci sequence fib: \x -> if (x > 1) fib n-1 + fib n-2 else x ``` ### Let expressions Let expressions introduce a new _variable_, or _let_, that can be referenced in the expression on the next line. ```haku x = y expr ``` The difference between lets and [defs](#Structure-of-a-brush) is that the value of a let can change, because it can depend on non-def values, such as function arguments (therefore making it _variable_.) This however means that lets have reduced _scope_. The name introduced by a def can be used in the entire program---even before the line it's introduced on---while the name introduced by a let can only be used in the expression that immediately follows the let. ```haku x: 1 f: \y -> z = x + 1 x + y + z -- ok z -- not ok ``` This also means that lets cannot be used to create recursive functions, because the name introduced by a let only becomes visible in its following expression. ```haku -- This is okay: defib: \x -> if (x > 1) defib n-1 + defib n-2 else x -- This will not work: letfib = \x -> if (x > 1) -- Because letfib is not yet defined at this point. letfib n-1 + letfib n-2 else x defib 5 + letfib 5 -- It is only defined in this expression. ``` Since a let can be followed up by any other expression, multiple lets can be chained together. ``` x = 4 y = x + 3 x + y ``` Note however that `x + y` finishes the chain of lets, which means we cannot introduce additional ones after that line. That would begin another expression! ## Types haku distinguishes values between a few different types. - [*nil*](#Nil) - [*tag*](#Tags) - [*boolean*]{id="Boolean-type"} - either [`False` or `True`](#Tags). Indicates truth or falsehood, used in [`if` conditions](#if-expression). - [*number*](#Numbers) - *vec* - a 4-dimensional vector, composed of four `number`s. - [*rgba*](#Colors) - an RGBA color, composed of four `number`s. This is the type of color literals. - [*function*](#Functions) - [*list*](#Lists) - *shape* - a mathematical shape. - _*effect*_ - an action that can be performed by rakugaki. - *scribble* - something that can be drawn on the wall. - *reticle* - an interaction the user can make with the wall. These types are incompatible with each other. If you pass in a *tag* to a value that expects a *number*, you will get an error. You can refer to the [system library documentation](system.html) for more information on the types accepted by functions. Note that it has a more precise notation for describing types, which explicitly documents the types of values that will be found in more nuanced situations, such as the `map` function. ### Truth Conditions in `if` expressions, as well as the `!` operator, consider certain types of values _truthy_, and others _falsy_. Falsy values include *nil* and the boolean `False`. All other values are considered truthy.