Nim

https://nim-lang.github.io/Nim
Admin
Nim is a statically-typed programming language that compiles to C, C++, JavaScript, and other...
Tokens:1,807,559
Snippets:20,001
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Example of installing foreign dependencies

Source: https://nim-lang.github.io/Nim/distros.html

This example shows how to use `foreignDep` to register dependencies for a specific distribution like Ubuntu. The output demonstrates the commands that would typically be run to install these dependencies.

```text
To complete the installation, run:

sudo apt-get install libblas-dev
sudo apt-get install libvoodoo
```

```nim
if detectOs(Ubuntu):
  foreignDep "lbiblas-dev"
  foreignDep "libvoodoo"
```

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

### Nim Documentation Files Example

Source: https://nim-lang.github.io/Nim/niminst.html

Lists documentation files to be included in the installer, such as HTML overviews.

```niminst
[Documentation]
; Files: "doc/*.html"
; Files: "doc/*.cfg"
; Files: "doc/*.pdf"
; Files: "doc/*.ini"
Files: "doc/html/overview.html"
Start: "doc/html/overview.html"

```

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

### InnoSetup Configuration Example

Source: https://nim-lang.github.io/Nim/niminst.html

Configures the path to the Inno Setup compiler and specifies flags to be passed to it.

```niminst
[InnoSetup]
path = r"c:\Program Files (x86)\Inno Setup 5\iscc.exe"
flags = "/Q"

```

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

### Nim Unix Installation Script Example

Source: https://nim-lang.github.io/Nim/niminst.html

Enables the generation of installation and uninstallation scripts for Unix-like systems.

```niminst
[Unix]
InstallScript: "yes"
UninstallScript: "yes"
Files: "bin/nim-gdb"
Files: "build_all.sh"

```

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

### Example: Get Server Port

Source: https://nim-lang.github.io/Nim/asynchttpserver.html

Demonstrates how to create a server, listen on port 0 (dynamic assignment), and assert that a valid port was assigned.

```nim
from std/nativesockets import Port
let server = newAsyncHttpServer()
server.listen(Port(0))
assert server.getPort.uint16 > 0
server.close()
```

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

### Full unittest example

Source: https://nim-lang.github.io/Nim/unittest.html

Demonstrates the structure of a test suite with setup, teardown, and various assertion types like 'require', 'check', and 'expect'.

```nim
suite "description for this stuff":
  echo "suite setup: run once before the tests"
  
  setup:
    echo "run before each test"
  
  teardown:
    echo "run after each test"
  
  test "essential truths":
    # give up and stop if this fails
    require(true)
  
  test "slightly less obvious stuff":
    # print a nasty message and move on, skipping
    # the remainder of this block
    check(1 != 1)
    check("asd"[2] == 'd')
  
  test "out of bounds error is thrown on bad access":
    let v = @[1, 2, 3]  # you can do initialization here
    expect(IndexDefect):
      discard v[4]
  
  echo "suite teardown: run once after the tests"
```

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

### niminst Config File 'files' Key Example

Source: https://nim-lang.github.io/Nim/niminst.html

Shows how to specify files and directories to be included in the installation using the 'files' key in the niminst configuration file. Supports wildcards and multiple entries.

```nimconfig
[Config]
Files: "configDir"
Files: "otherconfig/*.conf;otherconfig/*.cfg"

```

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

### Nim Downloadable Components Example

Source: https://nim-lang.github.io/Nim/niminst.html

Defines optional components that can be downloaded during installation, including documentation, MinGW, and DLLs.

```niminst
;           Section | dir | zipFile | size hint (in KB) | url | exe start menu entry
Download: r"Documentation|doc|docs.zip|13824|https://nim-lang.org/download/docs-${version}.zip|overview.html"
Download: r"C Compiler (MingW)|dist|mingw.zip|82944|https://nim-lang.org/download/${mingw}.zip"
Download: r"Support DLLs|bin|nim_dlls.zip|479|https://nim-lang.org/download/dlls.zip"
Download: r"Aporia Text Editor|dist|aporia.zip|97997|https://nim-lang.org/download/aporia-0.4.0.zip|aporia-0.4.0\bin\aporia.exe"
; for now only NSIS supports optional downloads

```

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

### Nim Windows Executables Example

Source: https://nim-lang.github.io/Nim/niminst.html

Lists Windows executable files to be installed, including the Nim compiler and related tools.

```niminst
[Windows]
Files: "bin/nim.exe"
Files: "bin/nimgrep.exe"
Files: "bin/nimsuggest.exe"
Files: "bin/nimble.exe"
Files: "bin/vccexe.exe"
Files: "bin/nimgrab.exe"
Files: "bin/nimpretty.exe"
Files: "bin/testament.exe"
Files: "bin/nim-gdb.bat"
Files: "bin/atlas.exe"

Files: "koch.exe"
Files: "finish.exe"
; Files: "bin/downloader.exe"

; Files: "dist/mingw"
Files: r"tools\start.bat"
BinPath: r"bin;dist\mingw\bin;dist"

```

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

### Nim Library Files Example

Source: https://nim-lang.github.io/Nim/niminst.html

Specifies the Nim library directory to be included in the installation.

```niminst
[Lib]
Files: "lib"

```

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

### Initialize RstGenerator Example

Source: https://nim-lang.github.io/Nim/rstgen.html

Example demonstrating how to initialize the `RstGenerator` with default configuration and output target.

```nim
import packages/docutils/rstgen

var gen: RstGenerator
gen.initRstGenerator(outHtml, defaultConfig(), "filename", {})
```

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

### Example: Setting and Getting XmlNode Attributes

Source: https://nim-lang.github.io/Nim/xmltree.html

Demonstrates setting attributes using XmlAttributes and retrieving them using the attr proc.

