uri module uses runnableExamples (#16982)

lib/pure/uri.nim

@@ -14,40 +14,33 @@
 ## as a locator, a name, or both. The term "Uniform Resource Locator"
 ## (URL) refers to the subset of URIs.
 ##
-## Basic usage
-## ===========
-##
-## Combine URIs
-## -------------
-## .. code-block::
-##    import uri
-##    let host = parseUri("https://nim-lang.org")
-##    let blog = "/blog.html"
-##    let bloguri = host / blog
-##    assert $host == "https://nim-lang.org"
-##    assert $bloguri == "https://nim-lang.org/blog.html"
-##
-## Access URI item
-## ---------------
-## .. code-block::
-##    import uri
-##    let res = parseUri("sftp://127.0.0.1:4343")
-##    if isAbsolute(res):
-##      assert res.port == "4343"
-##    else:
-##      echo "Wrong format"
-##
-## Data URI Base64
-## ---------------
-##
-## .. code-block::nim
-##    doAssert getDataUri("Hello World", "text/plain") == "data:text/plain;charset=utf-8;base64,SGVsbG8gV29ybGQ="
-##    doAssert getDataUri("Nim", "text/plain") == "data:text/plain;charset=utf-8;base64,Tmlt"
+## # Basic usage
 
-import std/private/since
 
-import strutils, parseutils, base64
-import std/private/decode_helpers
+## ## Combine URIs
+runnableExamples:
+  let host = parseUri("https://nim-lang.org")
+  let blog = "/blog.html"
+  let bloguri = host / blog
+  assert $host == "https://nim-lang.org"
+  assert $bloguri == "https://nim-lang.org/blog.html"
+
+## ## Access URI item
+runnableExamples:
+  let res = parseUri("sftp://127.0.0.1:4343")
+  if isAbsolute(res):
+    assert res.port == "4343"
+  else:
+    echo "Wrong format"
+
+## ## Data URI Base64
+runnableExamples:
+  doAssert getDataUri("Hello World", "text/plain") == "data:text/plain;charset=utf-8;base64,SGVsbG8gV29ybGQ="
+  doAssert getDataUri("Nim", "text/plain") == "data:text/plain;charset=utf-8;base64,Tmlt"
+
+
+import std/[strutils, parseutils, base64]
+import std/private/[since, decode_helpers]
 
 
 type
@@ -63,20 +56,20 @@ type
 
 
 proc uriParseError*(msg: string) {.noreturn.} =
-  ## Raises a ``UriParseError`` exception with message `msg`.
+  ## Raises a `UriParseError` exception with message `msg`.
   raise newException(UriParseError, msg)
 
 func encodeUrl*(s: string, usePlus = true): string =
   ## Encodes a URL according to RFC3986.
   ##
   ## This means that characters in the set
-  ## ``{'a'..'z', 'A'..'Z', '0'..'9', '-', '.', '_', '~'}`` are
+  ## `{'a'..'z', 'A'..'Z', '0'..'9', '-', '.', '_', '~'}` are
   ## carried over to the result.
-  ## All other characters are encoded as ``%xx`` where ``xx``
+  ## All other characters are encoded as `%xx` where `xx`
   ## denotes its hexadecimal value.
   ##
-  ## As a special rule, when the value of ``usePlus`` is true,
-  ## spaces are encoded as ``+`` instead of ``%20``.
+  ## As a special rule, when the value of `usePlus` is true,
+  ## spaces are encoded as `+` instead of `%20`.
   ##
   ## **See also:**
   ## * `decodeUrl func<#decodeUrl,string>`_
@@ -98,12 +91,12 @@ func encodeUrl*(s: string, usePlus = true): string =
 func decodeUrl*(s: string, decodePlus = true): string =
   ## Decodes a URL according to RFC3986.
   ##
-  ## This means that any ``%xx`` (where ``xx`` denotes a hexadecimal
-  ## value) are converted to the character with ordinal number ``xx``,
+  ## This means that any `%xx` (where `xx` denotes a hexadecimal
+  ## value) are converted to the character with ordinal number `xx`,
   ## and every other character is carried over.
-  ## If ``xx`` is not a valid hexadecimal value, it is left intact.
+  ## If `xx` is not a valid hexadecimal value, it is left intact.
   ##
-  ## As a special rule, when the value of ``decodePlus`` is true, ``+``
+  ## As a special rule, when the value of `decodePlus` is true, `+`
   ## characters are converted to a space.
   ##
   ## **See also:**
@@ -136,12 +129,12 @@ func encodeQuery*(query: openArray[(string, string)], usePlus = true,
     omitEq = true): string =
   ## Encodes a set of (key, value) parameters into a URL query string.
   ##
-  ## Every (key, value) pair is URL-encoded and written as ``key=value``. If the
-  ## value is an empty string then the ``=`` is omitted, unless ``omitEq`` is
+  ## Every (key, value) pair is URL-encoded and written as `key=value`. If the
+  ## value is an empty string then the `=` is omitted, unless `omitEq` is
   ## false.
-  ## The pairs are joined together by a ``&`` character.
+  ## The pairs are joined together by a `&` character.
   ##
-  ## The ``usePlus`` parameter is passed down to the `encodeUrl` function that
+  ## The `usePlus` parameter is passed down to the `encodeUrl` function that
   ## is used for the URL encoding of the string values.
   ##
   ## **See also:**
@@ -251,8 +244,8 @@ func parsePath(uri: string, i: var int, result: var Uri) =
     i.inc parseUntil(uri, result.anchor, {}, i)
 
 func initUri*(): Uri =
-  ## Initializes a URI with ``scheme``, ``username``, ``password``,
-  ## ``hostname``, ``port``, ``path``, ``query`` and ``anchor``.
+  ## Initializes a URI with `scheme`, `username`, `password`,
+  ## `hostname`, `port`, `path`, `query` and `anchor`.
   ##
   ## **See also:**
   ## * `Uri type <#Uri>`_ for available fields in the URI type
@@ -263,8 +256,8 @@ func initUri*(): Uri =
                 path: "", query: "", anchor: "")
 
 func initUri*(isIpv6: bool): Uri {.since: (1, 3, 5).} =
-  ## Initializes a URI with ``scheme``, ``username``, ``password``,
-  ## ``hostname``, ``port``, ``path``, ``query``, ``anchor`` and ``isIpv6``.
+  ## Initializes a URI with `scheme`, `username`, `password`,
+  ## `hostname`, `port`, `path`, `query`, `anchor` and `isIpv6`.
   ##
   ## **See also:**
   ## * `Uri type <#Uri>`_ for available fields in the URI type
@@ -303,7 +296,7 @@ func parseUri*(uri: string, result: var Uri) =
   # Check if this is a reference URI (relative URI)
   let doubleSlash = uri.len > 1 and uri[1] == '/'
   if i < uri.len and uri[i] == '/':
-    # Make sure ``uri`` doesn't begin with '//'.
+    # Make sure `uri` doesn't begin with '//'.
     if not doubleSlash:
       parsePath(uri, i, result)
       return