Syntax

The syntax of Nim resembles that of Python.^[26] Code blocks and nesting statements are identified through use of whitespace, according to the offside-rule. Many keywords are identical to their Python equivalents, which are mostly English keywords, whereas other programming languages usually use punctuation. With the goal of improving upon its influence languages, even though Nim supports indentation-based syntax like Python, it introduced additional flexibility. For example, a single statement may span multiple lines if a comma or binary operator is at the end of each line. Nim also supports user-defined operators.

Unlike Python, Nim implements (native) static typing. Nim's type system allows for easy type conversion, casting, and provides syntax for generic programming. Nim notably provides type classes which can stand in for multiple types, and provides several such type classes 'out of the box'. Type classes allow working with several types as if they were a single type. For example:

• openarray – Represents arrays of different sizes, sequences, and strings
• SomeSignedInt – Represents all the signed integer types
• SomeInteger – Represents all the Integer types, signed or not
• SomeOrdinal – Represents all the basic countable and ordered types, except of non integer number

This code sample demonstrates the use of typeclasses in Nim

# Let's declare a function that takes any type of number and displays its double
# In Nim functions with side effect are called "proc"
proc timesTwo(i: SomeNumber) =
  echo i * 2

# Let's write another function that takes any ordinal type, and returns
# the double of the input in its original type, if it is a number;
# or returns the input itself otherwise.
# We use a generic Type(T), and precise that it can only be an Ordinal
func twiceIfIsNumber[T: SomeOrdinal](i: T): T =
  when T is SomeNumber: # A `when` is an `if` evaluated during compile time
    result = i * 2 # You can also write `return i * 2`
  else:
    # If the Ordinal is not a number it is converted to int,
    # multiplied by two, and reconverted to its based type
    result = (i.int * 2).T

echo twiceIfIsNumber(67) # Passes an int to the function
echo twiceIfIsNumber(67u8) # Passes an uint8 
echo twiceIfIsNumber(true) # Passes a bool (Which is also an Ordinal)

Influence

According to the language creator, Nim was conceived to combine the best parts of Ada typing system, Python flexibility, and powerful Lisp macro system.^[27]

Nim was influenced by specific characteristics of existing languages, including the following:

• Modula-3: traced vs untraced pointers
• Object Pascal: type safe bit sets (set of char), case statement syntax, various type names and filenames in the standard library
• Ada: subrange types, distinct type, safe variants – case objects
• C++: operator overloading, generic programming
• Python: Off-side rule
• Lisp: Macro system, AST manipulation, homoiconicity
• Oberon: export marker
• C#: async/await, lambda macros
• ParaSail: pointer-free programming^[8]

Uniform Function Call Syntax

Nim supports Uniform Function Call Syntax (UFCS)^[28] and identifier equality, which provides a large degree of flexibility in use.

For example, each of these lines print "hello world", just with different syntax:

echo "hello world"
echo("hello world")
"hello world".echo()
"hello world".echo
echo("hello", " world")
"hello".echo(" world")
"hello".echo " world"

Identifier equality

Nim is almost fully style-insensitive; two identifiers are considered equal if they only differ by capitalization and underscores, as long as the first characters are identical. This is to enable a mixture of styles across libraries: one user can write a library using snake_case as a convention, and it can be used by a different user in a camelCase style without issue.^[29]

const useHttps = true
assert useHttps == useHttps
assert useHTTPS == useHttps
assert use_https == useHttps

Stropping

The stropping feature allows the use of any name for variables or functions, even when the names are reserved words for keywords. An example of stropping is the ability to define a variable named if, without clashing with the keyword if. Nim's implementation of this is achieved via backticks, allowing any reserved word to be used as an identifier.^[30]

type Type = object
  `int`: int

let `object` = Type(`int`: 9)
assert `object` is Type
assert `object`.`int` == 9

var `var` = 42
let `let` = 8
assert `var` + `let` == 50

const `assert` = true
assert `assert`

Compiler options

By default, the Nim compiler creates a debug build.^[33] With the option -d:release a release build can be created, which is optimized for speed and contains fewer runtime checks.^[33] With the option -d:danger all runtime checks can be disabled, if maximum speed is desired.^[33]

Memory management

Nim supports multiple memory management strategies, including the following:^[34]

• --gc:refc – Standard deferred reference counting based garbage collector with a simple mark-and-sweep backup GC in order to collect cycles. Heaps are thread-local.
• --gc:markAndSweep – Simple mark-and-sweep based garbage collector. Heaps are thread-local.
• --gc:boehm – Boehm based garbage collector, it offers a shared heap.
• --gc:go – Go's garbage collector, useful for interoperability with Go. Offers a shared heap.
• --gc:arc – Automatic reference counting (ARC) with move semantics optimizations, offers a shared heap. It offers fully deterministic performance for hard realtime systems.^[35] Reference cycles may cause memory leaks: these may be dealt with by manually annotating {.acyclic.} pragmas or by using --gc:orc.
• --gc:orc – Same as --gc:arc but adds a cycle collector (the "O") based on "trial deletion".^[36] The cycle collector only analyzes types if they are potentially cyclic.
• --gc:none – No memory management strategy nor a garbage collector. Allocated memory is simply never freed, unless manually freed by the developer's code.

As of Nim 2.0, ORC is the default GC.^[37]

Bundled

Many tools are bundled with the Nim install package, including:

Other notable tools

Some notable tools not included in the Nim distribution include:

Pure/impure libraries

Pure libraries are modules written in Nim only. They include no wrappers to access libraries written in other programming languages.

Impure libraries are modules of Nim code which depend on external libraries that are written in other programming languages such as C.

Standard library

The Nim standard library includes modules for all basic tasks, including:^[49]

• System and core modules
• Collections and algorithms
• String handling
• Time handling
• Generic Operating System Services
• Math libraries
• Internet Protocols and Support
• Threading
• Parsers
• Docutils
• XML Processing
• XML and HTML code generator
• Hashing
• Database support (PostgreSQL, MySQL and SQLite)
• Wrappers (Win32 API, POSIX)

Use of other libraries

A Nim program can use any library which can be used in a C, C++, or JavaScript program. Language bindings exist for many libraries, including GTK,^[50][51] Qt QML,^[52] wxWidgets,^[53] SDL 2,^[54][55] Cairo,^[56] OpenGL,^[57] WinAPI,^[58] zlib, libzip, OpenSSL, Vulkan^[59] and cURL.^[60] Nim works with PostgreSQL, MySQL, and SQLite databases.

There are open source tools of various degree of support that can be used to interface Nim with Lua,^[61] Julia,^[62] Rust,^[63] C#,^[64] and Python^[65] programming languages or transpile Nim to TypeScript.^[66]

Hello world

The "Hello, World!" program in Nim:

echo("Hello, World!")
# Procedures can be called with no parentheses
echo "Hello, World!"

Another version of "Hello World" can be accomplished by calling the write function with the stdout stream:

stdout.write("Hello, World!\n")
write(stdout, "Hello, World!\n")

Fibonacci

Several implementations of the Fibonacci function, showcasing implicit returns, default parameters, iterators, recursion, and while loops:

proc fib(n: Natural): Natural =
  if n < 2:
    return n
  else:
    return fib(n-1) + fib(n-2)
    
func fib2(n: int, a = 0, b = 1): int =
  if n == 0: a else: fib2(n-1, b, a+b)
  
iterator fib3: int =
  var a = 0
  var b = 1
  while true:
    yield a
    swap a, b
    b += a

Factorial

Program to calculate the factorial of a positive integer using the iterative approach, showcasing try/catch error handling and for loops:

import std/strutils

var n = 0
try:
  stdout.write "Input positive integer number: "
  n = stdin.readline.parseInt
except ValueError:
  raise newException(ValueError, "You must enter a positive number")

var fact = 1
for i in 2..n:
  fact = fact * i

echo fact

Using the module math from Nim's standard library:

import std/math
echo fac(x)

Reversing a string

A simple demonstration showing the implicit result variable and the use of iterators.

proc reverse(s: string): string =
  for i in countdown(s.high, 0):
    result.add s[i]

let str1 = "Reverse This!"
echo "Reversed: ", reverse(str1)

One of Nim's more exotic features is the implicit result variable. Every procedure in Nim with a non-void return type has an implicit result variable that represents the value to be returned. In the for loop we see an invocation of countdown which is an iterator. If an iterator is omitted, the compiler will attempt to use an items iterator, if one is defined for the type specified.

Graphical user interface

Using GTK 3 with GObject introspection through the gintro module:

import gintro/[gtk, glib, gobject, gio]

proc appActivate(app: Application) =
  let window = newApplicationWindow(app)
  window.title = "GTK3 application with gobject introspection"
  window.defaultSize = (400, 400)
  showAll(window)

proc main =
  let app = newApplication("org.gtk.example")
  connect(app, "activate", appActivate)
  discard run(app)

main()

This code requires the gintro module to work, which is not part of the standard library. To install the module gintro and many others you can use the tool nimble, which comes as part of Nim. To install the gintro module with nimble you do the following:

nimble install gintro

Functional programming

