Nim

https://nim-docs.readthedocs.io/en/latest
Admin
Nim is a statically typed, compiled programming language with a focus on efficiency, expressiveness,...
Tokens:101,536
Snippets:867
Trust Score:8.3
Update:7 months ago
Show doc for...
Tokens:
Raw
### C++ OpenSceneGraph Basic Triangle Example

Source: https://nim-docs.readthedocs.io/en/latest/howto/interop/cpp/where_to_start

This C++ code snippet demonstrates how to create a basic 3D triangle using the OpenSceneGraph library. It defines vertices, colors, and rendering modes, then uses osgViewer to display the geometry. Dependencies include osg and osgViewer.

```cpp
#include <osg/Referenced>
#include <osg/Geometry>
#include <osg/Geode>
#include <osg/Array>
#include <osgViewer/Viewer>

int main(int argc, char** argv)
{
    // Create the geometry which will define the triangle
    osg::ref_ptr<osg::Geometry> myTriangleGeometry = new osg::Geometry;

    // Define the triangle's 3 vertices
    osg::ref_ptr<osg::Vec3Array> vertices = new osg::Vec3Array;
    vertices->push_back(osg::Vec3(0, 0, 0));
    vertices->push_back(osg::Vec3(100, 0, 0));
    vertices->push_back(osg::Vec3(0, 0, 100));
    myTriangleGeometry->setVertexArray(vertices);

    // You can give each vertex its own color, but let's just make it green for now
    osg::ref_ptr<osg::Vec4Array> colors = new osg::Vec4Array;
    colors->push_back(osg::Vec4(0, 1.0, 0, 1.0)); // RGBA for green
    myTriangleGeometry->setColorArray(colors);
    myTriangleGeometry->setColorBinding(osg::Geometry::BIND_OVERALL);

    // Turn off lighting
    myTriangleGeometry->getOrCreateStateSet()->setMode(GL_LIGHTING, osg::StateAttribute::OFF);

    // Turn on blending
    myTriangleGeometry->getOrCreateStateSet()->setMode(GL_BLEND, osg::StateAttribute::ON);

    // Define the geometry type as 'triangles'
    myTriangleGeometry->addPrimitiveSet(new osg::DrawArrays(osg::PrimitiveSet::TRIANGLES, 0, vertices->size()));

    // Finally, let's add our triangle to a geode
    osg::ref_ptr<osg::Geode> myGeode = new osg::Geode;
    myGeode->addDrawable(myTriangleGeometry);

    // And now we can create a viewer to look at our geode
    osgViewer::Viewer viewer;
    viewer.setSceneData(myGeode);
    return viewer.run();
}

```

--------------------------------

### Compile and Run Nim OOP Example

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/macros

Provides the command to compile and run a Nim program that demonstrates object-oriented programming concepts. The output shows the results of method calls on different object types.

```bash
nim c -r oopmacro.nim
```

--------------------------------

### C++ OpenSceneGraph Compilation Command (Arch Linux)

Source: https://nim-docs.readthedocs.io/en/latest/howto/interop/cpp/where_to_start

This command compiles the OpenSceneGraph C++ example on Arch Linux. It links against the osg and osgViewer libraries and specifies include paths for the OpenSceneGraph headers. Ensure OpenSceneGraph is installed.

```bash
g++ -losg -losgViewer -I/usr/include/osg -I/usr/include/osgViewer ex01.cpp

```

--------------------------------

### Compiling and Running Nim Enum Example

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/enum_types

Shows the command to compile and run a Nim program that defines and uses enums, along with the expected output.

```bash
nim c -r enumdefs.nim
FF0000
Red
Orange Orange
```

--------------------------------

### Nim Template Parameter Lookup Rule Example

Source: https://nim-docs.readthedocs.io/en/latest/manual/templates

Explains Nim's template parameter lookup rules, showing how template arguments can be used as field names and can shadow global symbols. This example demonstrates the default behavior where the template parameter takes precedence.

```nim
# module 'm'
type
  Lev = enum
    levA, levB

var abclev = levB

template tstLev(abclev: Lev) =
  echo abclev, " ", m.abclev

tstLev(levA)
# produces: 'levA levA'
```

--------------------------------

### Compiling and Running Nim Ordinal Enum Example

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/enum_types

Shows the command to compile and run a Nim program demonstrating ordinal enum iteration and methods, along with the expected output.

```bash
nim c -r enums.nim
cdNorth ord: 0
cdEast ord: 1
cdSouth ord: 2
cdWest ord: 3
3

```

--------------------------------

### Nim Multi-methods Example

Source: https://nim-docs.readthedocs.io/en/latest/manual/methods

Illustrates Nim's multi-methods, where dispatch is determined by all object type parameters. This example requires compiling with the `--multimethods:on` flag. It shows how different `collide` method signatures are chosen based on the types of arguments passed.