```nim
var j = newElement("myTag")
let att = {"key1": "first value", "key2": "second value"}.toXmlAttributes
j.attrs = att
assert j.attr("key1") == "first value"
assert j.attr("key2") == "second value"
```

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

### Runnable Examples for Procedures

Source: https://nim-lang.github.io/Nim/contributing.html

Use `runnableExamples` for usage examples when possible. Code blocks can be used for examples not suitable for `runnableExamples`.

```nim
proc addThree*(x, y, z: int8): int =
  ## Adds three `int8` values, treating them as unsigned and
  ## truncating the result.
  ##
  ##   ```
  ##   # things that aren't suitable for a `runnableExamples` go in code block:
  ##   echo execCmdEx("git pull")
  ##   drawOnScreen()
  ##   ```
  runnableExamples:
    # `runnableExamples` is usually preferred to code blocks, when possible.
    doAssert addThree(3, 125, 6) == -122
  result = x +% y +% z

```

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

### Asynchronous Content Fetch Example

Source: https://nim-lang.github.io/Nim/httpclient.html

An example demonstrating how to create an AsyncHttpClient, fetch content from a URL asynchronously, and assert its content.

```nim
import std/[asyncdispatch, strutils]

proc asyncProc(): Future[string] {.async.} =
  let client = newAsyncHttpClient()
  result = await client.getContent("http://example.com")

let exampleHtml = waitFor asyncProc()
assert "Example Domain" in exampleHtml
assert "Pizza" notin exampleHtml
```

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

### Synchronous Content Fetch Example

Source: https://nim-lang.github.io/Nim/httpclient.html

An example demonstrating how to create an HttpClient, fetch content from a URL synchronously, and assert its content.

```nim
import std/strutils

let exampleHtml = newHttpClient().getContent("http://example.com")
assert "Example Domain" in exampleHtml
assert "Pizza" notin exampleHtml
```

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

### Runnable Examples Documentation

Source: https://nim-lang.github.io/Nim/system.html

Marks code sections as runnable examples for documentation generation and testing.

```nim
proc runnableExamples(rdoccmd = ""; body: untyped) {.magic: "RunnableExamples",
    ...raises: [], tags: [], forbids: [].}
```

```nim
proc timesTwo*(x: int): int =
  ## This proc doubles a number.
  runnableExamples:
    # at module scope
    const exported* = 123
    assert timesTwo(5) == 10
    block: # at block scope
      defer: echo "done"
  runnableExamples "-d:foo -b:cpp":
    import std/compilesettings
    assert querySetting(backend) == "cpp"
    assert defined(foo)
  runnableExamples "-r:off": ## this one is only compiled
     import std/browsers
     openDefaultBrowser "https://forum.nim-lang.org/"
  2 * x
```

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

### Pointer equality example

Source: https://nim-lang.github.io/Nim/system.html

Example demonstrating pointer equality.

```nim
var # this is a wildly dangerous example
  a = cast[pointer](0)
  b = cast[pointer](nil)
assert a == b # true due to the special meaning of `nil`/0 as a pointer
```

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

### Setup program

Source: https://nim-lang.github.io/Nim/compiler/ast.html

Initializes the program configuration and cache.

```Nim
proc setupProgram(config: ConfigRef; cache: IdentCache) {....raises: [], tags: [],
    forbids: [].}
```

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

### NSIS Flags Example

Source: https://nim-lang.github.io/Nim/niminst.html

Sets flags for the NSIS (Nullsoft Scriptable Install System) installer.

```niminst
[NSIS]
flags = "/V0"

```

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

### Example Configuration File Syntax

Source: https://nim-lang.github.io/Nim/parsecfg.html

Illustrates the supported syntax for configuration files, including comments, sections, key-value pairs, options, and various string literal formats.

```nim
# This is a comment.
; this too.

[Common]
cc=gcc     # '=' and ':' are the same
--foo="bar"   # '--cc' and 'cc' are the same, 'bar' and '"bar"' are the same (except for '#')
macrosym: "#"  # Note that '#' is interpreted as a comment without the quotation
--verbose

[Windows]
isConsoleApplication=False ; another comment

[Posix]
isConsoleApplication=True

key1: "in this string backslash escapes are interpreted\n"
key2: r"in this string not"
key3: """triple quotes strings
are also supported. They may span
multiple lines."""

--"long option with spaces": r"c:\myfiles\test.txt" 

```

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

### Example: Get OS Name

Source: https://nim-lang.github.io/Nim/posix_utils.html

Demonstrates how to import parsecfg and use osReleaseFile to get the OS name.

```nim
import std/parsecfg
when defined(linux):
  let data = osReleaseFile()
  echo "OS name: ", data.getSectionValue("", "NAME") ## the data is up to each distro.
```

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

### Get JavaScript Constructor Name Example

Source: https://nim-lang.github.io/Nim/jsutils.html

Shows how to get the constructor name for Nim-created JavaScript arrays like Float64Array.

```nim
import std/jsffi
let a = array[2, float64].default
assert jsConstructorName(a) == "Float64Array"
assert jsConstructorName(a.toJs) == "Float64Array"

```

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

### SizeOf Usage Examples

Source: https://nim-lang.github.io/Nim/system.html

Examples showing how to use sizeof with characters and integers.

```nim
sizeof('A') # => 1
sizeof(2) # => 8
```

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

### Initialize empty tables

Source: https://nim-lang.github.io/Nim/tables.html

Examples showing how to initialize empty ordered and standard tables.

```nim
let
  a = initOrderedTable[int, string]()
  b = initOrderedTable[char, seq[int]]()
```

```nim
let
  a = initTable[int, string]()
  b = initTable[char, seq[int]]()
