More function documentation

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

doc/function/contains.txt

@@ -0,0 +1,18 @@
+Function: contains
+
+--Usage--
+> contains(some_string, match: to_search_for)
+
+Does one string contain another at any position?
+
+--Parameters--
+| @input@	[[type:string]]		String to look in
+| @match@	[[type:string]]		String to look for
+
+--Examples--
+> contains("abcdefg", match:"abc")    == true
+> contains("abcdefg", match:"defg")   == true
+> contains("abcdefg", match:"abd")    == false
+
+--See also--
+| [[fun:match|match / match_rule]]	Does a string match a regular expression?

doc/function/filter_list.txt

@@ -0,0 +1,18 @@
+Function: filter_list
+
+--Usage--
+> filter_list(some_list, filter: some_predicate)
+
+Returns a new list that contain all elements in the list for which the filter predicate returns @true@.
+
+If possible, when using a set, use the [[fun:position]] and [[fun:number_of_items]] functions instead.
+
+--Parameters--
+| @input@	[[type:list]] or [[type:set]]	List to filter.
+| @filter@	[[type:function]]		Function indicating which values to keep,
+		  				Will be called with @input@ set to an item in the list.
+
+--Examples--
+> filter_list([1,2,3,4], filter: { input > 2 }     ) == [3,4]
+> filter_list([1,2,3,4], filter: { input % 2 == 0 }) == [2,4]
+> filter_list(set,       filter: { input.color == "red" }) == # red cards in the set

doc/function/format.txt

