repository·devel·Indexed 12 days ago
https://github.com/nim-lang/nimA programming language that compiles to C, C++, or JavaScript. This documentation covers the Nim compiler, its standard library, development tools like koch and nim-gdb, and detailed changelogs from v0.18.0 through v0.20.0.
Linenoise is a minimal, zero-configuration, BSD-licensed replacement for readline. It is designed to be lightweight and easy to embed in small utilities without the overhead of large libraries like readline (30k lines) or libedit (20k lines). It provides essential command-line features including:
niminst is a tool used to generate installers for Nim programs. It can create Windows installers via Inno Setup and installation/deinstallation scripts for UNIX-like systems.
To use niminst, you must provide a configuration file that describes your project, files, and target operating systems. The tool uses the Nim parsecfg module to parse this configuration.
koch program is Nim's maintenance script, designed as a portable replacement for make and shell scripting. It is primarily used to build the Nim compiler and perform various maintenance tasks like running tests or generating documentation.When contributing to Nim, familiarize yourself with these core directories:
compiler/: The compiler source code, including plugins in compiler/plugins/.lib/: The standard library.pure/: Modules written in pure Nim.impure/: Modules with dependencies in other languages.wrappers/: Wrappers for non-Nim dependencies.nimsuggest: The nimsuggest tool.config/: Configuration for the compiler and documentation generator.doc/: Documentation files (reStructuredText).tests/: Categorized tests for the compiler and standard library. Integration tests belong in tests/untestable.tools/: Tools including niminst (often invoked via koch).bin/, build/: Empty directories used during the build process.koch.nim: The tool used to bootstrap Nim and manage builds.The let statement declares a local or global single-assignment variable. Unlike var, let variables are immutable after creation and cannot be used as l-values (you cannot take their address or pass them to var parameters).
Because they are immutable, let statements must define a value at declaration, except when using importX pragmas (like {.importc.}) where the value is provided by native code (e.g., a C const).
let x = 10
# x = 20 # Error: cannot assign to let variableWhen matching an operand's type to a concept, the compiler treats the operand as a "potential implementation" and attempts to satisfy every definition in the concept body by substituting Self with that implementation.
Specificity Rules (Hierarchical Order Comparison): To avoid impractical complexity during overload resolution, Nim uses simplified rules when comparing concepts:
T or auto.A procedural type is internally a pointer to a procedure. The compatibility of two procedural types depends on their calling convention. If the calling conventions differ, they are not compatible.
Key Calling Conventions:
nimcall: The default convention for Nim proc. Equivalent to fastcall on supported C compilers.closure: The default for procedural types without pragmas. It includes a hidden environment pointer (takes two machine words).cdecl: Uses the C compiler's calling convention (e.g., __cdecl on Windows).stdcall: Microsoft's __stdcall convention.safecall: Microsoft's __safecall convention.inline: A hint to the C compiler to inline the procedure.noinline: Prevents the backend compiler from inlining.fastcall: Uses the C compiler's __fastcall implementation.thiscall: Microsoft's __thiscall (used for C++ class members on x86).syscall: Uses the C __syscall:c convention (for interrupts).noconv: Uses the C compiler's default convention (no explicit keyword).Compatibility Note: A nimcall procedure can be passed to a parameter expecting a closure as a special extension.
proc printItem(x: int) = ...
# This will NOT compile because calling conventions differ (cdecl vs nimcall)
proc forEach(c: proc (x: int) {.cdecl.}) = ...
forEach(printItem)
type
OnMouseMove = proc (x, y: int) {.closure.}
proc onMouseMove(mouseX, mouseY: int) =
echo "x: ", mouseX, " y: ", mouseY
proc setOnMouseMove(mouseMoveEvent: OnMouseMove) = discard
# This is OK: 'onMouseMove' has the default (nimcall) convention,
# which is compatible with 'closure'.
setOnMouseMove(onMouseMove)Nim's experimental pattern matching allows for special operators in templates and macros to manipulate the AST.
| (Ordered Choice): Creates an ordered choice in a pattern. Note that matching occurs after optimizations like constant folding, so echo 1 might not match a pattern expecting a literal if the compiler folded it.{} (Pattern Parameter): Binds a pattern expression to a parameter using expr{param} notation.~ (Not): Acts as the 'not' operator in patterns.* (Flatten): Flattens a nested binary expression (e.g., a & b & c) into a single argument list (e.g., &(a, b, c)). The second operator must be a parameter used to gather arguments.** (Gather with RPN): Similar to *, but also gathers the matched operators in Reverse Polish Notation (RPN).You can deactivate pattern matching globally using the --patterns:off command line option or locally with the patterns pragma.
# The `|` operator creates an ordered choice
template t{0|1}(): untyped = 3
let a = 1
echo a # outputs 3
# The `*` operator flattens expressions
template optConc{ `&&` * a }(a: string): untyped = &&a
let space = " "
echo "my" && (space & "awe" && "some " ) && "concat"