Functional programming is supported in Nim through first-class functions and code without side effects via the noSideEffect pragma or the func keyword.^[67] Nim will perform side effect analysis and raise compilation errors for code that does not obey the contract of producing no side effects when compiled with the experimental feature strictFuncs, planned to become the default in later versions.^[68]

Contrary to purely functional programming languages, Nim is a multi-paradigm programming language, so functional programming restrictions are opt-in on a function-by-function basis.

import std/[sequtils, sugar]

let powersOfTwo = @[1, 2, 4, 8, 16, 32, 64, 128, 256]

proc filter[T](s: openArray[T], pred: T -> bool): seq[T] =
  result = newSeq[T]()
  for i in 0 ..< s.len:
    if pred(s[i]):
      result.add(s[i])

echo powersOfTwo.filter(proc (x: int): bool = x > 32)
# syntactic sugar for the above, provided as a macro from std/sugar
echo powersOfTwo.filter(x => x > 32)

proc greaterThan32(x: int): bool = x > 32
echo powersOfTwo.filter(greaterThan32)

func binarySearch[T](a: openArray[T]; elem: T): int
# is short for...
proc binarySearch[T](a: openArray[T]; elem: T): int {.noSideEffect.}

{.experimental: "strictFuncs".}

type
  Node = ref object
    le, ri: Node
    data: string

func len(n: Node): int =
  # valid: len does not have side effects
  var it = n
  while it != nil:
    inc result
    it = it.ri

func mut(n: Node) =
  let m = n # is the statement that connected the mutation to the parameter
  m.data = "yeah" # the mutation is here
  # Error: 'mut' can have side effects
  # an object reachable from 'n' is potentially mutated

import std/[sequtils, sugar]

let numbers = @[1, 2, 3, 4, 5, 6, 7, 8, 7, 6, 5, 4, 3, 2, 1]
# a and b are special identifiers in the foldr macro
echo numbers.filter(x => x > 3).deduplicate.foldr(a + b) # 30

import std/tables

type
  Value = uint64
  Ident = string
  ExprKind = enum
    Literal, Variable, Abstraction, Application
  Expr = ref object
    case kind: ExprKind
    of Literal:
      litIdent: Value
    of Variable:
      varIdent: Ident
    of Abstraction:
      paramAbs: Ident
      funcAbs: Expr
    of Application:
      funcApp, argApp: Expr

func eval(expr: Expr, context: var Table[Ident, Value]): Value =
  case expr.kind
  of Literal:
    return expr.litIdent
  of Variable:
    return context[expr.varIdent]
  of Application:
    case expr.funcApp.kind
    of Abstraction:
      context[expr.funcApp.paramAbs] = expr.argApp.eval(context)
      return expr.funcAbs.eval(context)
    else:
      raise newException(ValueError, "Invalid expression!")
  else:
    raise newException(ValueError, "Invalid expression!")

Object-oriented programming

Despite being primarily an imperative and functional language, Nim supports various features for enabling object-oriented paradigms.^[75][76]

type Animal = ref object of RootObj
  name: string
  age: int
type Dog = ref object of Animal
type Cat = ref object of Animal

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

for a in animals:
  assert a of Animal

type Socket* = ref object
  host: int # private, lacks export marker

# getter of host address
proc host*(s: Socket): int = s.host

# setter of host address
proc `host=`*(s: var Socket, value: int) =
  s.host = value

var s: Socket
new s
assert s.host == 0  # same as host(s), s.host()
s.host = 34         # same as `host=`(s, 34)

import std/strformat

type
  Person = ref object of RootObj
    name: string
  Student = ref object of Person
  Teacher = ref object of Person

method introduce(a: Person) =
  raise newException(CatchableError, "Method without implementation override")

method introduce(a: Student) =
  echo &"I am a student named {a.name}!"

method introduce(a: Teacher) =
  echo &"I am a teacher named {a.name}!"
  
let people: seq[Person] = @[Teacher(name: "Alice"), Student(name: "Bob")]
for person in people:
  person.introduce()

Metaprogramming

template genType(name, fieldname: untyped, fieldtype: typedesc) =
  type
    name = object
      fieldname: fieldtype

genType(Test, foo, int)

var x = Test(foo: 4566)
echo(x.foo) # 4566

proc addThese[T](a, b: T): T = a + b
echo addThese(1, 2) # 3 (of int type)
echo addThese(uint8 1, uint8 2) # 3 (of uint8 type)

# we don't want to risk subtracting unsigned numbers!
proc subtractThese[T: SomeSignedInt | float](a, b: T): T = a - b
echo subtractThese(1, 2) # -1 (of int type)

import std/sequtils

# constrained generics can also be directly on the parameters
proc compareThese[T](a, b: string | seq[T]): bool =
  for (i, j) in zip(a, b):
    if i != j:
      return false

