Use runnableExamples for example nre code

lib/impure/nre.nim

@@ -40,29 +40,26 @@ export options
 ##
 ## .. _`some additional terms`: http://pcre.sourceforge.net/license.txt
 ##
-## Example
+runnableExamples:
-## -------
+  let vowels = re"[aeoui]"
-##
+
-## .. code-block:: nim
+  let expectedResults = [
-##
+    1 .. 1,
-##     import nre
+    2 .. 2,
-##
+    4 .. 4,
-##     let vowels = re"[aeoui]"
+    6 .. 6,
-##
+    7 .. 7,
-##     for match in "moigagoo".findIter(vowels):
+  ]
-##       echo match.matchBounds
+  var i = 0
-##     # (a: 1, b: 1)
+  for match in "moigagoo".findIter(vowels):
-##     # (a: 2, b: 2)
+    doAssert match.matchBounds == expectedResults[i]
-##     # (a: 4, b: 4)
+    inc i
-##     # (a: 6, b: 6)
+
-##     # (a: 7, b: 7)
+  let firstVowel = "foo".find(vowels)
-##
+  let hasVowel = firstVowel.isSome()
-##     let firstVowel = "foo".find(vowels)
+  if hasVowel:
-##     let hasVowel = firstVowel.isSome()
+    let matchBounds = firstVowel.get().captureBounds[-1]
-##     if hasVowel:
+    doAssert matchBounds.get().a == 1
-##       let matchBounds = firstVowel.get().captureBounds[-1]
-##       echo "first vowel @", matchBounds.get().a
-##       # first vowel @1
 
 
 # Type definitions {{{
@@ -208,6 +205,16 @@ type
     ## Thrown when studying the regular expression failes
     ## for whatever reason. The message contains the error
     ## code.
+
+runnableExamples:
+    # This MUST be kept in sync with the examples in RegexMatch
+    doAssert "abc".match(re"(\w)").get.captures[0] == "a"
+    doAssert "abc".match(re"(?<letter>\w)").get.captures["letter"] == "a"
+    doAssert "abc".match(re"(\w)\w").get.captures[-1] == "ab"
+
+    doAssert "abc".match(re"(\w)").get.captureBounds[0].get == 0 .. 0
+    doAssert "abc".match(re"").get.captureBounds[-1].get == 0 .. -1
+    doAssert "abc".match(re"abc").get.captureBounds[-1].get == 0 .. 2
 # }}}
 
 proc getinfo[T](pattern: Regex, opt: cint): T =
@@ -495,8 +502,12 @@ proc matchImpl(str: string, pattern: Regex, start, endpos: int, flags: int): Opt
 
 proc match*(str: string, pattern: Regex, start = 0, endpos = int.high): Option[RegexMatch] =
   ## Like ```find(...)`` <#proc-find>`_, but anchored to the start of the
-  ## string. This means that ``"foo".match(re"f") == true``, but
+  ## string.
-  ## ``"foo".match(re"o") == false``.
+  ##
+  runnableExamples:
+    doAssert "foo".match(re"f").isSome
+    doAssert "foo".match(re"o").isNone
+
   return str.matchImpl(pattern, start, endpos, pcre.ANCHORED)
 
 iterator findIter*(str: string, pattern: Regex, start = 0, endpos = int.high): RegexMatch =
@@ -570,29 +581,34 @@ proc findAll*(str: string, pattern: Regex, start = 0, endpos = int.high): seq[st
 proc contains*(str: string, pattern: Regex, start = 0, endpos = int.high): bool =
   ## Determine if the string contains the given pattern between the end and
   ## start positions:
-  ## -  "abc".contains(re"bc") == true
+  ## This function is equivalent to ``isSome(str.find(pattern, start, endpos))``.
-  ## -  "abc".contains(re"cd") == false
-  ## -  "abc".contains(re"a", start = 1) == false
   ##
-  ## Same as ``isSome(str.find(pattern, start, endpos))``.
+  runnableExamples:
+    doAssert "abc".contains(re"bc") == true
+    doAssert "abc".contains(re"cd") == false
+    doAssert "abc".contains(re"a", start = 1) == false
+
   return isSome(str.find(pattern, start, endpos))
 
 proc split*(str: string, pattern: Regex, maxSplit = -1, start = 0): seq[string] =
   ## Splits the string with the given regex. This works according to the
-  ## rules that Perl and Javascript use:
+  ## rules that Perl and Javascript use.
-  ##
-  ## -  If the match is zero-width, then the string is still split:
-  ##    ``"123".split(r"") == @["1", "2", "3"]``.
-  ##
-  ## -  If the pattern has a capture in it, it is added after the string
-  ##    split: ``"12".split(re"(\d)") == @["", "1", "", "2", ""]``.
-  ##
-  ## -  If ``maxsplit != -1``, then the string will only be split
-  ##    ``maxsplit - 1`` times. This means that there will be ``maxsplit``
-  ##    strings in the output seq.
-  ##    ``"1.2.3".split(re"\.", maxsplit = 2) == @["1", "2.3"]``
   ##
   ## ``start`` behaves the same as in ```find(...)`` <#proc-find>`_.
+  ##
+  runnableExamples:
+    # -  If the match is zero-width, then the string is still split:
+    doAssert "123".split(re"") == @["1", "2", "3"]
+
+    # -  If the pattern has a capture in it, it is added after the string
+    #    split:
+    doAssert "12".split(re"(\d)") == @["", "1", "", "2", ""]
+
+    # -  If ``maxsplit != -1``, then the string will only be split
+    #    ``maxsplit - 1`` times. This means that there will be ``maxsplit``
+    #    strings in the output seq.
+    doAssert "1.2.3".split(re"\.", maxsplit = 2) == @["1", "2.3"]
+
   result = @[]
   var lastIdx = start
   var splits = 0