```

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

### Nim Regex Lookbehind and Start Offset Example

Source: https://nim-lang.github.io/Nim/re.html

Demonstrates using lookbehind assertions and the `start` parameter in Nim's `find` and `match` functions. Note that output positions are relative to the start of the input string.

```nim
import std/re
## Unless specified otherwise, `start` parameter in each proc indicates
## where the scan starts, but outputs are relative to the start of the input
## string, not to `start`:
doAssert find("uxabc", re"(?<=x|y)ab", start = 1) == 2 # lookbehind assertion
doAssert find("uxabc", re"ab", start = 3) == -1 # we're past `start` => not found
doAssert not match("xabc", re"^abc$", start = 1)
  # can't match start of string since we're starting at 1
```

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

### Setup Virtual Machine

Source: https://nim-lang.github.io/Nim/compiler/scriptconfig.html

Initializes the virtual machine context for a specific module and script.

```nim
proc setupVM(module: PSym; cache: IdentCache; scriptName: string;
             graph: ModuleGraph; idgen: IdGenerator): PEvalContext {....raises: [],
    tags: [], forbids: [].}
```

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

### Nim Naming Conventions Example

Source: https://nim-lang.github.io/Nim/nep1.html

Illustrates Nim's naming conventions for constants and variables. Constants can start with either case, while variables must start with a lowercase letter.

```nim
# Constants can start with either a lower case or upper case letter.
const aConstant = 42
const FooBar = 4.2

var aVariable = "Meep" # Variables must start with a lowercase letter.
```

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

### StaticExec Usage Examples

Source: https://nim-lang.github.io/Nim/system.html

Examples of using staticExec for build information and cached execution.

```nim
const buildInfo = "Revision " & staticExec("git rev-parse HEAD") &
                  "\nCompiled on " & staticExec("uname -v")
```

```nim
const stateMachine = staticExec("dfaoptimizer", "input", "0.8.0")
```

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

### Example: Getting XmlNode Attribute Count

Source: https://nim-lang.github.io/Nim/xmltree.html

Shows how to check the attribute count before and after setting attributes.

```nim
var j = newElement("myTag")
assert j.attrsLen == 0
let att = {"key1": "first value", "key2": "second value"}.toXmlAttributes
j.attrs = att
assert j.attrsLen == 2
```

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

### Asynchronous File Read/Write Example

Source: https://nim-lang.github.io/Nim/asyncfile.html

Demonstrates opening a file asynchronously, writing data, seeking to the beginning, reading all content, and closing the file. Ensure the 'asyncfile', 'asyncdispatch', and 'os' modules are imported.

```nim
import std/[asyncfile, asyncdispatch, os]

proc main() {.async.} = 
  var file = openAsync(getTempDir() / "foobar.txt", fmReadWrite)
  await file.write("test")
  file.setFilePos(0)
  let data = await file.readAll()
  doAssert data == "test"
  file.close()

waitFor main()
```

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

### Basic Async HTTP Server Example

Source: https://nim-lang.github.io/Nim/asynchttpserver.html

This example demonstrates how to create an asynchronous HTTP server that listens on a dynamically chosen port. It responds to all requests with a '200 OK' status and 'Hello World' as the body. Ensure `asyncdispatch` is imported for `sleepAsync` and `waitFor`.

```nim
import std/asynchttpserver
# This example will create an HTTP server on an automatically chosen port.
# It will respond to all requests with a `200 OK` response code and "Hello World"
# as the response body.
import std/asyncdispatch
proc main {.async.} = 
  var server = newAsyncHttpServer()
  proc cb(req: Request) {.async.} = 
    echo (req.reqMethod, req.url, req.headers)
    let headers = {"Content-type": "text/plain; charset=utf-8"}
    await req.respond(Http200, "Hello World", headers.newHttpHeaders())

  server.listen(Port(0)) # or Port(8080) to hardcode the standard HTTP port.
  let port = server.getPort
  echo "test this with: curl localhost:" & $port.uint16 & "/"
  while true:
    if server.shouldAcceptRequest():
      await server.acceptRequest(cb)
    else:
      # too many concurrent connections, `maxFDs` exceeded
      # wait 500ms for FDs to be closed
      await sleepAsync(500)

waitFor main()
```

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

### open

Source: https://nim-lang.github.io/Nim/sexp.html

Initializes the SexpParser with an input stream.

```APIDOC
## proc open(my: var SexpParser; input: Stream)

### Description
Initializes the parser with an input stream.