import std/macros

macro twice(arg: untyped): untyped =
  result = quote do:
    `arg`
    `arg`

twice echo "Hello world!"

echo "Hello world!"
echo "Hello world!"

Foreign function interface (FFI)

Nim's FFI is used to call functions written in the other programming languages that it can compile to. This means that libraries written in C, C++, Objective-C, and JavaScript can be used in the Nim source code. One should be aware that both JavaScript and C, C++, or Objective-C libraries cannot be combined in the same program, as they are not as compatible with JavaScript as they are with each other. Both C++ and Objective-C are based on and compatible with C, but JavaScript is incompatible, as a dynamic, client-side web-based language.^[20]: 226

The following program shows the ease with which external C code can be used directly in Nim.

proc printf(formatstr: cstring) {.header: "<stdio.h>", varargs.}

printf("%s %d\n", "foo", 5)

In this code the printf function is imported into Nim and then used.

Basic example using 'console.log' directly for the JavaScript compilation target:

proc log(args: any) {.importjs: "console.log(@)", varargs.}
log(42, "z", true, 3.14)

The JavaScript code produced by the Nim compiler can be executed with Node.js or a web browser.

Parallelism

To activate threading support in Nim, a program should be compiled with --threads:on command line argument. Each thread has a separate garbage collected heap and sharing of memory is restricted, which helps with efficiency and stops race conditions by the threads.

import std/locks

var
  thr: array[0..4, Thread[tuple[a,b: int]]]
  L: Lock

proc threadFunc(interval: tuple[a,b: int]) {.thread.} =
  for i in interval.a..interval.b:
    acquire(L) # lock stdout
    echo i
    release(L)

initLock(L)

for i in 0..high(thr):
  createThread(thr[i], threadFunc, (i*10, i*10+5))
joinThreads(thr)

Nim also has a channels module that simplifies passing data between threads.

import std/os

type
  CalculationTask = object
    id*: int
    data*: int

  CalculationResult = object
    id*: int
    result*: int

var task_queue: Channel[CalculationTask]
var result_queue: Channel[CalculationResult]

proc workerFunc() {.thread.} =
  result_queue.open()

  while true:
    var task = task_queue.recv()
    result_queue.send(CalculationResult(id: task.id, result: task.data * 2))

var workerThread: Thread[void]
createThread(workerThread, workerFunc)

task_queue.open()
task_queue.send(CalculationTask(id: 1, data: 13))
task_queue.send(CalculationTask(id: 2, data: 37))

while true:
  echo "got result: ", repr(result_queue.recv())

Concurrency

Asynchronous IO is supported either via the asyncdispatch module in the standard library or the external chronos library.^[80] Both libraries add async/await syntax via the macro system, without need for special language support. An example of an asynchronous HTTP server:

import std/[asynchttpserver, asyncdispatch]
# chronos could also be alternatively used in place of asyncdispatch,
# with no other changes.

var server = newAsyncHttpServer()
proc cb(req: Request) {.async.} =
  await req.respond(Http200, "Hello World")

waitFor server.serve(Port(8080), cb)

Online

Nim has an active community on the self-hosted, self-developed official forum.^[81] Further, the project uses a Git repository, bug tracker, RFC tracker, and wiki hosted by GitHub, where the community engages with the language.^[82] There are also official online chat rooms, bridged between IRC, Matrix, Discord, Gitter, and Telegram.^[83]

Conventions

The first Nim conference, NimConf, took place on June 20, 2020. It was held digitally due to COVID-19, with an open call for contributor talks in the form of YouTube videos.^[84] The conference began with language overviews by Nim developers Andreas Rumpf and Dominik Picheta. Presentation topics included talks about web frameworks, mobile development, Internet of things (IoT) devices, and game development, including a talk about writing Nim for Game Boy Advance.^[85] NimConf 2020 is available as a YouTube playlist.^[86] NimConf 2021 occurred the following year, was also held digitally, and included talks about game development, REPLs, real-time operating systems, Nim in the industry, object-relational mapping (ORM), language design, and graphics libraries.^[87]

In addition to official conferences, Nim has been featured at various other conventions. A presentation on Nim was given at the O'Reilly Open Source Convention (OSCON) in 2015.^[88][89][90] Four speakers represented Nim at FOSDEM 2020, including the creator of the language, Andreas Rumpf.^[91] At FOSDEM 2022, Nim hosted their own developer room virtually due to the COVID-19 pandemic.^[92] Talks were held on concurrency, embedded programming, programming for GPUs, entity-component systems, game development, rules engines, Python interop, and metaprogramming.^[93]