Improved documentation of functions and default arguments a bit

doc/function/match.txt

@@ -22,6 +22,7 @@ When the match is performed many times the rule form is more efficient, because
 >
 > f := match_rule(match: "a+|b+")
 > f("xyz")  == false
+> f("aabb") == true
 
 --See also--
 | [[fun:contains]]		Does a string contain another one?

doc/script/control_structures.txt

@@ -2,7 +2,7 @@ Control structures
 
 MSE Script has two types of control structures.
 
---If-Then-Else--
+--Conditional statement (@if then else@)--
 
 To switch between two options use:
 
@@ -21,6 +21,12 @@ Note that if-then-else is an ''expression'', it can be used almost everywhere:
 > color := (if card.color == "red"   then "r") +
 >          (if card.color == "green" then "g")
 
+Multiple conditions can be checked by using @else if@:
+> if      card.color == "white"  then "W"
+> else if card.color == "red"    then "R"
+> else if card.color == "blue"   then "U"
+> else                                "something else"
+
 The @then@ and @else@ parts can also contain assignments and other control structures.
 > if card.color == "red" then
 >     filter := filter + "r"
@@ -36,25 +42,28 @@ To use multiple statements in the then or else branches you must use parentheses
 >     y := z
 > )
 
---For-Each--
+--Loop statement (@for each@)--
 
-To iterate over all elements in a [[type:list]] the @for each@ construct
+To iterate over all elements in a [[type:list]] the @for each@ construct can be used
 
 > for each variable in list do expression
 
 If list is a list of items, for example set.cards, the expression is evaluated for each item in that list.
 The variable becomes set to that each item in succession.
-The results of the expression are combined using the @+@ [[script:operators|operator]].
+The results of the expression are combined using the @+@ [[script:operators|operator]]:
+
+> for each x in ["a","b","c"] do x      ==  "abc"
+> for each x in ["a","b","c"] do [x+x]  ==  ["aa","bb","cc"]
 
 It is also possible to iterate over a range of values
 
 > for variable from begin to end do expression
 
-The expression is evaluated for each number from begin to end (including begin, not including end). The variable becomes set to that each number in succession. The results of the expression are combined using +.
+The expression is evaluated for each number from begin to end (including begin, not including end). The variable becomes set to that each number in succession. Again, the results of the expression are combined using +.
 
 --Summary--
 
 ! Syntax				Description
 | @if a then b else c@			If @a@ is @true@ evaluates to @b@, otherwise evaluates to @c@
-| @for each x in list do something@	Does something for each element in a list
-| @for x from 1 to 100 do something@	Does something for all numbers from 1 to 100
+| @for each x in list do something@	Does @something@ for each element in a list
+| @for x from 1 to 100 do something@	Does @something@ for all numbers from 1 to 100

doc/script/default_arguments.txt

+Default arguments
+
+It is possible to declare default arguments for functions using the @@@@ operator.
+> function := { "argument was: " + arg }@(arg:"default")
+If this function is called without the @arg@ argument, then the default value @"default"@ is used instead.
+For example:
+> function()                      == "argument was: default"
+> function(arg: "something else") == "argument was: something else"
+
+For determining whether the argument is set only explicit arguments count, not everything in scope, so
+> arg := "something else"
+> function()                      == "argument was: default"
+
+//Defaults are evaluated at the time the @@@@ operator is evaluated, so they can be used to simulate static scoping.
+
+--Rule functions--
+
+Some functions are available in ''rule form''.
+
+These rule form functions are functions that create a new [[type:function]] with some defaults filled in.
+That new function, the rule, applies some transformation to the input and returns the result.
+
+A rule is like a normal function with all parameters given, except for the @input@.
+
+Rules are often combined using the + operator, for example:
+> # First all "a"s are replaced, then all "b"s.
+> remove_as_and_bs := replace_rule(match: "a", replace: "") +
+>                     replace_rule(match: "b", replace: "")
+> 
+> text_with_as_and_bs := "bla bla bla"
+> text_without_as_and_bs := remove_as_and_bs(text_with_as_and_bs)
+
+
+<div style="text-align:right;">previous: <a href="functions">&larr; Functions</a> | next: <a href="control_structures">Control structures &rarr;</a></div>

