diff --git a/docs/haku.dj b/docs/haku.dj new file mode 100644 index 0000000..aa93e43 --- /dev/null +++ b/docs/haku.dj @@ -0,0 +1,520 @@ +# 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. diff --git a/rkgk.toml b/rkgk.toml index 5cd488c..21bc332 100644 --- a/rkgk.toml +++ b/rkgk.toml @@ -23,6 +23,7 @@ import_roots = [ "docs/rkgk.dj" = "Introduction to rakugaki" "docs/system.dj" = "System library" +"docs/haku.dj" = "haku language reference" [wall_broker.default_wall_settings]