Finished documenting scripting system.

This means the documentation is DONE (yay!)

git-svn-id: svn://svn.code.sf.net/p/magicseteditor/code/trunk@606 0fc631ac-6414-0410-93d0-97cfa31319b6

doc/script/variables.txt

@@ -0,0 +1,77 @@
+Variables and functions
+
+--Variables--
+MSE script has the notion of ''variables''.
+A variable is a name holding a value, assigned using the @:=@ operator:
+> variable := 1 + 1
+From now on (until another value is assigned) @variable@ evaluates to @2@ in the rest of the script.
+
+--Functions--
+It is possible to define your own [[type:function]]s in MSE script.
+The syntax for this is very simple, code in curly braces defines a function:
+> { code goes here }
+
+To be able to refer to the function it is usually assigned to a variable:
+> function := { code goes here }
+
+Calling a function is done using parentheses:
+> { code }()
+> function()
+this has the effect of evaluating the code inside the curly braces.
+
+--Scope--
+
+Assignments to variables are ''local'' to the current function.
+Consider:
+> function := {
+>     x := "something else"
+>     # here x is something else
+> }
+> x := 1
+> function()
+> # here x is still 1
+
+Unlike most programming languages MSE script uses [[http://en.wikipedia.org/wiki/Dynamic_scoping#Dynamic_scoping|dynamic scoping]].
+This means that assignments done in the calling function are visible in the called function:
+> fun := { "xyz is {xyz}" }
+> one := {
+>     xyz := 1
+>     fun()
+> }
+> two := {
+>     xyz := "two"
+>     fun()
+> }
+> one()  ==  "xyz is 1"
+> two()  ==  "xyz is two"
+
+--Parameters--
+The scoping can be used to pass parameters to functions as shown above.
+To make this easier, parameters can be specified inside the parentheses of the function call:
+> fun(xyz: "a parameter")  ==  "xyz is a parameter"
+These assignments are ''only'' visible to the called function.
+> xyz := "outside"
+> fun(xyz: "a parameter")
+> # xyz is still "outside"
+
+The syntax for parameters is @name: value@.
+Multiple parameters are separated by commas.
+
+The special syntax @value@ (without a name) means the variable @input@ is used:
+> fun := { input + var2 }
+> fun(var2: "yes", "no")  ==  "noyes"
+
+--Overriding functions--
+Like custom functions, the [[fun:index|built in functions]] are also stored in variables.
+It is possible to overwrite them:
+> to_upper := { input }
+> to_upper("xyz") == "xyz" # Not what it used to do
+
+A neat trick is adding 'extra' behaviour to functions.
+This can be done by first making a copy, and calling that:
+> real_to_upper := to_upper
+> to_upper := { "upper case: " + real_to_upper() }
+> to_upper("xyz") == "upper case: XYZ"
+Note that @real_to_upper@ is called without extra parameters, the @input@ variable is still set from the outer call to the new @to_upper@ itself.
+
+<div style="text-align:right;">next: <a href="control_structures">Control structures &rarr;</a></div>