NICKLE(1)

📦

version 2.108 · 6 versions

2.108 · alpine 3.24, arch rolling, epel 10, fedora 43, fedora 44, ubuntu stonking (latest)
2.103 · epel 9, fedora 43
2.97build2 · ubuntu noble
2.91 · debian bookworm, ubuntu jammy
2.107 · ubuntu resolute
2.103 · debian trixie, ubuntu questing

, in alpine 3.24, arch rolling, epel 10, fedora 43, fedora 44, ubuntu stonking

🌸 NICKLE(1) 🌸

okay bestie, sit down, hydrate, because we're about to talk about nickle — the desk calculator language from the General Commands Manual, and she is so much more than a calculator. 💅

✨ NAME ✨

nickle — a desk calculator language. that's it, that's the whole name section, but the way she's a language and a calculator at the same time?? main character energy fr fr. 👑

🎀 SYNOPSIS 🎀

nickle [--help|--usage] [-f file] [-l library] [-e expr] [-V] [ script ]
[--] [arg ...]

🦋 USAGE 🦋

so here's the vibe: any argument that doesn't start with a flag gets treated as a Nickle script, and it replaces standard input entirely. like, script comes in, stdin steps aside. 💖

Any remaining arguments that come after the script get dropped into the Nickle string array argv so your program can peek at them programmatically. yes bestie, you get real argv. iconic.

When you invoke Nickle with no expression and no script argument at all? She just reads from standard input and writes to standard output. cozy. 🌈

Options are as follows:

--help, --usage — print a help/usage message and exit. This is a built-in feature of Nickle's ParseArgs module, which means it's also true of any Nickle scripts that use this library. slay, inherited behaviour. ✨
-f, --file file — load file into Nickle before beginning execution. 📂
-l, --library library — load library into Nickle before beginning execution. (there's a description of the library facility further down, keep reading bestie 🫶)
-e, --expr expr — evaluate expr before beginning execution. 🔥
-V, --version — print the Nickle version and exit. 💫
-- — quit parsing arguments and pass the remainder, unevaluated, to argv. no take-backs, no interpretation, just raw vibes.

💜 SYNTAX 💜

okay so, to make the input language actually usable in an interactive setting, a newline only terminates statements at ``reasonable'' times. A newline terminates either expressions or single statements typed by the user — except for a few statements that require lookahead, most notably if() and twixt(), which have an optional else part. 🙈 Inside compound statements or function definitions, only a ; terminates statements. This approach is convenient and does not appear to cause problems in normal use. no cap. ✅

The syntax of Nickle programs is as follows. In this description, name denotes any sequence of letters, digits and _ characters not starting with a digit; E denotes any expression; S denotes any statement; and T denotes any type. The syntax X,X,...,X denotes one or more comma-separated Xs, unless otherwise indicated. 📝

🍓 Comments

C-style comments are enclosed in /* and */, and shell-style comments are denoted by a leading # at the start of a line.

🧚 Operands

real number — can include an exponent, and doesn't need to include a decimal point or sign. Will be treated as exact rationals. If a trailing decimal part contains an opening curly brace, the brace is silently ignored; if it contains a curly-bracketed trailing portion, it's treated as a repeating decimal. Floating point'' constants are currently represented internally as rationals — for floating constants with a given precision (and an infinite-precision exponent), use the imprecise()` builtin function described below. ✨
octal number — starts with a 0 (e.g., 014 is the same as 12).
hexidecimal number — starts with "0x" (e.g., 0x1a is the same as 26).
string — as in C. String constants are surrounded by double-quotes. Backslashed characters (including double-quotes) stand for themselves, except "\n" stands for newline, "\r" for carriage return, "\b" for backspace, "\t" for tab and "\f" for formfeed. 🎀
name — a variable reference.
name(), name(E,E,...,E) — a function call with zero or more arguments. Functions are fully call-by-value: arrays and structures are copied rather than being referenced as in C. yes really, copied. 🫶
desc name, T name = value — definition expressions: a new name is made available, with the value of the definition being the value of the initializer in the second form, and uninitialized in the first form. The descriptor desc is not optional: it consists of any combination of visibility, storage class or type (in that order). See QUALIFIERS immediately below for a description of these qualifiers. A structured value expression is also possible: see VALUES below. 👑

In addition to being able to initialize a definition with a Nickle value, C-style array, structure, and union definitions are also allowed. For example, the following

int[*,*] name = {{0,1},{2,3}}
int[2,2] name = {{0...}...}

are permitted with the obvious semantics. This is the context in which the dimensions in a type may be expressions: see the discussion of array types above. See the discussion of array and structure values for array and structure initializer syntax. 💖

🌈 QUALIFIERS 🌈

A declaration or definition may be qualified, as in C, to indicate details of programmatic behavior. But unlike in C, these qualifiers, while optional, must appear in the given order. order matters bestie, don't test her. 💅

🌟 Visibility

public — any definition expression (function definition, variable definition, type definition) can be qualified with public to indicate that the name being defined should be visible outside the current namespace, and should be automatically imported. See Namespaces below for further info. ✨
protected — any definition expression (function definition, variable definition, type definition) can be qualified with protected to indicate that the name being defined should be visible outside the current namespace, but should not be made available by import declarations. See Namespaces below for further info. 🔒

⏳ Lifetime

auto — an auto object is local to a particular block: its lifetime is at least the lifetime of that block. An auto object with an initializer will be re-initialized each time it is evaluated. This is the default lifetime for local objects. 🔄
static — a static object is local to a particular function definition: its lifetime is at least the lifetime of that definition. A new static object will be created each time its enclosing function definition is evaluated.

In Nickle, the keyword static has to do only with lifetime (like the use of static inside C functions), not with visibility (which is handled by separate qualifiers as described above, not like the use of static in global scope in C). iykyk. 🧠

global — a global object is global to the entire program: its lifetime is the lifetime of the program. A global object will be created and initialized when its definition is first seen. This is the default lifetime for global objects.

The distinction between static and global lifetime in Nickle is not possible in C, because C functions are not first class objects with nested scope. When deciding which to use in a Nickle program, think about what should happen if a definition is re-evaluated. 🤔

🔥 OPERATORS 🔥

Here are the basic Nickle operators, grouped in order of decreasing precedence. buckle up bestie, it's a long list but every single one is here. 💖

A[E,E,...,E] — refers to the E'th element of the array expression A, or the E1'th/E2'th/etc element of a multi-dimensional array. Both arrays of arrays ala C and multidimensional arrays ala NAWK are possible. 🌈
struct.tag — structure dereference.
struct->tag — structure pointer dereference ala C.

++ -- — unary increment/decrement. May be either postfix or prefix. 🔁
- — unary negate.
! E — logical negation.
E ! — factorial. Requires a non-negative integer argument.
* E — pointer dereference.
& E — reference construction.

(U) E — construct a value of union type with tag U and value E.

** — exponentiation. Both operands may be fractional. The left operand must be non-negative unless the right operand is integer. The result type is the type of the left operand if the right operand is integer, and real otherwise.

okay this one's important. This is the only known type-unsound feature of Nickle: an expression like 2 ** -3 will statically be of type integer, but dynamically will generate a rational result. This may cause a runtime type error later on — consider int x = 2 ** -3; she's giving chaos, be careful. 😭

* / // % — times, divide, integer divide, and remainder. The right operand of the last three operators must be nonzero. 🚨 The result type of the division operator will always be at least rational: the result type of the integer division operator will always be int. This is a notable departure from C, where integer division is implied by integer operands. Integer division is defined by

x // y == y > 0 ? floor (x / y) : ceil(x / y)

The remainder is always non-negative and is defined by:

x % y = x - (x // y) * y

+ - — addition and subtraction.

<< >> — bitwise left and right shift with integer operands. Negative right operands work as expected. These operators are defined by

x << y = x * 2 ** y
x >> y = x // 2 ** y

Another way to look at this is that negative left operands are considered to be in an infinite twos-complement representation (i.e., sign-extended to infinity), with right shift sign-extending its left operand. ✨

<= >= < > — relational operators.

== != — equality operators.

Finally, in order of decreasing precedence:

& — bitwise AND. Negative operands are considered to be in an infinite twos-complement representation (i.e., sign-extended to infinity). 💅
^ — bitwise XOR. Negative operands as in bitwise AND.
| — bitwise OR. Negative operands as in bitwise AND.
&& — short-circuit logical AND.
|| — short-circuit logical OR.
E ? E : E — conditional expression: if the first expression is logical true, the value is the second expression, else the third. 🎀
fork E — create (and return) a thread. See Thread below for details. 🧵
= += -= *= /= //= %= **= <<= >>= ^= &= |= — assignment operators. Left-hand-side must be assignable. x <op>= y is equivalent to x = x <op> y. 🔥
E , E — returns the right-hand expression.

phew, and that's just part one bestie — there's more coming, don't go anywhere. 💖🦋

💖 TYPES 💖

okay so bestie, here's the tea on Nickle types: the type declaration syntax is way more like the "left" variant of the Java syntax than the C syntax. and essentially, a type is made up of:

poly integer rational real string continuation void — these are the base types of the language. <pink>void</pink> is actually only usable in certain contexts, notably function returns. it's currently implemented as a "unit" type ala ML, and thus has slightly different behavior than in C. and <purple>poly</purple>? that one is the supertype of all other types (i.e., it can be used to inhibit static type checking), and it's the default type in most situations where a type need not appear. iconic behavior honestly.
file semaphore thread — also builtin base types, but integral to the File and Thread ADTs: see below. 🫶

🌈 More About Types 🌈

Nickle supports polymorphic data: as an expression is evaluated, a data type is chosen to fit the result. any Nickle object may be statically typed, in which case bounds violations will be flagged as errors at compile time. polymorphic variables and functions do not place restrictions on the assigned data type; this is the default type for all objects. no cap.

poly — this describes the union of all datatypes. a variable with this type can contain any data value.
int — arbitrary precision integers.
rational — arbitrary precision rational numbers.
real — arbitrary exponent precision floating point numbers. as many computations cannot be carried out exactly as rational numbers, Nickle implements non-precise arithmetic using its own machine-independent representation for floating point numbers. the builtin function imprecise(n) generates a real number with 256 bits of precision from the number n, while imprecise(n,p) generates a real number with p bits of precision. ✨
T[] — an array of type T, of one or more dimensions. there are no zero-dimensional arrays in Nickle. periodt.
T[*] — a one-dimensional array of type T. unlike in C, the dimension of an array is never part of its type in Nickle. further, arrays and pointers are unrelated types in Nickle.
T[*,*,...,*] — a two or more dimensional array of type T. the stars * are not optional. and as the previous paragraphs make clear, T[] is not a zero-dimensional array, bestie. 💅
T[E,E,...,E] — in definition contexts, integer values may be given for each dimension of an array context. these are strictly for value-creation purposes, and are not part of the type. an array type is determined only by the base type and number of dimensions of the array.
T0() T0(T,T,...,T) — a function returning type T0. a function accepts 0 or more arguments.
T0() T0(T,T,...,T ...) — a function accepting zero or more required arguments, plus an arbitrary number of optional arguments. the second sequence of three dots (ellipsis) is syntax, not metasyntax: see the description of varargs functions for details.
*T — a pointer to a location of type T. pointer arithmetic in Nickle operates only upon pointers to arrays: the pointer must be of the correct type, and may never stray out of bounds. a pointer may either point to some location or be null (0). as in C, the precedence of * is lower than the precedence of [] or (): use parenthesis as needed.
struct {T name; T name; ...} — a structure with fields of the given name and type. the types T are optional: in their absence, the type of the field is poly.
union {T name; T name; ...} — a "disjoint union" of the given types. this is more like the variant record type of Pascal or the datatype of ML than the C union type: the names are tags of the given type, exactly one of which applies to a given value at a given time.
(T) — parentheses for grouping. yes queen, that's the whole thing.

🏷️ Typedef 🏷️

as in C, new type names may be created with the typedef statement. the syntax is

typedef T typename;

where T is a Nickle type. the resulting typename may be used anywhere a type is expected. so clean, so iconic. 🎀

🌸 VALUES 🌸

values of the base types of Nickle are as expected. see the syntax for constants above. values of type file, semaphore, and continuation may currently be created only by calls to builtin functions: no Nickle constants of these types exist. 😭

as noted in TYPES above, Nickle has several kinds of "structured value": arrays, functions, pointers, structures and disjoint unions. all of these have some common properties. when created, all of the component values are uninitialized (unless otherwise specified). attempts to use an uninitialized value will result in either a compile-time error or a runtime exception. so like... don't. 🙈

🍓 Arrays 🍓

[E] — creates a (zero-based) array with E elements. E must be non-negative.
[E]{V,V,...,V} — creates an array with E elements, initialized to the Vs. if there are too few initializers, remaining elements will remain uninitialized.
[E]{V,V,...,V...} — the second ellipsis (three dots) is syntax, not metasyntax. create an array with E elements. the first elements in the array will be initialized according to the Vs, with any remaining elements receiving the same value as the last V. this syntax may be used in the obvious fashion with any of the array initializers below.
[*]{V,V,...,V} — creates an initialized array with exactly as many elements as initializers. there must be at least one initializer.
[E,E,...,E] [*,*,...,*] — creates multidimensional arrays. integer expressions and * cannot be mixed: an array's dimensions are entirely either specified or unspecified by the definition. these arrays may also be created initialized: see next paragraph for initializer syntax.
(T[E]) (T[E,E,...,E]) (T[E]){E,E,...,E}
(T[E,E,...,E]){{E,...},...,{E,...}} — alternate syntax for creating arrays of type T. the initializers, in curly braces, are optional. the number of initializers must be less than or equal to the given number of elements in each dimension. for multidimensional arrays, the extra curly braces per dimension in the initializer are required; this is unlike C, where they are optional.
(T[*]){E,E,...,E} (T[*,*,...,*]){{E,...},...,{E,...}} — creates arrays of type T, with each dimension's size given by the maximum number of initializers in any subarray in that dimension.

🎀 Pointers 🎀

0 — the null pointer, in contexts where a pointer is required.
&V &A[E,E,...,E] &S.N — creates a pointer to the given variable, array element, or structure member. the type of the pointer will be *T, where T is the type of the object pointed to.
*P — the value pointed to by pointer P. this can be viewed or modified as in C.

🦋 Functions 🦋

(T func(){S;S;...S;}) (T func(T name,T name,...T name){S;S;...S;}) — function expression: denotes a function of zero or more formal parameters with the given types and names, returning the given result type. the function body is given by the curly-brace-enclosed statement list. all types are optional, and default to poly. as noted above, functions are strictly call-by-value: in particular, arrays and structures are copied rather than referenced. yes bestie, that's a whole thing.
T function name(T name,T name,...,T name){S;S;...S;} — defines a function of zero or more arguments. syntactic sugar for

T(T,T,...T) name = (T func(T name,T name,...T name){S;S;...S;});

T function name(T name, T name ...) — the ellipsis here is syntax, not metasyntax: if the last formal argument to a function is followed by three dots, the function may be called with more actuals than formals. all "extra" actuals are packaged into the array formal of the given name, and typechecked against the optional type T of the last argument (default poly).

🧚 Structures 🧚

(struct { T name; T name; ...T name; }){name = E; name = E; ...name=E;} — create a value of a structured type. the named fields are initialized to the given values, with the remainder uninitialized. as indicated, initialization is by label rather than positional as in C.

💜 Unions 💜

(union { T name; T name; ...T name; }.name) E — create a value of the given union type, the variant given by .name, and the value given by E. E must be type-compatible with name.

📜 STATEMENTS 💅

okay bestie, the statement syntax is very closely related to C's — like, siblings energy — but we sprinkled in some extra syntax so Nickle's extra functionality can actually do its thing. let's gooo ✨

E; — just evaluates the expression. that's it, that's the whole statement, she's low maintenance 💅
{S ... S} — executes all the enclosed statements, in order, one after another. no skipping, no chaos.
if (E) S — the basic conditional, babes. classic.
if (E) S — conditional execution. (yes, she's listed twice up in here. the original said it twice and we respect her.)
else S — Else is allowed, with the usual syntax and semantics you already know and love. the important tea: an else binds to the most recent applicable if() or twixt(). she's clingy like that 🫶
while (E) S — C-style while loop, periodt.
do S while (E); — C-style do loop.
for (opt-E; opt-E; opt-E) S — C-style for loop, with all three expressions optional.
switch (E) { case E: S-list case E: S-list ... default: S-list } — C-style case statement. here's the glow-up: the case expressions are not required to be constant expressions, they may be arbitrary. the first case that evaluates to the switch argument is the one that gets taken; else the default if it's present; else the whole switch body just gets skipped. bye 👋
twixt(opt-E; opt-E) S
twixt(opt-E; opt-E) S else S — if the first argument expression evaluates to true, the body of the twixt() gets evaluated and then the second argument expression. if the first argument expression evaluates to false, the else statement runs if it's there. otherwise? the entire twixt() statement is skipped. simple as.

the twixt() statement guarantees that all of those events happen in the specified order, no matter how the twixt() is entered (from outside) or exited — and that includes exceptions, continuations, and break. (think of it like Java's finally clause, if Java were cooler.)

try S;
try S catch name (T name, ...) { S; ... };
try S catch name (T name, ...) { S; ... } ... ; — executes that first statement S. if an exception gets raised during execution, and the name matches the name in a catch block, then we bind the formal parameters in the catch block to the actual parameters of the exception, and execute the body of the catch block. you can have multiple catch blocks per try. zero catches is legal but, and I quote, relatively useless 🙈. after a catch block finishes, execution continues after the try clause. and same as else: a catch binds to the most recent applicable try-catch block.
raise name(name, name, ..., name) — raises the named exception with zero or more arguments. make some noise 📣
; — the null statement. does nothing, serves looks. 👑
break; — discontinue execution of the nearest enclosing for/do/while/switch/twixt statement. and heads up: the leave expression will be executed as the twixt statement is exited.
continue; — branches directly to the conditional test of the nearest enclosing for/do/while statement.
return E; — return value E from the nearest enclosing function.

🧚 Namespaces 🧚

like Java and C++, Nickle has a notion of a namespace: a collection of names with partially restricted visibility. in Nickle, namespaces get created with the namespace command. let's talk about it.

opt-P namespace N { S ... } — places all names defined in the statements S into a namespace named N. the optional qualifier P may be the keyword public, but beware bestie: this merely indicates that the name N itself is visible elsewhere in the current scope, and has nothing to do with the visibility of the items inside the namespace. don't let the name fool you 💀
extend namespace N { S ... } — reopens the given namespace N, and extends it with the names defined as public in the given statements S.

names defined inside the namespace are invisible outside the namespace unless they're qualified with the keyword public. public names may be referred to using path notation:

namespace::namespace::...::namespace::name

which refers to the given name as defined inside the given set of namespaces. the double-colon syntax is unfortunate, as it's slightly different in meaning than it is in C++ — but all the good symbols were taken, and it's believed to be a feature that the namespace separator is syntactically different from the structure operator. in Java, for example, the phrase

name.name.name

is syntactically ambiguous: that middle name could be either a structure or a namespace. not here. slay 🎀

import N; — the name N must refer to a namespace: all public names in this namespace are brought into the current scope (scoping out conflicting names). come on in, the water's fine 🌊

🛠️ BUILTINS 🔥

Nickle comes with a whole collection of standard functions built in. some of these are written in C, but many are written in Nickle itself. several collections of functions have associated builtin datatypes: their namespaces, together with their types, should be viewed as ADTs. yes queen, abstract data types ✨

🌟 Top-Level Builtins 🌟

int printf(string fmt, poly args...) — calls File::fprintf(stdout, fmt, args ...) and returns its result.
string function gets () — calls File::fgets(stdin) and returns its result.
string function scanf (string fmt, *poly args...) — calls File::vfscanf(stdin, fmt, args) and returns its result.
string function vscanf (string fmt, (*poly)[*] args) — calls File::vfscanf(stdin, fmt, args) and returns its result.
real imprecise(rational value) — see the discussion of type real above.
real imprecise(rational value, int prec) — see the discussion of type real above.
int string_to_integer(string s)
int atoi(string s) — the argument s is a signed digit string, and the result is the integer it represents. if the string s is syntactically a hexadecimal, octal, binary, or explicit base-10 constant, treat it as such.
int string_to_integer(string s, int base)
int atoi(string s, int base) — treat s as a string of digits in the given base. a base of 0 acts as with no base argument. otherwise, base specification syntax in the string is ignored.
int putchar(int c) — places the given character on the standard output using File::putc(c, stdout), and returns its result.
int sleep(int msecs) — tries to suspend the current thread for at least msecs milliseconds. returns 1 on early return, and 0 otherwise.
int exit(int status) — exits Nickle with the given status code. does not return anything. bye bestie 👋
int dim(poly[*] a) — given a one-dimensional array a, dim() returns the number of elements of a.
int[] dims(poly[] a) — given an arbitrary array a, dims() returns an array of integers giving the size of each dimension of a. so, dim(dims(a)) is the number of dimensions of a. it's giving recursion but make it cute 🦋
*poly reference(poly v) — given an arbitrary value v, "box" that value into storage and return a pointer to the box.
rational string_to_real(string s)
rational atof(string s) — converts the real constant string s into its associated real number.
number abs(real v) — returns the absolute value of v. the result type chosen will match the given context.
int floor(real v) — returns the largest integer less than or equal to v. this will fail if v is a real and the precision is too low.
int ceil(real v) — returns the smallest integer greater than or equal to v. this will fail if v is a real and the precision is too low.
int exponent(real v) — returns the exponent of the imprecise real v.
rational mantissa(real v) — returns the mantissa of the imprecise real v, as a rational m with 0 <= m <= 0.5 .
int numerator(rational v) — returns the numerator of the rational number v: i.e., if v = n/d in reduced form, return n.
int denominator(rational v) — returns the denominator of the rational number v: i.e., if v = n/d in reduced form, return d.
int precision(real v) — returns the number of bits of precision of the mantissa of the imprecise real number v.
int sign(real v) — returns -1 or 1 as v is negative or nonnegative.
int bit_width(int v) — returns the number of bits required to represent abs(v) internally.
int is_int(poly v) — type predicate.
int is_rational(poly v) — numeric type predicates are inclusive: e.g., is_rational(1) returns 1.
int is_number(poly v) — type predicate.
int is_string(poly v) — type predicate.
int is_file(poly v) — type predicate.
int is_thread(poly v) — type predicate.
int is_semaphore(poly v) — type predicate.
int is_continuation(poly v) — type predicate.
int is_array(poly v) — type predicate.
int is_ref(poly v) — type predicate: checks for pointer type. this is arguably a misfeature, and may change. ⚠️
int is_struct(poly v) — type predicate.
int is_func(poly v) — type predicate.
int is_void(poly v) — type predicate.
int gcd(int p, int q) — returns the GCD of p and q. the result is always positive. 💪
int xor(int a, int b) — returns a ^ b . this is mostly a holdover from before Nickle had an xor operator.
poly setjmp(continuation *c, poly retval) — the setjmp() and longjmp() primitives, together with the continuation type, form an ADT useful for nearly arbitrary transfers of flow-of-control. the setjmp() and longjmp() builtins are like those of C, except that the restriction that longjmp() always jump upwards is removed(!): a continuation saved via setjmp() never becomes invalid during the program lifetime. the setjmp() builtin saves the current location and context into its continuation pointer argument, and then returns its second argument.
void longjmp(continuation c, poly retval) — the longjmp() builtin never returns to the call site, but instead returns from the setjmp() that created the continuation, with return value equal to the second argument of longjmp().
string prompt — the prompt printed during interactive use when at top-level. default "> ". when waiting for the rest of a statement or expression, and when debugging, respectively. default values are "> ", "+ ", and "- ".
string prompt2 — the prompt printed during interactive use when waiting for the rest of a statement or expression. default "+ ".
string prompt3 — the prompt printed during interactive use when debugging. default "- ".
string format — the printf() format for printing top-level values. default "%g".
string version — the version number of the Nickle implementation you're literally running right now. 🦋
string build — when that Nickle build happened, formatted like "yyyy/mm/dd", or just "?" if the build date is somehow a mystery.
file stdin — bound to the standard input stream, bestie. 🫶
file stdout — bound to the standard output stream. 💅
file stderr — bound to the standard error stream. 😭

💖 Exceptions 💖

A few standard exceptions are predeclared and used internally by Nickle. So iconic of them.

exception uninitialized_value(string msg) — thrown when you try to use an uninitialized value. we've all been there. 🙈
exception invalid_argument(string msg, int arg, poly val) — the arg-th argument passed to a builtin function had an invalid value, val.
exception readonly_box(string msg, poly val) — attempt to change the value of a read-only quantity to val. no touching. 🚫
exception invalid_array_bounds(string msg, poly a, poly i) — attempt to access array a at index i and it's out of bounds.
exception divide_by_zero(string msg, real num, real den) — attempt to divide num by den where den == 0. math said no. 💀
exception invalid_struct_member(string msg, poly struct, string name) — attempt to refer to member name of the object struct, which does not exist.
exception invalid_binop_values(string msg, poly arg1, poly arg2) — attempt to evaluate a binary operator with args arg1 and arg2, where at least one of those values is invalid.
exception invalid_unop_values(string msg, poly arg) — attempt to evaluate a unary operator with an invalid argument arg.

🧚 Builtin Namespaces 🧚

Math

The math functions available in the Math namespace are implemented in a fashion intended to be compatible with the C library. Please consult the appropriate manuals for further details. (iykyk 📚)

real pi — imprecise constant giving the value of the circumference/diameter ratio of the circle, to the default precision of 256 bits.
protected real e — imprecise constant giving the value of the base of natural logarithms, to the default precision of 256 bits. Since e is protected, you must reference it via Math::e, so you don't run into problems using the fifth letter of the alphabet at top level. yes fr fr, that single letter is a menace. 😭
real function sqrt(real v) — returns the square root of v.
real function cbrt(real v) — returns the cube root of v.
real function exp(real v) — returns e**v. ✨
real function log(real a) — returns v such that e**v == a. Throws an invalid_argument exception if a is non-positive.
real function log10(real a) — returns v such that 10**v == a. Throws an invalid_argument exception if a is non-positive.
real function log2(real a) — returns v such that 2**v == a. Throws an invalid_argument exception if a is non-positive.
real function pi_value(int prec) — returns the ratio of the circumference of a circle to the diameter, with prec bits of precision.
real function sin(real a) — returns the ratio of the opposite side to the hypotenuse of angle a of a right triangle, given in radians.
real function cos(real a) — returns the ratio of the adjacent side to the hypotenuse of angle a of a right triangle, given in radians.
void function sin_cos(real a, *real sinp, *real cosp) — returns with sin(a) and cos(a) stored in the locations pointed to by sinp and cosp respectively. If either pointer is 0, don't store into that location. May be slightly faster than calling both trig functions independently. two-for-one, we love efficiency. 🎀
real function tan(real a) — returns the ratio of the opposite side to the adjacent side of angle a of a right triangle, given in radians. Note that tan(pi/2) is not currently an error: it will return a very large number dependent on the precision of its input. ⚠️
real function asin(real v) — returns a such that sin(a) == v.
real function acos(real v) — returns a such that cos(a) == v.
real function atan(real v) — returns a such that tan(a) == v.
real function atan2(real x, y) — returns a such that tan(a) == x / y. Deals correctly with y == 0. slay. 👑
real function pow(real a, real b) — the implementation of the ** operator.

File

The namespace File provides operations on file values. 🍓

int function fprintf(file f, string s, ....) — print formatted values to a file, as with the UNIX stdio library fprintf(). fprintf() and printf() accept a reasonable sub-set of the stdio library version: %c, %d, %e, %x, %o, %f, %s, %g work as expected, as does %v to smart-print a value. Format modifiers may be placed between the percent-sign and the format letter to modify formatting. There are a lot of known bugs with input and output formatting. 💀

Format Letters:

%c — requires a small integer argument (0..255), and formats as an ASCII character.
%d — requires an integer argument, and formats as an integer.
%x — requires an integer argument, and formats as a base-16 (hexadecimal) integer.
%o — requires an integer argument, and formats as a base-8 (octal) integer.
%e — requires a number argument, and formats in scientific notation.
%f — requires a number argument, and formats in fixed-point notation.
%s — requires a string argument, and emits the string literally.
%g — requires a number, and tries to pick a precise and readable representation to format it.

Format Modifiers:

digits — all format characters will take an integer format modifier indicating the number of blanks in the format field for the data to be formatted. The value will be printed right-justified in this space.
digits.digits — the real formats will take a pair of integer format modifiers indicating the field width and precision (number of chars after decimal point) of the formatted value. Either integer may be omitted.
- — a precision value indicating infinite precision.
* — the next argument to fprintf() is an integer indicating the field width or precision of the formatted value.

file function string_write() — return a file which collects written values into a string.
int function close(file f) — close file f and return an indication of success.
int function flush(file f) — flush the buffers of file f and return an indication of success.
int function getc(file f) — get the next character from file f and return it.
int function end(file f) — returns true if file f is at EOF, else false.
int function error(file f) — returns true if an error is pending on file f, else false.
int function clear_error(file f) — clears pending errors on file f, and returns an indication of success.
file function string_read(string s) — returns a virtual file whose contents are the string s.
string function string_string(file f) — return the string previously written into the file f, which should have been created by string_read() or string_write(). Behavior on other files is currently undefined. ⚠️
file function open(string path, string mode) — open the file at the given path with the given mode string, ala UNIX stdio fopen(). Permissible modes are as in stdio: "r", "w", "x", "r+", "w+" and "x+".
integer function fputc(integer c, file f) — output the character c to the output file f, and return an indication of success.
integer function ungetc(integer c, file f) — push the character c back onto the input file f, and return an indication of success.
integer function setbuf(file f, integer n) — set the size of the buffer associated with file f to n, and return n.
string function fgets (file f) — get a line of input from file f, and return the resulting string.
file function pipe(string path, string[*] argv, string mode) — start up the program at the given path, returning a file which is one end of a "pipe" to the given process. The mode argument can be "r" to read from the pipe or "w" to write to the pipe. The argv argument is an array of strings giving the arguments to be passed to the program, with argv[0] conventionally being the program name.
int function print (file f, poly v, string fmt, int base, int width, int prec, string fill) — print value v to file f in format fmt with the given base, width, prec, and fill. Used internally by File::fprintf().
int function fscanf(file f, string fmt, *poly args...) — fill the locations pointed to by the array args with values taken from file f according to string fmt. The format specifiers are much as in UNIX stdio scanf(): the "%d", "%e", "%f", "%c" and "%s" specifiers are supported with the expected modifiers.
int function vfscanf (file f, string fmt, (*poly)[*] args) — given the file f, the format fmt, and the array of arguments args, fscanf() appropriately.

Thread

The namespace Thread supports various operations useful for programming with threads, which provide concurrent flow of control in the shared address space. There is one piece of special syntax associated with threads. 🌈

fork(E) — accepts an arbitrary expression, and evaluates it in a new child thread. The parent thread receives the thread as the value of the fork expression.

The remainder of the Thread functions are fairly standard.

int function kill(thread list...) — kills every running thread in the array list. With no arguments, kills the currently running thread. Returns the number of threads killed. 💀
int function trace(poly list...) — shows the state of every running thread in the array list. With no arguments, traces the default continuation. Returns the number of threads traced.
int function cont() — continues execution of any interrupted threads, and returns the number of continued threads.
thread function current() — return the current thread.
int function list() — reports the currently running thread to stdout.
int function get_priority(thread t) — tells you the priority of thread t. gossip about the thread, basically. 💅
int function id_to_thread(int id) — hands you back the thread that matches id if it exists, and 0 if it doesn't. no thread, no vibe.
poly function join(thread t) — sits there waiting for thread t to finish, then gives you back whatever it returned. patient bestie energy 🫶
int function set_priority(thread t, int i) — tries to set thread t's priority to level i, and returns the new priority. higher priority = more runtime, periodt: a task with a higher priority will always run instead of a lower priority task. threads tied at the highest priority get pre-emptively multitasked. it's giving main character gets the CPU 👑

✨ Semaphore ✨

The Semaphore namespace wraps up all the operations on the semaphore built-in ADT. semaphores are for thread synchronization, bestie. every signal() on the semaphore wakes up the least-recent thread that called wait() on it. the ``count'' of waiting processes can be set when you make the semaphore.

semaphore function new(int c) — makes a fresh semaphore with an initial count c of waiting processes. if c is positive, that means c threads can wait on it before one blocks. if c is negative, it sets a count of threads that must be waiting on the semaphore before further waits won't block. negative count is the weird girl of this API, fr.
semaphore function new() — just calls semaphore(0) and returns the result.
int signal(semaphore s) — increments semaphore s. if s is non-positive and some thread is blocked on s, it releases the least-recently-blocked thread. returns 1 on success. slay.
int wait(semaphore s) — decrements semaphore s. if s is negative, it blocks until released. returns 1 on success. the waiting is the hardest part 😭
int test(semaphore s) — checks whether wait() on semaphore s would make the current thread block. if it would, returns 0. otherwise it attempts to decrement s, and returns 1 if that worked.

🌸 String 🌸

The String namespace has a few basic operations on the string ADT. lowkey essential.

int function length(string s) — returns how many characters are in s.
string function new(int c) — returns the single character c as a string.
string function new(int cv[*]) — returns a string made out of the characters in cv.
int function index(string t, string p) — returns the integer index of pattern string p inside target string t, or -1 if p isn't a substring of t. finding your people in the crowd 🦋
string function substr(string s, int i, int l) — returns the substring of s that starts at offset i (zero-based) and runs for l characters total. if l is negative, the substring is made of the characters preceding i instead of the ones succeeding it. yes, backwards. iconic behaviour, honestly.

🎲 PRNG 🎲

The PRNG namespace does pseudo-random number generation and manipulation. the core generator is the RC4 stream cipher generator, properly bootstrapped. this gives you a stream of cryptographically-secure pseudo-random bits at a reasonable amortized cost. (but beware — initialization is somewhat expensive. it's giving luxury ✨)

void function srandom(int s) — initializes the generator using the (arbitrarily-large) integer s as a seed.
void function dev_srandom(int nbits) — initializes the generator using nbits bits of entropy grabbed from some reasonable entropy source. on UNIX systems, that source is /dev/urandom. asking for more initial entropy than the system actually has may lead either to bootstrapping (as on UNIX) or to hanging, so use cautiously. ⚠️ do not yolo this one.
int function randbits(int n) — returns an n-bit pseudo-random number, in the range 0..(2**n)-1. useful for stuff like RSA. math girlies rise 💜
int function randint(int n) — returns a pseudo-random number in the range 0..n-1.
void function shuffle(*(poly[*]) a) — does an efficient in-place true shuffle (c.f. Knuth) of the array a. no cap, an actual shuffle.

🎀 Command 🎀

The Command namespace is what the top-level commands use, as described below. it's also occasionally useful all on its own.

string library_path — holds the current library search path: a colon-separated list of directories that get searched for library files.
int function undefine(string name) — this is the top-level undefine command. removes the name denoted by string name from the namespace. this removes all visible definitions of that name.
int function undefine(string[*] names) — removes each of the names in the array names from the namespace. this removes all visible definitions of each one.
int function delete(string name) — tries to remove the command with the given string name from the top-level command list, and returns 1 if it worked.
int function lex_file(string path) — tries to make the file at path the current source of Nickle code, and returns 1 if it worked. note that this effectively ``includes'' the file by pushing it onto a stack of files to be processed.
int function lex_library(string filename) — same as lex_file(), except it searches the directories listed in the library_path variable for the first file with the given filename.
int function lex_string(string code) — tries to make the Nickle code contained in the string code the next input.
int function edit(string[*] names) — this is the top-level edit command. the names in the array are a path of namespace names leading down to the symbol name, which comes last.
int function new(string name, poly func) — binds function func to the top-level command string name, i.e. it makes it part of the top-level command vocabulary.
int function new_names(string name, poly func) — binds function func to the top-level command string name, i.e. makes it part of the top-level command vocabulary. unlike new(), the string names handed to func at the top level are passed unevaluated, either as an array of string names or as a single string name.
int function pretty_print(file f, string[*] names) — this is the top-level print command. each passed name string gets looked up and the corresponding code gets printed to file f.
int function display(string fmt, poly val) — uses printf() to display the value val in format fmt.

🕰️ History 🕰️

Nickle keeps a top-level value history, which is super useful alongside command-line editing when you're calculating. the History namespace has the functions that reach into it.

int function show(string fmt) — the history top-level command with no arguments. shows the most recent history values with format fmt.
int function show(string fmt, int count) — the history top-level command with one argument. shows the last count history values with format fmt.
int function show(string fmt, int first, int last) — the history top-level command with two arguments.
poly function insert(poly val) — inserts val into the history list and returns it.

🌈 Environ 🌈

A lot of operating systems have some notion of ``environment variables.'' the Environ namespace has the functions to mess with them.

int function check(string name) — returns 1 if a variable with the given name is in the environment, and 0 otherwise.
string function get(string name) — tries to fetch and return the value of the environment variable with the given name. throws an invalid_argument exception if that variable isn't available. rude, honestly 😤
int function unset(string name) — tries to unset the environment variable with the given name, and returns an indication of success.
string function set(string name, string value) — tries to set the environment variable with the given name to the given value, and returns an indication of success.

💻 COMMANDS 💻

Nickle has a whole set of commands you can drop at the top level. here's the menu, bestie:

quit — exit Nickle. bye girl 💖
quit E — exit Nickle with integer status code E.
undefine NAME {,NAME} — remove these names from the system.
load E — load a file given by the string name E.
library E — load a library given by the string name E. see the discussion of the NICKLEPATH environment variable in ENVIRONMENT below, and the discussion of Command::library_path above.
E # E — print expr1 in base expr2 .
print NAME — display a formatted version of the object denoted by NAME. comments and original formatting are lost. if NAME is a variable, the type gets printed too, along with the value. sacrifice the formatting for the glow-up ✨
edit NAME — invoke $EDITOR on the named object, and re-incorporate the results of the edit. this is most useful with functions.
history — display the 10 most recently printed values. you can grab them with $n, where n is the number shown to the right of the value in this list.
history E — display the E most recent history values.
history E,E — display history values from the first integer E through the second.

🐛 DEBUGGER 🐛

When an unhandled exception reaches top level during execution, you get a dash prompt, which means debug mode is active. in this mode, the command-line environment is the one where the unhandled exception got raised. plus you get a bunch of debugging commands:

trace — get a stack backtrace showing the current state, like the GDB where command.
up — move up the stack (i.e., toward the top-level expression) ala GDB.
down — move down the stack (i.e., toward the current context) ala GDB.
done — leave debugging mode, abandoning execution. it's over 💀

In addition, the Debug namespace is scoped in in debugging mode. this is primarily of use in debugging Nickle itself.

collect() — run the garbage collector. take out the trash, bestie 🗑️✨
dump(function) — print the compiled byte code for function.

🌿 ENVIRONMENT 🌿

bestie, these are the little environment variables nickle sniffs around for when it wakes up. set them, don't set them, it's your world 💖

EDITOR — the editor that the edit command reaches for, and yes that's the same edit we already talked about back in COMMANDS ✨
NICKLERC — where your .nicklerc file lives. nickle will load it at the very beginning of execution, if it can 🫶
HOME — if NICKLERC isn't set, nickle uses this to go find your .nicklerc 🏠
NICKLEPATH — a colon-separated path, and every element in it is a directory full of Nickle code. the library command and the -l flag (both described above, iykyk) search this path for a filename that matches the one you gave. if this variable isn't set at all, the default library path is /usr/share/nickle 📚
NICKLESTART — the filename of the file that gets loaded as a bootstrap when nickle starts up. if this variable isn't set, the default is to load /usr/share/nickle/builtin.5c 🚀

✨ EXAMPLES ✨

ok so here's a whole lil demo, taken from the bc manual:

real function exponent(real x) {
    real a = 1;
    int b = 1;
    real s = 1;
    int i = 1;
    while (1) {
        a = a * x;
        b = b * i;
        real c = a / b;
        if (abs(c) < 1e-6)
            return s;
        s = s + c;
        i++;
    }
}

that right there defines a function that computes an approximate value of the exponential function e ** x. and then:

for (i = 1; i < 10; i++)
    printf ("%g\n", exponent (i));

which prints approximate values of the exponential function for the first ten integers. chef's kiss, honestly 💅

📌 VERSION 📌

this document describes version 1.99.2 of nickle, plus some newer features that snuck in. it was distributed with version "2.108" of nickle. yes, both numbers, they're different things, don't @ me 😭

💀 BUGS 💀

buckle up bestie, this is the part where we're honest:

go read the discussion of the type of the exponentiation operator ** above. that's the first thing 👀
due to a difficult-to-remove grammar ambiguity, you cannot use a bare assignment expression inside an array initializer — it gets confused with a structure initializer. like, watch:

> int x = 0;
> (int[*]){x = 1}
->     (int[*]) { x = 1 }
Non array initializer

the workaround is to parenthesize the assignment expression:

> (int[*]){(x = 1)}
[1]{1}

and because this bug is so rare, so hard to fix, and so easy to work around, it is unlikely to be fixed anytime soon. so, coping mechanisms only 🙈

there are a lot of known bugs with input and output formatting. the obvious stuff works. the other stuff does not. that's it, that's the bug report 💀
the semantics of division are unfortunately different from those of C. this is arguably because C is broken in this area — and no, we cannot currently see any obvious fix. C allows automatic implicit coercion of floating to integral types, but this implementation considers that a misfeature 🚫
and, uh, the implementation has not been thoroughly tested. no cap. ⚠️

👑 AUTHOR 👑

Nickle is the work of Keith Packard <keithp@keithp.com> and Bart Massey <bart_massey@iname.com>. legends, honestly 🌟

and now the legal bit, because we respect the paperwork 💜 — permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the names of the authors or their institutions shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the authors.

and that's a wrap on the whole page!! 🎀 this one's the NICKLE(1) man page, dated 2026-03-14, and you made it all the way to the end — obsessed with you fr fr 🦋✨ go write something cute in nickle, bestie, you've got this 💖

📦 where this page comes from

alpine 3.24: nickle-doc 2.108-r0 · MIT
arch rolling: nickle 2.108-1 · custom
epel 10: nickle 2.108-1.el10_3 · MIT
fedora 43: nickle 2.108-1.fc43 · MIT
fedora 43: nickle 2.108-1.fc43 · MIT
fedora 44: nickle 2.108-1.fc44 · MIT
fedora 44: nickle 2.108-1.fc44 · MIT
ubuntu stonking: nickle 2.108 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms