garden/README.md

305 lines
12 KiB
Markdown

# Garden
An experiment in combining [Fennel](https://fennel-lang.org) and [Terra](https://terralang.org).
## Rationale
Idk, seemed cool
## Goals and Non-Goals
At its core are a few a largely non-opinionated macros that directly expose the functionality
that is only available through Terra's custom syntax. Terra code is not necessarily meant to
read like Fennel or have the same semantics. Early returns are fine, all variables are mutable,
break and continue and imperative loops are the norm.
Ideally it would be possible to build a much cleaner set of macros on top of these base macros.
But the goal isn't to design a nice low-level language, it's to expose a powerful compilation
target. It's assumed that if you want to take advantage of Terra, it's probably because you
want to do horrible code-generation tricks. Hosting it inside Fennel simply makes it more
comfortable to do so.
## Usage
At the top of your file, include the following:
```fennel
(import-macros {: def : q : ttype : static} :terra)
```
The `def` macro defines a new terra function. The `q` macro defines a quoted terra expression.
The `ttype` macro allows you to specify terra type definitions that can't be expressed with
regular lua syntax. The `static` macro allows you to define "global" terra variables.
Notably, all of these macros return values, and none of them define new variables, local or global.
I could maybe be persuaded to make `def` work like `fn` and optionally define a local, but for now,
eh, whatever.
### def
Defines a function, compiling down to the `terra` keyword. Can also be used to create an undefined
function, if called with no statements.
```fennel
; syntax:
(def [argname1 argtype1 argname2 argtype2... : rettype1 rettype2...] statement...)
(def [argtype1 argtype2... : rettype1 rettype2...])
; examples:
(local add (def [x int y int : int]
(return (+ x y))))
; compiles to:
; local add = terra(x : int, y : int) : {int}
; return (x + y)
; end
(add 1 2) ; returns 3
(local even? (def [uint32 : bool]))
(local odd? (def [n uint32 : bool]
(if (= n 0)
(return false)
(return (even? (- n 1))))))
(even?:adddefinition (def [n uint32 : bool]
(if (= n 0)
(return true)
(return (odd? (- n 1))))))
; compiles to:
; local terra even_3f :: { uint32 } -> { bool }
; local odd_3f = terra(n : uint32) : { bool }
; if n == 0 then return true else return even_3f(n - 1) end
; end
; even_3f:adddefinition(terra(n : uint32) : { bool }
; if n == 0 then return false else return odd_3f(n - 1) end
; end)
```
To define a function as returning "void", simply end the argument list with a `:`.
To make terra infer the return type, do not include a `:` in the argument list at all.
Undefined functions can't have their return types inferred.
Unlike Fennel, we do not implement implicit return semantics, and early returns are A-OK.
Sorry Phil.
### q
Defines a terra quotation, compiling down to the `` ` `` operator if given one argument, and
`quote` / `in` / `end` if given more than one. The resulting quote can always be used as an
expression that returns a value; if `q` is passed more than one argument, the last form is
used as the `in` block. To force no value to be returned, you can pass `($)` as the last
argument, which corresponds to the empty tuple. Note that quotes inherently creates a new
temporary scope, so variables created in a quote will go out of scope by the end of the
quote.
```fennel
(fn inc [x] (q (+ x 1))) ; compiles to: function(x) return `(x + 1) end
(fn do-thing [f x]
(q (var z (+ ,x 1))
(f z)
($)))
; compiles to:
; function(f, x)
; return quote
; var z = [x] + 1
; f(z)
; in
; {}
; end
; end
```
### Type syntax
In Terra, types are Lua values and can be constructed from regular Lua code, outside of
`terra` or `quote` blocks. (There are certain places inside these blocks where types can
be constructed as well.) However, because Terra significantly extends the syntax of Lua to
allow for convenient type construction, Garden also must provide a mini-language to support
it.
Inside `terra` or `quote` blocks, whenever you have a form that requires a type to be passed
to it, the compiler will automatically enter a type-compiling context. Outside of these blocks,
the `ttype` macro can be used.
#### Pointers and arrays
Pointers to types and arrays of types use the Fennel "sequence table" syntax. Alternatively,
the `&` operator can be used.
```fennel
(local intptr (ttype [int])) ; compiles to: &int
(local intptr2 (ttype (& int))) ; also compiles to: &int
(local intarray (ttype [int 16])) ; compiles to: int[16]
```
#### Structs
Structs are defined using the Fennel "key-value table" syntax. For each row in the table,
the keys are Fennel symbols representing the name of the field, and the values are type
expressions. If, instead of a symbol, the compiler finds the string `:union`, the value
is expected to be another "key-value table" containing the same structure. Struct definitons
can be nested.
Note that the field names must be valid Lua symbols; no name-mangling is done. Might be
worth doing that at some point; it seems likely that I will be annoyed if we don't
auto-convert `-` to `_` at least.
```fennel
(local Variant (ttype {tag int
:union {number float
string [int8]
complex {real float imag float}}}))
; compiles to:
; local Variant = struct {
; tag : int,
; union {
; number : float,
; string : &int8,
; complex : struct {
; real : float,
; imag : float
; }
; }
; }
```
#### Function pointers
Function pointer types are defined with the `->` form, which a variable number of types as arguments.
Similar to `def`, you can put a `:` in your argument list to delineate between input parameters and
output types. Unlike `def`, if no `:` is present it is assumed that the function does not return a value,
as inference is not possible.
```fennel
(local callback (ttype (-> [int] int : int))) ; compiles to: local callback = { &int, int } -> { int }
(local callback (ttype (-> float))) ; compiles to: local callback = { float } -> {}
```
#### Tuples
Tuple types are defined in Terra with a generic Lua function call to `tuple` that takes a variable
number of types as parameters. This is supported directly, like any type declaration consisting of
a function call, but there is a shortened form using `$` to match the tuple instantiation syntax.
```fennel
(ttype (tuple int [int])) ; compiles to: tuple(int, &int)
(ttype ($ int [int])) ; compiles to: tuple(int, &int)
```
#### Escaping
Arbitrary Fennel expressions can be evaluated in a type-compilation context using Fennel's `,` prefix,
which is normally used by macros. If you need to re-enter a type-compilation context after escaping,
you'll need to nest a call to `ttype`. (I'm considering using `` ` `` for this purpose, but I might have
it consistently mean "create a quote" everywhere. Not sure.)
```fennel
(ttype ($ [int] (fn-accepting-type [int]) ,(fn-accepting-seq [5]) (fn-accepting-seq-of-types ,[(ttype [int])])))
; compiles to:
; tuple(&int, fn_accepting_type(&int), fn_accepting_seq({ 5 }), fn_accepting_seq_of_types({ &int }))
```
### Terra syntax
#### var
```fennel
(var name initial-value) ; compiles to: var name = initial-value
(var name type initial-value) ; compiles to: var name : type = initial-value
(var (name1 name2) val1 val2) ; compiles to: var name1, name2 = val1, val2
(var {name1 type1 name2 type2} val1 val2) ; compiles to: var name1 : type1, name2 : type2 = val1, val2
(var {undefined type}) ; compiles to: var undefined : type
```
Define a local variable named `var`, and set its initial value to `initial-value`. You can
manually specify a `type`, or you can let terra infer it from `initial-value`. Both forms
require `initial-value` to be provided.
You can define multiple type-inferred variables at once with the `(name1 name2)` syntax, and
multiple explicitly-typed variables with the `{name1 type1 name2 type2}` syntax. Both of those
forms accept any number of initial values. If no values are provided, the variables are left
uninitialized. If one value is passed, Terra will treat it as a tuple destructuring. Otherwise
you should probably pass the same number of values as names.
#### assignment
```fennel
(set varname value) ; compiles to: varname = value
(set struct.field value) ; compiles to: struct.field = value
(set (field1 field2) tuple) ; compiles to: field1, field2 = tuple
(tset struct (getfield) value) ; compiles to: struct.[getfield()] = value
```
#### Pointers and arrays
Dereferencing a pointer or accessing an element in an array uses the same syntax as defining a pointer
or array type - the Fennel sequence literal. To take a reference to a value, you can use the `&` form.
```fennel
(def [ptr [int]] (return [ptr])) ; compiles to: terra (ptr : &int) return @ptr end
(def [arr [int 8]] (return [arr 5])) ; compiles to: terra (arr : int[8]) return arr[5] end
(def [nested [[int]]] (return [nested 0 3])) ; compiles to: terra (nested : &&int) return nested[0][3] end
(def [nested [[int]]] (return [[nested] 3])) ; compiles to: terra (nested : &&int) return (@nested)[3] end
(def [ptr [int] : [int]] (return (& [ptr 1]))) ; compiles to: terra (ptr : &int): &int return &ptr[1] end
```
#### field access
```fennel
struct.field ; compiles to: struct.field
(struct.func) ; compiles to: struct.func()
(obj:method) ; compiles to: obj:method()
(. struct (getfield)) ; compiles to: struct.[getfield()]
(: obj (getmethod)) ; compiles to: struct:[getmethod()]()
```
#### cast
```fennel
(cast type expr)
```
Cast an expression `expr` to the type `type`.
```fennel
(cast [int] voidptr) ; compiles to: ([&int]voidptr)
(cast [int8] (C.malloc (* (sizeof int8) 16))) ; compiles to: ([&int8]C.malloc(sizeof(int8) * 16))
```
#### tuple literal
`$` can be used to create a tuple.
```fennel
($ 5 2.5 :hello) ; compiles to: { 5, 2.5, "hello" }
(var pair ($ int int) ($ 5 10)) ; compiles to: var pair : { int, int } = { 5, 10 }
```
#### struct literal
A fennel key-value table literal is interpreted as an anonymous struct literal.
If you "call" a struct type with a struct literal, it will coerce it to the given
type.
```fennel
(local Complex (ttype {real float imag float}))
; compiles to:
; local Complex = struct { real : float, imag : float }
(def [: Complex] (return (Complex { real 5 imag 1 })))
; compiles to:
; terra (): Complex
; return Complex({ real = 5, imag = 1 })
; end
```
#### Primitive operators
| Fennel | Terra | Meaning |
| ------------ | ------------ | ----------------------------------- |
| `(+ x y)` | `x + y` | add x and y |
| `(- x y)` | `x - y` | subtract y from x |
| `(/ x y)` | `x / y` | divide x by y |
| `(* x y)` | `x * y` | multiply x and y |
| `(% x y)` | `x % y` | x modulo y |
| `(< x y)` | `x < y` | x is less than y |
| `(<= x y)` | `x <= y` | x is less than or equal to y |
| `(= x y)` | `x == y` | x is equal to y |
| `(not= x y)` | `x ~= y` | x is not equal to y |
| `(> x y)` | `x > y` | x is greater than y |
| `(>= x y)` | `x >= y` | x is greater than or equal to y |
| `(and x y)` | `x and y` | x AND y (boolean or bitwise) |
| `(or x y)` | `x or y` | x OR y (boolean or bitwise) |
| `(not x)` | `not x` | NOT x (boolean or bitwise) |
| `(^ x y)` | `x ^ y` | x XOR y (bitwise) |
| `(<< x y)` | `x << y` | arithmetic shift x left by y bits |
| `(>> x y)` | `x >> y` | arithmetic shift x right by y bits |
#### return
Terra functions can return multiple values, or none. Returns must be explicitly
written with the `return` form.
```fennel
(def [: int] (return 5)) ; compiles to: terra (): { int } return 5 end
(def [: float float] (return -1.5 1.5)) ; compiles to: terra (): { float float } return -1.5, 1.5 end
```
#### Fennel escaping