@@ -0,0 +1,21 @@
+Function: format
+
+--Usage--
+> format(some_number, format: format_specification)
+> format_rule(format: format_specification)(some_number)
+
+Format a number or other string as a string, [[http://www.cplusplus.com/reference/clibrary/cstdio/printf.html|printf]] style.
+This function is available in [[script:rule form]].
+
+--Parameters--
+| @input@	[[type:int]] or [[type:double]] or [[type:string]]
+		  			Item to format.
+| @format@	[[type:string]]		Format specification.
+
+--Examples--
+> format(format: "%03X", 13)    ==  "00D"
+> format(format: "%03d", 13)    ==  "013"
+> format(format: "%3s",  "xy")  ==  " xy"
+>
+> f := format_rule(format: "%03d")
+> f(1) == "001"

doc/function/index.txt

@@ -8,23 +8,25 @@ These functions are built into the program, other [[type:function]]s can be defi
 | [[fun:to_title]]		Convert a string to title case, @"aBc" -> "Abc"@.
 | [[fun:reverse]]		Reverse a string, @"aBc" -> "cBa"@.
 | [[fun:substring]]		Extract a part of a string.
-| [[fun:format]]		Format a number as a string (printf).
-| [[fun:format_rule]]		^^^
+| [[fun:format|format / format_rule]]
+				Format a number as a string (printf).
 | [[fun:curly_quotes]]		Make quotes curly.
-| [[fun:replace]]		Replace text matching a regular expression.
-| [[fun:replace_rule]]		^^^
-| [[fun:filter_text]]		Keep only the text matching a regular expression.
-| [[fun:filter_rule]]		^^^
-| [[fun:sort_text]]		Sort the letters in a string using a custom order.
-| [[fun:sort_rule]]		^^^
+| [[fun:replace|replace / replace_rule]]
+				Replace text matching a regular expression.
+| [[fun:filter_text|filter_text / filter_rule]]
+				Keep only the text matching a regular expression.
+| [[fun:sort_text|sort_text / sort_rule]]
+				Sort the letters in a string using a custom order.
 | [[fun:contains]]		Does a string contain another one?
-| [[fun:match]]			Does a string match a regular expression?
-| [[fun:match_rule]]		^^^
+| [[fun:match|match / match_rule]]
+				Does a string match a regular expression?
+	
 ! [[type:tagged_string|Tags]]	<<<
-| [[fun:tag_contents]]		Change the contents of a specific tag.
-| [[fun:tag_contents_rule]]	^^^
-| [[fun:remove_tag]]		Remove a tag, keep the contents.
-| [[fun:tag_remove_rule]]	^^^
+| [[fun:tag_contents|tag_contents / tag_contents_rule]]
+				Change the contents of a specific tag.
+| [[fun:remove_tag|remove_tag / tag_remove_rule]]
+				Remove a tag, keep the contents.
+	
 ! [[type:list|Lists]]		<<<
 | [[fun:position]]		Find the position of an element in a list.
 | [[fun:number_of_items]]	Find the number of items in a list.
@@ -32,8 +34,8 @@ These functions are built into the program, other [[type:function]]s can be defi
 | [[fun:filter_list]]		Filter a list, keeping only elements that match a predicate.
 	
 ! Keywords			<<<
-| [[fun:expand_keywords]]	Expand the keywords in a piece of text.
-| [[fun:expand_keywords_rule]]	^^^
+| [[fun:expand_keywords|expand_keywords / expand_keywords_rule]]
+				Expand the keywords in a piece of text.
 | [[fun:keyword_usage]]		What keywords are used on a card, and how often are they used?
 	
 ! English language			<<<

doc/function/match.txt

@@ -0,0 +1,26 @@
+Function: match
+
+--Usage--
+> match(some_string, match: regular expression)
+> match_rule(regular expression)()
+
+Does a string match the given [[type:regex|regular expression]]?
+
+This function is available in [[script:rule form]].
+When the match is performed many times the rule form is more efficient, because the regular expression is only compiled once.
+
+--Parameters--
+| @input@	[[type:string]]		String to match.
+| @match@	[[type:regex]]		Regular expression to match.
+
+--Examples--
+> match("aaaa", match:"a*")   == true
+> match("a",    match:"b*")   == true
+> match("abc",  match:"b+")   == true
+> match("abc",  match:"$b+^") == false
+>
+> f := match_rule(match: "a+|b+")
+> f("xyz") == false
+
+--See also--
+| [[fun:contains]]		Does a string contain another one?

doc/function/number_of_items.txt

@@ -0,0 +1,22 @@
+Function: number_of_items
+
+--Usage--
+> number_of_items(in: some_collection)
+
+Returns the position of an item in a list or characters in a string.
+
+--Parameters--
+| @in@		[[type:list]] or [[type:map]] or [[type:set]] or [[type:string]]
+		  				Object to determine the number of items of.
+		  				When it is a set, returns the number of cards.
+		  				When it is a string, returns the number of characters.
+| @filter@	[[type:function]] (optional)	Act as if the list was [[fun:filter_list|filtered]] by this criterion.
+		  				Only when @in@ is a set.
+
+--Examples--
+> number_of_items(in: ["x", "y", "z"]) == 3
+> number_of_items(in: "pink") == 4
+> number_of_items(in: set) == # number of cards in the set
+>
+> # the number of red cards in the set
+> number_of_items(in: set, filter: { card.color == "red" } )

doc/function/reverse.txt

@@ -0,0 +1,12 @@
+Function: reverse
+
+--Usage--
+> reverse(some_string)
+
+Reverse a string.
+
+--Parameters--
+| @input@	[[type:string]]		String to reverse.
+
+--Examples--
+> reverse("abc")     == "cba"

doc/function/sort_list.txt

@@ -0,0 +1,17 @@
+Function: sort_list
+
+--Usage--
+> sort_list(some_list, order_by: some_function)
+
+Order the elements in a list in lexicographical order, from smallest to largest.
+Optionally order by some other property.
+
+--Parameters--
+| @input@	[[type:list]] or [[type:set]]	List to sort.
+| @order_by@	[[type:function]] (optional)	Function to order by, for example when @order_by: {input.name}@ orders items by their name property.
+
+--Examples--
+> sort_list([5,2,3,1,4])          ==  [1,2,3,4,5]
+> sort_list(["aaa","cccc","bb"])  ==  ["aaa","bb","cccc"]
+> sort_list(["aaa","cccc","bb"], order_by: {number_of_items(in:input)})
+>                                 ==  ["bb","aaa","cccc"]

doc/function/substring.txt

@@ -0,0 +1,19 @@
+Function: substring
+
+--Usage--
+> substring(some_string, begin: number, end: number)
+
+Extract a subsection of a string.
+
+--Parameters--
+| @input@	[[type:string]]		String to extract something from.
+| @begin@	[[type:int]] (optional)	Index of first character to keep (the first index is 0).
+		  			If ommitted, starts at the begining of the string.
+| @end@		[[type:int]] (optional)	Index just beyond the last character to keep.
+		  			If ommitted, runs to the end of the string.
+
+--Examples--
+> substring("abcdefg", end:2)          == "ab"
+> substring("abcdefg", begin:2)        == "cdefg"
+> substring("abcdefg", begin:2, end:4) == "cd"
+> substring("abcdefg", begin:2, end:2) == ""

doc/function/to_lower.txt

@@ -0,0 +1,17 @@
+Function: to_lower
+
+--Usage--
+> to_lower(some_string)
+
+Convert a string to lower case.
+
+--Parameters--
+| @input@	[[type:string]]		String to convert.
+
+--Examples--
+> to_lower("ABC")     == "abc"
+> to_lower("123 aBc") == "123 abc"
+
+--See also--
+| [[fun:to_upper]]		Convert a string to upper case, @"aBc" -> "ABC"@.
+| [[fun:to_title]]		Convert a string to title case, @"aBc" -> "Abc"@.

doc/function/to_title.txt

@@ -0,0 +1,17 @@
+Function: to_title
+
+--Usage--
+> to_title(some_string)
+
+Convert a string to title case, where each words starts with an upper case leter.
+
+--Parameters--
+| @input@	[[type:string]]		String to convert.
+
+--Examples--
+> to_title("ABC")     == "Abc"
+> to_title("123 aBc") == "123 Abc"
+
+--See also--
+| [[fun:to_lower]]		Convert a string to lower case, @"aBc" -> "abc"@.
+| [[fun:to_upper]]		Convert a string to upper case, @"aBc" -> "ABC"@.

doc/function/to_upper.txt

@@ -0,0 +1,17 @@
+Function: to_upper
+
+--Usage--
+> to_upper(some_string)
+
+Convert a string to upper case.
+
+--Parameters--
+| @input@	[[type:string]]		String to convert.
+
+--Examples--
+> to_upper("abc")     == "ABC"
+> to_upper("123 aBc") == "123 ABC"
+
+--See also--
+| [[fun:to_lower]]		Convert a string to lower case, @"aBc" -> "abc"@.
+| [[fun:to_title]]		Convert a string to title case, @"aBc" -> "Abc"@.

doc/function/trace.txt

@@ -0,0 +1,12 @@
+Function: trace
+
+--Usage--
+> trace(some_string)
+
+Output a message for debugging purposes, for example to investigate what is going on in some function.
+
+--Parameters--
+| @input@	[[type:string]]		Message
+
+--Examples--
+> trace("message") == "message"   # the message is reported in a message box