ginger/doc/runtime.md

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' can not be re-defined to be another value, and their first letters must be upper-case, thisis 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

Namespaces

Namespaces give names to defined scopes which can be referenced from elsewhere. The best way to show this is with an example:

[
(ns circle [
    (= Pi 3.14)
    (dfn area [R] (mul R R Pi)) ])

(circle/area 5) ; => 78.5
]

Embedded namespaces

Namespaces can be embedded into a tree-like structure:

[
(ns math [
    (= Pi 3.14)
    (ns circle
        (dfn area [R] (mul R R Pi)))
    (ns square
        (dfn area [R] (mul R R)))
])

(math.circle/area 5) ; => 78.5
(math.square/area 5) ; => 25
]

In the above example circle and square are both sub-namespaces of the math namespace. In circle the variable Pi is referenced. Ginger will look in the current scope for that variable, and when it's not found travel up the scope tree. Pi is defined in math's scope, so that value is used.

Namespace resolution

Let's do a more complicated example to show how namespace resolution works:

[
(ns tlns [
    (ns alpha
        (= A "The first letter in the alphabet"))
    (ns facts
        (= BestLetter alpha/A))
])

(println tlns.facts/BestLetter)
]

In the above example BestLetter is defined inside facts to be the variable A which exists in the namespace alpha. To resolve this variable ginger first looks inside facts's scope for a namespace called alpha, doesn't find it, then moves up to tlns's scope, which does contain a namespace called alpha. Similaraly, to resolve tlns.facts/BestLetter ginger first looks in that statements current scope for a namespace called tlns, which it finds, and looks in there for facts, etc...

Variable namespaces

A namespace is nothing more than a string literal. If a variable is used instead ginger will resolve the variable before trying to resolve the namespace.

[
(ns tlns [
    (ns alpha
        (= A "The first letter in the alphabet"))])

(= NS1 tlns)
(= NS2 alpha)
(= NS NS1.NS2)
(println NS/A) ; This would print the message defined above
]