From e423b6956f436ef492ccd4151cf26f341141b105 Mon Sep 17 00:00:00 2001
From: twanvl <twanvl@0fc631ac-6414-0410-93d0-97cfa31319b6>
Date: Sat, 27 Dec 2008 19:39:20 +0000
Subject: [PATCH] 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                   |  6 ++-
 doc/function/index.txt                        |  1 +
 doc/function/split_text.txt                   | 41 +++++++++++++++++++
 .../drupal/mse-drupal-modules/highlight.inc   |  1 +
 4 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 doc/function/split_text.txt

diff --git a/doc/function/break_text.txt b/doc/function/break_text.txt
index bea4ed70..3110aa15 100644
--- a/doc/function/break_text.txt
+++ b/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.
diff --git a/doc/function/index.txt b/doc/function/index.txt
index 01a98bd5..d5a9a9ba 100644
--- a/doc/function/index.txt
+++ b/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?
diff --git a/doc/function/split_text.txt b/doc/function/split_text.txt
new file mode 100644
index 00000000..fc39ed1a
--- /dev/null
+++ b/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.
diff --git a/tools/website/drupal/mse-drupal-modules/highlight.inc b/tools/website/drupal/mse-drupal-modules/highlight.inc
index 162f87d8..e07b8b96 100644
--- a/tools/website/drupal/mse-drupal-modules/highlight.inc
+++ b/tools/website/drupal/mse-drupal-modules/highlight.inc
@@ -27,6 +27,7 @@ $built_in_functions = array(
 	'replace'		=>'',	'replace_rule'	=> 'replace',
 	'filter_text'		=>'',	'filter_rule'	=> 'filter_text',
 	'break_text'		=>'',	'break_rule'	=> 'break_text',
+	'split_text'		=>'',
 	'sort_text'		=>'',	'sort_rule'	=> 'sort_text',
 	'contains'		=>'',
 	'match'			=>'',	'match_rule'	=> 'match',