```nim
type
  Thing = ref object of RootObj
  Unit = ref object of Thing
    x: int

method collide(a, b: Thing) {.inline.} = 
  quit "to override!"

method collide(a: Thing, b: Unit) {.inline.} = 
  echo "1"

method collide(a: Unit, b: Thing) {.inline.} = 
  echo "2"

var a, b: Unit
new a
new b
collide(a, b) # output: 2

```

--------------------------------

### Nim Integer Division Example Output

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/primitives

Provides the output of compiling and running a Nim program that performs integer division. The example demonstrates that the '/' operator returns a floating-point result even for integer operands.

```text
nim c -r numbers2.nim
2.0
```

--------------------------------

### Compile and Run Nim Matrix Addition Example

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/arrays

Shows the command to compile and run a Nim program that performs matrix addition. The output demonstrates the result of adding two 2x2 matrices.

```bash
nim c -r matrix.nim
1, 1, 
1, 1,
```

--------------------------------

### Nim: Compile and Run Example for Inheritance

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/oop

Provides the command to compile and run the Nim code demonstrating object inheritance and dynamic dispatch. The output shows the correct polymorphic behavior of the overridden methods.

```bash
nim c -r oop.nim

```

--------------------------------

### Nim Constructor and Method Call

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/macros

Shows how to create an instance of the 'Rabbit' object using its constructor 'newRabbit' and then calls its 'vocalize' and 'age_human_yrs' methods. It also highlights that the '$' operator is not dynamically dispatched.

```nim
let r = newRabbit("Fluffy", 3)
echo r.vocalize()
echo r.age_human_yrs()
```

--------------------------------

### Nim Defer Statement Rewritten as Try-Finally

Source: https://nim-docs.readthedocs.io/en/latest/manual/exception_handling

Illustrates the equivalent `try-finally` structure for the provided `defer` statement example, clarifying its execution flow.

```nim
proc main =
  var f = open("numbers.txt")
  try:
    f.write "abc"
    f.write "def"
  finally:
    close(f)
```

--------------------------------

### Instantiate and Use Nim Object Types

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/macros

Shows how to create instances of Nim object types, add them to sequences, and call their methods. It highlights dynamic dispatch for methods like 'vocalize' and 'age_human_yrs'.

```nim
var animals: seq[Animal] = @[]
animals.add(Dog(name: "Sparky", age: 10))
animals.add(Cat(name: "Mitten", age: 10))

for a in animals:
  echo a.vocalize()
  echo a.age_human_yrs()

let r = newRabbit("Fluffy", 3)
echo r.vocalize()
echo r.age_human_yrs()
# `$` is not dynamically dispatched--if `r`'s type was
# Animal instead of Rabbit, 'animal:…' would be printed.
echo r
```

--------------------------------

### Standard Varargs in Nim

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/varargs

Demonstrates how to define and use standard varargs in Nim, allowing multiple arguments of the same type to be passed to a function. The example shows printing a list of strings.

```nim
proc printThings(things: varargs[string]) = 
  for thing in things:
    echo thing

printThings "words", "to", "print"
```

```shell
nim c -r ./varargs1.nim
words
to
print
```

--------------------------------

### Define Nim Object Types with Inheritance

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/macros

Demonstrates how to define object types in Nim, including inheritance from a base object. It shows the structure of type definitions, including fields and methods.

```nim
type
  Animal = ref object of RootObj
    name: string
    age: int
  method vocalize: string {.base.} = "..." # use `base` pragma to annotate base methods
  method age_human_yrs: int {.base.} = self.age # `self` is injected
  proc `$`: string = "animal:" & self.name & ":" & $self.age

class Dog of Animal:
  method vocalize: string = "woof"
  method age_human_yrs: int = self.age * 7
  proc `$`: string = "dog:" & self.name & ":" & $self.age

class Cat of Animal:
  method vocalize: string = "meow"
  proc `$`: string = "cat:" & self.name & ":" & $self.age

class Rabbit of Animal:
  proc newRabbit(name: string, age: int) = # the constructor doesn't need a return type
    result = Rabbit(name: name, age: age)
  method vocalize: string = "meep"
  proc `$`: string = "rabbit:" & self.name & ":" & $self.age
```

--------------------------------

### Nim Compilation Option Pragmas Example

Source: https://nim-docs.readthedocs.io/en/latest/manual/pragmas/pragmas/pragma_compilation_option

This example demonstrates how to use Nim pragmas to control compilation options. It shows how to disable runtime checks and optimize code for speed using the 'checks' and 'optimization' pragmas.

```nim
{.checks: off, optimization: speed.}
# compile without runtime checks and optimize for speed

```

--------------------------------

### Nim Include Statement Example

Source: https://nim-docs.readthedocs.io/en/latest/manual/modules

Shows the usage of the `include` statement in Nim, which inserts the content of specified files into the current file. This is useful for splitting large modules.

```nim
include fileA, fileB, fileC

```

```nim
# Module A
echo "Hello World!"

```

```nim
# Module B
proc main() =
include A
main() # => Hello World!

```

--------------------------------

### Nim Case Statement Example

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/case

