From 31b75e1a2e008fb78ee65e59e3de87d44789e675 Mon Sep 17 00:00:00 2001 From: Sophie Ahumada Date: Fri, 21 Nov 2025 00:02:53 -0300 Subject: [PATCH] docs: further progress on the nim cheatsheet overhaul --- source/_posts/nim.md | 1430 ++++++++++++++---------------------------- 1 file changed, 485 insertions(+), 945 deletions(-) diff --git a/source/_posts/nim.md b/source/_posts/nim.md index 79b0256..9731101 100644 --- a/source/_posts/nim.md +++ b/source/_posts/nim.md @@ -1,6 +1,6 @@ --- title: Nim -date: 2024-05-15 8:03:44 +date: 2025-11-15 2:06:33 background: bg-[#eed547] tags: categories: @@ -13,7 +13,7 @@ plugins: ## Getting Started -### helloworld.nim {.row-span-3} +### helloworld.nim {.row-span-2} ```nim echo "Hello World!" @@ -54,14 +54,14 @@ We need to type: - [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-2} +### Variables {.row-span-1} ```nim # 'var' declares mutable variables. var number: int = 100 # Single line declaration -# A 'var' block can declarate multiple variables at once. +# A 'var' block can declare multiple variables at once. var letter: char = 'n' @@ -72,17 +72,29 @@ var truth = true ``` -### Inmutable Variables (let) +### Immutable Variables (let) ```nim -# 'let' declares inmutable variables. +# 'let' declares immutable variables. let salute: string = "Hello!" x: int = 10 y = x + 5 let z = 20 -z = 500 # Error: 'y' is immutable +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} @@ -95,17 +107,6 @@ const # Constants are declared at compile time and cannot be changed. ``` -### Procedures / Functions - -```nim -proc myFunction() = - echo "Hello, this is my function" - -myFunction() -``` - -See: [Procedures](#procedures) - ### "For" Loops ```nim @@ -118,18 +119,50 @@ echo "All done!" See: [Loops](#loops) -### Comments +### If Statements ```nim -# This is a comment +import std/strutils +let number = parseInt(readLine(stdin)) -#[ - This is a multiline comment. - In Nim, multiline comments can be nested, beginning with #[ - ... and ending with ]# -]# +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 @@ -165,7 +198,7 @@ echo "c / d = ", c / d # 3.0 ```nim let m = "word" - n = "A sentence with interpunction." + n = "A sentence with punctuation." o = "" p = "32" q = "!" @@ -205,6 +238,8 @@ echo "A\\B\\C" # backslash echo r"line1\nline2" ``` +See also: [Escape Sequences](https://nim-lang.org/docs/manual.html#lexical-analysis-string-literals) + ### Characters ```nim @@ -264,6 +299,17 @@ 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 @@ -289,17 +335,6 @@ echo 'a' in letters # true echo 'Z' in letters # false ``` -### Objects - -```nim -type Person = object - name: string - age: int - -let p = Person(name: "Ana", age: 20) -echo p.name -``` - ### Reference Objects ```nim @@ -313,9 +348,28 @@ echo n.value Needed for Object Oriented Programming within Nim. +### Slicing Sequences and Strings {.col-span-3} + +```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" +``` + ## Operators -### Arithmetic Operators {.row-span-3} +### Arithmetic Operators {.row-span-1} ```nim var @@ -343,19 +397,12 @@ echo a ^ b # 1000 | `mod` | Modulo | `x mod y` | | `^` | Power | `x ^ y` | -#### Update operations - -Nim does _not_ support C-style `+=`, `-=`, `*=`, etc. Use these instead: - -```nim -var x = 5 -x = x + 3 # valid -inc(x) # equivalent to x += 1 -dec(x) # equivalent to x -= 1 -``` +{.show-header} ### Assignment +These only work on mutable (`var`) variables, not on `let` or `const`. + ```nim var value = 1990 echo value # 1990 @@ -370,7 +417,22 @@ echo value # 2 | -------- | ------------ | ------- | | `=` | Assign value | `x = y` | -### Comparison Operators {.row-span-3} +{.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 @@ -383,14 +445,16 @@ echo x > y --- -| Symbol | Name | Example | -| ------ | ------------------------ | -------- | -| `==` | equals | x `==` y | -| `!=` | not equal to | x `!=` y | -| `>` | greater than | x `>` y | -| `<` | less than | x `<` y | -| `>=` | greater than or equal to | x `>=` y | -| `<=` | less than or equal to | x `<=` y | +| 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. @@ -408,60 +472,36 @@ echo 'a' < 'd' # true echo 'a' < 'Z' # false ``` -### Logical Operators {.row-span-2} +### Logical Operators {.row-span-2} {.col-span-2} -| Operator | Name | Example | -| -------- | ----------- | ------- | -| `and` | Logical AND | a and b | -| `or` | Logical OR | a or b | -| `not` | Logical NOT | not a | -| `xor` | Logical XOR | a xor b | +| Operator | Example | Meaning | +| -------- | ---------------------- | ------------------------ | +| `and` | `if a > 0 and a < 10:` | Between 1 and 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 -These use the **same keywords**, but operate on **integers**, not booleans. +| 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` | -| Operator | Name | Example | -| -------- | ----------- | ------- | -| `and` | Bitwise AND | x and y | -| `or` | Bitwise OR | x or y | -| `xor` | Bitwise XOR | x xor y | -| `not` | Invert | not x | -| `shl` | Shift Left | x shl 2 | -| `shr` | Shift Right | x shr 2 | +{.show-header} + +These work on integers bit-by-bit; use them for flags, masks, low-level code, etc. ## Flow Control -### Basic If-ElseIf-Else - -```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 - -```nim -let - a = 330 - b = 200 - -var r = "" - -r = if a > b: "a" else: "b" - -echo r - -``` - ### Match Case {.row-span-3} ```nim @@ -518,1009 +558,509 @@ 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 + +var r: int = +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 -### Basic For 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) -### WORK IN PROGRESS - -## Fake Flow Control[IN A MINUTE] [EVERYTHING DOWN FROM HERE HAS NOT BEEN TOUCHED BY MY PAW] - -### If statement +### While Loops ```nim -let - a = 11 - b = 22 - c = 999 +var counter = 0 -if a < b: - echo "a is smaller than b" - if 10*a < b: - echo "not only that, a is *much* smaller than b" - -if b < c: - echo "b is smaller than c" - if 10*b < c: - echo "not only that, b is *much* smaller than c" - -if a+b > c: - echo "a and b are larger than c" - if 1 < 100 and 321 > 123: - echo "did you know that 1 is smaller than 100?" - echo "and 321 is larger than 123! wow!" -#output -#a is smaller than b -#b is smaller than c -#not only that, b is *much* smaller than c +while counter <= 10: + counter = counter + 1 + echo counter # prints 1..10 ``` -### Case statement +### Infinite Loops ```nim -let name = readLine(stdin) -case name -of "": - echo "Poor soul, you lost your name?" -of "name": - echo "Very funny, your name is name." -of "Dave", "Frank": - echo "Cool name!" -else: - echo "Hi, ", name, "!" +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." ``` -### While statement +### Continue Statements ```nim -echo "What's your name? " -var name = readLine(stdin) -while name == "": - echo "Please tell me your name: " - name = readLine(stdin) # no `var`, because we do not declare a new variable here -``` - -### For statement - -```nim -echo "Counting to ten: " -for i in countup(1, 10): +for i in 1..5: + if i mod 2 == 0: continue echo i -# --> Outputs 1 2 3 4 5 6 7 8 9 10 on different lines +# prints only odd numbers: 1 3 5 ``` -### Scopes and the block statement +## Procedures + +### Simple Procedure ```nim -while false: - var x = "hi" -echo x # does not work -#-----------------------# -block myblock: - var x = "hi" -echo x # does not work either +proc salute() = + echo "Hello!" + +salute() # prints "Hello!" ``` -### Break statement +### Procedures with Parameters ```nim -block myblock: - echo "entering block" - while true: - echo "looping" - break # leaves the loop, but not the block - echo "still in block" -echo "outside the block" +proc addition(a: int, b: int): int = + a + b +echo addition(20, 30) # returns 50 ``` -### Continue statement +### Using result {.row-span-2} ```nim -for i in 1 .. 5: - if i <= 3: continue - echo i # will only print 4 and 5 +proc double(x: int): int = + result = x * 2 + +echo double(5) # returns 10 ``` -### When statement +--- + +Useful when building results step-by-step: ```nim - when system.hostOS == "windows": - echo "running on Windows!" -elif system.hostOS == "linux": - echo "running on Linux!" -elif system.hostOS == "macosx": - echo "running on Mac OS X!" -else: - echo "unknown operating system" +proc sumAll(xs: seq[int]): int = + for n in xs: + result += n + +echo sumAll(@[1,1,1,1,1]) # returns 5 ``` -### Statements and indentation +### Default Parameters {.col-span-2} ```nim -# no indentation needed for single-assignment statement: -if x: x = false +proc welcome(name = "stranger") = + echo "Hi, ", name -# indentation needed for nested if statement: -if x: - if y: - y = false - else: - y = true - -# indentation needed, because two statements follow the condition: -if x: - x = false - y = false +welcome("Sophie") # prints "Hi, Sophie" +welcome() # uses default, prints "Hi, stranger" ``` -### Procedures +### Procedures returning multiple values ```nim -proc yes(question: string): bool = - echo question, " (y/n)" - while true: - case readLine(stdin) - of "y", "Y", "yes", "Yes": return true - of "n", "N", "no", "No": return false - else: echo "Please be clear: yes or no" +proc divmod(a, b: int): (int, int) = + (a div b, a mod b) -if yes("Should I delete all your important files?"): - echo "I'm sorry Dave, I'm afraid I can't do that." -else: - echo "I think you know what the problem is just as well as I do." +let (q, r) = divmod(10, 3) +echo q, " ", r # 3 1 ``` -### Result variable +### Anonymous Procedures (Lambdas) ```nim -proc sumTillNegative(x: varargs[int]): int = - for i in x: - if i < 0: - return - result = result + i - -echo sumTillNegative() # echoes 0 -echo sumTillNegative(3, 4, 5) # echoes 12 -echo sumTillNegative(3, 4 , -1 , 6) # echoes 7 +let square = proc(x: int): int = x * x +echo square(5) # 25 ``` -### Parameters +### Procedures within Procedures {.row-span-2} ```nim -proc printSeq(s: seq, nprinted: int = -1) = - var nprinted = if nprinted == -1: s.len else: min(nprinted, s.len) - for i in 0 ..< nprinted: - echo s[i] -#------------------- # -proc divmod(a, b: int; res, remainder: var int) = - res = a div b # integer division - remainder = a mod b # integer modulo operation +proc outer() = + var count = 0 -var - x, y: int -divmod(8, 5, x, y) # modifies x and y -echo x -echo y + proc inner() = + inc(count) + echo count + + inner() + inner() + +outer() # prints 1 then 2 ``` -### Discard statement +### Overloading ```nim -discard yes("May I ask a pointless question?") +proc show(x: int) = echo "int: ", x +proc show(x: string) = echo "string: ", x -proc p(x, y: int): int {.discardable.} = - return x + y - -p(3, 4) # now valid +show(10) +show("hi") ``` -### Named arguments +### Discardable Procedure Returns ```nim -proc createWindow(x, y, width, height: int; title: string; show: bool): Window = ... +proc doSomething(): int {.discardable.} = + 123 -var w = createWindow(show = true, title = "My Application", x = 0, y = 0, height = 600, width = 800) - -var w = createWindow(0, 0, title = "My Application", - height = 600, width = 800, true) +doSomething() # allowed now ``` -### Default values +## Imports and Modules + +### Basic Imports ```nim -proc createWindow(x = 0, y = 0, width = 500, height = 700, - title = "unknown", - show = true): Window = +import std/math - -var w = createWindow(title = "My Application", height = 600, width = 800) +echo sqrt(9.0) # 3.0 ``` -### Overloaded procedures +See also: [Standard Library](https://nim-lang.org/docs/lib.html) + +### Importing Multiple Modules ```nim -proc toString(x: int): string = - result = - if x < 0: "negative" - elif x > 0: "positive" - else: "zero" +import std/[strutils, sequtils] -proc toString(x: bool): string = - result = - if x: "yep" - else: "nope" - -assert toString(13) == "positive" - # calls the toString(x: int) proc -assert toString(true) == "yep" - # calls the toString(x: bool) proc +echo "hi".toUpperAscii() # "HI" +echo @[1,2,3].mapIt(it * 2) # @[2, 4, 6] ``` -### Forward declarations +### Importing Specific Modules ```nim -proc odd(n: int): bool = - assert(n >= 0) # makes sure we don't run into negative recursion - if n == 0: false - else: - n == 1 or even(n-1) +from std/strutils import toLowerAscii -proc even(n: int): bool = - assert(n >= 0) # makes sure we don't run into negative recursion - if n == 1: false - else: - n == 0 or odd(n-1) +echo toLowerAscii("ABC") # "abc" ``` -### Iterators +### Renaming Modules ```nim -echo "Counting to ten: " -for i in countup(1, 10): - echo i +import std/random as rng -proc countup(a, b: int): int = - var res = a - while res <= b: - return res - inc(res) +rng.randomize() -iterator countup(a, b: int): int = - var res = a - while res <= b: - yield res - inc(res) +echo rng.rand(1..10) # anywhere from 1 to 10 ``` -### Type Conversion +_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 -var - x: int32 = 1.int32 # same as calling int32(1) - y: int8 = int8('a') # 'a' == 97'i8 - z: float = 2.5 # int(2.5) rounds down to 2 - sum: int = int(x) + int(y) + int(z) # sum == 100 +# utils.nim +proc greet*(name: string) = + echo "Hello, ", name ``` -### Internal type representation +(The asterisk means "export this procedure from the module".) + +--- ```nim -var - myBool = true - myCharacter = 'n' - myString = "nim" - myInteger = 42 - myFloat = 3.14 -echo myBool, ":", repr(myBool) -# --> true:true -echo myCharacter, ":", repr(myCharacter) -# --> n:'n' -echo myString, ":", repr(myString) -# --> nim:0x10fa8c050"nim" -echo myInteger, ":", repr(myInteger) -# --> 42:42 -echo myFloat, ":", repr(myFloat) -# --> 3.14:3.14 +# main.nim +import utils + +greet("John") # prints "Hello, John" ``` -### Enumerations +### `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() +``` + +## 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 x = south -# `x` is of type `Direction`; its value is `south` -#prints "south" -echo x +var d = north + +if d == north: + echo "Going up!" ``` -### Ordinal types - -| Operation | Comment | -| :--------- | :-----------------------------------------------------------: | -| ord(x) | returns the integer value that is used to represent x's value | -| inc(x) | increments x by one | -| inc(x, n) | increments x by n; n is an integer | -| dec(x) | decrements x by one | -| dec(x, n) | decrements x by n; n is an integer | -| succ(x) | returns the successor of x | -| succ(x, n) | returns the n'th successor of x | -| pred(x) | returns the predecessor of x | -| pred(x, n) | returns the n'th predecessor of x | - -### Subranges +### Enums and `case` ```nim type - MySubrange = range[0..5] + Direction = enum + north, east, south, west + +case d: +of north: echo "N" +of south: echo "S" +of east: echo "E" +of west: echo "W" ``` -### Sets - -```nim - var s: set[int64] - # Error: set is too large; use `std/sets` for ordinal types - # with more than 2^16 elements - type - CharSet = set[char] -var - x: CharSet -x = {'a'..'z', '0'..'9'} - # This constructs a set that contains the - # letters from 'a' to 'z' and the digits - # from '0' to '9' -``` - -### Bit fields +### Enum as an Ordinal ```nim type - MyFlag* {.size: sizeof(cint).} = enum - A - B - C - D - MyFlags = set[MyFlag] + Direction = enum + north, east, south, west -proc toNum(f: MyFlags): int = cast[cint](f) -proc toFlags(v: int): MyFlags = cast[MyFlags](v) - -assert toNum({}) == 0 -assert toNum({A}) == 1 -assert toNum({D}) == 8 -assert toNum({A, C}) == 5 -assert toFlags(0) == {} -assert toFlags(7) == {A, B, C} +echo ord(north) # 0 +echo succ(north) # east +echo pred(south) # east ``` -### Arrays +## Iterators + +### Basic Iterator {.row-span-2} ```nim -type - IntArray = array[0..5, int] # an array that is indexed with 0..5 -var - x: IntArray -x = [1, 2, 3, 4, 5, 6] -for i in low(x) .. high(x): - echo x[i] +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 ``` -### Sequences +### Common Built-In Iterators ```nim - var - x: seq[int] # a reference to a sequence of integers -x = @[1, 2, 3, 4, 5, 6] # the @ turns the array into a sequence allocated on the heap -for value in @[3, 4, 5]: - echo value -# --> 3 -# --> 4 -# --> 5 +for i in countup(1, 3): + echo i # 1 2 3 -for i, value in @[3, 4, 5]: - echo "index: ", $i, ", value:", $value -# --> index: 0, value:3 -# --> index: 1, value:4 -# --> index: 2, value:5 +for i in countdown(3, 1): + echo i # 3 2 1 ``` -### Open arrays +### Defining your own Iterator {.row-span-2} ```nim -var - fruits: seq[string] - # reference to a sequence of strings that is initialized with '@[]' - capitals: array[3, string] +iterator evensUpTo(n: int): int = + var x = 0 + while x <= n: + yield x + x += 2 - # array of strings with a fixed size - -capitals = ["New York", "London", "Berlin"] - # array 'capitals' allows assignment of only three elements -fruits.add("Banana") - # sequence 'fruits' is dynamically expandable during runtime -fruits.add("Mango") - -proc openArraySize(oa: openArray[string]): int = - oa.len - -assert openArraySize(fruits) == 2 - # procedure accepts a sequence as parameter -assert openArraySize(capitals) == 3 - # but also an array type +for e in evensUpTo(10): + echo e # 0 2 4 6 8 10 ``` -### Varargs +## Files & IO + +### Read / Write Whole File {.row-span-2} ```nim -proc myWriteln(f: File, a: varargs[string]) = - for s in items(a): - write(f, s) - write(f, "\n") +# Write whole file +writeFile("out.txt", "Hello Nim!\n") -myWriteln(stdout, "abc", "def", "xyz") -# is transformed by the compiler to: -myWriteln(stdout, ["abc", "def", "xyz"]) +# Read whole file +let text = readFile("out.txt") +echo text ``` -### Slices +### Manual Open/Close with `defer` ```nim -var - a = "Nim is a programming language" - b = "Slices are useless." +import std/syncio -echo a[7 .. 12] # --> 'a prog' -b[11 .. ^2] = "useful" -echo b # --> 'Slices are useful.' -``` - -### Objects - -```nim -type - Person = object - name: string - age: int - -var person1 = Person(name: "Peter", age: 30) - -echo person1.name # "Peter" -echo person1.age # 30 - -var person2 = person1 # copy of person 1 - -person2.age += 14 - -echo person1.age # 30 -echo person2.age # 44 - - -# the order may be changed -let person3 = Person(age: 12, name: "Quentin") - -# not every member needs to be specified -let person4 = Person(age: 3) -# unspecified members will be initialized with their default -# values. In this case it is the empty string. -doAssert person4.name == "" -``` - -### Tuples - -```nim -type - Person = tuple - name: string - age: int - - PersonX = tuple[name: string, age: int] - - PersonY = (string, int) - -var - person: Person - personX: PersonX - personY: PersonY - -person = (name: "Peter", age: 30) -# Person and PersonX are equivalent -personX = person - -# Create a tuple with anonymous fields: -personY = ("Peter", 30) - -person = personY -personY = person - -person = ("Peter", 30) - -echo person.name # "Peter" -echo person.age # 30 - -echo person[0] # "Peter" -echo person[1] # 30 - -var building: tuple[street: string, number: int] -building = ("Rue del Percebe", 13) -echo building.street - -``` - -### Reference and pointer types - -```nim -type - Node = ref object - le, ri: Node - data: int - -var n = Node(data: 9) -echo n.data -# no need to write n[].data; in fact n[].data is highly discouraged! -``` - -### Procedural type - -```nim -proc greet(name: string): string = - "Hello, " & name & "!" - -proc bye(name: string): string = - "Goodbye, " & name & "." - -proc communicate(greeting: proc (x: string): string, name: string) = - echo greeting(name) - -communicate(greet, "John") -communicate(bye, "Mary") -``` - -### Modules - -```nim -# Module A -var - x*, y: int - -proc `*` *(a, b: seq[int]): seq[int] = - # allocate a new sequence: - newSeq(result, len(a)) - # multiply two int sequences: - for i in 0 ..< len(a): result[i] = a[i] * b[i] +proc writeLog() = + var f = open("log.txt", fmWrite) + defer: f.close() + f.writeLine("entry 1") + f.writeLine("entry 2") when isMainModule: - # test the new `*` operator for sequences: - assert(@[1, 2, 3] * @[1, 2, 3] == @[1, 4, 9]) - - + writeLog() ``` -### Excluding symbols +### Read a File Line-By-Line ```nim -import mymodule except y - -# From statement -from mymodule import x, y, z -from mymodule import x, y, z - -x() - # use x without any qualification - -#Include statement -include fileA, fileB, fileC - +for line in lines("data.txt"): + echo line ``` -### Inheritance +### Check Paths and Existence {.row-span-2} ```nim -type - Person = ref object of RootObj - name*: string # the * means that `name` is accessible from other modules - age: int # no * means that the field is hidden from other modules +import std/os - Student = ref object of Person # Student inherits from Person - id: int # with an id field +if fileExists("data.txt"): + echo "File exists!" -var - student: Student - person: Person -assert(student of Student) # is true -# object construction: -student = Student(name: "Anton", age: 5, id: 2) -echo student[] +if dirExists("configs"): + echo "Directory exists!" + +echo getCurrentDir() +echo absolutePath("data.txt") ``` -### Mutually recursive types - -```nim -type - Node = ref object - # a reference to an object with the following field: - le, ri: Node - # left and right subtrees - sym: ref Sym - # leaves contain a reference to a Sym - - Sym = object - # a symbol - name: string - # the symbol's name - line: int - # the line the symbol was declared in - code: Node - # the symbol's abstract syntax tree -``` - -### Object variants - -```nim -# This is an example how an abstract syntax tree could be modelled in Nim -type - NodeKind = enum # the different node types - nkInt, # a leaf with an integer value - nkFloat, # a leaf with a float value - nkString, # a leaf with a string value - nkAdd, # an addition - nkSub, # a subtraction - nkIf # an if statement - Node = ref object - case kind: NodeKind # the `kind` field is the discriminator - of nkInt: intVal: int - of nkFloat: floatVal: float - of nkString: strVal: string - of nkAdd, nkSub: - leftOp, rightOp: Node - of nkIf: - condition, thenPart, elsePart: Node - -var n = Node(kind: nkFloat, floatVal: 1.0) -# the following statement raises an `FieldDefect` exception, because -# n.kind's value does not fit: -n.strVal = "" -``` - -### Method call syntax - -```nim -import std/strutils - -echo "abc".len # is the same as echo len("abc") -echo "abc".toUpperAscii() -echo({'a', 'b', 'c'}.card) -stdout.writeLine("Hallo") # the same as writeLine(stdout, "Hallo") -############################## -import std/[strutils, sequtils] - -stdout.writeLine("Give a list of numbers (separated by spaces): ") -stdout.write(stdin.readLine.splitWhitespace.map(parseInt).max.`$`) -stdout.writeLine(" is the maximum!") -``` - -### Properties - -```nim -type - Socket* = ref object of RootObj - h: int # cannot be accessed from the outside of the module due to missing star - -proc `host=`*(s: var Socket, value: int) {.inline.} = - ## setter of host address - s.h = value - -proc host*(s: Socket): int {.inline.} = - ## getter of host address - s.h - -var s: Socket -new s -s.host = 34 # same as `host=`(s, 34) - -type - Vector* = object - x, y, z: float - -proc `[]=`* (v: var Vector, i: int, value: float) = - # setter - case i - of 0: v.x = value - of 1: v.y = value - of 2: v.z = value - else: assert(false) - -proc `[]`* (v: Vector, i: int): float = - # getter - case i - of 0: result = v.x - of 1: result = v.y - of 2: result = v.z - else: assert(false) -``` - -### Dynamic dispatch - -```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 - -# watch out: 'eval' relies on dynamic binding -method eval(e: Expression): int {.base.} = - # override this base method - quit "to override!" - -method eval(e: Literal): int = e.x -method eval(e: PlusExpr): int = eval(e.a) + eval(e.b) - -proc newLit(x: int): Literal = Literal(x: x) -proc newPlus(a, b: Expression): PlusExpr = PlusExpr(a: a, b: b) - -echo eval(newPlus(newPlus(newLit(1), newLit(2)), newLit(4))) -``` - -### Raise statement - -```nim -var - e: ref OSError -new(e) -e.msg = "the request to the OS failed" -raise e - -raise newException(OSError, "the request to the OS failed") -``` - -### Try statement - -```nim -from std/strutils import parseInt - -# read the first two lines of a text file that should contain numbers -# and tries to add them -var - f: File -if open(f, "numbers.txt"): - try: - let a = readLine(f) - let b = readLine(f) - echo "sum: ", parseInt(a) + parseInt(b) - except OverflowDefect: - echo "overflow!" - except ValueError: - echo "could not convert string to integer" - except IOError: - echo "IO error!" - except CatchableError: - echo "Unknown exception!" - # reraise the unknown exception: - raise - finally: - close(f) -``` - -### Annotating procs with raised exceptions - -```nim -proc complexProc() {.raises: [IOError, ArithmeticDefect].} = - - -proc simpleProc() {.raises: [].} = - ... -``` - -### Generics - -```nim - type - BinaryTree*[T] = ref object # BinaryTree is a generic type with - # generic param `T` - le, ri: BinaryTree[T] # left and right subtrees; may be nil - data: T # the data stored in a node - -proc newNode*[T](data: T): BinaryTree[T] = - # constructor for a node - new(result) - result.data = data - -proc add*[T](root: var BinaryTree[T], n: BinaryTree[T]) = - # insert a node into the tree - if root == nil: - root = n - else: - var it = root - while it != nil: - # compare the data items; uses the generic `cmp` proc - # that works for any type that has a `==` and `<` operator - var c = cmp(it.data, n.data) - if c < 0: - if it.le == nil: - it.le = n - return - it = it.le - else: - if it.ri == nil: - it.ri = n - return - it = it.ri - -proc add*[T](root: var BinaryTree[T], data: T) = - # convenience proc: - add(root, newNode(data)) - -iterator preorder*[T](root: BinaryTree[T]): T = - # Preorder traversal of a binary tree. - # This uses an explicit stack (which is more efficient than - # a recursive iterator factory). - var stack: seq[BinaryTree[T]] = @[root] - while stack.len > 0: - var n = stack.pop() - while n != nil: - yield n.data - add(stack, n.ri) # push right subtree onto the stack - n = n.le # and follow the left pointer - -var - root: BinaryTree[string] # instantiate a BinaryTree with `string` -add(root, newNode("hello")) # instantiates `newNode` and `add` -add(root, "world") # instantiates the second `add` proc -for str in preorder(root): - stdout.writeLine(str) -``` - -### Templates - -```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)) -############################################# -const - debug = true - -proc log(msg: string) {.inline.} = - if debug: stdout.writeLine(msg) - -var - x = 4 -log("x has the value: " & $x) -#################################### -template withFile(f: untyped, filename: string, mode: FileMode, - body: untyped) = - let fn = filename - var f: File - if open(f, fn, mode): - try: - body - finally: - close(f) - else: - quit("cannot open: " & fn) - -withFile(txt, "ttempl3.txt", fmWrite): - txt.writeLine("line 1") - txt.writeLine("line 2") - -``` - -### Static Arguments - -```nim -import std/macros - -macro myMacro(arg: static[int]): untyped = - echo arg # just an int (7), not `NimNode` - -myMacro(1 + 2 * 3) -``` - -### Code Blocks as Arguments - -```nim -echo "Hello ": - let a = "Wor" - let b = "ld!" - a & b -``` - -### The Syntax Tree - -```nim -dumpTree: - var mt: MyType = MyType(a:123.456, b:"abcdef") - -# output: -# StmtList -# VarSection -# IdentDefs -# Ident "mt" -# Ident "MyType" -# ObjConstr -# Ident "MyType" -# ExprColonExpr -# Ident "a" -# FloatLit 123.456 -# ExprColonExpr -# Ident "b" -# StrLit "abcdef" -``` - -### Custom Semantic Checking - -```nim -macro myAssert(arg: untyped): untyped = - arg.expectKind nnkInfix -``` - -### Generating Code - -```nim -import std/macros - -type -MyType = object - a: float - b: string - -macro myMacro(arg: untyped): untyped = -var mt: MyType = MyType(a:123.456, b:"abcdef") - -# - -let mtLit = newLit(mt) - -result = quote do: - echo `arg` - echo `mtLit` - -myMacro("Hallo") -``` - -### Building Your First Macro - -```nim -import std/macros - -macro myAssert(arg: untyped): untyped = - # all node kind identifiers are prefixed with "nnk" - arg.expectKind nnkInfix - arg.expectLen 3 - # operator as string literal - let op = newLit(" " & arg[0].repr & " ") - let lhs = arg[1] - let rhs = arg[2] - - result = quote do: - if not `arg`: - raise newException(AssertionDefect,$`lhs` & `op` & $`rhs`) - -let a = 1 -let b = 2 - -myAssert(a != b) -myAssert(a == b) - -``` +## Templates and Macros