ginger/doc/runtime.md

112 lines
3.7 KiB
Markdown
Raw Normal View History

# Runtime
Any ginger data-structure can be put into a ginger file. The data itself has no executional meaning on its own, but if
the data is properly formed it can be parsed by the ginger interpreter and a thread of execution can be started. For
example, if I put the following in a file called `test.gng`:
```
(1 2 3)
```
It doesn't have any meaning, it's just a list. However, if you put the following:
```
(add 1 2 3)
```
and run `ginger test.gng` then a program can be interpreted from the given data. This file describes how given data can
be formed into a valid program.
## Eval
Ginger evaluation is done the same was as other lisp languages: the first item in a list is the function name, the rest
of the items in the list are arguments to the function. In the example above, `add` is the function name, and `1`, `2`,
and `3` are arguments to the function.
Arguments to a function can be functions to be eval'd themselves. An equivalent to the example above would have been:
```
(add 1 2 (add 1 2))
```
## Doing multiple things
It's not very useful to only be able to do one thing. A vector of lists is interpreted into sequentially eval'ing each
item in the vector. For (a trivial) example:
```
[ (add 1 2)
(sub 4 (add 1 2))
(mul 8 0) ]
```
## Variables/Scope
The above example does a few things, but it repeats itself in the second part (with the `sub`). If we could save the
result of the addition to a variable that would be awesomesauce. The `=` function does this! It makes it so that the
first argument is equivalent to the evaluation of the second argument. Variables' first letters must be upper-case, this
is how they're differentiated from raw string literals. The above could be re-written as:
```
[ (= AdditionResult (add 1 2))
(sub 4 AdditionResult)
(mul 8 0) ]
```
In the above example `AdditionResult` is a valid variable inside of the vector that contains its declaration, and any
vectors contained within that vector. For example:
```
[ (= AdditionResult (add 1 2))
[ (sub 4 AdditionResult) ;This works
(mul 8 0) ] ]
[ (add 4 AdditionResult) ] ;This does not work!
```
## Literals
We've determined that a list is interpreted as a function/arguments set, and an upper-case string is interpreted as a
variable name which will be de-referenced. What if we want to actually use these structures without eval'ing them? For
these cases we have the literal function `l`:
```
[ (concat (l (1 2 3)) (l (4 5 6))) ; => (1 2 3 4 5 6)
(println (l "I start with a capital letter and I DONT CARE!!!")) ]
```
## Functions
### Anonymous
Anonymous functions are declared using the `fn` function. The first argument is a vector of argument names (remember,
all upper-case!) and the second is a list/vector to be eval'd. Examples:
```
[ (= Add3 (fn [Num] (add Num 3)))
(Add3 4) ; => 7
(= Add3Sub1
(fn [Num] [
(= Added (add Num 3))
(sub Added 1)
]))
(Add3Sub1 4) ] ; => 6
```
`fn` returns a function, which can be passed around and assigned like any other value. In the above examples the
functions are assigned to the `Add3` and `Add3Sub1` variables. Functions can also be passed into other functions as
arguments:
```
;DoTwice takes a function Fun and a number Num. it will call Fun twice on Num and return the result.
[ (= DoTwice
(fn [Fun Num]
(Fun (Fun Num))))
(DoTwice (fn [Num] (add Num 1)) 3) ] ; => 5
```
### Defined
Defined functions attach the function definition to a string literal (lower-case) in the current scope. They are useful
as they support more features then an anonymous function, such as inline documentation. These extra features will be
documented elsewhere. To create a defined function use the `dfn` function:
```
[ (dfn add-four-sub-three [Num] [
(= A (add Num 4))
(sub A 3) ])
(add-four-sub-three 4) ] ; => 5
```