Demonstrates the syntax and usage of Nim's case statement. This construct allows for branching based on the value of a variable, requiring all possible cases to be explicitly handled.

```nim
let value = "3"
case value:
  of "0":
    echo "Number: ", 0
  of "1", "2":
    echo "1-2"
  of "3":
    echo 3
  else:
    echo "value > 3"
```

--------------------------------

### Nim User-Defined Converter Example

Source: https://nim-docs.readthedocs.io/en/latest/manual/type_relations

Demonstrates how to define and use a user-defined converter in Nim. The 'toInt' converter allows explicit conversion from 'char' to 'int', showcasing implicit and explicit usage.

```nim
converter toInt(x: char): int = result = ord(x)
var
  x: int
  chr: char = 'a'

# implicit conversion magic happens here
x = chr
echo x # => 97
# one can use the explicit form too
x = chr.toInt
echo x # => 97

```

--------------------------------

### Implicit Generic Procedure Conversion Examples in Nim

Source: https://nim-docs.readthedocs.io/en/latest/manual/generics

Illustrates how Nim implicitly converts specific procedure signatures involving `Table` to their generic equivalents. This shows automatic parameterization based on type usage.

```nim
proc p(t: Table; k: Table.Key): Table.Value

# is roughly the same as:

proc p[Key, Value](t: Table[Key, Value]; k: Key): Value
```

```nim
proc p(a: Table, b: Table)

# is roughly the same as:

proc p[Key, Value](a, b: Table[Key, Value])
```

```nim
proc p(a: Table, b: distinct Table)

# is roughly the same as:

proc p[Key, Value, KeyB, ValueB](a: Table[Key, Value], b: Table[KeyB, ValueB])
```

--------------------------------

### Nim Return Statement Example

Source: https://nim-docs.readthedocs.io/en/latest/manual/statements_expressions

Shows the basic usage of the 'return' statement in Nim to end the execution of a procedure and optionally return a value. It covers returning an expression and the implicit return of 'result'.

```nim
return 40+2
```

```nim
proc returnZero(): int =
  # implicitly returns 0
```

--------------------------------

### Defining and initializing arrays and sequences

Source: https://nim-docs.readthedocs.io/en/latest/manual/types

Provides examples of defining fixed-size arrays and dynamic sequences in Nim. It shows array and sequence constructors, type inference for array literals, and the conversion of array literals to sequences using the '@' operator.

```nim
type
  IntArray = array[0..5, int] # an array that is indexed with 0..5
  IntSeq = seq[int] # a sequence of integers
var
  x: IntArray
  y: IntSeq
x = [1, 2, 3, 4, 5, 6]  # [] is the array constructor
y = @[1, 2, 3, 4, 5, 6] # the @ turns the array into a sequence

let z = [1.0, 2, 3, 4] # the type of z is array[0..3, float]

```

--------------------------------

### Nim Case Statement Example

Source: https://nim-docs.readthedocs.io/en/latest/manual/statements_expressions

Demonstrates the basic usage of the Nim 'case' statement for multi-way selection based on an expression's value. It handles multiple matching values and a default 'else' case.

```nim
case readline(stdin):
  of "delete-everything", "restart-computer":
    echo "permission denied"
  of "go-for-a-walk":     echo "please yourself"
  else:                   echo "unknown command"
```

--------------------------------

### Nim Standard OOP Code

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/macros

This code defines classes and methods using Nim's standard syntax. It serves as the baseline for comparison with the macro-generated syntax, highlighting the verbosity that the macro aims to reduce.

```nim
type Animal = ref object of RootObj
  name: string
  age: int
method vocalize(self: Animal): string {.base.} = "..."
method ageHumanYrs(self: Animal): int {.base.} = self.age

type Dog = ref object of Animal
method vocalize(self: Dog): string = "woof"
method ageHumanYrs(self: Dog): int = self.age * 7

type Cat = ref object of Animal
method vocalize(self: Cat): string = "meow"
```

--------------------------------

### Nim Setter and Getter Syntax for Properties

Source: https://nim-docs.readthedocs.io/en/latest/manual/procedures

Illustrates Nim's approach to properties using setter and getter procedures. The example shows how to define a setter (`host=`) and a getter (`host`) for a `Socket` object, and how to use the property syntax (`s.host = 34`) to interact with these procedures.

```nim
# Module asocket
type
Socket* = ref object of RootObj
  host: int # cannot be accessed from the outside of the module
proc `host=`*(s: var Socket, value: int) {.inline.} = 
  ## setter of hostAddr.
  ## This accesses the 'host' field and is not a recursive call to
  ## `host=` because the builtin dot access is preferred if it is
  ## available:
  s.host = value

proc host*(s: Socket): int {.inline.} = 
  ## getter of hostAddr
  ## This accesses the 'host' field and is not a recursive call to
  ## `host` because the builtin dot access is preferred if it is
  ## available:
  s.host

```

```nim
# module B
import asocket
var s: Socket
new s
s.host = 34  # same as `host=`(s, 34)
```

--------------------------------

### Nim Operator Iterators

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/iterators