doc/script/functions.txt

+Functions
+
+It is possible to define your own functions 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.
+
+--Parameters--
+
+When calling a function, parameters can be specified inside the parentheses of the function call:
+> fun := { "xyz is {xyz}" }
+> 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 that the variable @input@ is used:
+> fun := { input + var2 }
+> fun(var2: "yes", "no")  ==  "noyes"
+
+<div style="text-align:right;">previous: <a href="variables">&larr; Variables</a> | next: <a href="default_arguments">Default arguments &rarr;</a></div>

doc/script/index.txt

@@ -5,7 +5,9 @@ MSE uses a custom scripting language to add complicated behaviour to [[type:fiel
 --Topics--
 * [[script:introduction|Introduction to scripting]]
 * [[script:Operators]]
-* [[script:variables|Variables and functions]]
+* [[script:variables|Variables]]
+* [[script:functions|Functions]]
+* [[script:default_arguments|Default arguments]]
 * [[script:Control structures]]
 * [[script:Predefined variables]]
 * [[script:Best practices]]
@@ -18,10 +20,10 @@ See also:
 | @"stuff"@		[[type:string|A literal string]]
 | @[a,b,c]@		[[type:list|A literal list]]
 | @[a:b, c:d]@		[[type:map|A literal map]]
-| @{ expr }@		[[script:variables#Functions|Function definition]]
-| @fun(a:b, c:d)@	[[script:variables#Functions|Function call]]
-| @fun(value)@		[[script:variables#Functions|Function call with '@input@' argument]]
-| @fun@@(a:b)@		[[script:variables#Default arguments|Default arguments]]
+| @{ expr }@		[[script:functions|Function definition]]
+| @fun(a:b, c:d)@	[[script:functions|Function call]]
+| @fun(value)@		[[script:functions|Function call with '@input@' argument]]
+| @fun@@(a:b)@		[[script:default_arguments|Default arguments]]
 | @a.b@			[[script:operators|Property 'b' of 'a']]
 | @a[b]@		[[script:operators|Property 'value of b' of 'a']]
 | @-a@			[[script:operators|Negation]]

doc/script/variables.txt

-Variables and functions
+Variables
 
---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.
@@ -45,21 +31,7 @@ This means that assignments done in the calling function are visible in the call
 > 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"
+This can be very useful for variables like @card@, which are used by many functions.
 
 --Overriding functions--
 Like custom functions, the [[fun:index|built in functions]] are also stored in variables.
@@ -74,17 +46,4 @@ This can be done by first making a copy, and calling that:
 > 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.
 
---Default arguments--
-It is possible to declare default arguments for functions using the @@@@ operator.
-> function := { "argument was: " + arg }@(arg:"default")
-If this function is called without the @arg@ argument, then the default value @default@ is used instead.
-For example:
-> function()                      == "argument was: default"
-> function(arg: "something else") == "argument was: something else"
-For determining whether the argument is set only explicit arguments count, not everything in scope, so
-> arg := "something else"
-> function()                      == "argument was: default"
-
-Defaults are evaluated at the time the @@@@ operator is evaluated, so they can be used to simulate static scoping.
-
-<div style="text-align:right;">next: <a href="control_structures">Control structures &rarr;</a></div>
+<div style="text-align:right;">previous: <a href="operators">&larr; Operators</a> | next: <a href="functions">Functions &rarr;</a></div>

doc/type/function.txt

@@ -6,6 +6,8 @@ The [[script:index|scripting language]] allows you to define custom functions.
 --Syntax--
 A piece of code enclosed in curly braces defines a function.
 
+A function can be called using parentheses, for example @function(argument:value)@.
+
 --Composition--
 Functions can be composed using the @+@ operator, evaluating @a + b@ first evaluates @a@ and uses its result as @input@ for @b@:
 > example := to_upper + { "result == {input}" }