Files

1225 lines
19 KiB
Markdown

---
title: Nim
date: 2025-11-23 1:04:20
background: bg-[#eed547]
tags:
categories:
- Programming
intro: |
The Nim quick reference cheat sheet that aims at providing help on writing basic syntax and methods.
plugins:
- copyCode
---
## Getting Started
### helloworld.nim {.row-span-2}
```nim
echo "Hello World!"
# This is a comment
echo "What's your name? "
var name: string = readLine(stdin)
# readLine(stdin) asks you to type in a string.
echo "Hi, ", name, "!"
```
Compile `helloworld.nim` with `nim compile`
```bash
$ nim compile helloworld.nim
```
Run the compiled binary `helloworld` (or `helloworld.exe` if you're on Windows)
```
./helloworld
Hello, World!
What's your name?
Hi, <name>!
```
There is also a possibility
to both compile and run the
program with just one command.
We need to type:
`$ nim c -r helloworld.nim`
#### Common compile commands (terminal)
```sh
nim c -r main.nim # debug build, run after compile
nim c -d:release main.nim # optimized release build
nim c --mm:arc main.nim # ARC memory management (Nim 2 default)
```
### Useful Resources {.col-span-2}
- [Nim](https://www.nim-lang.org/) _(nim-lang.org)_
- [The Nim Manual](https://nim-lang.org/docs/manual.html) _(../docs/manual.html)_
- [Nim Basics](https://narimiran.github.io/nim-basics/) _(narimiran.github.io)_
- [Learn X in Y minutes](https://learnxinyminutes.com/docs/nim/) _(learnxinyminutes.com)_
### Variables {.row-span-1}
```nim
# 'var' declares mutable variables.
var number: int = 100 # Single line declaration
# A 'var' block can declare multiple variables at once.
var
letter: char = 'n'
lang = "N" & "im"
length = len(lang)
counter: int = 7
boat: float
truth = true
```
### Immutable Variables (let)
```nim
# 'let' declares immutable variables.
let
salute: string = "Hello!"
x: int = 10
y = x + 5
let z = 20
z = 500 # Error: 'z' is immutable
```
### Comments
```nim
# This is a comment
#[
This is a multiline comment.
In Nim, multiline comments can be nested, beginning with #[
... and ending with ]#
]#
```
### Constants {.row-span-1}
```nim
const
debug = true
compileBadCode = false
# Constants are declared at compile time and cannot be changed.
```
### "For" Loops
```nim
for item in (1 ..< 6):
if item == 3: break
echo item
echo "All done!"
```
See: [Loops](#loops)
### If Statements
```nim
import std/strutils
let number = parseInt(readLine(stdin))
if number <= 5:
echo "Small sized number."
elif number > 5 and number <= 25:
echo "Medium sized number."
else:
echo "Big number."
```
See: [Flow Control](#flow-control)
### Procedures / Functions
```nim
proc myFunction() =
echo "Hello, this is my function"
myFunction()
# prints "Hello, this is my function"
```
See: [Procedures](#procedures)
### Formatted Strings
```nim
import std/strformat
let
a = "Hello there."
b = "How's it going?"
c = "These are variables."
echo fmt"{a} {b} {c}" # "Hello there. How's it going? These are variables."
```
See: [Imports](#imports-and-modules)
## Data Types
### Integers
```nim
let
a = 11
b = 4
echo "a + b = ", a + b # 15
echo "a - b = ", a - b # 7
echo "a * b = ", a * b # 44
echo "a / b = ", a / b # 2.75
echo "a div b = ", a div b # 2
echo "a mod b = ", a mod b # 3
```
### Floats
```nim
let
c = 6.75
d = 2.25
echo "c + d = ", c + d # 9.0
echo "c - d = ", c - d # 4.5
echo "c * d = ", c * d # 15.1875
echo "c / d = ", c / d # 3.0
```
### Strings {.row-span-3}
```nim
let
m = "word"
n = "A sentence with punctuation."
o = ""
p = "32"
q = "!"
echo m
# prints "word"
echo p, " is a string."
# prints "32 is a string."
```
#### String Concatenation
```nim
var
p = "abc"
q = "xy"
r = 'z'
p.add("def") # modifies p
q.add(r) # chars can be added to strings
echo p # "abcdef"
echo q # "xyz"
# `&` creates a new string:
echo p & q # "abcdefxyz"
```
#### Special Escape Sequences
```nim
echo "line1\nline2" # newline
echo "col1\tcol2" # tab
echo "A\\B\\C" # backslash
# Raw strings ignore escapes:
echo r"line1\nline2"
```
See also: [Escape Sequences](https://nim-lang.org/docs/manual.html#lexical-analysis-string-literals)
### Characters
```nim
let
h = 'z'
i = '+'
j = '2'
k = '35' # error: too many characters
l = 'xy' # error: too many characters
```
### Booleans
```nim
let x = true
let y = false
# Boolean literals are lowercase.
```
### Type Conversion {.col-span-2}
```nim
let e = 5
let f = 23.987
# Converting between ints and floats:
echo float(e) # 5.0
echo int(f) # 23
# Mixed operations require explicit conversion:
echo float(e) + f # 28.987
echo e + int(f) # 28
```
## Compound Types
### Arrays
```nim
type IntArray = array[0..3, int]
let a: IntArray = [10, 20, 30, 40]
echo a[0] # 10
echo a.len # 4
```
### Sequences
```nim
var s: seq[int] = @[1, 2, 3]
s.add(4)
echo s # @[1, 2, 3, 4]
echo s.len # 4
```
### Objects
```nim
type Person = object
name: string
age: int
let p = Person(name: "Ana", age: 20)
echo p.name
```
### Tuples
```nim
var person = (name: "Sophie", age: 18)
echo person.name # Sophie
echo person.age # 18
# swapping values:
var (x, y) = (1, 2)
(x, y) = (y, x)
echo x, " ", y # 2 1
```
### Sets
```nim
type CharSet = set[char]
let letters: CharSet = {'a'..'z'}
echo 'a' in letters # true
echo 'Z' in letters # false
```
### Reference Objects
```nim
type Node = ref object
value: int
next: Node # linked list style
var n = Node(value: 10)
echo n.value
```
Needed for Object Oriented Programming within Nim.
### Slicing Sequences and Strings {.col-span-2}
```nim
let xs = @[10, 20, 30, 40]
echo xs[1..2] # @[20, 30]
echo xs[^2..^1] # @[30, 40]
```
---
```nim
let s = "abcdef"
echo s[0..2] # "abc"
echo s[3..^1] # "def" (^1 = last char)
echo s[1..<4] # "bcd"
```
### Tables/Dictionaries
```nim
import std/tables
var ages = initTable[string, int]()
ages["Ana"] = 20
ages["Sophie"] = 18
echo ages["Ana"] # 20
echo ages.getOrDefault("X", -1) # -1
for name, age in ages:
echo name, ": ", age
```
## Operators
### Arithmetic Operators {.row-span-1}
```nim
var
a = 10
b = 3
echo a + b # 13
echo a - b # 7
echo a * b # 30
echo a / b # 3.333333
echo a div b # 3
echo a mod b # 1
echo a ^ b # 1000
```
---
| Operator | Name | Example |
| -------- | -------------- | --------- |
| `+` | Add | `x + y` |
| `-` | Subtract | `x - y` |
| `*` | Multiply | `x * y` |
| `/` | Float Divide | `x / y` |
| `div` | Integer Divide | `x div y` |
| `mod` | Modulo | `x mod y` |
| `^` | Power | `x ^ y` |
{.show-header}
### Assignment
These only work on mutable (`var`) variables, not on `let` or `const`.
```nim
var value = 1990
echo value # 1990
value = 2
echo value # 2
```
---
| Operator | Description | Example |
| -------- | ------------ | ------- |
| `=` | Assign value | `x = y` |
{.show-header}
#### Update operations
| Syntax | Expands to | Meaning |
| -------- | ----------- | ---------------- |
| `x += y` | `x = x + y` | add, assign |
| `x -= y` | `x = x - y` | subtract, assign |
| `x *= y` | `x = x * y` | multiply, assign |
{.show-header}
Other variants like `/=` or `mod=` are not available,
so just write them out explicitly, e.g. `x = x / y`.
### Comparison Operators {.row-span-2}
```nim
let
x = 5
y = 3
echo x > y
# prints "true" because 5 is greater than 3
```
---
| Symbol | Meaning | Example |
| ------ | ------------------------ | -------------- |
| `==` | equals | `if x == y`... |
| `!=` | not equal to | `if x != y`... |
| `>` | greater than | `if x > y`... |
| `<` | less than | `if x < y`... |
| `>=` | greater than or equal to | `if x >= y`... |
| `<=` | less than or equal to | `if x <= y`... |
{.show-header}
Comparison operators are used to compare two values.
#### Lexicographical Comparison
They also work on `char` and `string` values via lexicographic order.
```nim
echo "apple" < "banana" # true
echo "axyz" < "axyb" # true
echo "ooooo" > "o" # true
echo "abc" < "ab" # false
echo 'a' < 'd' # true
echo 'a' < 'Z' # false
```
### Logical Operators {.row-span-2} {.col-span-2}
| Operator | Example | Meaning |
| -------- | ---------------------- | ------------------------ |
| `and` | `if a > 0 and a < 10:` | From 1 to 9 |
| `or` | `if x == 0 or y == 0:` | Either one of them is 0 |
| `not` | `if not isValid:` | If `isValid` is not true |
| `xor` | `if flagA xor flagB:` | Only one of them is true |
{.show-header}
Logical operators work on `bool`.
#### Extra Bitwise Operators
| Operator | Example | Result (with a = 60, b = 13) |
| -------- | --------- | ---------------------------- |
| `and` | `a and b` | `12` |
| `or` | `a or b` | `61` |
| `xor` | `a xor b` | `49` |
| `not` | `not a` | `-61` |
| `shl` | `a shl 2` | `240` |
| `shr` | `a shr 2` | `15` |
{.show-header}
These work on integers bit-by-bit; use them for flags, masks, low-level code, etc.
## Flow Control
### Match Case {.row-span-3}
```nim
let x = 5
case x:
of 0, 1:
echo "small"
of 2, 3, 4:
echo "medium"
else:
echo "large"
```
---
`case of` can look for ranges too.
```nim
let age = 17
case age:
of 0..12:
echo "child"
of 13..19:
echo "teen"
else:
echo "adult"
```
---
...and `strings` and `chars`, too
```nim
let cmd = "quit"
case cmd:
of "help":
echo "show help"
of "quit", "exit":
echo "bye!"
else:
echo "unknown command"
```
---
```nim
let ch = 'g'
case ch:
of {'a', 'e', 'i', 'o', 'u'}:
echo "vowel"
else:
echo "consonant or symbol"
```
### Basic If-Else {.col-span-2}
```nim
let num = 5
if num > 10:
echo "num is bigger than 10"
elif num < 10:
echo "num is smaller than 10"
else:
echo "num is exactly 10"
```
### One Liners {.col-span-2}
```nim
let
a = 330
b = 200
let r = if a > b: a else: b
echo r # 330
```
### Compile-Time Conditions {.col-span-2}
```nim
when defined(linux):
echo "Compiled on Linux"
elif defined(windows):
echo "Compiled on Windows"
else:
echo "Unknown OS"
```
## Loops
### For Loops {.row-span-2}
```nim
for i in 1..5:
echo i
# 1 2 3 4 5
```
---
```nim
for i in 0..<3:
echo i
# 0 1 2
```
---
```nim
# i = index, v = value in sequence
for i, v in @[10, 20, 30]:
echo i, ": ", v
# 0: 10
# 1: 20
# 2: 30
```
**Keep in mind**: \
1..5 = Inclusive (1 2 3 4 5) \
1..<5 = Exclusive (1 2 3 4)
### While Loops
```nim
var counter = 0
while counter <= 10:
counter = counter + 1
echo counter # prints 1..10
```
### Infinite Loops
```nim
while true:
echo "ay! "
```
---
```nim
while 1 > 0:
echo "echo... "
```
### Break Statements
```nim
var query = ""
while true:
echo "Do you want out?"
query = readLine(stdin)
if query == "yes":
echo "Well then."
break
else:
echo "I'll ask again."
```
### Continue Statements
```nim
for i in 1..5:
if i mod 2 == 0: continue
echo i
# prints only odd numbers: 1 3 5
```
## Procedures
### Simple Procedure
```nim
proc salute() =
echo "Hello!"
salute() # prints "Hello!"
```
### Procedures with Parameters
```nim
proc addition(a: int, b: int): int =
a + b
echo addition(20, 30) # returns 50
```
### Using result {.row-span-2}
```nim
proc double(x: int): int =
result = x * 2
echo double(5) # returns 10
```
---
Useful when building results step-by-step:
```nim
proc sumAll(xs: seq[int]): int =
for n in xs:
result += n
echo sumAll(@[1,1,1,1,1]) # returns 5
```
### Default Parameters {.col-span-2}
```nim
proc welcome(name = "stranger") =
echo "Hi, ", name
welcome("Sophie") # prints "Hi, Sophie"
welcome() # uses default, prints "Hi, stranger"
```
### Procedures returning multiple values
```nim
proc divmod(a, b: int): (int, int) =
(a div b, a mod b)
let (q, r) = divmod(10, 3)
echo q, " ", r # 3 1
```
### Anonymous Procedures (Lambdas)
```nim
let square = proc(x: int): int = x * x
echo square(5) # 25
```
### Procedures within Procedures {.row-span-2}
```nim
proc outer() =
var count = 0
proc inner() =
inc(count)
echo count
inner()
inner()
outer() # prints 1 then 2
```
### Overloading
```nim
proc show(x: int) = echo "int: ", x
proc show(x: string) = echo "string: ", x
show(10)
show("hi")
```
### Discardable Procedure Returns
```nim
proc doSomething(): int {.discardable.} =
123
doSomething() # allowed now
```
## Object-Oriented Programming
### Ref Objects and Inheritance {.row-span-2}
```nim
type
Animal = ref object of RootObj
name: string
Dog = ref object of Animal
breed: string
method speak(a: Animal) {.base.} =
echo a.name, " makes a sound."
method speak(d: Dog) =
echo d.name, " barks!"
var
a: Animal = Animal(name: "Creature")
d: Animal = Dog(name: "Fido", breed: "Mutt") # Dog upcasted to Animal
speak(a) # Creature makes a sound.
speak(d) # Fido barks!
```
Use `ref object of RootObj` + `method` when you need runtime polymorphism.
### Procs as Methods
```nim
type
Counter = ref object
value: int
proc inc(c: var Counter) =
inc c.value
var c = Counter(value: 0)
inc(c)
echo c.value # 1
```
### Constructor Procs
```nim
type
Dog = ref object
name: string
age: int
proc newDog(name: string; age: int): Dog =
Dog(name: name, age: age)
let d = newDog("Fido", 3)
echo d.name, " is ", d.age, " years old"
```
### Type tests and Downcasting {.col-span-2}
```nim
type
Animal = ref object of RootObj
name: string
Dog = ref object of Animal
breed: string
proc newDog(name, breed: string): Dog =
Dog(name: name, breed: breed)
var a: Animal = newDog("Fido", "mutt")
if a of Dog: # runtime type check
let d = Dog(a) # downcast
echo d.name, " is a ", d.breed
```
`x of Type` checks the dynamic type; `Type(x)` downcasts (unsafe if you lie).
## Imports and Modules
### Basic Imports
```nim
import std/math
echo sqrt(9.0) # 3.0
```
See also: [Standard Library](https://nim-lang.org/docs/lib.html)
### Importing Multiple Modules
```nim
import std/[strutils, sequtils]
echo "hi".toUpperAscii() # "HI"
echo @[1,2,3].mapIt(it * 2) # @[2, 4, 6]
```
### Importing Specific Modules
```nim
from std/strutils import toLowerAscii
echo toLowerAscii("ABC") # "abc"
```
### Renaming Modules
```nim
import std/random as rng
rng.randomize()
echo rng.rand(1..10) # anywhere from 1 to 10
```
_Don't forget to use randomize() if you're using the std/random library, or else you won't have randomness._
### Creating Modules {.col-span-2}
```nim
# utils.nim
proc greet*(name: string) =
echo "Hello, ", name
```
(The asterisk means "export this procedure from the module".)
---
```nim
# main.nim
import utils
greet("John") # prints "Hello, John"
```
### `when isMainModule`
```nim
proc run() =
echo "Running..."
when isMainModule:
run() # Only runs when this file is the program entry point
```
_Code inside when isMainModule: is skipped when the file is imported._
### Re-exporting {.col-span-2}
```nim
# utils.nim
import std/strutils
export strutils # re-export everything from strutils
```
---
Now main.nim can use toUpperAscii directly, through utils.
```nim
# main.nim
import utils
echo "hi".toUpperAscii()
```
### Prelude Module {.col-span-3}
```nim
import std/prelude
include std/prelude
# same as:
# import std/[os, strutils, times, parseutils, hashes, tables, sets, sequtils, parseopt, strformat]
let x = 1
assert "foo $# $#" % [$x, "bar"] == "foo 1 bar"
assert toSeq(1..3) == @[1, 2, 3]
when not defined(js) or defined(nodejs):
assert getCurrentDir().len > 0
assert ($now()).startsWith "20"
```
## Error Handling
### Try - Except - Finally {.row-span-2}
```nim
import std/strutils
try:
let x = parseInt("42a") # invalid integer
echo x
except ValueError as e:
echo "Value error: ", e.msg # catch conversion error
except IOError:
echo "I/O error!"
finally:
echo "This always runs"
```
### Raising Exceptions
```nim
type
MyError* = object of Exception
proc loadData(name: string) =
if name == "":
raise newException(MyError, "No name provided")
# ... else proceed
loadData("") # raises MyError
```
### `defer` for Cleanup
```nim
proc processFile(path: string) =
var f = open(path, fmRead)
defer:
close(f)
# work with f …
```
### Try as Exception
```nim
import std/strutils
let result = try: parseInt("bad")
except ValueError: -1
echo result # prints -1
```
### Exception Tracking with raises
```nim
proc riskyOperation() {.raises: [IOError].} =
# this proc may raise IOError
raise newException(IOError, "fail")
# A proc with {.raises: []} must not raise any catchable exception.
```
## Enums
### Basic Usage
```nim
type
Direction = enum
north, east, south, west
var d = north
if d == north:
echo "Going up!"
```
### Enums and `case`
```nim
# with the same Direction enum:
var d = north
case d:
of north: echo "N"
of south: echo "S"
of east: echo "E"
of west: echo "W"
```
### Enum as an Ordinal
```nim
# with the same Direction enum:
echo ord(north) # 0
echo succ(north) # east
echo pred(south) # east
```
## Iterators
### Basic Iterator {.row-span-2}
```nim
iterator countUp(a, b: int): int =
var i = a
while i <= b:
yield i # `yield` produces a value for the `for` loop
inc i
for n in countUp(1, 5):
echo n
# 1 2 3 4 5
```
### Common Built-In Iterators
```nim
for i in countup(1, 3):
echo i # 1 2 3
for i in countdown(3, 1):
echo i # 3 2 1
```
### Defining your own Iterator {.row-span-2}
```nim
iterator evensUpTo(n: int): int =
var x = 0
while x <= n:
yield x
x += 2
for e in evensUpTo(10):
echo e # 0 2 4 6 8 10
```
## Files & IO
### Check Paths and Existence {.row-span-2}
```nim
import std/os
if fileExists("data.txt"):
echo "File exists!"
if dirExists("configs"):
echo "Directory exists!"
echo getCurrentDir()
echo absolutePath("data.txt")
```
### Read / Write Whole File {.row-span-1}
```nim
# Write whole file
writeFile("out.txt", "Hello Nim!\n")
# Read whole file
let text = readFile("out.txt")
echo text
```
### Manual Open/Close with `defer` {.row-span-2}
```nim
import std/syncio
proc writeLog() =
var f = open("log.txt", fmWrite)
defer: f.close()
f.writeLine("entry 1")
f.writeLine("entry 2")
when isMainModule:
writeLog()
```
### Read a File Line-By-Line
```nim
for line in lines("data.txt"):
echo line
```
## Generics
### Generic Types and Procedures {.col-span-3}
```nim
type
Box[T] = object
value: T
proc wrap[T](x: T): Box[T] =
Box[T](value: x)
let a = wrap(10) # Box[int]
let b = wrap("hello") # Box[string]
echo a.value # 10
echo b.value # hello
```
## Templates and Macros
### Templates
```nim
# Template = macro-like, expanded at compile time
template times2(x: untyped): untyped = (x) * 2
echo times2(21) # 42
```
### Macros {.row-span-2} {.col-span-2}
```nim
import std/macros
macro dbg(expr: untyped): untyped =
# prints both the expression and its value
result = quote do:
echo astToStr(`expr`), " = ", `expr`
let x = 10
dbg(x * 2)
# prints: x * 2 = 20
```