Shows how to define and use iterators as operators in Nim. The example defines a custom range operator `...` that iterates from a starting value to an ending value. This allows for a more natural syntax when defining ranges.

```nim
# Give it a different name to avoid conflict
iterator `...`*[T](a: T, b: T): T =
  var res: T = a
  while res <= b:
    yield res
    inc res

for i in 0...5:
  echo i

```

--------------------------------

### Nim Iterator Completion Check with `system.finished` (Corrected Example)

Source: https://nim-docs.readthedocs.io/en/latest/manual/iterators_for

Presents the correct way to use `system.finished` with Nim iterators. This pattern involves checking `finished` *after* attempting to get the next value and breaking the loop if the iterator is done, discarding the last potentially invalid value.

```nim
var c = mycount # instantiate the iterator
while true:
  let value = c(1, 3)
  if finished(c): break # and discard 'value'!
  echo value
```

--------------------------------

### Nim Tuples and Sequences

Source: https://nim-docs.readthedocs.io/en/latest/learn/overview/learn_nim_in_5_minutes

Illustrates the declaration and usage of tuples with named fields and sequences in Nim. It shows how to assign values to tuples and add elements to sequences, along with checking for element existence and accessing elements by index.

```nim
# Tuples

var
  child: tuple[name: string, age: int]   # Tuples have *both* field names
  today: tuple[sun: string, temp: float] # *and* order.

child = (name: "Rudiger", age: 2) # Assign all at once with literal ()
today.sun = "Overcast"            # or individual fields.
today.temp = 70.1

# Sequences

var
  drinks: seq[string]

drinks = @["Water", "Juice", "Chocolate"] # @[V1,..,Vn] is the sequence literal

drinks.add("Milk")

if "Milk" in drinks:
  echo "We have Milk and ", drinks.len - 1, " other drinks"

let myDrink = drinks[2]
```

--------------------------------

### Nim Recursive Procedure Example

Source: https://nim-docs.readthedocs.io/en/latest/manual/procedures

A simple example showing that Nim procedures can call themselves recursively.

```nim
# A procedure may call itself recursively.
# Example not provided in source text, but concept is mentioned.
```

--------------------------------

### Nim Anonymous Procedure (Lambda) Example

Source: https://nim-docs.readthedocs.io/en/latest/manual/procedures

Provides an example of using an anonymous procedure in Nim, specifically for sorting a list of strings based on their length. This demonstrates passing a procedure literal as an argument to another procedure.

```nim
var cities = @["Frankfurt", "Tokyo", "New York", "Kyiv"]
cities.sort(proc (x,y: string): int = 
    cmp(x.len, y.len))

```

--------------------------------

### Nim: Examples of Unary Minus Tokenization

Source: https://nim-docs.readthedocs.io/en/latest/manual/lexis/lexical_analysis

Provides examples illustrating how Nim's parser distinguishes between the unary minus operator and its inclusion as part of a numeric literal. The behavior depends on the preceding characters.

```nim
# Examples where -1 is a single token
echo -1
echo(-1)
echo [-1]
echo 3,-1
"abc";-1

# Examples where -1 is parsed as two separate tokens (- and 1)
echo x-1
echo (int)-1
echo [a]-1
"abc"-1

```

--------------------------------

### Nim Procedures with Input and Output Parameters

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/procs

Provides examples of Nim procedures that combine input parameters with a return value. The return type is specified after the input parameters. One example returns a string, and another returns an integer.

```nim
proc sum(a,b: int): string = 
  return "Total: " & $(a+b)

echo sum(10,20)

```

```nim
proc sum(a,b: int): int = a + b

echo sum(10,20)

```

--------------------------------

### Nim Template with Defer and Try-Finally for Resource Management

Source: https://nim-docs.readthedocs.io/en/latest/manual/exception_handling

Compares template implementations using `defer` and `try-finally` for safe file opening and writing, highlighting differences in scope and usage.

```nim
template safeOpenDefer(f, path) =
  var f = open(path, fmWrite)
  defer: close(f)

template safeOpenFinally(f, path, body) =
  var f = open(path, fmWrite)
  try: body # without `defer`, `body` must be specified as parameter
  finally: close(f)

block:
  safeOpenDefer(f, "/tmp/z01.txt")
  f.write "abc"
block:
  safeOpenFinally(f, "/tmp/z01.txt"):
    f.write "abc" # adds a lexical scope
block:
  var f = open("/tmp/z01.txt", fmWrite)
  try:
    f.write "abc" # adds a lexical scope
  finally: close(f)
```

--------------------------------

### Nim Channels: Using Higher-Level Spawn

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/channels

Illustrates inter-thread communication using Nim's higher-level `spawn` function with channels. This example shows a more concise way to manage threads and channel operations, including sending and receiving string messages.

```nim
import threadpool, std/os

var commChan: Channel[string]

proc sendMsg() = 
  sleep(500)
  commChan.send("Hi there!")

proc recvMsg() = 
  let msg = commChan.recv()
  echo "Received msg: " & msg

commChan.open()
spawn recvMsg()
spawn sendMsg()
sync()

```

