//
//------------------ DOK FILE --------------------------------------------------
+Header	core.util.regexp
=pkg	core.util.regexp
=title	core.util.regexp
=short	regular expressions
=desc
This library manages regular expressions. [[regexpCreate]] is used to create a parser from a regular expression.
Then [[regexpNext]] or [[regexpTest]] are used to parse a string with it.
//
//
//------------------ PROTO ----------------------------------------------------- RegExp
+Proto	RegExp
=type	RegExp
=mode	sum
=pkg	core.util.regexp
=impl	mcy
=link	
=desc	This is the type of a regular expression parser.
//
//
//------------------ PROTO ----------------------------------------------------- regexpCreate
+Proto	regexpCreate
=type	fun Str -> RegExp
=mode	function
=pkg	core.util.regexp
=impl	mcy
=link	
=desc
This function generates a parser from the supplied regular expression.
	> regexpCreate ("(0|\\+33)[1-9]( *[0-9]{2}){4}")
//
+arg	str
=type	Str
=desc	A string defining a regular expression
//
+arg	result
=type	RegExp
=desc	A regular expression parser
//
//
//------------------ PROTO ----------------------------------------------------- regexpNext
+Proto	regexpNext
=type	fun Str RegExp Int -> [Int list Str]
=mode	function
=pkg	core.util.regexp
=impl	mcy
=link	
=desc
This function returns the position of the next matching substring, starting at position index. It returns this position and the list of matching substrings, all of them starting at this position.
It returns nil when no matching substring is found.
	> let regexpCreate ("[0-8]+") -> regexp in regexpNext ("+331 23 4567 89 00", regexp, 0)
>-> [Int list Str]: #2 [
>   0:
>     Int: 1 (0x1)
>   1:
>     list:
>       Str: "3"
>       Str: "33"
>       Str: "331"
>]
	> let regexpCreate ("[0-8]+") -> regexp in regexpNext ("ABCDEF", regexp, 0)
>-> [Int list Str]:  nil
//
+arg	src
=type	Str
=desc	A string
//
+arg	pattern
=type	RegExp
=desc	A regular expression parser
//
+arg	i
=type	Int
=desc	An index
//
+arg	result
=type	[Int list Str]
=desc	A tuple [position list_of_matching_substrings]
//
//
//------------------ PROTO ----------------------------------------------------- regexpTest
+Proto	regexpTest
=type	fun Str RegExp Int -> list Str
=mode	function
=pkg	core.util.regexp
=impl	mcy
=link	
=desc
This function checks if the regular expression matches in src starting at position index.
It returns a list of matching substrings, all of them starting at position index.
	> let regexpCreate ("[0-8]+") -> regexp in regexpTest ("+331 23 4567 89 00", regexp, 1)
>-> list Str:
>   Str: "3"
>   Str: "33"
>   Str: "331"
//
+arg	src
=type	Str
=desc	Any string
//
+arg	pattern
=type	RegExp
=desc	A regular expression parser
//
+arg	index
=type	Int
=desc	An integer
//
+arg	result
=type	list Str
=desc	A list of strings