documented the split_text script function

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

doc/function/break_text.txt

@@ -20,6 +20,10 @@ So for example where @break_text@ returns @["a","b","c"]@, @filter_text@ would r
 In fact, @filter_text@ could be implemented as
 > filter_text := { for part in break_text() do part }
 
+--Split vs. break--
+
+The function @split_text@ does the opposite of @break_text@, keeping the parts between the regular expression matches, instead of the matching text itself.
+
 --Parameters--
 ! Parameter	Type			Description
 | @input@	[[type:string]]		String to replace in.
@@ -38,4 +42,4 @@ In fact, @filter_text@ could be implemented as
 
 --See also--
 | [[fun:filter_text]]		Keep only the text matching a regular expression.
-
+| [[fun:split_text]]		Split text into parts separated by a regular expression.

doc/function/index.txt

@@ -28,6 +28,7 @@ These functions are built into the program, other [[type:function]]s can be defi
 | [[fun:replace]]		Replace text matching a regular expression.
 | [[fun:filter_text]]		Keep only the text matching a regular expression.
 | [[fun:break_text]]		Break text into parts each matching a regular expression.
+| [[fun:split_text]]		Split text into parts separated by a regular expression.
 | [[fun:sort_text]]		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?

doc/function/split_text.txt

@@ -0,0 +1,41 @@
+Function: split_text
+
+DOC_MSE_VERSION: since 0.3.8
+
+--Usage--
+> split_text(some_string, match: regular expression, in_context: regular expression)
+
+Split text by keeping the parts between separators matching a regular expression.
+The function returns a [[type:list]] of parts.
+
+When the @split_text@ is used many times with the same @match@ or @in_context@ values it is more efficient to declare these as default arguments:
+> my_break := split_text@(match: ",")
+> my_break("a,b,c") # called many times
+This way the regular expression is only compiled once.
+
+--Split vs. break--
+
+The function @break_text@ does the opposite of @split_text@, keeping the parts mathing the regular expression, instead of the parts between it.
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:string]]		String to replace in.
+| @match@	[[type:regex]]		Regular expression to match.
+| @include_empty@	[[type:boolean]] (default: @true@)	If set to @false@, remove all empty parts
+
+--Examples--
+> split_text(match: ",", "ab,cd,,ef")                       ==  ["ab","cd","","ef"]
+> split_text(match: ",", "ab,cd,,ef", include_empty:false)  ==  ["ab","cd","ef"]
+> split_text(match: "a", "banana")  ==  ["b","n","n",""]
+> break_text(match: "a", "banana")  ==  ["a","a","a"]
+
+--See also--
+| [[fun:break_text]]		Break text into parts each matching a regular expression.
+
+For working with comma separated lists, such as those from multiple choice fields, there are special functions:
+| [[fun:chosen]]			Is the given choice selected in a multiple choice value?
+| [[fun:count_chosen]]			Count then number of choices selected in a multiple choice value.
+| [[fun:require_choice]]		Require that at least one of the given choices is selected.
+| [[fun:exclusive_choice]]		Require that at most one of the given choices is selected.
+| [[fun:require_exclusive_choice]]	Require that exactly one of the given choices is selected.
+| [[fun:remove_choice]]			Remove the given choices from a multiple choice value.