--------------------------------

### Nim Iterator Completion Check with `system.finished` (Error-Prone Example)

Source: https://nim-docs.readthedocs.io/en/latest/manual/iterators_for

Illustrates a common pitfall when using `system.finished` with Nim iterators. This example shows how `finished` returns true one iteration *after* the iterator has actually finished, leading to unexpected output.

```nim
iterator mycount(a, b: int): int {.closure.} =
  var x = a
  while x <= b:
    yield x
    inc x

var c = mycount # instantiate the iterator
while not finished(c):
  echo c(1, 3)

# Produces
# 1
# 2
# 3
# 0
```

--------------------------------

### Nim: Compile and Run Example for Subtype Checking

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/oop

Provides the command to compile and run the Nim code that demonstrates the usage of the 'of' operator for subtype checking. The output reflects the boolean results of the type comparisons.

```bash
nim c -r of_op.nim

```

--------------------------------

### Nim computedGoto Pragma Example

Source: https://nim-docs.readthedocs.io/en/latest/manual/pragmas/pragmas/pragma_computedgoto

Demonstrates the usage of the computedGoto pragma in Nim to optimize a case statement within a 'while true' loop. This is particularly useful for implementing interpreters. The pragma is ignored if the backend does not support computed goto.

```nim
type
  MyEnum = enum
    enumA, enumB, enumC, enumD, enumE

proc vm() = 
  var instructions: array[0..100, MyEnum]
  instructions[2] = enumC
  instructions[3] = enumD
  instructions[4] = enumA
  instructions[5] = enumD
  instructions[6] = enumC
  instructions[7] = enumA
  instructions[8] = enumB

  instructions[12] = enumE
  var pc = 0
  while true:
    {.computedGoto.}
    let instr = instructions[pc]
    case instr
    of enumA:
      echo "yeah A"
    of enumC, enumD:
      echo "yeah CD"
    of enumB:
      echo "yeah B"
    of enumE:
      break
    inc(pc)

vm()

```

--------------------------------

### Nim Procedure Definition with Indentation

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/blocks

Demonstrates how Nim uses indentation to define the body of a procedure. The code inside the procedure is indented, creating a code block. This example defines a procedure 'example' that takes an integer, calculates a new value, and prints it.

```nim
proc example(val:int) = 
  # prints val plus 20
  let value = val + 20  
  echo value

example(10)

```

--------------------------------

### Nim IO and Control Flow (case, readLine, while, if)

Source: https://nim-docs.readthedocs.io/en/latest/learn/overview/learn_nim_in_5_minutes

Demonstrates basic input/output operations and control flow structures in Nim. It includes the `case` statement for conditional branching based on user input, and a `while` loop with `if`, `continue`, and `break` for iterative processing.

```nim
# IO and Control Flow

# `case`, `readLine()`

echo "Read any good books lately?"
case readLine(stdin)
of "no", "No":
  echo "Go to your local library."
of "yes", "Yes":
  echo "Carry on, then."
else:
  echo "That's great; I assume."

# `while`, `if`, `continue`, `break`

import strutils as str # http://nim-lang.org/docs/strutils.html
echo "I'm thinking of a number between 41 and 43. Guess which!"
let number: int = 42
var
  raw_guess: string
  guess: int
while guess != number:
  raw_guess = readLine(stdin)
  if raw_guess == "": continue # Skip this iteration
  guess = str.parseInt(raw_guess)
  if guess == 1001:
    echo("AAAAAAGGG!")
    break
  elif guess > number:
    echo("Nope. Too high.")
  elif guess < number:
    echo(guess, " is too low")
  else:
    echo("Yeeeeeehaw!")
```

--------------------------------

### Nim Documentation Comments: Single-line and Multi-line

Source: https://nim-docs.readthedocs.io/en/latest/manual/lexis/lexical_analysis

Shows the syntax for documentation comments in Nim, which start with '##'. These can be single-line or multi-line, enclosed by '##[' and ']##', and support nesting.

```nim
proc foo =
##[Long documentation comment
here.
]##
```

--------------------------------

### Nim Break Statement

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/while

Illustrates the use of the 'break' statement to immediately exit a loop in Nim. The example shows breaking out of an infinite loop when a condition is met.

```nim
var i = 0
while true:
  if i > 5:
    break
  echo i
  i += 1
```

--------------------------------

### Compile Nim to C++ with Cache

Source: https://nim-docs.readthedocs.io/en/latest/howto/interop/cpp/methods

Demonstrates how to compile Nim code to C++ and specify a cache directory for generated files. This is useful for inspecting the intermediate C++ code to verify the correctness of the wrapping. The command `nim cpp --nimcache:myfolder ex01.nim` compiles `ex01.nim` and places generated C++ files in the `myfolder` directory.

```shell
nim cpp --nimcache:myfolder ex01.nim

```

--------------------------------

### Process Multiline Raw Strings by Line in Nim