### Parameters
#### Path Parameters
- **my** (var SexpParser) - Description not available
- **input** (Stream) - Description not available
```

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

### Integrate Atlas with GitHub Actions

Source: https://nim-lang.github.io/Nim/atlas.html

Example configuration for caching dependencies and installing Atlas in a CI environment.

```yaml
    ... Nim setup ...
    
    - name: Install Latest Atlas (recommend until Nim's Atlas verision catches up in 2.2.8+)
      run: |
        nimble install 'https://github.com/nim-lang/atlas@#head'
    
    - name: Cache packages
      uses: actions/cache@v3
      with:
        path: deps/
        key: ${{ runner.os }}-${{ hashFiles('foo.nimble') }}
    
    - name: Install Deps
      run: |
        atlas install --feature=test --feature=other # etc
```

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

### Setup C generation

Source: https://nim-lang.github.io/Nim/compiler/cgen.html

Sets up the context for C code generation.

```Nim
proc setupCgen(graph: ModuleGraph; module: PSym; idgen: IdGenerator): PPassContext {
    ...raises: [KeyError, OSError, Exception, ValueError, IOError], tags: [
    ReadEnvEffect, ReadIOEffect, ReadDirEffect, RootEffect, WriteDirEffect],
    forbids: [].}
```

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

### Get match bounds from RegexMatch

Source: https://nim-lang.github.io/Nim/nre.html

Retrieves the start and end indices of the entire match from a `RegexMatch` object as an `HSlice[int, int]`.

```nim
func matchBounds(pattern: RegexMatch): HSlice[int, int] {
    ...raises: [], tags: [],
    forbids: [].
}
```

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

### Build C Sources

Source: https://nim-lang.github.io/Nim/koch.html

Builds the C sources for installation. Accepts the same options as the 'boot' command.

```nim
csource
```

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

### Prepare output directory

Source: https://nim-lang.github.io/Nim/compiler/options.html

Creates the output directory and returns the full path to the output file.

```nim
proc prepareToWriteOutput(conf: ConfigRef): AbsoluteFile {. 
    ...raises: [OSError, IOError], tags: [ReadDirEffect, WriteDirEffect],
    forbids: [].}
```

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

### Get capture bounds from RegexMatch

Source: https://nim-lang.github.io/Nim/nre.html

Retrieves the start and end indices of captured groups within a `RegexMatch` object as a `CaptureBounds` slice.

```nim
func captureBounds(pattern: RegexMatch): CaptureBounds {
    ...raises: [], tags: [],
    forbids: [].
}
```

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

### Get JavaScript Type of Value Example

Source: https://nim-lang.github.io/Nim/jsutils.html

Illustrates using jsTypeOf to identify JavaScript types like 'number', 'boolean', 'object', and 'bigint'.

```nim
import std/[jsffi, jsbigints]
assert jsTypeOf(1.toJs) == "number"
assert jsTypeOf(false.toJs) == "boolean"
assert [1].toJs.jsTypeOf == "object" # note the difference with `getProtoName`
assert big"1".toJs.jsTypeOf == "bigint"

```

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

### Example: Using startsWith with RegExp

Source: https://nim-lang.github.io/Nim/jsre.html

Illustrates how to use the 'startsWith' procedure to verify if a string begins with a pattern defined by a RegExp.

```nim
let jsregex: RegExp = newRegExp(r"abc", r"i")
assert "abcd".startsWith jsregex
```

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

### niminst Configuration File Example

Source: https://nim-lang.github.io/Nim/niminst.html

Demonstrates the syntax for niminst configuration files, including comments, key-value pairs, and string literal variations. Supports variables via the `$variable` notation.

```nimconfig
# This is a comment.
; this too.

[Common]
cc=gcc     # '=' and ':' are the same
--foo="bar"   # '--cc' and 'cc' are the same, 'bar' and '"bar"' are the same (except for '#')
macrosym: "#"  # Note that '#' is interpreted as a comment without the quotation
--verbose

[Windows]
isConsoleApplication=False ; another comment

[Posix]
isConsoleApplication=True

key1: "in this string backslash escapes are interpreted\n"
key2: r"in this string not"
key3: """triple quotes strings
are also supported. They may span
multiple lines."""

--"long option with spaces": r"c:\myfiles\test.txt"

```

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

### skMacro Example

Source: https://nim-lang.github.io/Nim/idetools.html

Example output for a macro. The third column is the macro name, and the fourth column is its signature. The docstring is provided if available.

```nim
proc testMacro() =
  expect(EArithmetic):
--> col 2: idetools_api.expect
    col 3: proc (varargs[expr], stmt): stmt
    col 7: ""
```

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

### Interfacing with a C++ library

Source: https://nim-lang.github.io/Nim/manual.html

Example of linking and importing a C++ library using header and importcpp pragmas.

```nim
# Horrible example of how to interface with a C++ engine ... ;-)

{.link: "/usr/lib/libIrrlicht.so".}

{.emit: """
using namespace irr;
using namespace core;
using namespace scene;
using namespace video;
using namespace io;
using namespace gui;
""".}

const
  irr = "<irrlicht/irrlicht.h>"

type
  IrrlichtDeviceObj {.header: irr,
                      importcpp: "IrrlichtDevice".} = object
  IrrlichtDevice = ptr IrrlichtDeviceObj

proc createDevice(): IrrlichtDevice {. 
  header: irr, importcpp: "createDevice(@)".}
proc run(device: IrrlichtDevice): bool {. 
  header: irr, importcpp: "#.run(@)".}
```

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

### NimScript Command-Line Switch Examples

Source: https://nim-lang.github.io/Nim/nims.html

Demonstrates how to use the `switch` proc in NimScript to map command-line arguments to configuration settings. These examples show direct mapping and handling of values.

```nim
# command-line: --opt:size
switch("opt", "size")
# command-line: --define:release or -d:release
switch("define", "release")
# command-line: --forceBuild
switch("forceBuild")
# command-line: --hint[Conf]:off or --hint:Conf:off
switch("hint", "[Conf]:off")
```

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

### Get JavaScript Object Prototype Name Example

Source: https://nim-lang.github.io/Nim/jsutils.html

Demonstrates using getProtoName to identify JavaScript types like Number, String, BigInt, and Arrays.

```nim
import std/[jsffi, jsbigints]
type A = ref object
assert 1.toJs.getProtoName == "[object Number]"
assert "a".toJs.getProtoName == "[object String]"
assert big"1".toJs.getProtoName == "[object BigInt]"
assert false.toJs.getProtoName == "[object Boolean]"
assert (a: 1).toJs.getProtoName == "[object Object]"
assert A.default.toJs.getProtoName == "[object Null]"
assert [1].toJs.getProtoName == "[object Int32Array]" # implementation defined
assert @[1].toJs.getProtoName == "[object Array]" # ditto

```

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

### Nim Regex find Examples

Source: https://nim-lang.github.io/Nim/re.html

Demonstrates the usage of the `find` procedure for various scenarios, including finding matches, not found cases, and using the `start` parameter.

```nim
doAssert find("abcdefg", re"cde") == 2
doAssert find("abcdefg", re"abc") == 0
doAssert find("abcdefg", re"zz") == -1 # not found
doAssert find("abcdefg", re"cde", start = 2) == 2 # still 2
doAssert find("abcdefg", re"cde", start = 3) == -1 # we're past the start position
doAssert find("xabc", re"(?<=x|y)abc", start = 1) == 1
  # lookbehind assertion `(?<=x|y)` can look behind `start`

```

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

### wsaStartup

Source: https://nim-lang.github.io/Nim/winlean.html

Initiates use of the Winsock DLL by a process.

```APIDOC
## wsaStartup

### Description
Initiates use of the Winsock DLL by a process.

### Signature
`wsaStartup(wVersionRequired: int16; WSData: ptr WSAData): cint`
```

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

### Get Rune Byte Length for string

Source: https://nim-lang.github.io/Nim/unicode.html

Returns the number of bytes a rune takes starting at a specific index in a string. Use when working directly with strings.

```nim
proc runeLenAt(s: string; i: Natural): int {.inline, ...raises: [], tags: [],
    forbids: [].}

let a = "añyóng"
doAssert a.runeLenAt(0) == 1
doAssert a.runeLenAt(1) == 2
```

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

### Reverse Split String by Character

Source: https://nim-lang.github.io/Nim/strutils.html

Splits a string into a sequence of substrings using a character as a delimiter, starting from the end of the string. Useful for path manipulation to get the tail.

```nim
func rsplit(s: string; sep: char; maxsplit: int = -1): seq[string] {....gcsafe,
    extern: "nsuRSplitChar", raises: [], tags: [], forbids: [].}
```

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

### Styled Text Output Example

Source: https://nim-lang.github.io/Nim/terminal.html

Demonstrates various ways to style text output using `styledWriteLine` and `styledEcho`. Shows how to apply styles, colors, and backgrounds, and how to reset them.

```nim
import std/terminal
stdout.styledWriteLine({styleBright, styleBlink, styleUnderscore}, "styled text ")
stdout.styledWriteLine(fgRed, "red text ")
stdout.styledWriteLine(fgWhite, bgRed, "white text in red background")
stdout.styledWriteLine(" ordinary text without style ")

stdout.setBackGroundColor(bgCyan, true)
stdout.setForeGroundColor(fgBlue)
stdout.write("blue text in cyan background")
stdout.resetAttributes()

# You can specify multiple text parameters. Style parameters
# only affect the text parameter right after them.
styledEcho styleBright, fgGreen, "[PASS]", resetStyle, fgGreen, " Yay!"

stdout.styledWriteLine(fgRed, "red text ", styleBright, "bold red", fgDefault, " bold text")
```

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

### Example: Get Environment Variable with Default Value

Source: https://nim-lang.github.io/Nim/envvars.html

Demonstrates retrieving an environment variable, showing the default empty string for a non-existent variable and a custom default value.

```nim
assert getEnv("unknownEnv") == ""
assert getEnv("unknownEnv", "doesn't exist") == "doesn't exist"
```

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

### Example: Respond with JSON

Source: https://nim-lang.github.io/Nim/asynchttpserver.html

Handles a request for '/hello-world' by responding with a JSON object containing a 'message' field. For other paths, it returns a 'Not Found' response.

```nim
import std/json
proc handler(req: Request) {.async.} =
  if req.url.path == "/hello-world":
    let msg = %* {"message": "Hello World"}
    let headers = newHttpHeaders([("Content-Type","application/json")])
    await req.respond(Http200, $msg, headers)
  else:
    await req.respond(Http404, "Not Found")
```

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

### Using StdTmpl Filter with Standard Parameters

Source: https://nim-lang.github.io/Nim/filters.html

An example of using the stdtmpl filter with its default parameters for generating HTML. Lines starting with the meta character '#' are treated as Nim code.

```nim
#? stdtmpl | standard
#proc generateHTMLPage(title, currentTab, content: string,
#                      tabs: openArray[string]): string =
```

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

### Start Serving HTTP Requests with a Callback

Source: https://nim-lang.github.io/Nim/asynchttpserver.html

Initiates the server to listen for connections and execute a provided callback for each incoming request. Allows control over error handling and file descriptor limits.

```nim
proc serve(server: AsyncHttpServer; port: Port; callback: proc (request: Request): Future[void] {.closure, ...gcsafe.}; address = ""; assumedDescriptorsPerRequest = -1; domain = AF_INET): owned(Future[void]) {....stackTrace: false, raises: [Exception, OSError, ValueError, SslError, LibraryError, KeyError], tags: [RootEffect, WriteIOEffect, ReadIOEffect, TimeEffect], forbids: []}.

```

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

### Get Rune Byte Length for openArray[char]

Source: https://nim-lang.github.io/Nim/unicode.html

Returns the number of bytes a rune takes starting at a specific index in an openArray of characters. Use when working with character arrays.

```nim
proc runeLenAt(s: openArray[char]; i: Natural): int {....raises: [], tags: [],
    forbids: [].}

let a = "añyóng"
doAssert a.runeLenAt(0) == 1
doAssert a.runeLenAt(1) == 2
```

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

### Example: Open Nim Website in Browser

Source: https://nim-lang.github.io/Nim/browsers.html

Demonstrates how to call the `openDefaultBrowser` procedure to open a specific URL in the default browser.

```nim
openDefaultBrowser("https://nim-lang.org")
```

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

### initToJsonOptions

Source: https://nim-lang.github.io/Nim/jsonutils.html

Initializes `ToJsonOptions` with default, sane options for JSON serialization. This procedure provides a convenient way to get started with JSON serialization without manually configuring all options.

```APIDOC
## proc initToJsonOptions(): ToJsonOptions

### Description
Initializes `ToJsonOptions` with sane options.
```

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

### Basic inotify Usage Example

Source: https://nim-lang.github.io/Nim/inotify.html

Demonstrates initializing an inotify file descriptor, adding a watch for create and delete events on a directory, and subsequently removing the watch. Ensure the 'linux' compilation flag is defined.

```nim
import std/inotify
when defined(linux):
  let inotifyFd = inotify_init()  # create and get new inotify FileHandle
  doAssert inotifyFd >= 0         # check for errors

  let wd = inotifyFd.inotify_add_watch("/tmp", IN_CREATE or IN_DELETE)  # Add new watch
  doAssert wd >= 0                 # check for errors

  discard inotifyFd.inotify_rm_watch(wd) # remove watch
```

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

### Nim NRE findIter and toSeq Example

Source: https://nim-lang.github.io/Nim/nre.html

Illustrates using findIter to get matches and then converting them to a sequence using sequtils.toSeq. It also shows how to access capture bounds and the first match.

```nim
import std/nre
import std/sugar
let vowels = re"[aeoui]"
let bounds = collect:
  for match in "moiga".findIter(vowels): match.matchBounds
assert bounds == @[1 .. 1, 2 .. 2, 4 .. 4]
from std/sequtils import toSeq
let s = sequtils.toSeq("moiga".findIter(vowels))
  # fully qualified to avoid confusion with nre.toSeq
assert s.len == 3

let firstVowel = "foo".find(vowels)
let hasVowel = firstVowel.isSome()
assert hasVowel
let matchBounds = firstVowel.get().captureBounds[-1]
assert matchBounds.a == 1

# as with module `re`, unless specified otherwise, `start` parameter in each
# proc indicates where the scan starts, but outputs are relative to the start
# of the input string, not to `start`:
assert find("uxabc", re"(?<=x|y)ab", start = 1).get.captures[-1] == "ab"
assert find("uxabc", re"ab", start = 3).isNone
```

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

### Example: System Information

Source: https://nim-lang.github.io/Nim/posix_utils.html

Demonstrates how to access and assert system information using the uname procedure.

```nim
echo uname().nodename, uname().release, uname().version
doAssert uname().sysname.len != 0
```

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

### Get Specific Parameter

Source: https://nim-lang.github.io/Nim/cmdline.html

Returns the i-th command line argument. Indexing starts from 1 for parameters, but 0 may return the executable name. Availability depends on the environment; test with declared().

```nim
when declared(paramStr):
  # Use paramStr() here
else:
  # Do something else!
```

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

### Creating a Configuration File with newConfig and setSectionKey

Source: https://nim-lang.github.io/Nim/parsecfg.html

Shows how to programmatically create a new configuration object and populate it with sections and key-value pairs using setSectionKey. The resulting configuration can be stringified for verification.

```nim
import std/parsecfg
var dict = newConfig()
dict.setSectionKey("","charset", "utf-8")
dict.setSectionKey("Package", "name", "hello")
dict.setSectionKey("Package", "--threads", "on")
dict.setSectionKey("Author", "name", "nim-lang")
dict.setSectionKey("Author", "website", "nim-lang.org")
assert $dict == """
charset=utf-8
[Package]
name=hello
--threads:on
[Author]
name=nim-lang
website=nim-lang.org
"""

```

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

### Create new ConfigRef

Source: https://nim-lang.github.io/Nim/compiler/options.html

Initializes a new full configuration reference.

```nim
proc newConfigRef(): ConfigRef {....raises: [], tags: [], forbids: [].}
```

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

### Getting Source Language Enum

Source: https://nim-lang.github.io/Nim/highlite.html

This example shows how to use the `getSourceLanguage` procedure to convert string representations of programming languages into their corresponding `SourceLanguage` enum values. Useful for dynamically setting the language for the highlighter.

```nim
for l in ["C", "c++", "jAvA", "Nim", "c#"]: echo getSourceLanguage(l)
```

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

### Get MIME Type from File Extension

Source: https://nim-lang.github.io/Nim/mimetypes.html

Retrieves the MIME type associated with a given file extension. Returns a default MIME type if the extension is not found. The extension can optionally start with a dot, and it is converted to lowercase before lookup.

```nim
func getMimetype(mimedb: MimeDB; ext: string; default = "text/plain"): string {.raises: [], tags: [], forbids: [].}

     Gets mimetype which corresponds to `ext`. Returns `default` if `ext` could not be found. `ext` can start with an optional dot which is ignored. `ext` is lowercased before querying `mimedb`. Source Edit
```

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

### Send Email with STARTTLS

Source: https://nim-lang.github.io/Nim/smtp.html

Example showing how to send an email using STARTTLS for a secure connection. This involves connecting to the SMTP server, initiating STARTTLS, authenticating, and then sending the email.

```nim
var msg = createMessage("Hello from Nim's SMTP",
                        "Hello!.\n Is this awesome or what?",
                        @["foo@gmail.com"])
let smtpConn = newSmtp(debug=true)
smtpConn.connect("smtp.mailtrap.io", Port 2525)
smtpConn.startTls()
smtpConn.auth("username", "password")
smtpConn.sendmail("username@gmail.com", @["foo@gmail.com"], $msg)
```

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

### Walk Directory (Non-Recursive)

Source: https://nim-lang.github.io/Nim/osdirs.html

Use walkDir to iterate over items in a single directory. Set 'relative' to true to get paths relative to the starting directory. 'checkDir' raises an error if the directory does not exist. 'skipSpecial' filters out non-regular files on Unix.

```nim
iterator walkDir(dir: string; relative = false; checkDir = false;
                 skipSpecial = false): tuple[kind: PathComponent, path: string] {
    ...tags: [ReadDirEffect], raises: [OSError], forbids: [].}

```

```nim
import std/[strutils, sugar]
# note: order is not guaranteed
# this also works at compile time
assert collect(for k in walkDir("dirA"): k.path).join(" ") ==
                      "dirA/dirB dirA/dirC dirA/fileA2.txt dirA/fileA1.txt"

```

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

### Create and Use a String Table

Source: https://nim-lang.github.io/Nim/strtabs.html

Demonstrates the basic creation and usage of a string table using `newStringTable` and direct key-value assignments. Asserts the length and checks for key existence.

```nim
import std/strtabs
var t = newStringTable()
t["name"] = "John"
t["city"] = "Monaco"
doAssert t.len == 2
doAssert t.hasKey "name"
doAssert "name" in t
```

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

### Punycode Encoding and Decoding Examples

Source: https://nim-lang.github.io/Nim/punycode.html

Demonstrates various use cases for the `encode` and `decode` procedures, including empty strings, single characters, mixed ASCII and Unicode, and strings with spaces. Ensure the 'punycode' module is installed via nimble.

```nim
import src/punycode
static:
  block:
    doAssert encode("") == ""
    doAssert encode("a") == "a-"
    doAssert encode("A") == "A-"
    doAssert encode("3") == "3-"
    doAssert encode("-") == "--"
    doAssert encode("--") == "---"
    doAssert encode("abc") == "abc-"
    doAssert encode("London") == "London-"
    doAssert encode("Lloyd-Atkinson") == "Lloyd-Atkinson-"
    doAssert encode("This has spaces") == "This has spaces-"
    doAssert encode("ü") == "tda"
    doAssert encode("München") == "Mnchen-3ya"
    doAssert encode("Mnchen-3ya") == "Mnchen-3ya-"
    doAssert encode("München-Ost") == "Mnchen-Ost-9db"
    doAssert encode("Bahnhof München-Ost") == "Bahnhof Mnchen-Ost-u6b"
  block:
    doAssert decode("") == ""
    doAssert decode("a-") ==  "a"
    doAssert decode("A-") == "A"
    doAssert decode("3-") == "3"
    doAssert decode("--") == "-"
    doAssert decode("---") == "--"
    doAssert decode("abc-") == "abc"
    doAssert decode("London-") == "London"
    doAssert decode("Lloyd-Atkinson-") == "Lloyd-Atkinson"
    doAssert decode("This has spaces-") == "This has spaces"
    doAssert decode("tda") == "ü"
    doAssert decode("Mnchen-3ya") == "München"
    doAssert decode("Mnchen-3ya-") == "Mnchen-3ya"
    doAssert decode("Mnchen-Ost-9db") == "München-Ost"
    doAssert decode("Bahnhof Mnchen-Ost-u6b") == "Bahnhof München-Ost"
```

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

### my_init

Source: https://nim-lang.github.io/Nim/mysql.html

Initializes the MySQL client library.

```APIDOC
## my_init

### Description
Initializes the MySQL client library.

### Method
Not specified (likely internal or SDK function)

### Returns
`my_bool` - Returns true on success, false otherwise.
```

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

### InstallExt Variable

Source: https://nim-lang.github.io/Nim/nimscript.html

A sequence of strings representing file extensions for installation.

```nim
installExt: seq[string] = @[]
```

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

### find(str: string; pattern: Regex; start = 0; endpos = int.high): Option[RegexMatch]

Source: https://nim-lang.github.io/Nim/nre.html

Finds the given pattern in the string between the start and end positions. `start` is the starting index for matching, and `endpos` is the maximum index for a match.

```APIDOC
## find(str: string; pattern: Regex; start = 0; endpos = int.high): Option[RegexMatch]

### Description
Finds the given pattern in the string between the start and end positions. `start` is the starting index for matching, and `endpos` is the maximum index for a match.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```nim
# Example usage would go here if provided in source
```

### Response
#### Success Response (Option[RegexMatch])
- Returns `Some(RegexMatch)` if the pattern is found, `None` otherwise.

#### Response Example
```nim
# Example response would go here if provided in source
```
```

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

### Using Local and Session Storage

Source: https://nim-lang.github.io/Nim/dom.html

Demonstrates how to use `localStorage` and `sessionStorage` for client-side data persistence.

```nim
import js/dom

let window = getWindow()
let localStorage = window.localStorage
let sessionStorage = window.sessionStorage

# Local Storage
localStorage.setItem("username", "nim_user")
let storedUsername = localStorage.getItem("username")
echo "Local Storage Username: ", storedUsername
localStorage.removeItem("username")

# Session Storage
sessionStorage.setItem("session_id", "12345")
let sessionId = sessionStorage.getItem("session_id")
echo "Session Storage ID: ", sessionId
sessionStorage.clear()

echo "Local Storage length: ", localStorage.length
echo "Session Storage length: ", sessionStorage.length
```

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

### Initialize MultipartData with Key-Value Pairs

Source: https://nim-lang.github.io/Nim/httpclient.html

Example of creating a MultipartData object and populating it with key-value pairs for actions like login.

```nim
var data = newMultipartData({"action": "login", "format": "json"})
```

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

### Check if String Starts with Peg Pattern

Source: https://nim-lang.github.io/Nim/pegs.html

Returns true if the string `s` starts with the pattern `prefix`. The `start` parameter specifies the offset to begin checking.

```nim
func startsWith(s: string; prefix: Peg; start = 0): bool {....gcsafe,
    extern: "npegs$1", gcsafe, gcsafe, raises: [], tags: [RootEffect],
    forbids: [].}
```

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

### Regex Matching with Start Position

Source: https://nim-lang.github.io/Nim/nre2.html

Illustrates how the `start` parameter affects regex matching, noting that output positions are relative to the original string start.

```nim
# as with module `re`, unless specified otherwise, `start` parameter in each
# proc indicates where the scan starts, but outputs are relative to the start
# of the input string, not to `start`:
assert find("uxabc", re"(?<=x|y)ab", start = 1).get.captures[-1] == "ab"
assert find("uxabc", re"ab", start = 3).isNone
```

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

### Nim Proc: sysconf

Source: https://nim-lang.github.io/Nim/posix.html

Gets system configuration variables. Requires the <unistd.h> header.

```nim
proc sysconf(a1: cint): int {.importc, header: "<unistd.h>", ...raises: [],
                              tags: [], forbids: [].}
```

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

### serve

Source: https://nim-lang.github.io/Nim/asynchttpserver.html

Starts the server to listen for incoming connections and process requests using a provided callback.

```APIDOC
## proc serve

### Description
Starts the process of listening for incoming HTTP connections on the specified address and port. When a request is made by a client the specified callback will be called. If `assumedDescriptorsPerRequest` is 0 or greater the server cares about the process's maximum file descriptor limit. It then ensures that the process still has the resources for `assumedDescriptorsPerRequest` file descriptors before accepting a connection. You should prefer to call `acceptRequest` instead with a custom server loop so that you're in control over the error handling and logging.

### Parameters
* `server`: AsyncHttpServer - The server instance.
* `port`: Port - The port to listen on.
* `callback`: proc (request: Request): Future[void] - The procedure to handle incoming requests.
* `address`: string - The address to bind to (defaults to "").
* `assumedDescriptorsPerRequest`: int - The number of file descriptors to reserve (defaults to -1).
* `domain`: int - The address domain (defaults to AF_INET).
```

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

### Get Class Attribute

Source: https://nim-lang.github.io/Nim/dom.html

Gets the class attribute of a node.

```APIDOC
## class(n: Node): cstring

### Description

Gets the class attribute of a node.

### Method

class

### Parameters

- **n** (Node) - The node to get the class attribute from.

### Returns

- cstring - The value of the class attribute.
```

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

### Styled Write Examples

Source: https://nim-lang.github.io/Nim/terminal.html

Demonstrates how to use the `styledWrite` macro to output text with different foreground colors.

```nim
stdout.styledWrite(fgRed, "red text ")
stdout.styledWrite(fgGreen, "green text")
```

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

### Nim Regex `find` Proc

Source: https://nim-lang.github.io/Nim/nre2.html

Finds the given pattern in the string between the end and start positions. `start` is the starting index for matching, and `endpos` is the maximum index for a match.

```nim
proc find(str: string; pattern: Regex; start = 0; endpos = int.high): Option[
    RegexMatch] {....raises: [], tags: [RootEffect], forbids: [].}
```

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

### Demonstrate left-to-right evaluation order

Source: https://nim-lang.github.io/Nim/manual.html

Example showing how expressions are evaluated from left to right, inside-out.

```nim
var s = ""

proc p(arg: int): int =
  s.add $arg
  result = arg

discard p(p(1) + p(2))

doAssert s == "123"
```

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

### Procedure Naming: Get and Put with Operator Overloading

Source: https://nim-lang.github.io/Nim/nep1.html

Suggests overloading the '[]=' operator for 'put' operations and the '[]' operator for 'get' operations, and avoiding 'get' prefixes like 'getLen'.

```nim
proc `[]=`(x: var Foo, index: int, value: string)
proc `[]`(x: Foo, index: int): string
proc len(x: Foo): int
```

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

### Setup global context

Source: https://nim-lang.github.io/Nim/compiler/vm.html

Initializes the global VM context for a module.

```nim
proc setupGlobalCtx(module: PSym; graph: ModuleGraph; idgen: IdGenerator) {.
    ...raises: [], tags: [], forbids: [].}
```

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

### server_init

Source: https://nim-lang.github.io/Nim/mysql.html

Initializes the MySQL server.

```APIDOC
## server_init

### Description
Initializes the MySQL server.

### Method
Not specified (likely internal or SDK function)

### Parameters
* **argc** (cint) - The number of arguments.
* **argv** (cstringArray) - The argument values.
* **groups** (cstringArray) - The group names.
```

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

### StaticRead Usage Example

Source: https://nim-lang.github.io/Nim/system.html

Example of embedding a binary file at compile-time.

```nim
const myResource = staticRead"mydatafile.bin"
```

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

### Future borrowing syntax

Source: https://nim-lang.github.io/Nim/manual.html

Example of a proposed syntax for explicit borrowing from specific parameters.

```nim
proc foo(other: Y; container: var X): var T from container
```

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

### Build and Test Examples for Nim OpenSSL Wrapper

Source: https://nim-lang.github.io/Nim/openssl.html

These commands demonstrate how to build and run tests for the Nim OpenSSL wrapper. They cover different configurations such as dynamic linking, threading, and specific OpenSSL version usage.

```bash
./bin/nim c -d:ssl -p:. -r tests/stdlib/tssl.nim
```

```bash
./bin/nim c -d:ssl --threads:on -p:. -r tests/stdlib/thttpclient_ssl.nim
```

```bash
./bin/nim c -d:ssl -p:. -r tests/untestable/tssl.nim
```

```bash
./bin/nim c -d:ssl -p:. --dynlibOverride:ssl --passl:-lcrypto --passl:-lssl -r tests/untestable/tssl.nim
```

```bash
./bin/nim r --putenv:NIM_TESTAMENT_REMOTE_NETWORKING:1 -d:ssl -p:testament/lib --threads:on tests/untestable/thttpclient_ssl_remotenetwork.nim
```

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

### Set subset example

Source: https://nim-lang.github.io/Nim/system.html

Example demonstrating the subset operator for sets.

```nim
let
  a = {3, 5}
  b = {1, 3, 5, 7}
  c = {2}
assert a <= b
assert a <= a
assert not (a <= c)
```

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

### Check for runnable examples

Source: https://nim-lang.github.io/Nim/compiler/trees.html

Checks if the node contains runnable examples.

```Nim
proc isRunnableExamples(n: PNode): bool {.
    ...raises: [KeyError, OSError, Exception, ValueError],
    tags: [ReadEnvEffect, ReadIOEffect, ReadDirEffect, RootEffect], forbids: [].}
```
Tokens:
Raw