# System library haku comes with a set of built-in functions, called the _system library._ This is a reference for these functions. ## Preamble: how to read this reference Each function comes with a _signature description_. These descriptions read like this: ```haku stroke thickness : number color : rgba position : vec -> scribble ``` The first element is always the function's name - in this case `stroke`. Following this are `argumentName : argumentType` pairs, which describe the arguments that need to be passed to the function. The last element is always the type of data this function produces. Function names which are made up of symbols instead of letters are _operators_. Operators may have one or two arguments, where one argument corresponds to a prefix form `-x`, and two arguments correspond to an infix form `x - y`. Note that this documentation lists a unary and binary operator of the same spelling as _two separate functions_, not overloads of a single function. The argument name usually does not matter when calling the function - it is only used for documentation purposes. The one exception is arguments called `...`, which signify that zero or more arguments can be passed to the function at that position. (Currently there are no functions that accept any number of arguments, though.) The argument _type_ however is important. If you try to use a function with the wrong type of value as its argument, it will fail with an error. For example, consider a brush where we pass a number as `stroke`'s `color` and `position` arguments. ```haku stroke 1 1 1 ``` This brush will fail to render, since `stroke` expects an `rgba` as its 2nd argument. With that said, there are several types of values in haku that can be passed into, and returned by functions. - `_` - special type used to signify that any value may be passed into the function. - `()` - also known as _nil_, means _no value._ - `boolean` - either `False` or `True`. Indicates truth or falsehood, used in `if` conditions. - `number` - a real number, with 32 bits of precision. - `vec` - a 4-dimensional vector, composed of four `number`s. - `rgba` - an RGBA color, composed of four `number`s. - `\a -> r` - a function taking in the parameter `a` and returning `r`, as returned by `\x -> x` literals. - `list t` - a list of values, where each value is of the type `t`. - `shape` - a mathematical shape. - `shapeLike` - anything that can be turned into a `shape` using `toShape`. - `scribble` - something that can be drawn on the wall. Additionally, the syntax `a | b` may be used to signify that one of the listed types is accepted or returned. ## Math ```haku - a : number -> number ``` `-`, when used in its unary form `-x`, returns the number `x` with the opposite sign. ```haku + a : number b : number -> number ``` `+` adds two numbers together. ```haku - a : number b : number -> number ``` `-`, when used in its binary form `x - y`, subtracts two numbers from one another. ```haku * a : number b : number -> number ``` `*` multiplies two numbers together. ```haku / a : number b : number -> number ``` `/` divides a number by another number. ```haku floor x : number -> number ceil x : number -> number round x : number -> number ``` `floor`, `ceil`, and `round` are rounding functions. Each of them rounds a little differently: - `floor` rounds towards -∞. - `ceil` rounds towards +∞. - `round` rounds half towards +∞. ```haku abs x : number -> number ``` `abs` returns the absolute value of the given number. If `x` is less than zero, returns `-x`. Otherwise returns `x`. ```haku mod x : number y : number -> number ``` `mod` is the modulo operation. It returns the remainder of dividing `x` by `y`. haku uses the Euclidean definition, which means the remainder returned by `mod` is _always non-negative_. ```haku pow base : number exponent : number -> number ``` `pow` raises `base` to the given `exponent`. ```haku sqrt x : number -> number cbrt x : nunber -> number ``` `sqrt` returns the square root of the given number. `cbrt` returns the cubic root of the given number. Other roots may be obtained using `pow x (1 / base)`. ```haku exp x : number -> number ln x : number -> number ``` In the following functions, `e` is the base of the natural logarithm (approximately `2.7128`.) The `e` constant (Euler's number) is currently not exposed to haku source code; you have to define it yourself. `exp` is the exponential function `pow e x`. `ln` is the natural logarithm (logarithm base `e` of `x`.) ```haku expMinus1 x : number -> number ln1Plus x : number -> number ``` `expMinus1` is `pow e x - 1`, but accurate even when `x` is close to zero. `ln1Plus` is `ln (1 + x)`, but more accurate than if the operations are performed separately. ```haku exp2 x : number -> number ``` `exp2` is the exponential function `pow 2 x`. ```haku log2 x : number -> number log10 x : number -> number ``` `log2` is the logarithm base `2` of `x`. `log10` is the logarithm base `10` of `x`. ```haku hypot x : number y : number -> number ``` `hypot` is the hypotenuse of the Pythagorean triangle with right angle-adjacent sides `x` and `y`. ```haku sin x : number -> number cos x : number -> number tan x : number -> number ``` `sin`, `cos`, and `tan` are the [trigonometric functions][] sine, cosine, and tangent. Their argument `x` is counted in radians. [trigonometric functions]: https://wikipedia.org/Trigonometric_functions ```haku asin x : number -> number acos x : number -> number atan x : number -> number ``` `asin`, `acos`, and `atan` are the [inverse trigonometric functions][] arc sine, arc cosine, and arc tangent. Their argument `x` is counted in radians. [inverse trigonometric functions]: https://wikipedia.org/Inverse_trigonometric_functions ```haku atan2 y : number x : number -> number ``` `atan2` is the angle between the positive X axis and a line that passes through `(0, 0)` and `(x, y)`. Note the reverse argument order---`y` comes first, due to `atan2` being a convenience function over `atan (y / x)` that is defined for all arguments. ```haku sinh x : number -> number cosh x : number -> number tanh x : number -> number asinh x : number -> number acosh x : number -> number atanh x : number -> number ``` `sinh`, `cosh`, `tanh`, `asinh`, `acosh`, and `atanh`, are the six [hyperbolic functions][]. [hyperbolic functions]: https://en.wikipedia.org/wiki/Hyperbolic_functions ## Logic The following functions are used to compare values and work with `boolean`s. ```haku ! a : _ -> boolean ``` If `b` is `()` or `False`, `not` returns `true`. Otherwise it returns `False`. ```haku == a : _ b : _ -> boolean != a : _ b : _ -> boolean ``` `==` returns `True` if `a` and `b` are equal. Whether two values are considered equal depends on their type: - If the type of the two values differs, `False` is returned. - If the two values are `number`s: - If any of the values are `NaN`, `False` is returned. - Otherwise `True` is returned if the two numbers have the exact same bit representation. - If the two values are `vec`s, `True` is returned if each of their `number` components is equal to each other using the rules above. - Likewise with `rgba`s. - All other types of values use _reference_ equality - `True` is returned only if `a` and `b` are located in the same place in memory. This more or less means that the values are considered equal if they are produced by the same call to a system function, in time. `!=` returns `!(a == b)`. ```haku < a : _ b : _ -> boolean <= a : _ b : _ -> boolean > a : _ b : _ -> boolean >= a : _ b : _ -> boolean ``` `<` returns `True` if `a` is less than `b`, and `<=` returns `True` if `a` is less than _or_ equal to `b`. Order is only well-defined for numbers. Other types may assume an arbitrary but consistent ordering - `()` may be less than `True`, or it may not be less than `True`, but this will not change between executions of the program. `a > b` is the same as `b < a`. `a >= b` is the same as `b <= a`. --- Note that `and` and `or` are currently missing from this list, but are reserved keywords. You can implement them using regular functions as a replacement. ```haku boolAnd = \a, b -> if (a) if (b) True else False else False boolOr = \a, b -> if (a) True else if (b) True else False ``` ## Vectors ```haku vec x : number -> vec vec x : number y : number -> vec vec x : number y : number z : number -> vec vec x : number y : number z : number w : number -> vec ``` Creates a new `vec` from one to four number values. A `vec` always has four dimensions. If any of the arguments are omitted, its corresponding dimension is initialized to zero. ```haku vecX v : vec -> number vecY v : vec -> number vecZ v : vec -> number vecW v : vec -> number ``` `vecX`, `vecY`, `vecZ`, and `vecW` extract the individual components of a `vec`. --- Note that mathematical operations are currently not defined for vectors. You may define your own vector operations like so: ```haku -- Vector addition addv = \a, b -> vec (vecX a + vecX b) (vecY a + vecY b) (vecZ a + vecZ b) (vecW a + vecW b) -- Likewise for subtraction, multiplication, and division. ``` Note that haku-defined vector operations like these are more costly the more components they operate on. Therefore, it's recommended to only define them for two dimensions, unless you really need more. ```haku addv2 = \a, b -> vec (vecX a + vecX b) (vecY a + vecY b) ``` ## Colors ```haku rgba r : number g : number b : number a : number -> rgba ``` Creates a new `rgba` with the given color channels. Note that unlike `vec`, all color channels have to be provided to form an `rgba`. ```haku rgbaR color : rgba -> number rgbaG color : rgba -> number rgbaB color : rgba -> number rgbaA color : rgba -> number ``` `rgbaR`, `rgbaG`, `rgbaB`, `rgbaA` extract color channels out of an `rgba`. --- haku uses RGBA values in a normalized `0` to `1` range rather than `0` to `255`, which may be unfamiliar if you're coming from other image editing software. This is because it's easier to do math on normalized colors. For example, consider multiplicatively blending two colors. ```haku -- This is how you can multiply two colors together. mulRgba = \a, b -> rgba (rgbaR a * rgbaR b) (rgbaG a * rgbaG b) (rgbaB a * rgbaB b) (rgbaA a * rgbaA b) ``` If haku represented colors using an 8-bit `0` to `255` range instead, to multiply two colors together, you would have to divide them by `255` to get them back into the correct range. ```haku -- NOTE: This example does NOT work correctly. mulRgba = \a, b -> let red = (rgbaR a * rgbaR b) / 255 let green = (rgbaG a * rgbaG b) / 255 let blue = (rgbaB a * rgbaB b) / 255 let alpha = (rgbaA a * rgbaA b) / 255 rgba red green blue alpha ``` Note that haku does not clamp colors to the `0` to `1` range. It is perfectly valid to have a color that is out of range or even `NaN`, but when drawing scribbles: - `∞` is clamped back to `1`. - `-∞` is clamped back to `0`. - any scribble with a `NaN` color is ignored. Note that just like vectors, arithmetic operations on colors are currently not defined. Before scribbles are drawn to the wall, colors are converted to 8-bit integers for more efficient rasterization and storage. This means some loss of precision will happen, which may cause issues with brushes like this one: ```haku stroke 128 #00000004 (vec 0 0) ``` If you try to to use this brush to fill up a single spot with black, you will notice that despite all the math suggesting so, the color will end up gray instead. ## Shapes ```haku toShape value : _ -> () | shape ``` Converts the given value to a shape. - For `shape`, clones the shape that was passed in. - For `vec`, returns a point `shape`. - For anything else, returns `()`. ```haku line start : vec end : vec -> shape ``` Creates a line segment shape with the provided `start` and `end` points. ```haku rect position : vec size : vec -> shape rect x : number y : number width : number height : number -> shape ``` Creates a rectangle shape with its top-left corner at `position`, with a given `size` stretching from the top-left corner. The alternative 4-argument version takes in the rectangle's X/Y coordinates, width, and height as separate arguments instead of aggregating them into a `vec`. ```haku circle center : vec radius : number -> shape circle x : number y : number radius : number -> shape ``` Creates a circle shape, with its center at `center`, with the provided radius. The alternative 3-argument version takes in the circle's center X/Y coordinates as separate arguments instead of aggregating them into a `vec`. ## Scribbles ```haku stroke thickness : number color : rgba shape : shapeLike -> scribble ``` Creates a stroke scribble, which outlines the provided shape with a stroke of the given thickness and color. Point shapes are drawn as squares, and `line` shapes have square caps at the line's endpoints. ```haku fill color : rgba shape : shapeLike -> scribble ``` Creates a fill scribble, which fills in the entire area of the provided shape with a solid color. Since this requires the shape to have a surface area, this does not do anything when point and `line` shapes are passed in.