Source: https://nim-docs.readthedocs.io/en/latest/learn/overview/learn_nim_in_5_minutes

Illustrates the use of multiline raw strings in Nim and how to iterate over each line of the string after splitting it. This is helpful for processing text blocks.

```nim
let myString = """
an <example>
`string` to
play with
"""

for line in splitLines(myString):
  echo(line)
```

--------------------------------

### Nim Importing Modules from Subdirectories

Source: https://nim-docs.readthedocs.io/en/latest/manual/modules

Illustrates how to import modules located in subdirectories using path notation in Nim. It shows the correct way to specify paths and the limitations regarding module naming.

```nim
import lib/pure/os, "lib/pure/times"

```

--------------------------------

### Nim Comment Syntax: Single-line and Multi-line

Source: https://nim-docs.readthedocs.io/en/latest/manual/lexis/lexical_analysis

Illustrates the syntax for single-line and multi-line comments in Nim. Single-line comments start with '#', while multi-line comments are enclosed by '#[' and ']#'.

```nim
i = 0     # This is a single comment over multiple lines.
# The lexer merges these two pieces.
# The comment continues here.

#[Comment here.
Multiple lines
are not a problem.]#
```

--------------------------------

### Nim Template Definition and Invocation

Source: https://nim-docs.readthedocs.io/en/latest/manual/templates

Demonstrates the basic definition and invocation of a Nim template, showing how it performs a simple substitution. The `!=` operator is presented as an example of a built-in template.

```nim
template `!=` (a, b: untyped): untyped =
# this definition exists in the System module
not (a == b)
assert(5 != 6) # the compiler rewrites that to: assert(not (5 == 6))
```

--------------------------------

### Import C strcmp Function using FFI in Nim

Source: https://nim-docs.readthedocs.io/en/latest/learn/overview/learn_nim_in_5_minutes

Shows how to import a C standard library function (`strcmp`) into Nim using the `{.importc.}` pragma. This enables calling C functions directly from Nim code, highlighting Nim's FFI capabilities.

```nim
proc strcmp(a, b: cstring): cint {.importc: "strcmp", nodecl.}

let cmp = strcmp("C?", "Easy!")
```

--------------------------------

### Nim Generic Inference Restrictions

Source: https://nim-docs.readthedocs.io/en/latest/manual/generics

Illustrates Nim's restrictions on generic type inference for `var T` and `typedesc[T]`. It provides examples of allowed and disallowed generic instantiations.

```nim
proc g[T](f: proc(x: T); x: T) = 
  f(x)

proc c(y: int) = echo y
proc v(y: var int) = 
  y += 100
var i: int

# allowed: infers 'T' to be of type 'int'
g(c, 42)

# not valid: 'T' is not inferred to be of type 'var int'
g(v, i)

# also not allowed: explicit instantiation via 'var int'
g[var int](v, i)
```

--------------------------------

### Nim Line Comments

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/comments

Demonstrates the use of single-line comments in Nim, which start with a '#' symbol and extend to the end of the line. Comments can appear on their own line or at the end of a code line.

```nim
# This is a comment
echo "This is code" # This is another comment

```

--------------------------------

### Nim Overloaded Procedures with 'result' Variable

Source: https://nim-docs.readthedocs.io/en/latest/manual/procedures

Provides an example of overloaded procedures in Nim, demonstrating the use of the implicit 'result' variable for return values and how overloading resolution works.

```nim
proc toLower(c: char): char = # toLower for characters
  if c in {'A'..'Z'}:
    result = chr(ord(c) + (ord('a') - ord('A')))
  else:
    result = c

proc toLower(s: string): string = # toLower for strings
  result = newString(len(s))
  for i in 0..len(s) - 1:
    result[i] = toLower(s[i]) # calls toLower for characters; no recursion!
```

--------------------------------

### Nim Object Definition and Inheritance

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/macros

Defines a base 'Animal' object with properties and methods, and then creates derived classes 'Dog', 'Cat', and 'Rabbit' that inherit from 'Animal'. Demonstrates method overriding and the use of the 'base' pragma.

```nim
type
  RootObj = ref object

  Animal = ref object of RootObj
    name: string
    age: int
  method vocalize(self: Animal): string {.base.} = "..."
  method age_human_yrs(self: Animal): int {.base.} = self.age
  proc `$`(self: Animal): string = "animal:" & self.name & ":" & $self.age

  Dog = ref object of Animal
  method vocalize(self: Dog): string = "woof"
  method age_human_yrs(self: Dog): int = self.age * 7
  proc `$`(self: Dog): string = "dog:" & self.name & ":" & $self.age

  Cat = ref object of Animal
  method vocalize(self: Cat): string = "meow"
  proc `$`(self: Cat): string = "cat:" & self.name & ":" & $self.age

  Rabbit = ref object of Animal
  proc newRabbit(name: string, age: int): Rabbit = # the constructor doesn't need a return type
    result = Rabbit(name: name, age: age)
  method vocalize(self: Rabbit): string = "meep"
  proc `$`(self: Rabbit): string = "rabbit:" & self.name & ":" & $self.age
```

