Added break_text function

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

doc/function/break_text.txt

@@ -0,0 +1,39 @@
+Function: break_text
+
+--Usage--
+> break_text(some_string, match: regular expression, in_context: regular expression)
+> break_rule(match: ..., in_context: ...)(some_string)
+
+Break text by only keeping the parts of the input that match the regular expression.
+The function returns a [[type:list]] of parts.
+
+If @in_context@ is given, the context must also match the string where the match is represented as <tt>&lt;match></tt>.
+
+This function is available in [[script:rule form]].
+When the @break_text@ is used many times the rule form is more efficient, because the regular expression is only compiled once.
+
+--Filter vs. break--
+
+The function @filter_text@ is very similar to @break_text@, instead of returning a list it concatenates the items.
+So for example where @break_text@ would return @["a","b","c"]@, @filter_text@ would return @"abc"@.
+In fact, @filter_text@ could be implemented as
+> filter_text := { for part in break_text() do part }
+
+--Parameters--
+! Parameter	Type			Description
+| @input@	[[type:string]]		String to replace in.
+| @match@	[[type:regex]]		Regular expression to match.
+| @in_context@	[[type:regex]] (optional)	Context to match
+
+--Examples--
+> break_text(match: "a",    "banana")  ==  ["a","a","a"]
+> break_text(match: "na|.", "banana")  ==  ["b","a","na","na"]
+> break_text(match: "ap",   "banana")  ==  []
+>
+> f := break_rule(match: "xx+")
+> f("xyzxxxxyyzz") == ["xxxx"]
+
+--See also--
+| [[fun:filter_text|filter_text / filter_rule]]
+				Keep only the text matching a regular expression.
+

doc/function/filter_text.txt

@@ -9,7 +9,7 @@ Filter text by only keeping the parts of the input that match the regular expres
 If @in_context@ is given, the context must also match the string where the match is represented as <tt>&lt;match></tt>.
 
 This function is available in [[script:rule form]].
-When the filter is used many times the rule form is more efficient, because the regular expression is only compiled once.
+When the @filter_text@ is used many times the rule form is more efficient, because the regular expression is only compiled once.
 
 --Parameters--
 ! Parameter	Type			Description
@@ -26,5 +26,7 @@ When the filter is used many times the rule form is more efficient, because the
 > f("xyzxxyyzz") == "xx"
 
 --See also--
+| [[fun:break_text|break_text / break_rule]]
+				Break text into parts each matching a regular expression.
 | [[fun:replace|replace / replace_rule]]
 				Replace text matching a regular expression.

doc/function/index.txt

@@ -16,6 +16,8 @@ These functions are built into the program, other [[type:function]]s can be defi
 				Replace text matching a regular expression.
 | [[fun:filter_text|filter_text / filter_rule]]
 				Keep only the text matching a regular expression.
+| [[fun:break_text|break_text / break_rule]]
+				Break text into parts each 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?