jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Replace double backticks with single backticks - Part 2 out of ~6 (#17206)

Browse source
This commit is contained in:
Danil Yarantsev 2021-03-01 10:15:26 +03:00 • committed by GitHub
commit 82d8e9bff3
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
10 changed files with 136 additions and 136 deletions
Download patch file Download diff file Expand all files Collapse all files

158
lib/core/macros.nim
View file

@ -124,7 +124,7 @@ type
NimIdent* {.deprecated.} = object of RootObj NimIdent* {.deprecated.} = object of RootObj
## Represents a Nim identifier in the AST. **Note**: This is only ## Represents a Nim identifier in the AST. **Note**: This is only
## rarely useful, for identifier construction from a string ## rarely useful, for identifier construction from a string
## use ``ident"abc"``. ## use `ident"abc"`.
NimSymObj = object # hidden NimSymObj = object # hidden
NimSym* {.deprecated.} = ref NimSymObj NimSym* {.deprecated.} = ref NimSymObj
@ -193,8 +193,8 @@ proc `[]=`*(n: NimNode, i: BackwardsIndex, child: NimNode) =
n[n.len - i.int] = child n[n.len - i.int] = child
template `or`*(x, y: NimNode): NimNode = template `or`*(x, y: NimNode): NimNode =
## Evaluate ``x`` and when it is not an empty node, return ## Evaluate `x` and when it is not an empty node, return
## it. Otherwise evaluate to ``y``. Can be used to chain several ## it. Otherwise evaluate to `y`. Can be used to chain several
## expressions to get the first expression that is not empty. ## expressions to get the first expression that is not empty.
## ##
## .. code-block:: nim ## .. code-block:: nim
@ -291,11 +291,11 @@ proc getType*(n: NimNode): NimNode {.magic: "NGetType", noSideEffect.}
## kind of type it is, call `typeKind` on getType's result. ## kind of type it is, call `typeKind` on getType's result.
proc getType*(n: typedesc): NimNode {.magic: "NGetType", noSideEffect.} proc getType*(n: typedesc): NimNode {.magic: "NGetType", noSideEffect.}
## Version of ``getType`` which takes a ``typedesc``. ## Version of `getType` which takes a `typedesc`.
proc typeKind*(n: NimNode): NimTypeKind {.magic: "NGetType", noSideEffect.} proc typeKind*(n: NimNode): NimTypeKind {.magic: "NGetType", noSideEffect.}
## Returns the type kind of the node 'n' that should represent a type, that ## Returns the type kind of the node 'n' that should represent a type, that
## means the node should have been obtained via ``getType``. ## means the node should have been obtained via `getType`.
proc getTypeInst*(n: NimNode): NimNode {.magic: "NGetType", noSideEffect.} = proc getTypeInst*(n: NimNode): NimNode {.magic: "NGetType", noSideEffect.} =
## Returns the `type`:idx: of a node in a form matching the way the ## Returns the `type`:idx: of a node in a form matching the way the
@ -316,12 +316,12 @@ proc getTypeInst*(n: NimNode): NimNode {.magic: "NGetType", noSideEffect.} =
doAssert(dumpTypeInst(c) == "Vec[4, float32]") doAssert(dumpTypeInst(c) == "Vec[4, float32]")
proc getTypeInst*(n: typedesc): NimNode {.magic: "NGetType", noSideEffect.} proc getTypeInst*(n: typedesc): NimNode {.magic: "NGetType", noSideEffect.}
## Version of ``getTypeInst`` which takes a ``typedesc``. ## Version of `getTypeInst` which takes a `typedesc`.
proc getTypeImpl*(n: NimNode): NimNode {.magic: "NGetType", noSideEffect.} = proc getTypeImpl*(n: NimNode): NimNode {.magic: "NGetType", noSideEffect.} =
## Returns the `type`:idx: of a node in a form matching the implementation ## Returns the `type`:idx: of a node in a form matching the implementation
## of the type. Any intermediate aliases are expanded to arrive at the final ## of the type. Any intermediate aliases are expanded to arrive at the final
## type implementation. You can instead use ``getImpl`` on a symbol if you ## type implementation. You can instead use `getImpl` on a symbol if you
## want to find the intermediate aliases. ## want to find the intermediate aliases.
runnableExamples: runnableExamples:
type type
@ -356,7 +356,7 @@ proc symBodyHash*(s: NimNode): string {.noSideEffect.} =
discard discard
proc getTypeImpl*(n: typedesc): NimNode {.magic: "NGetType", noSideEffect.} proc getTypeImpl*(n: typedesc): NimNode {.magic: "NGetType", noSideEffect.}
## Version of ``getTypeImpl`` which takes a ``typedesc``. ## Version of `getTypeImpl` which takes a `typedesc`.
proc `intVal=`*(n: NimNode, val: BiggestInt) {.magic: "NSetIntVal", noSideEffect.} proc `intVal=`*(n: NimNode, val: BiggestInt) {.magic: "NSetIntVal", noSideEffect.}
proc `floatVal=`*(n: NimNode, val: BiggestFloat) {.magic: "NSetFloatVal", noSideEffect.} proc `floatVal=`*(n: NimNode, val: BiggestFloat) {.magic: "NSetFloatVal", noSideEffect.}
@ -386,7 +386,7 @@ proc newNimNode*(kind: NimNodeKind,
{.magic: "NNewNimNode", noSideEffect.} {.magic: "NNewNimNode", noSideEffect.}
## Creates a new AST node of the specified kind. ## Creates a new AST node of the specified kind.
## ##
## The ``lineInfoFrom`` parameter is used for line information when the ## The `lineInfoFrom` parameter is used for line information when the
## produced code crashes. You should ensure that it is set to a node that ## produced code crashes. You should ensure that it is set to a node that
## you are transforming. ## you are transforming.
@ -394,7 +394,7 @@ proc copyNimNode*(n: NimNode): NimNode {.magic: "NCopyNimNode", noSideEffect.}
proc copyNimTree*(n: NimNode): NimNode {.magic: "NCopyNimTree", noSideEffect.} proc copyNimTree*(n: NimNode): NimNode {.magic: "NCopyNimTree", noSideEffect.}
proc error*(msg: string, n: NimNode = nil) {.magic: "NError", benign.} proc error*(msg: string, n: NimNode = nil) {.magic: "NError", benign.}
## Writes an error message at compile time. The optional ``n: NimNode`` ## Writes an error message at compile time. The optional `n: NimNode`
## parameter is used as the source for file and line number information in ## parameter is used as the source for file and line number information in
## the compilation error message. ## the compilation error message.
@ -435,13 +435,13 @@ proc newIdentNode*(i: NimIdent): NimNode {.compileTime, deprecated.} =
proc newIdentNode*(i: string): NimNode {.magic: "StrToIdent", noSideEffect.} proc newIdentNode*(i: string): NimNode {.magic: "StrToIdent", noSideEffect.}
## Creates an identifier node from `i`. It is simply an alias for ## Creates an identifier node from `i`. It is simply an alias for
## ``ident(string)``. Use that, it's shorter. ## `ident(string)`. Use that, it's shorter.
proc ident*(name: string): NimNode {.magic: "StrToIdent", noSideEffect.} proc ident*(name: string): NimNode {.magic: "StrToIdent", noSideEffect.}
## Create a new ident node from a string. ## Create a new ident node from a string.
type type
BindSymRule* = enum ## specifies how ``bindSym`` behaves BindSymRule* = enum ## specifies how `bindSym` behaves
brClosed, ## only the symbols in current scope are bound brClosed, ## only the symbols in current scope are bound
brOpen, ## open wrt overloaded symbols, but may be a single brOpen, ## open wrt overloaded symbols, but may be a single
## symbol if not ambiguous (the rules match that of ## symbol if not ambiguous (the rules match that of
@ -454,12 +454,12 @@ proc bindSym*(ident: string | NimNode, rule: BindSymRule = brClosed): NimNode {.
magic: "NBindSym", noSideEffect.} magic: "NBindSym", noSideEffect.}
## Creates a node that binds `ident` to a symbol node. The bound symbol ## Creates a node that binds `ident` to a symbol node. The bound symbol
## may be an overloaded symbol. ## may be an overloaded symbol.
## if `ident` is a NimNode, it must have ``nnkIdent`` kind. ## if `ident` is a NimNode, it must have `nnkIdent` kind.
## If ``rule == brClosed`` either an ``nnkClosedSymChoice`` tree is ## If `rule == brClosed` either an `nnkClosedSymChoice` tree is
## returned or ``nnkSym`` if the symbol is not ambiguous. ## returned or `nnkSym` if the symbol is not ambiguous.
## If ``rule == brOpen`` either an ``nnkOpenSymChoice`` tree is ## If `rule == brOpen` either an `nnkOpenSymChoice` tree is
## returned or ``nnkSym`` if the symbol is not ambiguous. ## returned or `nnkSym` if the symbol is not ambiguous.
## If ``rule == brForceOpen`` always an ``nnkOpenSymChoice`` tree is ## If `rule == brForceOpen` always an `nnkOpenSymChoice` tree is
## returned even if the symbol is not ambiguous. ## returned even if the symbol is not ambiguous.
## ##
## Experimental feature: ## Experimental feature:
@ -502,10 +502,10 @@ proc getColumn(arg: NimNode): int {.magic: "NLineInfo", noSideEffect.}
proc getFile(arg: NimNode): string {.magic: "NLineInfo", noSideEffect.} proc getFile(arg: NimNode): string {.magic: "NLineInfo", noSideEffect.}
proc copyLineInfo*(arg: NimNode, info: NimNode) {.magic: "NLineInfo", noSideEffect.} proc copyLineInfo*(arg: NimNode, info: NimNode) {.magic: "NLineInfo", noSideEffect.}
## Copy lineinfo from ``info``. ## Copy lineinfo from `info`.
proc lineInfoObj*(n: NimNode): LineInfo {.compileTime.} = proc lineInfoObj*(n: NimNode): LineInfo {.compileTime.} =
## Returns ``LineInfo`` of ``n``, using absolute path for ``filename``. ## Returns `LineInfo` of `n`, using absolute path for `filename`.
result = LineInfo(filename: n.getFile, line: n.getLine, column: n.getColumn) result = LineInfo(filename: n.getFile, line: n.getLine, column: n.getColumn)
proc lineInfo*(arg: NimNode): string {.compileTime.} = proc lineInfo*(arg: NimNode): string {.compileTime.} =
@ -524,14 +524,14 @@ proc internalErrorFlag*(): string {.magic: "NError", noSideEffect.}
proc parseExpr*(s: string): NimNode {.noSideEffect, compileTime.} = proc parseExpr*(s: string): NimNode {.noSideEffect, compileTime.} =
## Compiles the passed string to its AST representation. ## Compiles the passed string to its AST representation.
## Expects a single expression. Raises ``ValueError`` for parsing errors. ## Expects a single expression. Raises `ValueError` for parsing errors.
result = internalParseExpr(s) result = internalParseExpr(s)
let x = internalErrorFlag() let x = internalErrorFlag()
if x.len > 0: raise newException(ValueError, x) if x.len > 0: raise newException(ValueError, x)
proc parseStmt*(s: string): NimNode {.noSideEffect, compileTime.} = proc parseStmt*(s: string): NimNode {.noSideEffect, compileTime.} =
## Compiles the passed string to its AST representation. ## Compiles the passed string to its AST representation.
## Expects one or more statements. Raises ``ValueError`` for parsing errors. ## Expects one or more statements. Raises `ValueError` for parsing errors.
result = internalParseStmt(s) result = internalParseStmt(s)
let x = internalErrorFlag() let x = internalErrorFlag()
if x.len > 0: raise newException(ValueError, x) if x.len > 0: raise newException(ValueError, x)
@ -641,7 +641,7 @@ proc expectLen*(n: NimNode, len: int) {.compileTime.} =
if n.len != len: error("Expected a node with " & $len & " children, got " & $n.len, n) if n.len != len: error("Expected a node with " & $len & " children, got " & $n.len, n)
proc expectLen*(n: NimNode, min, max: int) {.compileTime.} = proc expectLen*(n: NimNode, min, max: int) {.compileTime.} =
## Checks that `n` has a number of children in the range ``min..max``. ## Checks that `n` has a number of children in the range `min..max`.
## If this is not the case, compilation aborts with an error message. ## If this is not the case, compilation aborts with an error message.
## This is useful for writing macros that check its number of arguments. ## This is useful for writing macros that check its number of arguments.
if n.len < min or n.len > max: if n.len < min or n.len > max:
@ -656,7 +656,7 @@ proc newTree*(kind: NimNodeKind,
proc newCall*(theProc: NimNode, proc newCall*(theProc: NimNode,
args: varargs[NimNode]): NimNode {.compileTime.} = args: varargs[NimNode]): NimNode {.compileTime.} =
## Produces a new call node. `theProc` is the proc that is called with ## Produces a new call node. `theProc` is the proc that is called with
## the arguments ``args[0..]``. ## the arguments `args[0..]`.
result = newNimNode(nnkCall) result = newNimNode(nnkCall)
result.add(theProc) result.add(theProc)
result.add(args) result.add(args)
@ -666,7 +666,7 @@ proc newCall*(theProc: NimNode,
proc newCall*(theProc: NimIdent, args: varargs[NimNode]): NimNode {.compileTime, deprecated: proc newCall*(theProc: NimIdent, args: varargs[NimNode]): NimNode {.compileTime, deprecated:
"Deprecated since v0.18.1; use 'newCall(string, ...)' or 'newCall(NimNode, ...)' instead".} = "Deprecated since v0.18.1; use 'newCall(string, ...)' or 'newCall(NimNode, ...)' instead".} =
## Produces a new call node. `theProc` is the proc that is called with ## Produces a new call node. `theProc` is the proc that is called with
## the arguments ``args[0..]``. ## the arguments `args[0..]`.
result = newNimNode(nnkCall) result = newNimNode(nnkCall)
result.add(newIdentNode(theProc)) result.add(newIdentNode(theProc))
result.add(args) result.add(args)
@ -676,7 +676,7 @@ proc newCall*(theProc: NimIdent, args: varargs[NimNode]): NimNode {.compileTime,
proc newCall*(theProc: string, proc newCall*(theProc: string,
args: varargs[NimNode]): NimNode {.compileTime.} = args: varargs[NimNode]): NimNode {.compileTime.} =
## Produces a new call node. `theProc` is the proc that is called with ## Produces a new call node. `theProc` is the proc that is called with
## the arguments ``args[0..]``. ## the arguments `args[0..]`.
result = newNimNode(nnkCall) result = newNimNode(nnkCall)
result.add(newIdentNode(theProc)) result.add(newIdentNode(theProc))
result.add(args) result.add(args)
@ -833,7 +833,7 @@ proc newLit*[T: tuple](arg: T): NimNode {.compileTime.} =
proc nestList*(op: NimNode; pack: NimNode): NimNode {.compileTime.} = proc nestList*(op: NimNode; pack: NimNode): NimNode {.compileTime.} =
## Nests the list `pack` into a tree of call expressions: ## Nests the list `pack` into a tree of call expressions:
## ``[a, b, c]`` is transformed into ``op(a, op(c, d))``. ## `[a, b, c]` is transformed into `op(a, op(c, d))`.
## This is also known as fold expression. ## This is also known as fold expression.
if pack.len < 1: if pack.len < 1:
error("`nestList` expects a node with at least 1 child") error("`nestList` expects a node with at least 1 child")
@ -843,7 +843,7 @@ proc nestList*(op: NimNode; pack: NimNode): NimNode {.compileTime.} =
proc nestList*(op: NimNode; pack: NimNode; init: NimNode): NimNode {.compileTime.} = proc nestList*(op: NimNode; pack: NimNode; init: NimNode): NimNode {.compileTime.} =
## Nests the list `pack` into a tree of call expressions: ## Nests the list `pack` into a tree of call expressions:
## ``[a, b, c]`` is transformed into ``op(a, op(c, d))``. ## `[a, b, c]` is transformed into `op(a, op(c, d))`.
## This is also known as fold expression. ## This is also known as fold expression.
result = init result = init
for i in countdown(pack.len - 1, 0): for i in countdown(pack.len - 1, 0):
@ -891,16 +891,16 @@ proc treeRepr*(n: NimNode): string {.compileTime, benign.} =
n.treeTraverse(result, isLisp = false, indented = true) n.treeTraverse(result, isLisp = false, indented = true)
proc lispRepr*(n: NimNode; indented = false): string {.compileTime, benign.} = proc lispRepr*(n: NimNode; indented = false): string {.compileTime, benign.} =
## Convert the AST ``n`` to a human-readable lisp-like string. ## Convert the AST `n` to a human-readable lisp-like string.
## ##
## See also ``repr``, ``treeRepr``, and ``astGenRepr``. ## See also `repr`, `treeRepr`, and `astGenRepr`.
result = "" result = ""
n.treeTraverse(result, isLisp = true, indented = indented) n.treeTraverse(result, isLisp = true, indented = indented)
proc astGenRepr*(n: NimNode): string {.compileTime, benign.} = proc astGenRepr*(n: NimNode): string {.compileTime, benign.} =
## Convert the AST ``n`` to the code required to generate that AST. ## Convert the AST `n` to the code required to generate that AST.
## ##
## See also ``repr``, ``treeRepr``, and ``lispRepr``. ## See also `repr`, `treeRepr`, and `lispRepr`.
const const
NodeKinds = {nnkEmpty, nnkIdent, nnkSym, nnkNone, nnkCommentStmt} NodeKinds = {nnkEmpty, nnkIdent, nnkSym, nnkNone, nnkCommentStmt}
@ -945,7 +945,7 @@ proc astGenRepr*(n: NimNode): string {.compileTime, benign.} =
macro dumpTree*(s: untyped): untyped = echo s.treeRepr macro dumpTree*(s: untyped): untyped = echo s.treeRepr
## Accepts a block of nim code and prints the parsed abstract syntax ## Accepts a block of nim code and prints the parsed abstract syntax
## tree using the ``treeRepr`` proc. Printing is done *at compile time*. ## tree using the `treeRepr` proc. Printing is done *at compile time*.
## ##
## You can use this as a tool to explore the Nim's abstract syntax ## You can use this as a tool to explore the Nim's abstract syntax
## tree and to discover what kind of nodes must be created to represent ## tree and to discover what kind of nodes must be created to represent
@ -965,11 +965,11 @@ macro dumpTree*(s: untyped): untyped = echo s.treeRepr
## Ident "echo" ## Ident "echo"
## StrLit "Hello, World!" ## StrLit "Hello, World!"
## ##
## Also see ``dumpAstGen`` and ``dumpLisp``. ## Also see `dumpAstGen` and `dumpLisp`.
macro dumpLisp*(s: untyped): untyped = echo s.lispRepr(indented = true) macro dumpLisp*(s: untyped): untyped = echo s.lispRepr(indented = true)
## Accepts a block of nim code and prints the parsed abstract syntax ## Accepts a block of nim code and prints the parsed abstract syntax
## tree using the ``lispRepr`` proc. Printing is done *at compile time*. ## tree using the `lispRepr` proc. Printing is done *at compile time*.
## ##
## You can use this as a tool to explore the Nim's abstract syntax ## You can use this as a tool to explore the Nim's abstract syntax
## tree and to discover what kind of nodes must be created to represent ## tree and to discover what kind of nodes must be created to represent
@ -989,11 +989,11 @@ macro dumpLisp*(s: untyped): untyped = echo s.lispRepr(indented = true)
## (Ident "echo") ## (Ident "echo")
## (StrLit "Hello, World!"))) ## (StrLit "Hello, World!")))
## ##
## Also see ``dumpAstGen`` and ``dumpTree``. ## Also see `dumpAstGen` and `dumpTree`.
macro dumpAstGen*(s: untyped): untyped = echo s.astGenRepr macro dumpAstGen*(s: untyped): untyped = echo s.astGenRepr
## Accepts a block of nim code and prints the parsed abstract syntax ## Accepts a block of nim code and prints the parsed abstract syntax
## tree using the ``astGenRepr`` proc. Printing is done *at compile time*. ## tree using the `astGenRepr` proc. Printing is done *at compile time*.
## ##
## You can use this as a tool to write macros quicker by writing example ## You can use this as a tool to write macros quicker by writing example
## outputs and then copying the snippets into the macro for modification. ## outputs and then copying the snippets into the macro for modification.
@ -1014,7 +1014,7 @@ macro dumpAstGen*(s: untyped): untyped = echo s.astGenRepr
## ) ## )
## ) ## )
## ##
## Also see ``dumpTree`` and ``dumpLisp``. ## Also see `dumpTree` and `dumpLisp`.
proc newEmptyNode*(): NimNode {.compileTime, noSideEffect.} = proc newEmptyNode*(): NimNode {.compileTime, noSideEffect.} =
## Create a new empty node. ## Create a new empty node.
@ -1066,15 +1066,15 @@ proc newColonExpr*(a, b: NimNode): NimNode {.compileTime.} =
proc newIdentDefs*(name, kind: NimNode; proc newIdentDefs*(name, kind: NimNode;
default = newEmptyNode()): NimNode {.compileTime.} = default = newEmptyNode()): NimNode {.compileTime.} =
## Creates a new ``nnkIdentDefs`` node of a specific kind and value. ## Creates a new `nnkIdentDefs` node of a specific kind and value.
## ##
## ``nnkIdentDefs`` need to have at least three children, but they can have ## `nnkIdentDefs` need to have at least three children, but they can have
## more: first comes a list of identifiers followed by a type and value ## more: first comes a list of identifiers followed by a type and value
## nodes. This helper proc creates a three node subtree, the first subnode ## nodes. This helper proc creates a three node subtree, the first subnode
## being a single identifier name. Both the ``kind`` node and ``default`` ## being a single identifier name. Both the `kind` node and `default`
## (value) nodes may be empty depending on where the ``nnkIdentDefs`` ## (value) nodes may be empty depending on where the `nnkIdentDefs`
## appears: tuple or object definitions will have an empty ``default`` node, ## appears: tuple or object definitions will have an empty `default` node,
## ``let`` or ``var`` blocks may have an empty ``kind`` node if the ## `let` or `var` blocks may have an empty `kind` node if the
## identifier is being assigned a value. Example: ## identifier is being assigned a value. Example:
## ##
## .. code-block:: nim ## .. code-block:: nim
@ -1087,7 +1087,7 @@ proc newIdentDefs*(name, kind: NimNode;
## # b = 3 ## # b = 3
## ##
## If you need to create multiple identifiers you need to use the lower level ## If you need to create multiple identifiers you need to use the lower level
## ``newNimNode``: ## `newNimNode`:
## ##
## .. code-block:: nim ## .. code-block:: nim
## ##
@ -1124,7 +1124,7 @@ proc newProc*(name = newEmptyNode();
pragmas: NimNode = newEmptyNode()): NimNode {.compileTime.} = pragmas: NimNode = newEmptyNode()): NimNode {.compileTime.} =
## Shortcut for creating a new proc. ## Shortcut for creating a new proc.
## ##
## The ``params`` array must start with the return type of the proc, ## The `params` array must start with the return type of the proc,
## followed by a list of IdentDefs which specify the params. ## followed by a list of IdentDefs which specify the params.
if procType notin RoutineNodes: if procType notin RoutineNodes:
error("Expected one of " & $RoutineNodes & ", got " & $procType) error("Expected one of " & $RoutineNodes & ", got " & $procType)
@ -1140,7 +1140,7 @@ proc newProc*(name = newEmptyNode();
proc newIfStmt*(branches: varargs[tuple[cond, body: NimNode]]): proc newIfStmt*(branches: varargs[tuple[cond, body: NimNode]]):
NimNode {.compileTime.} = NimNode {.compileTime.} =
## Constructor for ``if`` statements. ## Constructor for `if` statements.
## ##
## .. code-block:: nim ## .. code-block:: nim
## ##
@ -1300,17 +1300,17 @@ proc `$`*(node: NimNode): string {.compileTime.} =
badNodeKind node, "$" badNodeKind node, "$"
iterator items*(n: NimNode): NimNode {.inline.} = iterator items*(n: NimNode): NimNode {.inline.} =
## Iterates over the children of the NimNode ``n``. ## Iterates over the children of the NimNode `n`.
for i in 0 ..< n.len: for i in 0 ..< n.len:
yield n[i] yield n[i]
iterator pairs*(n: NimNode): (int, NimNode) {.inline.} = iterator pairs*(n: NimNode): (int, NimNode) {.inline.} =
## Iterates over the children of the NimNode ``n`` and its indices. ## Iterates over the children of the NimNode `n` and its indices.
for i in 0 ..< n.len: for i in 0 ..< n.len:
yield (i, n[i]) yield (i, n[i])
iterator children*(n: NimNode): NimNode {.inline.} = iterator children*(n: NimNode): NimNode {.inline.} =
## Iterates over the children of the NimNode ``n``. ## Iterates over the children of the NimNode `n`.
for i in 0 ..< n.len: for i in 0 ..< n.len:
yield n[i] yield n[i]
@ -1329,7 +1329,7 @@ template findChild*(n: NimNode; cond: untyped): NimNode {.dirty.} =
res res
proc insert*(a: NimNode; pos: int; b: NimNode) {.compileTime.} = proc insert*(a: NimNode; pos: int; b: NimNode) {.compileTime.} =
## Insert node ``b`` into node ``a`` at ``pos``. ## Insert node `b` into node `a` at `pos`.
if len(a)-1 < pos: if len(a)-1 < pos:
# add some empty nodes first # add some empty nodes first
for i in len(a)-1..pos-2: for i in len(a)-1..pos-2:
@ -1397,32 +1397,32 @@ proc eqIdent*(a: string; b: string): bool {.magic: "EqIdent", noSideEffect.}
## Style insensitive comparison. ## Style insensitive comparison.
proc eqIdent*(a: NimNode; b: string): bool {.magic: "EqIdent", noSideEffect.} proc eqIdent*(a: NimNode; b: string): bool {.magic: "EqIdent", noSideEffect.}
## Style insensitive comparison. ``a`` can be an identifier or a ## Style insensitive comparison. `a` can be an identifier or a
## symbol. ``a`` may be wrapped in an export marker ## symbol. `a` may be wrapped in an export marker
## (``nnkPostfix``) or quoted with backticks (``nnkAccQuoted``), ## (`nnkPostfix`) or quoted with backticks (`nnkAccQuoted`),
## these nodes will be unwrapped. ## these nodes will be unwrapped.
proc eqIdent*(a: string; b: NimNode): bool {.magic: "EqIdent", noSideEffect.} proc eqIdent*(a: string; b: NimNode): bool {.magic: "EqIdent", noSideEffect.}
## Style insensitive comparison. ``b`` can be an identifier or a ## Style insensitive comparison. `b` can be an identifier or a
## symbol. ``b`` may be wrapped in an export marker ## symbol. `b` may be wrapped in an export marker
## (``nnkPostfix``) or quoted with backticks (``nnkAccQuoted``), ## (`nnkPostfix`) or quoted with backticks (`nnkAccQuoted`),
## these nodes will be unwrapped. ## these nodes will be unwrapped.
proc eqIdent*(a: NimNode; b: NimNode): bool {.magic: "EqIdent", noSideEffect.} proc eqIdent*(a: NimNode; b: NimNode): bool {.magic: "EqIdent", noSideEffect.}
## Style insensitive comparison. ``a`` and ``b`` can be an ## Style insensitive comparison. `a` and `b` can be an
## identifier or a symbol. Both may be wrapped in an export marker ## identifier or a symbol. Both may be wrapped in an export marker
## (``nnkPostfix``) or quoted with backticks (``nnkAccQuoted``), ## (`nnkPostfix`) or quoted with backticks (`nnkAccQuoted`),
## these nodes will be unwrapped. ## these nodes will be unwrapped.
proc expectIdent*(n: NimNode, name: string) {.compileTime, since: (1,1).} = proc expectIdent*(n: NimNode, name: string) {.compileTime, since: (1,1).} =
## Check that ``eqIdent(n,name)`` holds true. If this is not the ## Check that `eqIdent(n,name)` holds true. If this is not the
## case, compilation aborts with an error message. This is useful ## case, compilation aborts with an error message. This is useful
## for writing macros that check the AST that is passed to them. ## for writing macros that check the AST that is passed to them.
if not eqIdent(n, name): if not eqIdent(n, name):
error("Expected identifier to be `" & name & "` here", n) error("Expected identifier to be `" & name & "` here", n)
proc hasArgOfName*(params: NimNode; name: string): bool {.compileTime.}= proc hasArgOfName*(params: NimNode; name: string): bool {.compileTime.}=
## Search ``nnkFormalParams`` for an argument. ## Search `nnkFormalParams` for an argument.
expectKind(params, nnkFormalParams) expectKind(params, nnkFormalParams)
for i in 1..<params.len: for i in 1..<params.len:
for j in 0..<params[i].len-2: for j in 0..<params[i].len-2:
@ -1430,7 +1430,7 @@ proc hasArgOfName*(params: NimNode; name: string): bool {.compileTime.}=
return true return true
proc addIdentIfAbsent*(dest: NimNode, ident: string) {.compileTime.} = proc addIdentIfAbsent*(dest: NimNode, ident: string) {.compileTime.} =
## Add ``ident`` to ``dest`` if it is not present. This is intended for use ## Add `ident` to `dest` if it is not present. This is intended for use
## with pragmas. ## with pragmas.
for node in dest.children: for node in dest.children:
case node.kind case node.kind
@ -1447,8 +1447,8 @@ proc boolVal*(n: NimNode): bool {.compileTime, noSideEffect.} =
when defined(nimMacrosGetNodeId): when defined(nimMacrosGetNodeId):
proc nodeID*(n: NimNode): int {.magic: "NodeId".} proc nodeID*(n: NimNode): int {.magic: "NodeId".}
## Returns the id of ``n``, when the compiler has been compiled ## Returns the id of `n`, when the compiler has been compiled
## with the flag ``-d:useNodeids``, otherwise returns ``-1``. This ## with the flag `-d:useNodeids`, otherwise returns `-1`. This
## proc is for the purpose to debug the compiler only. ## proc is for the purpose to debug the compiler only.
macro expandMacros*(body: typed): untyped = macro expandMacros*(body: typed): untyped =
@ -1468,8 +1468,8 @@ macro expandMacros*(body: typed): untyped =
## dump(x + y) ## dump(x + y)
## ##
## will actually dump `x + y`, but at the same time will print at ## will actually dump `x + y`, but at the same time will print at
## compile time the expansion of the ``dump`` macro, which in this ## compile time the expansion of the `dump` macro, which in this
## case is ``debugEcho ["x + y", " = ", x + y]``. ## case is `debugEcho ["x + y", " = ", x + y]`.
echo body.toStrLit echo body.toStrLit
result = body result = body
@ -1614,17 +1614,17 @@ proc getProjectPath*(): string = discard
## which returns the path of the source file containing that template ## which returns the path of the source file containing that template
## call. ## call.
## ##
## For example, assume a ``dir1/foo.nim`` that imports a ``dir2/bar.nim``, ## For example, assume a `dir1/foo.nim` that imports a `dir2/bar.nim`,
## have the ``bar.nim`` print out both ``getProjectPath`` and ## have the `bar.nim` print out both `getProjectPath` and
## ``currentSourcePath`` outputs. ## `currentSourcePath` outputs.
## ##
## Now when ``foo.nim`` is compiled, the ``getProjectPath`` from ## Now when `foo.nim` is compiled, the `getProjectPath` from
## ``bar.nim`` will return the ``dir1/`` path, while the ``currentSourcePath`` ## `bar.nim` will return the `dir1/` path, while the `currentSourcePath`
## will return the path to the ``bar.nim`` source file. ## will return the path to the `bar.nim` source file.
## ##
## Now when ``bar.nim`` is compiled directly, the ``getProjectPath`` ## Now when `bar.nim` is compiled directly, the `getProjectPath`
## will now return the ``dir2/`` path, and the ``currentSourcePath`` ## will now return the `dir2/` path, and the `currentSourcePath`
## will still return the same path, the path to the ``bar.nim`` source ## will still return the same path, the path to the `bar.nim` source
## file. ## file.
## ##
## The path returned by this proc is set at compile time. ## The path returned by this proc is set at compile time.
@ -1633,16 +1633,16 @@ proc getProjectPath*(): string = discard
## * `getCurrentDir proc <os.html#getCurrentDir>`_ ## * `getCurrentDir proc <os.html#getCurrentDir>`_
proc getSize*(arg: NimNode): int {.magic: "NSizeOf", noSideEffect.} = proc getSize*(arg: NimNode): int {.magic: "NSizeOf", noSideEffect.} =
## Returns the same result as ``system.sizeof`` if the size is ## Returns the same result as `system.sizeof` if the size is
## known by the Nim compiler. Returns a negative value if the Nim ## known by the Nim compiler. Returns a negative value if the Nim
## compiler does not know the size. ## compiler does not know the size.
proc getAlign*(arg: NimNode): int {.magic: "NSizeOf", noSideEffect.} = proc getAlign*(arg: NimNode): int {.magic: "NSizeOf", noSideEffect.} =
## Returns the same result as ``system.alignof`` if the alignment ## Returns the same result as `system.alignof` if the alignment
## is known by the Nim compiler. It works on ``NimNode`` for use ## is known by the Nim compiler. It works on `NimNode` for use
## in macro context. Returns a negative value if the Nim compiler ## in macro context. Returns a negative value if the Nim compiler
## does not know the alignment. ## does not know the alignment.
proc getOffset*(arg: NimNode): int {.magic: "NSizeOf", noSideEffect.} = proc getOffset*(arg: NimNode): int {.magic: "NSizeOf", noSideEffect.} =
## Returns the same result as ``system.offsetof`` if the offset is ## Returns the same result as `system.offsetof` if the offset is
## known by the Nim compiler. It expects a resolved symbol node ## known by the Nim compiler. It expects a resolved symbol node
## from a field of a type. Therefore it only requires one argument ## from a field of a type. Therefore it only requires one argument
## instead of two. Returns a negative value if the Nim compiler ## instead of two. Returns a negative value if the Nim compiler

2
lib/deprecated/pure/events.nim
View file

@ -12,7 +12,7 @@
## Unstable API. ## Unstable API.
## ##
## This module implements an event system that is not dependent on external ## This module implements an event system that is not dependent on external
## graphical toolkits. It was originally called ``NimEE`` because ## graphical toolkits. It was originally called `NimEE` because
## it was inspired by Python's PyEE module. There are two ways you can use ## it was inspired by Python's PyEE module. There are two ways you can use
## events: one is a python-inspired way; the other is more of a C-style way. ## events: one is a python-inspired way; the other is more of a C-style way.
## ##

2
lib/deprecated/pure/ospaths.nim
View file

@ -7,7 +7,7 @@
# distribution, for details about the copyright. # distribution, for details about the copyright.
# #
## This module is deprecated, ``import os`` instead. ## This module is deprecated, `import os` instead.
{.deprecated: "import os.nim instead".} {.deprecated: "import os.nim instead".}
import os import os

12
lib/deprecated/pure/parseopt2.nim
View file

@ -13,8 +13,8 @@
## ##
## Supported syntax: ## Supported syntax:
## ##
## 1. short options - ``-abcd``, where a, b, c, d are names ## 1. short options - `-abcd`, where a, b, c, d are names
## 2. long option - ``--foo:bar``, ``--foo=bar`` or ``--foo`` ## 2. long option - `--foo:bar`, `--foo=bar` or `--foo`
## 3. argument - everything else ## 3. argument - everything else
{.deprecated: "Use the 'parseopt' module instead".} {.deprecated: "Use the 'parseopt' module instead".}
@ -29,16 +29,16 @@ type
CmdLineKind* = enum ## the detected command line token CmdLineKind* = enum ## the detected command line token
cmdEnd, ## end of command line reached cmdEnd, ## end of command line reached
cmdArgument, ## argument detected cmdArgument, ## argument detected
cmdLongOption, ## a long option ``--option`` detected cmdLongOption, ## a long option `--option` detected
cmdShortOption ## a short option ``-c`` detected cmdShortOption ## a short option `-c` detected
OptParser* = OptParser* =
object of RootObj ## this object implements the command line parser object of RootObj ## this object implements the command line parser
cmd: seq[string] cmd: seq[string]
pos: int pos: int
remainingShortOptions: string remainingShortOptions: string
kind*: CmdLineKind ## the detected command line token kind*: CmdLineKind ## the detected command line token
key*, val*: string ## key and value pair; ``key`` is the option key*, val*: string ## key and value pair; `key` is the option
## or the argument, ``value`` is not "" if ## or the argument, `value` is not "" if
## the option was given a value ## the option was given a value
proc initOptParser*(cmdline: seq[string]): OptParser {.rtl.} = proc initOptParser*(cmdline: seq[string]): OptParser {.rtl.} =

2
lib/deprecated/pure/securehash.nim
View file

@ -1,6 +1,6 @@
## This module is a deprecated alias for the ``sha1`` module. ## This module is a deprecated alias for the `sha1` module.
{.deprecated.} {.deprecated.}
include "../std/sha1" include "../std/sha1"

34
lib/system/iterators.nim
View file

@ -130,22 +130,22 @@ iterator items*[T: Ordinal](s: Slice[T]): T =
yield x yield x
iterator pairs*[T](a: openArray[T]): tuple[key: int, val: T] {.inline.} = iterator pairs*[T](a: openArray[T]): tuple[key: int, val: T] {.inline.} =
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs. ## Iterates over each item of `a`. Yields `(index, a[index])` pairs.
var i = 0 var i = 0
while i < len(a): while i < len(a):
yield (i, a[i]) yield (i, a[i])
inc(i) inc(i)
iterator mpairs*[T](a: var openArray[T]): tuple[key: int, val: var T]{.inline.} = iterator mpairs*[T](a: var openArray[T]): tuple[key: int, val: var T]{.inline.} =
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs. ## Iterates over each item of `a`. Yields `(index, a[index])` pairs.
## ``a[index]`` can be modified. ## `a[index]` can be modified.
var i = 0 var i = 0
while i < len(a): while i < len(a):
yield (i, a[i]) yield (i, a[i])
inc(i) inc(i)
iterator pairs*[IX, T](a: array[IX, T]): tuple[key: IX, val: T] {.inline.} = iterator pairs*[IX, T](a: array[IX, T]): tuple[key: IX, val: T] {.inline.} =
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs. ## Iterates over each item of `a`. Yields `(index, a[index])` pairs.
var i = low(IX) var i = low(IX)
if i <= high(IX): if i <= high(IX):
while true: while true:
@ -154,8 +154,8 @@ iterator pairs*[IX, T](a: array[IX, T]): tuple[key: IX, val: T] {.inline.} =
inc(i) inc(i)
iterator mpairs*[IX, T](a: var array[IX, T]): tuple[key: IX, val: var T] {.inline.} = iterator mpairs*[IX, T](a: var array[IX, T]): tuple[key: IX, val: var T] {.inline.} =
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs. ## Iterates over each item of `a`. Yields `(index, a[index])` pairs.
## ``a[index]`` can be modified. ## `a[index]` can be modified.
var i = low(IX) var i = low(IX)
if i <= high(IX): if i <= high(IX):
while true: while true:
@ -164,7 +164,7 @@ iterator mpairs*[IX, T](a: var array[IX, T]): tuple[key: IX, val: var T] {.inlin
inc(i) inc(i)
iterator pairs*[T](a: seq[T]): tuple[key: int, val: T] {.inline.} = iterator pairs*[T](a: seq[T]): tuple[key: int, val: T] {.inline.} =
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs. ## Iterates over each item of `a`. Yields `(index, a[index])` pairs.
var i = 0 var i = 0
let L = len(a) let L = len(a)
while i < L: while i < L:
@ -173,8 +173,8 @@ iterator pairs*[T](a: seq[T]): tuple[key: int, val: T] {.inline.} =
assert(len(a) == L, "the length of the seq changed while iterating over it") assert(len(a) == L, "the length of the seq changed while iterating over it")
iterator mpairs*[T](a: var seq[T]): tuple[key: int, val: var T] {.inline.} = iterator mpairs*[T](a: var seq[T]): tuple[key: int, val: var T] {.inline.} =
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs. ## Iterates over each item of `a`. Yields `(index, a[index])` pairs.
## ``a[index]`` can be modified. ## `a[index]` can be modified.
var i = 0 var i = 0
let L = len(a) let L = len(a)
while i < L: while i < L:
@ -183,7 +183,7 @@ iterator mpairs*[T](a: var seq[T]): tuple[key: int, val: var T] {.inline.} =
assert(len(a) == L, "the length of the seq changed while iterating over it") assert(len(a) == L, "the length of the seq changed while iterating over it")
iterator pairs*(a: string): tuple[key: int, val: char] {.inline.} = iterator pairs*(a: string): tuple[key: int, val: char] {.inline.} =
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs. ## Iterates over each item of `a`. Yields `(index, a[index])` pairs.
var i = 0 var i = 0
let L = len(a) let L = len(a)
while i < L: while i < L:
@ -192,8 +192,8 @@ iterator pairs*(a: string): tuple[key: int, val: char] {.inline.} =
assert(len(a) == L, "the length of the string changed while iterating over it") assert(len(a) == L, "the length of the string changed while iterating over it")
iterator mpairs*(a: var string): tuple[key: int, val: var char] {.inline.} = iterator mpairs*(a: var string): tuple[key: int, val: var char] {.inline.} =
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs. ## Iterates over each item of `a`. Yields `(index, a[index])` pairs.
## ``a[index]`` can be modified. ## `a[index]` can be modified.
var i = 0 var i = 0
let L = len(a) let L = len(a)
while i < L: while i < L:
@ -202,7 +202,7 @@ iterator mpairs*(a: var string): tuple[key: int, val: var char] {.inline.} =
assert(len(a) == L, "the length of the string changed while iterating over it") assert(len(a) == L, "the length of the string changed while iterating over it")
iterator pairs*(a: cstring): tuple[key: int, val: char] {.inline.} = iterator pairs*(a: cstring): tuple[key: int, val: char] {.inline.} =
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs. ## Iterates over each item of `a`. Yields `(index, a[index])` pairs.
when defined(js): when defined(js):
var i = 0 var i = 0
var L = len(a) var L = len(a)
@ -216,8 +216,8 @@ iterator pairs*(a: cstring): tuple[key: int, val: char] {.inline.} =
inc(i) inc(i)
iterator mpairs*(a: var cstring): tuple[key: int, val: var char] {.inline.} = iterator mpairs*(a: var cstring): tuple[key: int, val: var char] {.inline.} =
## Iterates over each item of `a`. Yields ``(index, a[index])`` pairs. ## Iterates over each item of `a`. Yields `(index, a[index])` pairs.
## ``a[index]`` can be modified. ## `a[index]` can be modified.
when defined(js): when defined(js):
var i = 0 var i = 0
var L = len(a) var L = len(a)
@ -297,10 +297,10 @@ iterator fieldPairs*[T: tuple|object](x: T): tuple[key: string, val: RootObj] {.
## Iterates over every field of `x` returning their name and value. ## Iterates over every field of `x` returning their name and value.
## ##
## When you iterate over objects with different field types you have to use ## When you iterate over objects with different field types you have to use
## the compile time ``when`` instead of a runtime ``if`` to select the code ## the compile time `when` instead of a runtime `if` to select the code
## you want to run for each type. To perform the comparison use the `is ## you want to run for each type. To perform the comparison use the `is
## operator <manual.html#generics-is-operator>`_. ## operator <manual.html#generics-is-operator>`_.
## Another way to do the same without ``when`` is to leave the task of ## Another way to do the same without `when` is to leave the task of
## picking the appropriate code to a secondary proc which you overload for ## picking the appropriate code to a secondary proc which you overload for
## each field type and pass the `value` to. ## each field type and pass the `value` to.
## ##

36
lib/system/nimscript.nim
View file

@ -14,11 +14,11 @@
const const
buildOS* {.magic: "BuildOS".}: string = "" buildOS* {.magic: "BuildOS".}: string = ""
## The OS this build is running on. Can be different from ``system.hostOS`` ## The OS this build is running on. Can be different from `system.hostOS`
## for cross compilations. ## for cross compilations.
buildCPU* {.magic: "BuildCPU".}: string = "" buildCPU* {.magic: "BuildCPU".}: string = ""
## The CPU this build is running on. Can be different from ``system.hostCPU`` ## The CPU this build is running on. Can be different from `system.hostCPU`
## for cross compilations. ## for cross compilations.
template builtin = discard template builtin = discard
@ -57,7 +57,7 @@ proc warningImpl(arg, orig: string) = discard
proc hintImpl(arg, orig: string) = discard proc hintImpl(arg, orig: string) = discard
proc paramStr*(i: int): string = proc paramStr*(i: int): string =
## Retrieves the ``i``'th command line parameter. ## Retrieves the `i`'th command line parameter.
builtin builtin
proc paramCount*(): int = proc paramCount*(): int =
@ -66,7 +66,7 @@ proc paramCount*(): int =
proc switch*(key: string, val="") = proc switch*(key: string, val="") =
## Sets a Nim compiler command line switch, for ## Sets a Nim compiler command line switch, for
## example ``switch("checks", "on")``. ## example `switch("checks", "on")`.
builtin builtin
proc warning*(name: string; val: bool) = proc warning*(name: string; val: bool) =
@ -82,9 +82,9 @@ proc hint*(name: string; val: bool) =
proc patchFile*(package, filename, replacement: string) = proc patchFile*(package, filename, replacement: string) =
## Overrides the location of a given file belonging to the ## Overrides the location of a given file belonging to the
## passed package. ## passed package.
## If the ``replacement`` is not an absolute path, the path ## If the `replacement` is not an absolute path, the path
## is interpreted to be local to the Nimscript file that contains ## is interpreted to be local to the Nimscript file that contains
## the call to ``patchFile``, Nim's ``--path`` is not used at all ## the call to `patchFile`, Nim's `--path` is not used at all
## to resolve the filename! ## to resolve the filename!
## ##
## Example: ## Example:
@ -112,19 +112,19 @@ proc cmpic*(a, b: string): int =
cmpIgnoreCase(a, b) cmpIgnoreCase(a, b)
proc getEnv*(key: string; default = ""): string {.tags: [ReadIOEffect].} = proc getEnv*(key: string; default = ""): string {.tags: [ReadIOEffect].} =
## Retrieves the environment variable of name ``key``. ## Retrieves the environment variable of name `key`.
builtin builtin
proc existsEnv*(key: string): bool {.tags: [ReadIOEffect].} = proc existsEnv*(key: string): bool {.tags: [ReadIOEffect].} =
## Checks for the existence of an environment variable named ``key``. ## Checks for the existence of an environment variable named `key`.
builtin builtin
proc putEnv*(key, val: string) {.tags: [WriteIOEffect].} = proc putEnv*(key, val: string) {.tags: [WriteIOEffect].} =
## Sets the value of the environment variable named ``key`` to ``val``. ## Sets the value of the environment variable named `key` to `val`.
builtin builtin
proc delEnv*(key: string) {.tags: [WriteIOEffect].} = proc delEnv*(key: string) {.tags: [WriteIOEffect].} =
## Deletes the environment variable named ``key``. ## Deletes the environment variable named `key`.
builtin builtin
proc fileExists*(filename: string): bool {.tags: [ReadIOEffect].} = proc fileExists*(filename: string): bool {.tags: [ReadIOEffect].} =
@ -265,7 +265,7 @@ proc exec*(command: string) {.
## Executes an external process. If the external process terminates with ## Executes an external process. If the external process terminates with
## a non-zero exit code, an OSError exception is raised. ## a non-zero exit code, an OSError exception is raised.
## ##
## **Note:** If you need a version of ``exec`` that returns the exit code ## **Note:** If you need a version of `exec` that returns the exit code
## and text output of the command, you can use `system.gorgeEx ## and text output of the command, you can use `system.gorgeEx
## <system.html#gorgeEx,string,string,string>`_. ## <system.html#gorgeEx,string,string,string>`_.
log "exec: " & command: log "exec: " & command:
@ -286,7 +286,7 @@ proc exec*(command: string, input: string, cache = "") {.
proc selfExec*(command: string) {. proc selfExec*(command: string) {.
raises: [OSError], tags: [ExecIOEffect].} = raises: [OSError], tags: [ExecIOEffect].} =
## Executes an external command with the current nim/nimble executable. ## Executes an external command with the current nim/nimble executable.
## ``Command`` must not contain the "nim " part. ## `Command` must not contain the "nim " part.
let c = selfExe() & " " & command let c = selfExe() & " " & command
log "exec: " & c: log "exec: " & c:
if rawExec(c) != 0: if rawExec(c) != 0:
@ -323,9 +323,9 @@ proc projectPath*(): string =
builtin builtin
proc thisDir*(): string = proc thisDir*(): string =
## Retrieves the directory of the current ``nims`` script file. Its path is ## Retrieves the directory of the current `nims` script file. Its path is
## obtained via ``currentSourcePath`` (although, currently, ## obtained via `currentSourcePath` (although, currently,
## ``currentSourcePath`` resolves symlinks, unlike ``thisDir``). ## `currentSourcePath` resolves symlinks, unlike `thisDir`).
builtin builtin
proc cd*(dir: string) {.raises: [OSError].} = proc cd*(dir: string) {.raises: [OSError].} =
@ -369,7 +369,7 @@ proc writeTask(name, desc: string) =
echo name, spaces, desc echo name, spaces, desc
proc cppDefine*(define: string) = proc cppDefine*(define: string) =
## tell Nim that ``define`` is a C preprocessor ``#define`` and so always ## tell Nim that `define` is a C preprocessor `#define` and so always
## needs to be mangled. ## needs to be mangled.
builtin builtin
@ -404,8 +404,8 @@ when not defined(nimble):
## task build, "default build is via the C backend": ## task build, "default build is via the C backend":
## setCommand "c" ## setCommand "c"
## ##
## For a task named ``foo``, this template generates a ``proc`` named ## For a task named `foo`, this template generates a `proc` named
## ``fooTask``. This is useful if you need to call one task in ## `fooTask`. This is useful if you need to call one task in
## another in your Nimscript. ## another in your Nimscript.
## ##
## Example: ## Example:

16
lib/system/orc.nim
View file

@ -407,14 +407,14 @@ proc GC_runOrc* =
collectCycles() collectCycles()
proc GC_enableOrc*() = proc GC_enableOrc*() =
## Enables the cycle collector subsystem of ``--gc:orc``. This is a ``--gc:orc`` ## Enables the cycle collector subsystem of `--gc:orc`. This is a `--gc:orc`
## specific API. Check with ``when defined(gcOrc)`` for its existence. ## specific API. Check with `when defined(gcOrc)` for its existence.
when not defined(nimStressOrc): when not defined(nimStressOrc):
rootsThreshold = defaultThreshold rootsThreshold = defaultThreshold
proc GC_disableOrc*() = proc GC_disableOrc*() =
## Disables the cycle collector subsystem of ``--gc:orc``. This is a ``--gc:orc`` ## Disables the cycle collector subsystem of `--gc:orc`. This is a `--gc:orc`
## specific API. Check with ``when defined(gcOrc)`` for its existence. ## specific API. Check with `when defined(gcOrc)` for its existence.
when not defined(nimStressOrc): when not defined(nimStressOrc):
rootsThreshold = high(int) rootsThreshold = high(int)
@ -424,16 +424,16 @@ proc GC_partialCollect*(limit: int) =
partialCollect(limit) partialCollect(limit)
proc GC_fullCollect* = proc GC_fullCollect* =
## Forces a full garbage collection pass. With ``--gc:orc`` triggers the cycle ## Forces a full garbage collection pass. With `--gc:orc` triggers the cycle
## collector. This is an alias for ``GC_runOrc``. ## collector. This is an alias for `GC_runOrc`.
collectCycles() collectCycles()
proc GC_enableMarkAndSweep*() = proc GC_enableMarkAndSweep*() =
## For ``--gc:orc`` an alias for ``GC_enableOrc``. ## For `--gc:orc` an alias for `GC_enableOrc`.
GC_enableOrc() GC_enableOrc()
proc GC_disableMarkAndSweep*() = proc GC_disableMarkAndSweep*() =
## For ``--gc:orc`` an alias for ``GC_disableOrc``. ## For `--gc:orc` an alias for `GC_disableOrc`.
GC_disableOrc() GC_disableOrc()
when optimizedOrc: when optimizedOrc:

2
lib/system/stacktraces.nim
View file

@ -19,7 +19,7 @@ when defined(nimStackTraceOverride):
## Procedure types for overriding the default stack trace. ## Procedure types for overriding the default stack trace.
type type
cuintptr_t* {.importc: "uintptr_t", nodecl.} = uint cuintptr_t* {.importc: "uintptr_t", nodecl.} = uint
## This is the same as the type ``uintptr_t`` in C. ## This is the same as the type `uintptr_t` in C.
StackTraceOverrideGetTracebackProc* = proc (): string {. StackTraceOverrideGetTracebackProc* = proc (): string {.
nimcall, gcsafe, locks: 0, raises: [], tags: [], noinline.} nimcall, gcsafe, locks: 0, raises: [], tags: [], noinline.}

8
lib/system/threads.nim
View file

@ -11,7 +11,7 @@
## ##
## **Note**: This is part of the system module. Do not import it directly. ## **Note**: This is part of the system module. Do not import it directly.
## To activate thread support you need to compile ## To activate thread support you need to compile
## with the ``--threads:on`` command line switch. ## with the `--threads:on` command line switch.
## ##
## Nim's memory model for threads is quite different from other common ## Nim's memory model for threads is quite different from other common
## programming languages (C, Pascal): Each thread has its own ## programming languages (C, Pascal): Each thread has its own
@ -97,7 +97,7 @@ proc onThreadDestruction*(handler: proc () {.closure, gcsafe, raises: [].}) =
## Registers a *thread local* handler that is called at the thread's ## Registers a *thread local* handler that is called at the thread's
## destruction. ## destruction.
## ##
## A thread is destructed when the ``.thread`` proc returns ## A thread is destructed when the `.thread` proc returns
## normally or when it raises an exception. Note that unhandled exceptions ## normally or when it raises an exception. Note that unhandled exceptions
## in a thread nevertheless cause the whole process to die. ## in a thread nevertheless cause the whole process to die.
threadDestructionHandlers.add handler threadDestructionHandlers.add handler
@ -261,7 +261,7 @@ when hostOS == "windows":
## Creates a new thread `t` and starts its execution. ## Creates a new thread `t` and starts its execution.
## ##
## Entry point is the proc `tp`. ## Entry point is the proc `tp`.
## `param` is passed to `tp`. `TArg` can be ``void`` if you ## `param` is passed to `tp`. `TArg` can be `void` if you
## don't need to pass any data to the thread. ## don't need to pass any data to the thread.
t.core = cast[PGcThread](allocShared0(sizeof(GcThread))) t.core = cast[PGcThread](allocShared0(sizeof(GcThread)))
@ -310,7 +310,7 @@ else:
## Creates a new thread `t` and starts its execution. ## Creates a new thread `t` and starts its execution.
## ##
## Entry point is the proc `tp`. `param` is passed to `tp`. ## Entry point is the proc `tp`. `param` is passed to `tp`.
## `TArg` can be ``void`` if you ## `TArg` can be `void` if you
## don't need to pass any data to the thread. ## don't need to pass any data to the thread.
t.core = cast[PGcThread](allocShared0(sizeof(GcThread))) t.core = cast[PGcThread](allocShared0(sizeof(GcThread)))