--------------------------------

### Nim Identifier Syntax Rules

Source: https://nim-docs.readthedocs.io/en/latest/manual/lexis/lexical_analysis

Defines the rules for constructing valid identifiers in Nim. Identifiers must start with a letter, cannot end with an underscore, and cannot contain consecutive underscores.

```nim
letter ::= 'A'..'Z' | 'a'..'z' | '\x80'..\xff' digit ::= '0'..'9' IDENTIFIER ::= letter ( ['_'] (letter | digit) )*
```

--------------------------------

### Manage experimental 'parallel' feature scope with push/pop in Nim

Source: https://nim-docs.readthedocs.io/en/latest/manual/pragmas/pragmas/pragma_experimental

This example shows how to manage the scope of the experimental 'parallel' feature using {.push experimental: "parallel".} and {.pop.} in Nim. This is useful for macro and generic instantiations that cross module boundaries, ensuring the feature is only enabled within the specified block.

```nim
# client.nim
proc useParallel*[T](unused: T) =
  # use a generic T here to show the problem.
  {.push experimental: "parallel".}
  parallel:
    for i in 0..4:
      echo "echo in parallel"

  {.pop.}

```

```nim
import client
useParallel(1)

```

--------------------------------

### Importc Pragma for Procedures

Source: https://nim-docs.readthedocs.io/en/latest/manual/pragmas/ffi/pragma_importc

Demonstrates how to use the 'importc' pragma to import a C procedure like 'printf'. It shows how to specify the C identifier and include necessary headers.

```APIDOC
## importc Pragma for Procedures

### Description
Imports a procedure or variable from C. The optional argument is a string containing the C identifier. If the argument is missing, the C name is the Nim identifier exactly as spelled.

### Method
Pragma

### Endpoint
N/A

### Parameters
#### Pragma Parameters
- **importc** (string) - Optional - The C identifier for the procedure or variable.
- **header** (string) - Optional - The header file to include for the C function.
- **varargs** - Optional - Indicates that the procedure accepts a variable number of arguments.

### Request Example
```nim
proc printf(formatstr: cstring) {.header: "<stdio.h>", importc: "printf", varargs.}
```

### Response
#### Success Response
N/A (This is a compile-time pragma)

#### Response Example
N/A
```

--------------------------------

### Attempting to modify cstring literal (unsafe)

Source: https://nim-docs.readthedocs.io/en/latest/manual/types

Shows an example of attempting to modify a cstring literal. This operation is considered unsafe and incorrect because cstring literals are typically stored in read-only memory.

```nim
var x = cstring"literals"
x[1] = 'A' # This is wrong!!!

```

--------------------------------

### Nim Comments and Variable Declaration

Source: https://nim-docs.readthedocs.io/en/latest/learn/overview/learn_nim_in_5_minutes

Demonstrates single-line and multi-line comments in Nim, as well as variable declaration using `var` with and without type annotations. It also shows the use of `let` for immutable bindings and `const` for compile-time constants.

```nim
# Single-line comments start with a #

#[
  This is a multiline comment.
  In Nim, multiline comments can be nested, beginning with #[
  ... and ending with ]#
]#

discard """
This can also work as a multiline comment.
Or for unparsable, broken code
"""

var                     # Declare (and assign) variables,
  letter: char = 'n'    # with or without type annotations
  lang = "N" & "im"
  nLength: int = len(lang)
  boat: float
  truth: bool = false

let            # Use let to declare and bind variables *once*.
  legs = 400   # legs is immutable.
  arms = 2_000 # _ are ignored and are useful for long numbers.
  aboutPi = 3.15

const            # Constants are computed at compile time. This provides
  debug = true   # performance and is useful in compile time expressions.
  compileBadCode = false

when compileBadCode:            # `when` is a compile time `if`
  legs = legs + 1               # This error will never be compiled.
  const input = readline(stdin) # Const values must be known at compile time.

discard 1 > 2 # Note: The compiler will complain if the result of an expression
              # is unused. `discard` bypasses this.
```

--------------------------------

### Nim Continue Statement

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/while

Explains the 'continue' statement in Nim, which skips the rest of the current loop iteration and proceeds to the next. The example shows skipping certain iterations based on a condition.

```nim
var i = 0
while true:
  if i > 3 and i <= 5:
    i += 1      # required to avoid infinite loop
    continue
  elif i > 5:
    break
  echo "inner ", i
  i += 1
  # `continue` will take you here

echo "end"
```

--------------------------------

### Overload Resolution Algorithm Example

Source: https://nim-docs.readthedocs.io/en/latest/manual/overload_resolution

Illustrates the overload resolution algorithm by comparing counts of different matching categories for routines 'p' and 'q'. It returns true if 'p' matches better than 'q', false otherwise, or 'ambiguous' if further disambiguation is needed.

