mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2026-06-05 03:14:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Replace double backticks with single backticks - Part 4 out of ~7 (#17216)

Browse Source
This commit is contained in:
Danil Yarantsev
2021-03-02 05:00:58 +03:00
committed by GitHub
parent 4f97898753
commit 285539c87a
6 changed files with 122 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
lib/packages/docutils/highlite.nim
View File

@@ -11,7 +11,7 @@
## Currently only few languages are supported, other languages may be added.
## The interface supports one language nested in another.
##
## **Note:** Import ``packages/docutils/highlite`` to use this module
## **Note:** Import `packages/docutils/highlite` to use this module
##
## You can use this to build your own syntax highlighting, check this example:
##
@@ -34,7 +34,7 @@
## echo toknizr.kind # All the kinds of tokens can be processed here.
## echo substr(code, toknizr.start, toknizr.length + toknizr.start - 1)
##
## The proc ``getSourceLanguage`` can get the language ``enum`` from a string:
## The proc `getSourceLanguage` can get the language `enum` from a string:
##
## .. code::nim
## for l in ["C", "c++", "jAvA", "Nim", "c#"]: echo getSourceLanguage(l)

90
lib/pure/json.nim
View File

@@ -20,18 +20,18 @@
## Parsing JSON
## ------------
##
## JSON often arrives into your program (via an API or a file) as a ``string``.
## JSON often arrives into your program (via an API or a file) as a `string`.
## The first step is to change it from its serialized form into a nested object
## structure called a ``JsonNode``.
## structure called a `JsonNode`.
##
## The ``parseJson`` procedure takes a string containing JSON and returns a
## ``JsonNode`` object. This is an object variant and it is either a
## ``JObject``, ``JArray``, ``JString``, ``JInt``, ``JFloat``, ``JBool`` or
## ``JNull``. You check the kind of this object variant by using the ``kind``
## The `parseJson` procedure takes a string containing JSON and returns a
## `JsonNode` object. This is an object variant and it is either a
## `JObject`, `JArray`, `JString`, `JInt`, `JFloat`, `JBool` or
## `JNull`. You check the kind of this object variant by using the `kind`
## accessor.
##
## For a ``JsonNode`` who's kind is ``JObject``, you can access its fields using
## the ``[]`` operator. The following example shows how to do this:
## For a `JsonNode` who's kind is `JObject`, you can access its fields using
## the `[]` operator. The following example shows how to do this:
##
## .. code-block:: Nim
## import std/json
@@ -44,15 +44,15 @@
## Reading values
## --------------
##
## Once you have a ``JsonNode``, retrieving the values can then be achieved
## Once you have a `JsonNode`, retrieving the values can then be achieved
## by using one of the helper procedures, which include:
##
## * ``getInt``
## * ``getFloat``
## * ``getStr``
## * ``getBool``
## * `getInt`
## * `getFloat`
## * `getStr`
## * `getBool`
##
## To retrieve the value of ``"key"`` you can do the following:
## To retrieve the value of `"key"` you can do the following:
##
## .. code-block:: Nim
## import std/json
@@ -61,15 +61,15 @@
##
## doAssert jsonNode["key"].getFloat() == 3.14
##
## **Important:** The ``[]`` operator will raise an exception when the
## **Important:** The `[]` operator will raise an exception when the
## specified field does not exist.
##
## Handling optional keys
## ----------------------
##
## By using the ``{}`` operator instead of ``[]``, it will return ``nil``
## when the field is not found. The ``get``-family of procedures will return a
## type's default value when called on ``nil``.
## By using the `{}` operator instead of `[]`, it will return `nil`
## when the field is not found. The `get`-family of procedures will return a
## type's default value when called on `nil`.
##
## .. code-block:: Nim
## import std/json
@@ -84,8 +84,8 @@
## Using default values
## --------------------
##
## The ``get``-family helpers also accept an additional parameter which allow
## you to fallback to a default value should the key's values be ``null``:
## The `get`-family helpers also accept an additional parameter which allow
## you to fallback to a default value should the key's values be `null`:
##
## .. code-block:: Nim
## import std/json
@@ -100,7 +100,7 @@
## -------------
##
## In addition to reading dynamic data, Nim can also unmarshal JSON directly
## into a type with the ``to`` macro.
## into a type with the `to` macro.
##
## Note: Use `Option <options.html#Option>`_ for keys sometimes missing in json
## responses, and backticks around keys with a reserved keyword as name.
@@ -123,7 +123,7 @@
## Creating JSON
## =============
##
## This module can also be used to comfortably create JSON using the ``%*``
## This module can also be used to comfortably create JSON using the `%*`
## operator:
##
## .. code-block:: nim
@@ -201,7 +201,7 @@ proc newJString*(s: string): JsonNode =
proc newJRawNumber(s: string): JsonNode =
## Creates a "raw JS number", that is a number that does not
## fit into Nim's ``BiggestInt`` field. This is really a `JString`
## fit into Nim's `BiggestInt` field. This is really a `JString`
## with the additional information that it should be converted back
## to the string representation without the quotes.
result = JsonNode(kind: JString, str: s, isUnquoted: true)
@@ -237,28 +237,28 @@ proc newJArray*(): JsonNode =
proc getStr*(n: JsonNode, default: string = ""): string =
## Retrieves the string value of a `JString JsonNode`.
##
## Returns ``default`` if ``n`` is not a ``JString``, or if ``n`` is nil.
## Returns `default` if `n` is not a `JString`, or if `n` is nil.
if n.isNil or n.kind != JString: return default
else: return n.str
proc getInt*(n: JsonNode, default: int = 0): int =
## Retrieves the int value of a `JInt JsonNode`.
##
## Returns ``default`` if ``n`` is not a ``JInt``, or if ``n`` is nil.
## Returns `default` if `n` is not a `JInt`, or if `n` is nil.
if n.isNil or n.kind != JInt: return default
else: return int(n.num)
proc getBiggestInt*(n: JsonNode, default: BiggestInt = 0): BiggestInt =
## Retrieves the BiggestInt value of a `JInt JsonNode`.
##
## Returns ``default`` if ``n`` is not a ``JInt``, or if ``n`` is nil.
## Returns `default` if `n` is not a `JInt`, or if `n` is nil.
if n.isNil or n.kind != JInt: return default
else: return n.num
proc getFloat*(n: JsonNode, default: float = 0.0): float =
## Retrieves the float value of a `JFloat JsonNode`.
##
## Returns ``default`` if ``n`` is not a ``JFloat`` or ``JInt``, or if ``n`` is nil.
## Returns `default` if `n` is not a `JFloat` or `JInt`, or if `n` is nil.
if n.isNil: return default
case n.kind
of JFloat: return n.fnum
@@ -268,7 +268,7 @@ proc getFloat*(n: JsonNode, default: float = 0.0): float =
proc getBool*(n: JsonNode, default: bool = false): bool =
## Retrieves the bool value of a `JBool JsonNode`.
##
## Returns ``default`` if ``n`` is not a ``JBool``, or if ``n`` is nil.
## Returns `default` if `n` is not a `JBool`, or if `n` is nil.
if n.isNil or n.kind != JBool: return default
else: return n.bval
@@ -277,14 +277,14 @@ proc getFields*(n: JsonNode,
OrderedTable[string, JsonNode] =
## Retrieves the key, value pairs of a `JObject JsonNode`.
##
## Returns ``default`` if ``n`` is not a ``JObject``, or if ``n`` is nil.
## Returns `default` if `n` is not a `JObject`, or if `n` is nil.
if n.isNil or n.kind != JObject: return default
else: return n.fields
proc getElems*(n: JsonNode, default: seq[JsonNode] = @[]): seq[JsonNode] =
## Retrieves the array of a `JArray JsonNode`.
##
## Returns ``default`` if ``n`` is not a ``JArray``, or if ``n`` is nil.
## Returns `default` if `n` is not a `JArray`, or if `n` is nil.
if n.isNil or n.kind != JArray: return default
else: return n.elems
@@ -340,13 +340,13 @@ proc `%`*[T](elements: openArray[T]): JsonNode =
for elem in elements: result.add(%elem)
proc `%`*[T](table: Table[string, T]|OrderedTable[string, T]): JsonNode =
## Generic constructor for JSON data. Creates a new ``JObject JsonNode``.
## Generic constructor for JSON data. Creates a new `JObject JsonNode`.
result = newJObject()
for k, v in table: result[k] = %v
proc `%`*[T](opt: Option[T]): JsonNode =
## Generic constructor for JSON data. Creates a new ``JNull JsonNode``
## if ``opt`` is empty, otherwise it delegates to the underlying value.
## Generic constructor for JSON data. Creates a new `JNull JsonNode`
## if `opt` is empty, otherwise it delegates to the underlying value.
if opt.isSome: %opt.get else: newJNull()
when false:
@@ -355,8 +355,8 @@ when false:
# causing problems later on.
proc `%`*(elements: set[bool]): JsonNode =
## Generic constructor for JSON data. Creates a new `JObject JsonNode`.
## This can only be used with the empty set ``{}`` and is supported
## to prevent the gotcha ``%*{}`` which used to produce an empty
## This can only be used with the empty set `{}` and is supported
## to prevent the gotcha `%*{}` which used to produce an empty
## JSON array.
result = newJObject()
assert false notin elements, "usage error: only empty sets allowed"
@@ -381,7 +381,7 @@ proc `%`*(o: ref object): JsonNode =
proc `%`*(o: enum): JsonNode =
## Construct a JsonNode that represents the specified enum value as a
## string. Creates a new ``JString JsonNode``.
## string. Creates a new `JString JsonNode`.
result = %($o)
proc toJsonImpl(x: NimNode): NimNode {.compileTime.} =
@@ -526,7 +526,7 @@ proc contains*(node: JsonNode, val: JsonNode): bool =
proc `{}`*(node: JsonNode, keys: varargs[string]): JsonNode =
## Traverses the node and gets the given value. If any of the
## keys do not exist, returns ``nil``. Also returns ``nil`` if one of the
## keys do not exist, returns `nil`. Also returns `nil` if one of the
## intermediate data structures is not an object.
##
## This proc can be used to create tree structures on the
@@ -544,7 +544,7 @@ proc `{}`*(node: JsonNode, keys: varargs[string]): JsonNode =
proc `{}`*(node: JsonNode, index: varargs[int]): JsonNode =
## Traverses the node and gets the given value. If any of the
## indexes do not exist, returns ``nil``. Also returns ``nil`` if one of the
## indexes do not exist, returns `nil`. Also returns `nil` if one of the
## intermediate data structures is not an array.
result = node
for i in index:
@@ -565,7 +565,7 @@ proc `{}`*(node: JsonNode, key: string): JsonNode =
proc `{}=`*(node: JsonNode, keys: varargs[string], value: JsonNode) =
## Traverses the node and tries to set the value at the given location
## to ``value``. If any of the keys are missing, they are added.
## to `value`. If any of the keys are missing, they are added.
var node = node
for i in 0..(keys.len-2):
if not node.hasKey(keys[i]):
@@ -574,7 +574,7 @@ proc `{}=`*(node: JsonNode, keys: varargs[string], value: JsonNode) =
node[keys[keys.len-1]] = value
proc delete*(obj: JsonNode, key: string) =
## Deletes ``obj[key]``.
## Deletes `obj[key]`.
assert(obj.kind == JObject)
if not obj.fields.hasKey(key):
raise newException(KeyError, "key not in object")
@@ -617,7 +617,7 @@ proc nl(s: var string, ml: bool) =
proc escapeJsonUnquoted*(s: string; result: var string) =
## Converts a string `s` to its JSON representation without quotes.
## Appends to ``result``.
## Appends to `result`.
for c in s:
case c
of '\L': result.add("\\n")
@@ -639,7 +639,7 @@ proc escapeJsonUnquoted*(s: string): string =
proc escapeJson*(s: string; result: var string) =
## Converts a string `s` to its JSON representation with quotes.
## Appends to ``result``.
## Appends to `result`.
result.add("\"")
escapeJsonUnquoted(s, result)
result.add("\"")
@@ -732,12 +732,12 @@ proc pretty*(node: JsonNode, indent = 2): string =
proc toUgly*(result: var string, node: JsonNode) =
## Converts `node` to its JSON Representation, without
## regard for human readability. Meant to improve ``$`` string
## regard for human readability. Meant to improve `$` string
## conversion performance.
##
## JSON representation is stored in the passed `result`
##
## This provides higher efficiency than the ``pretty`` procedure as it
## This provides higher efficiency than the `pretty` procedure as it
## does **not** attempt to format the resulting JSON to make it human readable.
var comma = false
case node.kind:
@@ -873,7 +873,7 @@ iterator parseJsonFragments*(s: Stream, filename: string = ""; rawIntegers = fal
## for nice error messages.
## The JSON fragments are separated by whitespace. This can be substantially
## faster than the comparable loop
## ``for x in splitWhitespace(s): yield parseJson(x)``.
## `for x in splitWhitespace(s): yield parseJson(x)`.
## This closes the stream `s` after it's done.
## If `rawIntegers` is true, integer literals will not be converted to a `JInt`
## field but kept as raw numbers via `JString`.

28
lib/pure/memfiles.nim
View File

@@ -48,8 +48,8 @@ proc mapMem*(m: var MemFile, mode: FileMode = fmRead,
mappedSize = -1, offset = 0, mapFlags = cint(-1)): pointer =
## returns a pointer to a mapped portion of MemFile `m`
##
## ``mappedSize`` of ``-1`` maps to the whole file, and
## ``offset`` must be multiples of the PAGE SIZE of your OS
## `mappedSize` of `-1` maps to the whole file, and
## `offset` must be multiples of the PAGE SIZE of your OS
if mode == fmAppend:
raise newEIO("The append mode is not supported.")
@@ -83,12 +83,12 @@ proc mapMem*(m: var MemFile, mode: FileMode = fmRead,
proc unmapMem*(f: var MemFile, p: pointer, size: int) =
## unmaps the memory region ``(p, <p+size)`` of the mapped file `f`.
## unmaps the memory region `(p, <p+size)` of the mapped file `f`.
## All changes are written back to the file system, if `f` was opened
## with write access.
##
## ``size`` must be of exactly the size that was requested
## via ``mapMem``.
## `size` must be of exactly the size that was requested
## via `mapMem`.
when defined(windows):
if unmapViewOfFile(p) == 0: raiseOSError(osLastError())
else:
@@ -98,21 +98,21 @@ proc unmapMem*(f: var MemFile, p: pointer, size: int) =
proc open*(filename: string, mode: FileMode = fmRead,
mappedSize = -1, offset = 0, newFileSize = -1,
allowRemap = false, mapFlags = cint(-1)): MemFile =
## opens a memory mapped file. If this fails, ``OSError`` is raised.
## opens a memory mapped file. If this fails, `OSError` is raised.
##
## ``newFileSize`` can only be set if the file does not exist and is opened
## `newFileSize` can only be set if the file does not exist and is opened
## with write access (e.g., with fmReadWrite).
##
##``mappedSize`` and ``offset``
##`mappedSize` and `offset`
## can be used to map only a slice of the file.
##
## ``offset`` must be multiples of the PAGE SIZE of your OS
## `offset` must be multiples of the PAGE SIZE of your OS
## (usually 4K or 8K but is unique to your OS)
##
## ``allowRemap`` only needs to be true if you want to call ``mapMem`` on
## `allowRemap` only needs to be true if you want to call `mapMem` on
## the resulting MemFile; else file handles are not kept open.
##
## ``mapFlags`` allows callers to override default choices for memory mapping
## `mapFlags` allows callers to override default choices for memory mapping
## flags with a bitwise mask of a variety of likely platform-specific flags
## which may be ignored or even cause `open` to fail if misspecified.
##
@@ -301,9 +301,9 @@ proc flush*(f: var MemFile; attempts: Natural = 3) =
when defined(posix) or defined(nimdoc):
proc resize*(f: var MemFile, newFileSize: int) {.raises: [IOError, OSError].} =
## resize and re-map the file underlying an ``allowRemap MemFile``.
## resize and re-map the file underlying an `allowRemap MemFile`.
## **Note**: this assumes the entire file is mapped read-write at offset zero.
## Also, the value of ``.mem`` will probably change.
## Also, the value of `.mem` will probably change.
## **Note**: This is not (yet) available on Windows.
when defined(posix):
if f.handle == -1:
@@ -514,7 +514,7 @@ proc newMemMapFileStream*(filename: string, mode: FileMode = fmRead,
## creates a new stream from the file named `filename` with the mode `mode`.
## Raises ## `OSError` if the file cannot be opened. See the `system
## <system.html>`_ module for a list of available FileMode enums.
## ``fileSize`` can only be set if the file does not exist and is opened
## `fileSize` can only be set if the file does not exist and is opened
## with write access (e.g., with fmReadWrite).
var mf: MemFile = open(filename, mode, newFileSize = fileSize)
new(result)

18
lib/pure/mimetypes.nim
View File

@@ -16,7 +16,7 @@ runnableExamples:
## Values can be uppercase too.
doAssert m.getMimetype("MP4") == "video/mp4"
doAssert m.getExt("TEXT/HTML") == "html"
## If values are invalid then ``default`` is returned.
## If values are invalid then `default` is returned.
doAssert m.getMimetype("INVALID") == "text/plain"
doAssert m.getExt("INVALID/NONEXISTENT") == "txt"
doAssert m.getMimetype("") == "text/plain"
@@ -1906,9 +1906,9 @@ func newMimetypes*(): MimeDB =
result.mimes = mimes.newStringTable()
func getMimetype*(mimedb: MimeDB, ext: string, default = "text/plain"): string =
## Gets mimetype which corresponds to ``ext``. Returns ``default`` if ``ext``
## could not be found. ``ext`` can start with an optional dot which is ignored.
## ``ext`` is lowercased before querying ``mimedb``.
## Gets mimetype which corresponds to `ext`. Returns `default` if `ext`
## could not be found. `ext` can start with an optional dot which is ignored.
## `ext` is lowercased before querying `mimedb`.
if ext.startsWith("."):
result = mimedb.mimes.getOrDefault(ext.toLowerAscii.substr(1))
else:
@@ -1917,9 +1917,9 @@ func getMimetype*(mimedb: MimeDB, ext: string, default = "text/plain"): string =
return default
func getExt*(mimedb: MimeDB, mimetype: string, default = "txt"): string =
## Gets extension which corresponds to ``mimetype``. Returns ``default`` if
## ``mimetype`` could not be found. Extensions are returned without the
## leading dot. ``mimetype`` is lowercased before querying ``mimedb``.
## Gets extension which corresponds to `mimetype`. Returns `default` if
## `mimetype` could not be found. Extensions are returned without the
## leading dot. `mimetype` is lowercased before querying `mimedb`.
result = default
let mimeLowered = mimetype.toLowerAscii()
for e, m in mimedb.mimes:
@@ -1928,8 +1928,8 @@ func getExt*(mimedb: MimeDB, mimetype: string, default = "txt"): string =
break
func register*(mimedb: var MimeDB, ext: string, mimetype: string) =
## Adds ``mimetype`` to the ``mimedb``.
## ``mimetype`` and ``ext`` are lowercased before registering on ``mimedb``.
## Adds `mimetype` to the `mimedb`.
## `mimetype` and `ext` are lowercased before registering on `mimedb`.
assert ext.strip.len > 0, "ext argument can not be empty string"
assert mimetype.strip.len > 0, "mimetype argument can not be empty string"
{.noSideEffect.}:

40
lib/pure/parsejson.nim
View File

@@ -8,7 +8,7 @@
#
## This module implements a json parser. It is used
## and exported by the ``json`` standard library
## and exported by the `json` standard library
## module, but can also be used in its own right.
import strutils, lexbase, streams, unicode
@@ -21,13 +21,13 @@ type
jsonString, ## a string literal
jsonInt, ## an integer literal
jsonFloat, ## a float literal
jsonTrue, ## the value ``true``
jsonFalse, ## the value ``false``
jsonNull, ## the value ``null``
jsonObjectStart, ## start of an object: the ``{`` token
jsonObjectEnd, ## end of an object: the ``}`` token
jsonArrayStart, ## start of an array: the ``[`` token
jsonArrayEnd ## end of an array: the ``]`` token
jsonTrue, ## the value `true`
jsonFalse, ## the value `false`
jsonNull, ## the value `null`
jsonObjectStart, ## start of an object: the `{` token
jsonObjectEnd, ## end of an object: the `}` token
jsonArrayStart, ## start of an array: the `[` token
jsonArrayEnd ## end of an array: the `]` token
TokKind* = enum # must be synchronized with TJsonEventKind!
tkError,
@@ -49,12 +49,12 @@ type
errNone, ## no error
errInvalidToken, ## invalid token
errStringExpected, ## string expected
errColonExpected, ## ``:`` expected
errCommaExpected, ## ``,`` expected
errBracketRiExpected, ## ``]`` expected
errCurlyRiExpected, ## ``}`` expected
errQuoteExpected, ## ``"`` or ``'`` expected
errEOC_Expected, ## ``*/`` expected
errColonExpected, ## `:` expected
errCommaExpected, ## `,` expected
errBracketRiExpected, ## `]` expected
errCurlyRiExpected, ## `}` expected
errQuoteExpected, ## `"` or `'` expected
errEOC_Expected, ## `*/` expected
errEofExpected, ## EOF expected
errExprExpected ## expr expected
@@ -71,7 +71,7 @@ type
filename: string
rawStringLiterals: bool
JsonKindError* = object of ValueError ## raised by the ``to`` macro if the
JsonKindError* = object of ValueError ## raised by the `to` macro if the
## JSON kind is incorrect.
JsonParsingError* = object of ValueError ## is raised for a JSON error
@@ -119,18 +119,18 @@ proc close*(my: var JsonParser) {.inline.} =
lexbase.close(my)
proc str*(my: JsonParser): string {.inline.} =
## returns the character data for the events: ``jsonInt``, ``jsonFloat``,
## ``jsonString``
## returns the character data for the events: `jsonInt`, `jsonFloat`,
## `jsonString`
assert(my.kind in {jsonInt, jsonFloat, jsonString})
return my.a
proc getInt*(my: JsonParser): BiggestInt {.inline.} =
## returns the number for the event: ``jsonInt``
## returns the number for the event: `jsonInt`
assert(my.kind == jsonInt)
return parseBiggestInt(my.a)
proc getFloat*(my: JsonParser): float {.inline.} =
## returns the number for the event: ``jsonFloat``
## returns the number for the event: `jsonFloat`
assert(my.kind == jsonFloat)
return parseFloat(my.a)
@@ -151,7 +151,7 @@ proc getFilename*(my: JsonParser): string {.inline.} =
result = my.filename
proc errorMsg*(my: JsonParser): string =
## returns a helpful error message for the event ``jsonError``
## returns a helpful error message for the event `jsonError`
assert(my.kind == jsonError)
result = "$1($2, $3) Error: $4" % [
my.filename, $getLine(my), $getColumn(my), errorMessages[my.err]]

64
lib/pure/parseopt.nim
View File

@@ -14,21 +14,21 @@
## Supported Syntax
## ================
##
## The following syntax is supported when arguments for the ``shortNoVal`` and
## ``longNoVal`` parameters, which are
## The following syntax is supported when arguments for the `shortNoVal` and
## `longNoVal` parameters, which are
## `described later<#shortnoval-and-longnoval>`_, are not provided:
##
## 1. Short options: ``-abcd``, ``-e:5``, ``-e=5``
## 2. Long options: ``--foo:bar``, ``--foo=bar``, ``--foo``
## 3. Arguments: everything that does not start with a ``-``
## 1. Short options: `-abcd`, `-e:5`, `-e=5`
## 2. Long options: `--foo:bar`, `--foo=bar`, `--foo`
## 3. Arguments: everything that does not start with a `-`
##
## These three kinds of tokens are enumerated in the
## `CmdLineKind enum<#CmdLineKind>`_.
##
## When option values begin with ':' or '=', they need to be doubled up (as in
## ``--delim::``) or alternated (as in ``--delim=:``).
## `--delim::`) or alternated (as in `--delim=:`).
##
## The ``--`` option, commonly used to denote that every token that follows is
## The `--` option, commonly used to denote that every token that follows is
## an argument, is interpreted as a long option, and its name is the empty
## string.
##
@@ -39,12 +39,12 @@
## created with `initOptParser<#initOptParser,string,set[char],seq[string]>`_,
## and `next<#next,OptParser>`_ advances the parser by one token.
##
## For each token, the parser's ``kind``, ``key``, and ``val`` fields give
## information about that token. If the token is a long or short option, ``key``
## is the option's name, and ``val`` is either the option's value, if provided,
## or the empty string. For arguments, the ``key`` field contains the argument
## itself, and ``val`` is unused. To check if the end of the command line has
## been reached, check if ``kind`` is equal to ``cmdEnd``.
## For each token, the parser's `kind`, `key`, and `val` fields give
## information about that token. If the token is a long or short option, `key`
## is the option's name, and `val` is either the option's value, if provided,
## or the empty string. For arguments, the `key` field contains the argument
## itself, and `val` is unused. To check if the end of the command line has
## been reached, check if `kind` is equal to `cmdEnd`.
##
## Here is an example:
##
@@ -75,27 +75,27 @@
## The `getopt iterator<#getopt.i,OptParser>`_, which is provided for
## convenience, can be used to iterate through all command line options as well.
##
## ``shortNoVal`` and ``longNoVal``
## ================================
## `shortNoVal` and `longNoVal`
## ============================
##
## The optional ``shortNoVal`` and ``longNoVal`` parameters present in
## The optional `shortNoVal` and `longNoVal` parameters present in
## `initOptParser<#initOptParser,string,set[char],seq[string]>`_ are for
## specifying which short and long options do not accept values.
##
## When ``shortNoVal`` is non-empty, users are not required to separate short
## When `shortNoVal` is non-empty, users are not required to separate short
## options and their values with a ':' or '=' since the parser knows which
## options accept values and which ones do not. This behavior also applies for
## long options if ``longNoVal`` is non-empty. For short options, ``-j4``
## becomes supported syntax, and for long options, ``--foo bar`` becomes
## long options if `longNoVal` is non-empty. For short options, `-j4`
## becomes supported syntax, and for long options, `--foo bar` becomes
## supported. This is in addition to the `previously mentioned
## syntax<#supported-syntax>`_. Users can still separate options and their
## values with ':' or '=', but that becomes optional.
##
## As more options which do not accept values are added to your program,
## remember to amend ``shortNoVal`` and ``longNoVal`` accordingly.
## remember to amend `shortNoVal` and `longNoVal` accordingly.
##
## The following example illustrates the difference between having an empty
## ``shortNoVal`` and ``longNoVal``, which is the default, and providing
## `shortNoVal` and `longNoVal`, which is the default, and providing
## arguments for those two parameters:
##
## .. code-block::
@@ -197,11 +197,11 @@ proc initOptParser*(cmdline = "", shortNoVal: set[char] = {},
allowWhitespaceAfterColon = true): OptParser =
## Initializes the command line parser.
##
## If ``cmdline == ""``, the real command line as provided by the
## ``os`` module is retrieved instead if it is available. If the
## If `cmdline == ""`, the real command line as provided by the
## `os` module is retrieved instead if it is available. If the
## command line is not available, a `ValueError` will be raised.
##
## ``shortNoVal`` and ``longNoVal`` are used to specify which options
## `shortNoVal` and `longNoVal` are used to specify which options
## do not take values. See the `documentation about these
## parameters<#shortnoval-and-longnoval>`_ for more information on
## how this affects parsing.
@@ -242,8 +242,8 @@ proc initOptParser*(cmdline: seq[string], shortNoVal: set[char] = {},
allowWhitespaceAfterColon = true): OptParser =
## Initializes the command line parser.
##
## If ``cmdline.len == 0``, the real command line as provided by the
## ``os`` module is retrieved instead if it is available. If the
## If `cmdline.len == 0`, the real command line as provided by the
## `os` module is retrieved instead if it is available. If the
## command line is not available, a `ValueError` will be raised.
## Behavior of the other parameters remains the same as in
## `initOptParser(string, ...)
@@ -310,8 +310,8 @@ proc handleShortOption(p: var OptParser; cmd: string) =
proc next*(p: var OptParser) {.rtl, extern: "npo$1".} =
## Parses the next token.
##
## ``p.kind`` describes what kind of token has been parsed. ``p.key`` and
## ``p.val`` are set accordingly.
## `p.kind` describes what kind of token has been parsed. `p.key` and
## `p.val` are set accordingly.
runnableExamples:
var p = initOptParser("--left -r:2 file.txt")
p.next()
@@ -420,7 +420,7 @@ iterator getopt*(p: var OptParser): tuple[kind: CmdLineKind, key,
## Convenience iterator for iterating over the given
## `OptParser<#OptParser>`_.
##
## There is no need to check for ``cmdEnd`` while iterating.
## There is no need to check for `cmdEnd` while iterating.
##
## See also:
## * `initOptParser proc<#initOptParser,string,set[char],seq[string]>`_
@@ -461,14 +461,14 @@ iterator getopt*(cmdline: seq[string] = @[],
##
## This creates a new `OptParser<#OptParser>`_. If no command line
## arguments are provided, the real command line as provided by the
## ``os`` module is retrieved instead.
## `os` module is retrieved instead.
##
## ``shortNoVal`` and ``longNoVal`` are used to specify which options
## `shortNoVal` and `longNoVal` are used to specify which options
## do not take values. See the `documentation about these
## parameters<#shortnoval-and-longnoval>`_ for more information on
## how this affects parsing.
##
## There is no need to check for ``cmdEnd`` while iterating.
## There is no need to check for `cmdEnd` while iterating.
##
## See also:
## * `initOptParser proc<#initOptParser,seq[string],set[char],seq[string]>`_