```nim
proc takesInt(x: int) = echo "int"
proc takesInt[T](x: T) = echo "T"
proc takesInt(x: int16) = echo "int16"
takesInt(4) # "int"
var x: int32
takesInt(x) # "T"
var y: int16
takesInt(y) # "int16"
var z: range[0..4] = 0
takesInt(z) # "T"
```

--------------------------------

### Nim Methods with Dynamic Dispatch Example

Source: https://nim-docs.readthedocs.io/en/latest/manual/methods

Demonstrates Nim methods using dynamic dispatch for polymorphic behavior. It defines abstract base classes and concrete implementations for expressions, showcasing how method calls resolve at runtime based on the object's actual type. Requires Nim compiler.

```nim
type
Expression = ref object of RootObj ## abstract base class for an expression
Literal = ref object of Expression
x: int
PlusExpr = ref object of Expression
a, b: Expression

method eval(e: Expression): int {.base.} = 
  # override this base method
  raise newException(CatchableError, "Method without implementation override")

method eval(e: Literal): int = return e.x

method eval(e: PlusExpr): int = 
  # watch out: relies on dynamic binding
  result = eval(e.a) + eval(e.b)

proc newLit(x: int): Literal = 
  new(result)
  result.x = x

proc newPlus(a, b: Expression): PlusExpr = 
  new(result)
  result.a = a
  result.b = b

echo eval(newPlus(newPlus(newLit(1), newLit(2)), newLit(4)))

```

--------------------------------

### C++ osg::Vec3Array Declaration

Source: https://nim-docs.readthedocs.io/en/latest/howto/interop/cpp/nothing_new1

This is a standard C++ declaration for creating an instance of osg::Vec3Array using a reference pointer. It's provided as context for the Nim wrapping examples.

```cpp
osg::ref_ptr<osg::Vec3Array> vertices = new osg::Vec3Array;

```

--------------------------------

### Nim OpenArray Example

Source: https://nim-docs.readthedocs.io/en/latest/manual/types

Demonstrates the usage of the `openArray` type in Nim procedures, allowing them to accept arrays or sequences of varying sizes. The `repr` function is used to show the type of the passed argument.

```nim
proc testOpenArray(x: openArray[int]) = echo repr(x)
testOpenArray([1,2,3])  # array[]
testOpenArray(@[1,2,3]) # seq[]
```

--------------------------------

### Nim Method Call Syntax Examples

Source: https://nim-docs.readthedocs.io/en/latest/manual/procedures

Demonstrates the method call syntax in Nim, allowing procedures to be called with the first argument preceding the procedure name and a dot. This syntax is applicable to objects and other types, and parentheses can be omitted for procedures without arguments.

```nim
echo "abc".len # is the same as echo len "abc"
echo "abc".toUpper()
echo {'a', 'b', 'c'}.card
stdout.writeLine("Hallo") # the same as writeLine(stdout, "Hallo")
```

--------------------------------

### Importc Pragma for Variables and Constants

Source: https://nim-docs.readthedocs.io/en/latest/manual/pragmas/ffi/pragma_importc

Explains how to use the 'importc' pragma with 'let' statements to import C constants. It shows how to declare a Nim variable that corresponds to a C constant.

```APIDOC
## importc Pragma for Variables and Constants

### Description
When `importc` is applied to a `let` statement, it can omit its value, which will then be expected to come from C. This can be used to import a C `const`.

### Method
Pragma

### Endpoint
N/A

### Parameters
#### Pragma Parameters
- **importc** - Required - Indicates that the variable is imported from C.
- **nodecl** - Optional - Prevents the declaration of the variable in the generated C code.

### Request Example
```nim
{.emit: "const int cconst = 42;"}
let cconst {.importc, nodecl.}: cint

assert cconst == 42
```

### Response
#### Success Response
N/A (This is a compile-time pragma)

#### Response Example
N/A
```

--------------------------------

### Macro Pragmas Transformation to Async (Nim)

Source: https://nim-docs.readthedocs.io/en/latest/manual/pragmas/user_defined_pragmas

This example illustrates the transformation of a macro pragma applied to a procedure type. The `.async.` pragma is converted into an `async` wrapper around the procedure type.

```nim
type
  AsyncEventHandler = proc (x: Event) {.async.}

```

--------------------------------

### Nim Defining a Custom Exception Type

Source: https://nim-docs.readthedocs.io/en/latest/manual/exception_handling

Provides an example of how to define a custom exception type in Nim by inheriting from the base `Exception` object. Ending the name with 'Error' is a recommended convention.

```nim
type
LoadError* = object of Exception
```

--------------------------------

### Nim String Literal Examples

Source: https://nim-docs.readthedocs.io/en/latest/learn/nim_by_example/strings

Demonstrates the creation and basic usage of different string literal types in Nim: quoted strings, raw strings, and proc strings. It also shows a simple procedure for string manipulation.

```nim
echo "words words words ⚑"
echo """
<html>
  <head>
  </head>

  <body>
  </body>
</html> "

proc re(s: string): string = s

echo r".".
echo re"\b[a-z]++\b"

```
Tokens:
Raw