Introduction

ucode is a small scripting language with ECMAScript syntax, written in C, that runs on Linux systems — particularly on routers. It is an interpreter you can put in 30 KB, a library you can link into a daemon, and a template engine, and it speaks JSON natively. It is not a browser's JavaScript, and it is not an attempt to become one.

What ucode is

A ucode program is a sequence of statements in a syntax a JavaScript reader can follow without a translation layer: let, const, function, arrow functions, objects with identifier keys, template literals, for/while/switch, truthiness and coercion rules that mostly match. Under that syntax is a different, smaller thing: byte strings rather than character strings, no classes, no throw statement, no coroutines, and no asynchronous anything. Errors are exceptions and are catchable, but there is nothing to await, and a program cannot raise one itself except with die(). Values are JSON-shaped — null, boolean, integer, double, string, array, object — plus three kinds that JSON has no word for: regular expressions, functions, and resources (file handles, sockets, connections).

The language comes with a standard library in loadable modules rather than a monolithic runtime: file system, I/O, math, time, JSON, regular expressions, struct packing, digests, zlib, sockets, serial ports, a POSIX-regex engine, DNS resolution, netlink routing and wireless, the OpenWrt ubus message bus and uci configuration API, an event loop, and a C FFI. Which modules exist is a build-time choice (chapter 2); which you use is a require() away (chapter 17).

Three things characterise it in use:

• It is synchronous. There is one flow of control, and concurrency, when needed, comes from the event loop module (uloop, chapter 36) rather than from the language.
• It is data-first. sprintf("%J", value) renders any value as JSON and json(text) parses it back, so a script that talks to ubus, rpcd, uhttpd or a config file is not writing a serialiser.
• It is a system tool. Modules reach the operating system: routes, interfaces, wifi, DNS, serial consoles, processes, signals, and the raw netlink and ioctl level below them.

Why it exists

The development of ucode was motivated by the need to rewrite OpenWrt's firewall framework around nftables: firewall4 needed to turn a declarative UCI configuration into nftables rules, which is a job for a language with real data structures and templates, not for shell scripts parsing text. ucode began as a template processor for exactly that and grew into the general system scripting language the modules above describe. Its design goals, in the order the source states them, are easy integration with C applications, efficient handling of JSON data and complex data structures, support for the ubus message bus, and a broad set of built-in functions in the spirit of Perl 5 — plus a small executable size.

That history explains most of the shapes that look unusual coming from JavaScript. Templates are a first-class mode of the interpreter itself — a separate Jinja-style template processing with its own command (utpl) and its own markup, distinct from the backtick template literals of the language itself (chapter 16). The builtins are Perl's vocabulary — substr, index, rindex, splice, shift, unshift, split, join, trim, hex, ord, chr — as functions, because on a device with 8 MB of flash, methods on values cost dictionary lookups the language can avoid by simply not having them. Synchronous flow, byte strings, and a value model that maps one-to-one onto JSON are the same trade: less machinery, predictable cost.

How it differs from its neighbours

From JavaScript. Same surface syntax, deliberately smaller semantics. Values are not objects: "abc".length and arr.push(x) are errors, not silent undefineds (chapter 9, chapter 22). There are no classes, no throw statement, no async/await/promises, no generators, no destructuring, no default parameters, and no typeof operator — type(v) is a function that returns a string. try/catch does exist and catches real exception objects; there is no finally clause (chapter 14). == on arrays and objects compares identity, as in JavaScript, so a copy of a structure is not equal to its original, and the integer type is 64-bit signed with / on two integers truncating toward zero (chapter 6). Chapter 19 lists the differences in one place; they are worth reading before writing anything longer than a line.

From Lua. ucode replaces Lua in the same niche that Lua occupied in OpenWrt, and the differences run the other way: the syntax is C-like rather than Algol-like, keys()/values() replace pairs(), length() replaces #, + concatenates strings, != is inequality, and metamethods live in a value's prototype rather than in a side table passed to setmetatable (chapter 12). There are no coroutines. printf is available under its C name rather than as string.format.

From shell. Everything that makes shell painful for configuration logic — text as the only data type, word splitting, quoting, subshells as function calls — is absent. system() runs a command and returns its exit status, not its output; to capture output you fs.popen() and read from the handle. The argument-array forms of system() and fs.popen() bypass /bin/sh entirely, which is what you want whenever any part of the command comes from outside the script. In return you inherit a language where a typo in a name is a runtime error rather than a silently empty string, and where a missing quoting decision fails loudly.

The implementation

One repository builds four things:

libucode.so        the interpreter: lexer, compiler, VM, value layer, core library
ucode              the command line interpreter
udbg               the debugger client
lib/ucode/*.so     the optional modules (fs, socket, ubus, ...)

The core is about 25,000 lines of C — lib.c (the builtin functions) 6,300, compiler.c 4,300, vm.c 3,800, types.c 3,100, lexer.c 1,400, the rest split between source handling, bytecode images and the command line. The modules add roughly 44,000 more, the largest being the netlink, socket, struct and event-loop bindings. A size-optimised build of libucode.so is around 170 KB of text and the ucode binary 16 KB — the interpreter is a shared library precisely so that several host programs can carry one copy of it.

The only hard external dependency is json-c, used for parsing and serialising JSON. Everything else is optional and is probed for a library at configure time: zlib, libmd (digests), libffi, libubox, libubus + libblobmsg-json, libuci, libnl-tiny. Regular expressions are compiled by the host C library through regcomp(), so their exact feature set is the host's POSIX ERE, not ucode's (chapter 13).

Execution runs lex → single-pass compile → bytecode → VM, with the bytecode image optionally written to a file by the compiler (ucc, chapter 3) so a device can load programs without compiling them. Values are reference-counted, with a periodic mark-and-sweep pass over unreclaimed objects to catch cycles; the pass runs on an allocation interval and can be triggered from a script with gc(). There are no threads in the language; concurrency is the event loop's business, and the C API's.

Embedding is a central design goal rather than an afterthought: rpcd and uhttpd both embed ucode, and the examples/ directory of the source tree holds small C programs that execute a file, execute a string, add a native function, and install an exception handler. Part IV of this book describes that API.

Where things come from

ucode is written by Jo-Philipp Wich and released under the ISC license, a two-clause permissive licence; the whole tree, including the modules, carries it. Development happens in the ucode-lang/ucode repository, with releases tagged by date (v0.0.20250529 and so on) and packaged into Debian (ucode, ucode-modules, libucode, libucode-dev) and into OpenWrt (ucode, libucode, and one ucode-mod-* package per module). The generated reference documentation lives at ucode.mein.io, derived from the same source comments this book cites.

The notable users define what the language is for: firewall4, the OpenWrt firewall and the origin of the language; LuCI, the OpenWrt web interface, whose luci-lib-ucode bindings and templates run on ucode; rpcd and uhttpd, which embed the interpreter; and the hostapd/wpa_supplicant ubus glue and wifi-scripts that implement modern OpenWrt wireless configuration. Part V of this book examines what each of them does with it.

A taste

The following script reads a UCI configuration and prints the interfaces that are up, which is the shape of most real ucode programs:

let rv = { ok: true, ifaces: [
	{ name: "lo", up: true, mtu: 65536 },
	{ name: "lan", up: true, mtu: 1500 },
	{ name: "wan", up: false, mtu: 1500 }
] };

let up = filter(rv.ifaces, (i) => i.up);

printf("%d up: %s\n", length(up), join(", ", map(up, (i) => `${i.name}/${i.mtu}`)));
printf("%J\n", map(up, (i) => i.name));

2 up: lo/65536, lan/1500
[ "lo", "lan" ]

No imports were needed: arrays, objects, filter, map, join, sprintf, and template literals are all part of the core (chapter 20). Reading that structure from a real configuration file, from a ubus call, or from a JSON string takes three different one-liners, and each of them has its own chapter.

Conventions used in this book

Code examples appear in ucode blocks, showing the script as a ucode program, with the interpreter's output for the same example in the text block that follows it. Where an example is meant to be run at a shell prompt, a console block shows a shell session, with $ denoting the prompt. Where a behaviour is version-specific — a POSIX regex feature, a libc printf quirk — the chapter says so explicitly rather than relying on the examples.

Summary

Installing ucode

What you need

ucode is written in C99 with GNU extensions, is built with CMake 3.13 or later, and relies on json-c, which is the one hard dependency: it is probed with pkg_check_modules(JSONC REQUIRED json-c) and the build stops without it. Everything else is optional and is enabled by finding the library at configure time.

ucode has been tested with glibc and musl libc on Linux, and on OS X. _GNU_SOURCE is always defined, and a libc beyond those is on its own. libdl is linked if dlopen is not already in libc and libm if fmod is not; the math module additionally links libm if ceil is missing from libc. Because regular expressions are compiled by the host C library, the regexp feature set is whatever the target's regcomp() implements (chapter 13) — a musl target and a glibc host will not agree on every construct.

Building

$ git clone https://github.com/ucode-lang/ucode && cd ucode
$ cmake -B build
$ cmake --build build -j4
$ sudo cmake --install build          # or: sudo make -C build install

CMake prints what it found and what it therefore will build. A configure run on a machine with only json-c produces the core, the CLI, the debugger and the modules that need nothing else:

$ cmake -B build
-- Found JSONC: ...
-- Configuring done
$ ls build/*.so
build/debug.so   build/io.so     build/resolv.so  build/socket.so
build/fs.so      build/log.so    build/math.so    build/struct.so
build/serial.so

That listing is the answer to "why is require('uci') failing on my build host" more often than any other explanation: the module was never built because its library was absent. The modules global and the failure message of require (chapter 17) tell you the same thing at run time.

Running from the build tree

The built build/ucode does not know about build/*.so unless the search path says so — pass -L:

$ build/ucode -L build -e 'const fs = require("fs"); printf("%J\n", fs.access("/etc"))'
true

Without -L build, require("fs") searches the compiled-in default path — which on a development checkout points at an installation prefix that holds nothing. For scripts, the same -L works, and so does setting REQUIRE_SEARCH_PATH inside the program (chapter 20).

The feature toggles

Each module is a CMake option. Those with a fixed ON default always build; the others default to ON only if their library was found, which is why the same source tree configures differently on a laptop, a build container and a router SDK.

Three more options change the shape of the binaries rather than the set of modules:

To build a specific set, name the toggles on the configure line. This is the invocation that produces a bare router-side interpreter with no compiler and nothing but the three OpenWrt-facing modules:

$ cmake -B build \
    -DCOMPILE_SUPPORT=OFF \
    -DFFI_SUPPORT=OFF -DDIGEST_SUPPORT=OFF -DZLIB_SUPPORT=OFF \
    -DRTNL_SUPPORT=OFF -DNL80211_SUPPORT=OFF -DSERIAL_SUPPORT=OFF \
    -DUBUS_SUPPORT=ON -DUCI_SUPPORT=ON -DULOOP_SUPPORT=ON

What the toggles buy in bytes is worth knowing when the target is a small embedded device. On a size-optimised x86-64 build of the same revision, the modules range from 21 KB for log.so to about 105 KB for nl80211.so, ffi.so and rtnl.so, with the core library at 208 KB installed and the interpreter itself at 32 KB:

The debug module and udbg are the pieces to drop first on a device that only runs precompiled scripts; ffi is the one to drop before anything that talks to the kernel, since it drags in a C declaration parser.

What gets installed

${bindir}/ucode            the interpreter
${bindir}/udbg             the debugger client (chapter 42)
${bindir}/ucc              symlink to ucode, compile mode (chapter 3)
${bindir}/utpl             symlink to ucode, template mode (chapter 16)
${libdir}/libucode.so.0    the VM, with a libucode.so symlink for developers
${libdir}/ucode/*.so       the enabled modules
${prefix}/include/ucode/*.h   the embedding API (part IV)

The two extra command names are plain symlinks created at build time — the interpreter reduces argv[0] to its basename and behaves accordingly, so a distribution that installs only ucode can still offer the other two modes with -c and -T.

The default module search path is a build-time string:

<prefix>/<libdir>/ucode/*.so : <prefix>/share/ucode/*.uc : ./*.so : ./*.uc

-L dir prepends dir/*.so and dir/*.uc to it (a -L argument containing * is taken verbatim), and -L may be repeated. Since the path is compiled in, moving an installation means rebuilding it or carrying REQUIRE_SEARCH_PATH in the environment of every program — the packaging in both distributions keeps the default consistent by installing to the standard prefix.

Testing the build

Tests are enabled by a CMake definition rather than an option, and run through CTest:

$ cmake -B build -DUNIT_TESTING=ON
$ cmake --build build -j4
$ ctest --test-dir build --output-on-failure

The suite is written in ucode itself — tests/custom/ holds directories named 00_syntax, 01_arithmetic, 02_runtime, 03_stdlib, 04_modules, 06_metamethods, 99_bugs, 99_debugger and more, driven by tests/custom/run_tests.uc — with a handful of cram tests for the command line and a tests/fuzz corpus. When the compiler is Clang, UNIT_TESTING also builds a ucode-san binary with address, leak and undefined behaviour sanitisers, which is the binary to run the suite against after changing the value layer or the VM (part IV's chapter on the C API notes where those hooks are).

Debian

The source tree carries Debian packaging that produces four binary packages:

The build dependencies are debhelper-compat (= 13), cmake, pkgconf, libjson-c-dev, libmd-dev and zlib1g-dev, so a Debian build always has the digest and zlib modules; the OpenWrt-specific ones (uci, ubus, uloop, rtnl, nl80211) appear only if the additional libraries are installed, and libnl-tiny in particular is not in the Debian archive in the form the build expects.

$ dpkg -l 'ucode*' 'libucode*'
ii  libucode      ...  Tiny scripting and templating language (library)
ii  ucode         ...  Tiny scripting and templating language
ii  ucode-modules ...  Tiny scripting and templating language (modules)
$ ucode -e 'const fs = require("fs"); printf("%d modules\n", length(fs.glob("/usr/lib/ucode/*.so")))'
9 modules

OpenWrt

On OpenWrt, ucode is preinstalled on modern releases — the base system needs it for the network and firewall scripts. The packaging in openwrt/ucode/Makefile splits it the same way: a libucode package depending on libjson-c, a ucode package depending on libucode, and one ucode-mod-* package per module, each with its own library dependency:

The menu entry is Languages → ucode, and the modules are individually selectable in make menuconfig, which is the intended way to pay for only what a device uses. On a device image, the relevant check is not which ucode but whether the modules a script requires are present:

# ucode -e 'const fs = require("fs"); printf("%J\n", sort(fs.glob("/usr/lib/ucode/*.so")))'
[ "/usr/lib/ucode/fs.so", "/usr/lib/ucode/math.so", "/usr/lib/ucode/uci.so" ]

Cross-compiling

For an OpenWrt target the package builds inside the SDK or the source tree with the toolchain file that OpenWrt generates; the CMake probes then find the target's libubus, libuci and libnl-tiny in the staging directory rather than on the host, which is what turns the corresponding modules on. Outside OpenWrt, a CMake toolchain file works as it would for any project, with two cautions specific to ucode: the rtnl and nl80211 modules are guarded on LINUX, so a non-Linux target silently loses them, and the Apple build path links modules with -undefined dynamic_lookup and installs to the Homebrew prefix when one is detected, which is rarely what a cross build wants — pass -DCMAKE_INSTALL_PREFIX explicitly.

A common embedded configuration is: no COMPILE_SUPPORT (so no ucc and no run-time compilation), no ffi, no debug, and the modules the device's scripts actually require — although the OpenWrt package instead ships the standard feature set, with all modules available as ucode-mod-* packages. With BUILD_OPTIMIZE_SIZE and LINK_GC_SECTIONS at their defaults, that configuration is a few hundred kilobytes of library plus the modules chosen.

Checking an installation

Four commands, in order, tell you whether the interpreter you just built is the one your scripts will see:

$ which ucode ucc utpl udbg
$ ucode -p '2 ** 8'
256
$ ucode -e 'printf("%J\n", REQUIRE_SEARCH_PATH)'
[ "/usr/lib/ucode/*.so", "/usr/share/ucode/*.uc", "./*.so", "./*.uc" ]
$ ucode -e 'const m = require("fs"); printf("%J\n", type(m))'
"object"

A failed require raises a Runtime error naming the module — No module named 'fs' could be found — and the message is the same whether the file is absent from the search path or was never built. The cmake -B build output, or fs.glob("/usr/lib/ucode/*.so") at run time, is what tells the two apart.

Summary

A first program

Getting started

This chapter gets a program on screen and off again. It is deliberately narrow: the interpreter's command line, the two output functions, how statements end, how a program reports its status, and the ways a program can be handed to the interpreter. Everything the language itself offers is a chapter away.

Printing

print(...) writes its arguments to standard output, one after another, with no separators and no trailing newline — a program that wants lines has to write them itself:

print("Hello, World!\n");
print("a"); print("b"); print("\n");
print("x", 1, "\n");

Hello, World!
ab
x1

Values are rendered by the rules of chapter 4 — an array or object in its JSON form, a function as its source text — with one exception worth knowing early: a null (or undefined) argument contributes nothing at all, it is not even written as null:

let missing = null;

print("before", missing, "after", "\n");
printf("printf %%s: [%s]\n", missing);
printf("printf %%J: [%J]\n", missing);

beforeafter
printf %s: [(null)]
printf %J: [null]

The same value through printf with %s becomes (null), and through %J becomes null; only print and printf's implicit rendering omit it.

printf(fmt, ...) is the C function, and like the C function it adds nothing of its own — the format string carries the newline. The %J conversion renders a ucode value in its JSON form and is the most useful single thing in the language for inspecting data:

printf("%s: %d\n", "count", 3);
printf("routes: %J\n", ["default", "lan", "wan"]);
printf("%J %J %J\n", { port: 67, on: true }, null, 1.5);

count: 3
routes: [ "default", "lan", "wan" ]
{ "port": 67, "on": true } null 1.5

sprintf() is the same function returning a string instead of writing it, and warn(...) writes to standard error without a newline, which makes it the place diagnostics go:

let line = sprintf("%J\n", { ok: 1 });

printf("formatted %d bytes\n", length(line));
warn("this goes to stderr\n");

formatted 12 bytes

The whole formatting family — widths, padding, the integer conversions, the %.J pretty-printing variant — is chapter 21.

Statements and blocks

A statement is terminated by a semicolon, and the semicolon is required between two statements:

let a = 1; let b = 2; printf("%d\n", a + b);

3

Writing the last statement of a block, or of the whole program, without its semicolon is allowed, which is why the single-statement examples in this book look unterminated:

let sum = 0;
for (let i = 1; i <= 4; i++) {
	sum += i
}
printf("%d\n", sum)

10

Blocks are written in braces, and a block is a scope of its own: let, const and function declarations inside it are not visible outside (chapter 5). There are no labels in ucode, so outer: { ... } is a syntax error, and a bare { at the start of a statement always opens a block — an object literal has to be made part of an expression instead, by wrapping it in parentheses, assigning it, or passing it to a function:

({ a: 1 });
let o = { b: 2 };
printf("%J %J\n", { c: 3 }, o)

{ "c": 3 } { "b": 2 }

Comments are // to the end of the line and /* … */ across lines. Block comments do not nest, so commenting out a region that already contains a /* … */ ends the comment at the first */ and leaves the rest of the region as code:

// a line comment
printf("after comments\n"); /* and a trailing
                                block comment */

after comments

There is no comment-out-a-region convention beyond deleting the text or wrapping it in if (false).

Command line

The interpreter is one binary with several personalities:

ucode [options] [script.uc [args...]]
ucode -e "expression" [args...]
ucc [options] -o out.uc script.uc
utpl [options] template.uc

Run a script file, with the arguments after the script name reaching the program as ARGV. The script's own path is in SCRIPT_NAME:

printf("script=%J argv=%J\n", SCRIPT_NAME, ARGV);

Run an expression straight off the command line — the form this book uses for short examples:

$ ucode -e 'printf("%J\n", 2 ** 10)'
1024

-p is -e with the value of the expression printed afterwards, which makes it a calculator. It adds no newline either:

$ ucode -p '2 ** 10'
1024$

Read the program from standard input by naming the script -, which is what lets a pipeline carry a program and still pass arguments to it:

$ echo 'printf("%J\n", ARGV)' | ucode - one two
[ "one", "two" ]

A file is opened once, and only the first file name is taken as the program; every later argument is script data, not another source file to run, despite what ucode -h suggests. To run several files as one program, require them (chapter 17) or concatenate them.

Other options worth knowing at this stage:

The full list is in ucode -h, and chapter 20 covers the environment these options feed.

Exit status

A program ends by running out of statements, by exit(code), or by die(message):

printf("about to exit\n");
exit(3);
printf("never printed\n");

about to exit

The status is what the shell sees:

$ ucode -e 'exit(3)'; echo $?
3
$ ucode -e 'print("done\n")'; echo $?
done
0

An uncaught runtime error — a call to something that is not a function, an out-of-range array access, a failed require — ends the program with status 254 and a report on standard error, and a syntax error with status 255. die(message) is the deliberate version of the same thing: the message on standard error without a newline, status 254:

$ ucode -e 'let o = null; o.field'; echo $?
Reference error: left-hand side expression is null
In [-e argument], line 1, byte 17:

 `let o = null; o.field`
  Near here ------^

254

Those error reports come with the offending source line and a caret; the line text is available even for -e arguments, because the source stays resident. The error types themselves are chapter 14, and exit/die/assert are in chapter 20.

Shebang scripts

A ucode file can be an executable the way a shell script is. The first line is a comment as far as ucode is concerned, so nothing special is needed to make it work:

$ cat > leases.uc
#!/usr/bin/env ucode
let fs = require("fs");
let path = ARGV[0] ?? "/tmp/dnsmasq.leases";

if (!fs.access(path))
	die(`no leases at ${path}\n`);

printf("%d leases\n", length(filter(split(fs.readfile(path), "\n"), (l) => l != "")));
$ chmod +x leases.uc
$ ./leases.uc /tmp/dnsmasq.leases
12 leases

#!/usr/bin/env ucode is the portable form; a hard-coded #!/usr/bin/ucode breaks on systems where the interpreter lives elsewhere, which on a build host it usually does. On a router it does not.

Precompiling

ucode -c (or the ucc name for the same binary) turns sources into a bytecode image. The output begins with an interpreter line, so the compiled file is executable in place:

$ ucc -o leases.bin leases.uc       # or: ucode -c -o leases.bin leases.uc
$ head -1 leases.bin
#!/usr/bin/env ucode
$ chmod +x leases.bin
$ ./leases.bin /tmp/dnsmasq.leases
12 leases

A compiled file is loaded by parsing the image rather than by lexing and compiling the source, which is the difference that matters on a device with a few hundred scripts on it: it saves the compile time and the text of the source. loadfile(path) reads either form and returns a function which, called, runs the program and returns whatever it returned:

let fs = require("fs");

fs.writefile("/tmp/uc3-prog.uc", "return { ok: true };");
let prog = loadfile("/tmp/uc3-prog.uc");
printf("loaded %s as %s, value %J\n", "file", type(prog), prog());
fs.unlink("/tmp/uc3-prog.uc");

loaded file as function, value { "ok": true }

Compile options go after -c as a comma-separated list: -c,no-interp omits the interpreter line, -c,interp=/usr/bin/ucode overrides it, -c,module produces a loadable module rather than a program, and -s leaves out the debug information that error reports and the debugger use — which is how the compiled form of a script gets small enough to be worth its flash space:

$ ucode -c,s -o /tmp/tiny.uc /tmp/prog.uc

Templates

The same binary also renders templates, and the utpl name enables that mode without an option — utpl page.uc is ucode -T page.uc. A template is a file of text with {{ expression }} to interpolate and {% statement %} to control it:

$ cat > iface.tpl
Interface {{ name }} is {{ up ? "up" : "down" }}.
{% for (let i = 0; i < 2; i++): %}address {{ i }}
{% endfor %}
$ ucode -T -D name=lan -D up=true iface.tpl
Interface lan is up.
address 0
address 1

The block tags use the alternative block syntax of chapter 7 — the opening tag ends in a colon and the closing tag is {% endfor %}, {% endif %} and so on — and a name with no value renders as the empty string. Data comes from -D name=value options or from a JSON file via -F name=path; the details, including the whitespace-control flags, are in chapter 16. This {{ }} markup is a different feature from the backtick template literals of the language itself (chapter 9).

Summary

Values and types

ucode has nine kinds of value. Four of them — null, booleans, numbers and strings — are scalars you meet in any language. Three more — arrays, objects and functions — are the structures you build things out of. A regular expression is a value of its own, and the interpreter carries a handful of internal resources (open files, sockets, ubus connections) that behave like objects but are not part of the language's own inventory.

type()

The builtin type() names the kind of a value:

let values = [null, true, 1, 1.5, "text", [1], { a: 1 }, type, regexp("a")];

for (let i = 0; i < length(values); i++)
    printf("[%s] ", type(values[i]));

print("\n");

[(null)] [bool] [int] [double] [string] [array] [object] [function] [regexp]

The first entry is printed as (null) because that is how printf() renders a missing string argument; print() renders it as nothing at all.

Note the last line's null: type(null) returns null rather than the string "null", which is why it prints as nothing at all. undefined is not a separate value in ucode — an unset variable, a missing object key and an out-of-range array index all yield the same null:

print(undefined === null, " ", nosuchvariable === null, "\n");

true true

Reading a name that was never declared gives null in the default sloppy mode; under -S (strict mode) it raises a reference error instead. Writing to an undeclared name creates a global variable, in both modes unless -S says otherwise.

Truth

Every value is either true or false when the interpreter needs a decision. The falsy values are null, false, 0, -0 and the empty string:

let vals = [null, false, true, 0, 1, "", "x", [], [0], {}, json("{}")];

for (let i = 0; i < length(vals); i++)
    printf("%s ", vals[i] ? "true" : "false");

print("\n");

false false true false true false true true true true true

(There are ten values in the list; the last true is the object returned by json("{}").)

The two results worth memorising are that [] and {} are true. In Lua an empty table is true, and in JavaScript it is as well, so ucode agrees with both here; and, unlike shell, the existence of a container says nothing on its own — a list with no elements still branches into the true arm.

Numbers

Numbers come in two flavours, and the difference only shows up in edge cases.

Integers are 64-bit. They are written in decimal, or in hexadecimal, octal or binary:

print(0xff, " ", 017, " ", 0b1011, " ", 08, "\n");

255 15 11 8

A leading 0 means octal, as in C, so 017 is fifteen; a digit sequence that cannot be octal is read as decimal, which is why 08 is eight. 0o17 is not a number at all — it is a syntax error — and neither are digit separators: 1_000_000 does not parse.

Doubles are IEEE 754 64-bit floats, recognised by a decimal point, an exponent, or by the operation that produced them.

Division is the operator that behaves least like JavaScript. When both operands are integers, / performs integer division, truncating towards zero:

print(7 / 2, " ", -7 / 2, " ", 1 / 3, " ", 7.0 / 2, "\n");

3 -3 0 3.5

% follows the sign of its left operand, and works on doubles as well:

print(7 % 2, " ", -7 % 2, " ", 7.5 % 2, "\n");

1 -1 1.5

** exponentiation yields an integer when it can and a double when it must:

print(2 ** 10, " ", type(2 ** 10), " ", 2 ** -1, " ", type(2 ** -1), "\n");

1024 int 0.5 double

Doubles print without trailing zeros, and switch to exponential notation for large and small magnitudes. The conversion is round-trip friendly but not exhaustive, which is why 0.1 + 0.2 looks better in ucode than in a browser console:

print(3.0, " ", 0.1 + 0.2, " ", 1e20, " ", 1e-9, " ", 1e300 * 1e300, "\n");

3 0.3 1e+20 1e-09 Infinity

Signed and unsigned integers

Here is the part with no equivalent in JavaScript, where all numbers are doubles.

An integer value in ucode is either signed or unsigned, and the flavour is part of the value. When the operands of an arithmetic operation are all positive, the calculation is done with unsigned operands and the result is inferred to be unsigned too, which lets a computation hold magnitudes larger than 2**63 - 1:

let big = 2 ** 63;

print(big, " ", type(big), " ", big + 1, "\n");

9223372036854775808 int 9223372036854775809

9223372036854775808 does not fit in a signed 64-bit integer, and ucode does not fall back to a double for it — it stays an integer, rendered in full unsigned magnitude. Bring a negative operand into the same expression and the arithmetic turns signed:

print(0 - 2 ** 63, " ", sprintf("%d", 2 ** 63), "\n");

-9223372036854775808 -9223372036854775808

The same bits, two readings: sprintf() with %d converts to a signed integer, while the natural rendering of an unsigned value prints its full magnitude. Bitwise operators produce unsigned results, which is how you meet this behaviour first:

print(~6, " ", ~6 == -7, "\n");

18446744073709551609 false

~6 is the two's complement of seven, 0xfffffffffffffff9. Read as a signed value that is -7; ucode reads it as an unsigned value and prints 18446744073709551609, and the equality with -7 is false because the two values are compared as the numbers they denote, not as the bit patterns that happen to implement them. Likewise:

print(2 ** 63 < 0, " ", 2 ** 63 == -9223372036854775808, "\n");

false false

Overflow wraps silently. There is no exception and no automatic widening to a double:

print(2 ** 64, " ", (2 ** 63) * 2, "\n");

0 0

Three rules keep you out of trouble. If you mix a negative operand in, you get signed arithmetic. If you print with %d, you get the signed reading. And if a computation can reach 2**63, check the sign of the operands on both sides of every comparison, because x == -1 is false for the unsigned value whose bits are all ones.

Converting to a number

int() converts a value to an integer, and unlike the operators it is strict about the text it accepts:

print(int("42"), " ", int("42abc"), " ", int("010"), " ", int("0x1f"), " ", int("zz"), "\n");

42 42 10 0 NaN

The conversion is decimal only: a leading 0 does not request octal, a 0x prefix is not understood (yielding 0), trailing garbage is silently dropped, and text with no leading digits at all produces NaN. To parse a hexadecimal numeral, including an optional 0x prefix, as a number, use hex(); hexdec() does something different — it decodes a hex-encoded digit sequence into a binary string.

Arithmetic on strings coerces as JavaScript does — + concatenates if either side is a string, the other operators convert:

print("3" + 4, " ", "3" * "4", " ", true + 1, " ", null + 1, " ", [] + 1, "\n");

34 12 2 1 NaN

An array or object has no numeric value, so arithmetic on one yields NaN rather than raising. Comparisons are strict about type and never coerce; == compares values of different types as unequal, and 1 < 2 < 3 is true only because 1 < 2 yields the boolean true, which then compares as 1.

Strings are byte strings

A string is a sequence of bytes with a length, not a sequence of characters. ucode does not interpret the bytes as UTF-8 and does not care whether they decode: substr() cuts at byte offsets and can split a multi-byte character in half. Treat string indices and lengths as byte counts and everything works as documented.

The practical consequence is that "héllo" has a length of six, not five, and that sorting, matching and slicing behave exactly the same on non-ASCII text as on ASCII — bytewise.

Notes

• type() is the only type inspection the language offers; there is no typeof operator and no instanceof.
• Handles to external things — the file returned by fs.open(), a socket, a ubus connection — are resources, and type() names them as such:

import * as fs from "fs";

let f = fs.open("/dev/null", "r");

print(type(f), " ", type(fs), " ", type(fs.open), "\n");

resource object function

A resource is not one of the language's own types, but it carries a prototype whose methods (read(), close(), and so on) are reached with ordinary field access.

• Small integers do not allocate: they are encoded directly in the value representation (see Inside the interpreter), so loops over integers are cheap.
• NaN is not equal to anything, including itself; test with x != x.

Names, scope and bindings

Identifiers

An identifier is made of ASCII letters, digits and the underscore, and may not start with a digit. There is no $, and non-ASCII characters are not identifier characters — a name is a run of bytes, and the lexer refuses anything outside its alphabet:

let _private = 1, max_lease_count = 2, ifname2 = 3;

printf("%d %d %d\n", _private, max_lease_count, ifname2);

1 2 3

The following words are reserved and cannot be used as names:

break   case    catch   const   continue  default  delete  else
elif    endfor  endif   endwhile  endfunction  export  false  for
function  if    import  in      let       null     return  switch
this    true    try     while

Case matters: if_, IF, If and ifname are all ordinary names.

let If = 1, IF_ = 2, ifname = 3;

printf("%d %d %s\n", If, IF_, ifname);

1 2 3

Bindings

A binding is introduced by let, const or function. let may be left without a value, in which case the name holds null; several names may be declared in one statement:

let a;
let b = 2, c = "three";

printf("%J %d %s\n", a, b, c);

null 2 three

const requires an initializer, and rebinding the name is refused — by the compiler, so the program does not run at all:

const limit = 1500;

printf("%d\n", limit);

1500

const limit = 1500;
limit = 9000;

A constant protects the binding, not the value behind it. An object or array held in a const stays as mutable as any other:

const ports = [80, 443];

push(ports, 8080);
ports[0] = 8000;
printf("%J\n", ports);

[ 8000, 443, 8080 ]

A function declaration binds the name to the function; that binding is writable and may be re-declared, which is what makes monkey-patching possible. function name; — a forward declaration — is the opposite case: the binding becomes a constant that only a definition may fill. Chapter 8 covers both.

Declaring a name a second time in the same scope is accepted, and the later declaration wins. This holds for let and const alike, and for a let/const over a function declaration (strict mode rejects it):

let mode = "fast";
let mode = "safe";

printf("%s\n", mode);

safe

The exception is a name that was forward-declared with function: after function foo;, a let foo, a const foo, a second function foo; or a second definition of foo are all syntax errors (chapter 8).

delete removes object properties, not bindings — naming a variable is a syntax error:

let temp = { a: 1 };

printf("%J %J\n", delete temp.a, temp);

true { }

Scope

Bindings belong to the innermost enclosing block — the braces of a function body, a conditional, a loop, or a bare block — and are invisible outside it. An inner block may shadow an outer name; the outer binding is untouched and remains visible to code outside the shadow:

let scope_name = "outer";

function show() {
	let scope_name = "inner";

	return scope_name;
}

{
	let scope_name = "block";
	printf("%s\n", scope_name);
}

printf("%s %s %s\n", scope_name, show(), scope_name);

block
outer inner outer

Function parameters are bindings of the function's own scope, and the loop variables of a for header belong to the loop — two loops in one function can reuse the same name, and neither leaks out:

function twice(list) {
	let out = [];

	for (let i = 0; i < length(list); i++) {
		push(out, list[i]);
	}

	for (let i = length(list) - 1; i >= 0; i--) {
		push(out, list[i]);
	}

	return out;
}

printf("%J %J\n", twice([1, 2]), (function () { try { return i; } catch (e) { return null; } })());

[ 1, 2, 2, 1 ] null

A function declared inside a block or inside another function is scoped to it (chapter 8), which means the same name can serve as a private helper at several levels:

function outer() {
	function helper() { return "outer helper"; }

	function inner() {
		function helper() { return "inner helper"; }

		return helper();
	}

	return [helper(), inner()];
}

printf("%J\n", outer());

[ "outer helper", "inner helper" ]

Closures and upvalues

A function refers to the bindings of the scopes around it, not to copies of their values at the moment the function was created. Reads and writes are shared with everyone else who sees that binding, and they stay shared for as long as the function lives — which is why the same name can be read through a closure after the code that created it finished:

let counter = 0;

function bump() {
	counter = counter + 1;

	return counter;
}

bump();
bump();
printf("%d\n", counter);

2

Holding the state inside a function, rather than at the top level, is the standard way to make a private variable:

function make_gate(name) {
	let passes = 0;

	return {
		through: function () { passes++; return [name, passes]; },
		count: () => passes
	};
}

let gate = make_gate("wan");

gate.through();
gate.through();
printf("%J %J\n", gate.through(), gate.count());

[ "wan", 3 ] 3

The one subtlety is the for header variable: it is a single binding for the whole loop, so closures created in the body share it and see the value the loop finished with. A binding declared inside the body is created fresh by each iteration:

let from_header = [], from_body = [];

for (let i = 0; i < 3; i++) {
	let snapshot = i;

	push(from_header, () => i);
	push(from_body, () => snapshot);
}

printf("%J %J\n", map(from_header, (f) => f()), map(from_body, (f) => f()));

[ 3, 3, 3 ] [ 0, 1, 2 ]

Before the declaration

One difference from JavaScript: ucode has no hoisting. A binding is not known before its declaration statement, so what a read of the name before that resolves to depends on strict mode. Outside strict mode the read falls through to the global object, finds nothing there, and returns null, as if the name were undeclared:

printf("%J ", value);

let value = 42;

printf("%J\n", value);

null 42

In strict mode (-S), the same read is a Reference error naming the variable, and the program stops:

$ ucode -S -e 'printf("%.J\n", x)'
Reference error: access to undeclared variable x
In [-e argument], line 1, byte 17:

 `printf("%.J\n", x)`
  Near here ------^

The same applies to reading a name inside its own declaration — the difference is that the compiler catches this at compile time and rejects the program, in either mode, so no try can catch it. A name may not be referenced inside its own initializer, not even from a function that would run later:

let node = {
	toString: () => node
};

print(node);

The message is Can't access lexical declaration 'node' before initialization. Declaring the name first and assigning afterwards moves the reference out of the initializer (chapter 8 uses the same technique to let a published object call back into itself).

The global object

Names that no lexical binding provides are looked up in the global object, reachable under its own name global. It holds the builtin functions and constants, and it is where a name that has never been declared ends up living. A lookup that finds nothing answers null, so reading an undeclared name is a perfectly ordinary null, not an error — the error comes when the result is used as something it is not:

printf("%J\n", definitely_not_declared);
printf("%J\n", (function () { try { return definitely_not_declared.field; } catch (e) { return "error: " + e; } })());

null
"error: left-hand side expression is null"

A caught exception carries the message on its own; the Reference error: prefix seen above is part of how an uncaught error is reported, not part of the message (chapter 14).

Assigning to an undeclared name creates a key on the global object, from inside a function as much as at the top level (strict mode refuses both the read and the write):

function remember() {
	remembered = "value";
}

remember();
printf("%J %J\n", remembered, exists(global, "remembered"));
printf("%J\n", delete global.remembered);
printf("%J\n", exists(global, "remembered"));

"value" true
true
false

The reverse does not hold: a top-level let, const or function declaration is a binding of the script's outermost lexical scope, not a key of the global object. Two scripts therefore cannot step on each other's top-level names, and keys(global) shows only what the interpreter installed plus what was assigned without declaring:

let top_level = 1;
implicit_global = 2;

printf("%J %J\n", exists(global, "top_level"), exists(global, "implicit_global"));

false true

global itself is an ordinary object with the usual key operations available, and it refers to itself under global.global. Besides the functions of chapter 19 and following, it carries a few names of interest to the embedding and module machinery — ARGV, REQUIRE_SEARCH_PATH, modules, NaN and Infinity:

printf("%J %J %J\n", global.global == global, type(global.print), length(keys(global)) > 50);
printf("%J %J\n", type(ARGV), type(REQUIRE_SEARCH_PATH));

true "function" true
"array" "array"

To ask whether a name exists rather than read it, use exists(global, name). Note the difference to the in operator, which also consults prototype chains that exists() ignores, and to rawget(), which follows the prototype chain but skips __get__ metamethods (chapter 12):

let base = { shared: 1 };
let derived = proto({}, base);

printf("%J %J %J\n", exists(derived, "shared"), "shared" in derived, rawget(derived, "shared"));

false true 1

Code that runs through call() gets a global environment of its own, and a module or a template has its own scope as well; in all three cases the surrounding globals are inherited unless explicitly replaced. Chapters 8, 16 and 17 deal with each.

Strict mode

The rules above are the permissive ones. Two switches turn them off: the -S option, which compiles every source of a run strictly, and a "use strict"; pragma, which strictens the function it appears in. Strictness is lexical — a nested function inherits it — and since the top level of a file is itself a function body, a pragma in the first line strictens the whole file.

Strict mode changes four things, and nothing else:

"use strict";

let counter = 0;
counter++;

printf("%J %J\n", counter, (function () { try { return counter2; } catch (e) { return "error: " + e; } })());

1 "error: access to undeclared variable counter2"

The pragma is recognised only as the first statement of a body. Anywhere else — after another statement, or as the first thing inside a plain block — it is an ordinary string expression with no further meaning:

let prepared = 1;
"use strict";

printf("%J\n", still_permissive);

null

The reference errors are ordinary exceptions, so a try block sees them like any other (chapter 14), including from inside a callback:

"use strict";

function lookup(name) {
	try {
		return config_for[name];
	} catch (e) {
		return "default";
	}
}

printf("%s\n", lookup("lan"));

default

Compiling at run time takes the same switch as a member of the parse configuration object accepted by loadstring() and loadfile() (chapter 20), and the C API's script configuration carries the equivalent strict_declarations field (chapter 41 onward). In a template, the pragma goes in the first {% ... %} block that opens the file.

What strict mode does not touch is everything else in this chapter: a constant's value stays mutable, delete still cannot remove a binding, a binding is still visible from the top of its block before its declaration runs, and global remains a rebindable name.

Operators

ucode's operators are largely the ones you expect from ECMAScript, with a handful of differences that matter. Arithmetic on integers stays in the integer domain, the power operator associates to the left, division by zero is a value rather than an error, and bitwise operators hand back unsigned values. This chapter is the inventory, together with the precedence table the parser actually uses.

Arithmetic

print(7 / 2, " ", -7 / 2, " ", 1 / 3, " ", 7.5 / 2, "\n");
print(7 % 2, " ", -7 % 2, " ", 7.5 % 2, "\n");

3 -3 0 3.75
1 -1 1.5

When both operands of / are integers the result is an integer, truncated towards zero — 1 / 3 is 0, not 0.333. When one operand of a binary operation is a double, the operation is carried out in the double domain — but only from that operation on: the operands of an earlier operation keep the domain they arrived in, so 4 / 3 * 1.0 is 1.0 (the division yields the integer 1, which the multiplication then converts), not 1.3333. % takes the sign of its left operand and works on doubles too, since it is implemented with fmod().

Dividing by zero does not raise, and follows IEEE-754: the infinity carries the sign the division rules give it, and zero over zero is NaN:

print(5 / 0, " ", -5.0 / 0, " ", 0.0 / 0, " ", 5 % 0, " ", NaN != NaN, "\n");

Infinity -Infinity NaN NaN true

The double path (vm.c:1947-1949) is the hardware division itself, so -5.0 / 0 is negative infinity and 0.0 / 0 is NaN. The integer path (vm.c:2042-2048) has no hardware answer to lean on and reproduces the same result itself: signed infinity with the sign of the numerator, NaN for 0 / 0. The last two columns show where this leaves you: 5 % 0 goes through fmod() and really is NaN, and NaN != NaN is true only because it is computed by a path that handles NaN properly. Overflow, likewise, wraps silently; there is no automatic promotion to double:

print(2 ** 64, " ", (2 ** 63) * 2, " ", (0 - 2 ** 63) / -1, "\n");

0 0 9223372036854775808

The third result deserves a moment. INT64_MIN / -1 would trap with SIGFPE in C, so the interpreter special-cases it and returns 2**63 as an unsigned integer — the value does not fit in the signed range, so it does not claim to. Note how the signed INT64_MIN had to be manufactured with 0 - 2 ** 63; the expression 2 ** 63 / -1 is something else again, because the left operand there is the unsigned two to the sixty-third, which saturates to INT64_MAX when the mixed-signedness division needs a signed operand:

print(2 ** 63 / -1, " ", (0 - 2 ** 63) / -1, "\n");

-9223372036854775807 9223372036854775808

** is right-associative in JavaScript. In ucode it is a plain left-associative binary operator, and unary minus binds tighter than it does:

print(2 ** 3 ** 2, " ", -2 ** 2, " ", 2 ** -1, "\n");

64 4 0.5

2 ** 3 ** 2 is (2 ** 3) ** 2, and -2 ** 2 is (-2) ** 2, which is why it comes out positive. JavaScript rejects the second form outright; ucode accepts it and means something slightly different from what a JS reader would guess. A negative exponent produces a double, since the integer result would be zero.

Bitwise

&, |, ^, <<, >> and ~ work on the 64-bit integer representations:

print(5 << 2, " ", 5 >> 1, " ", 5 & 3, " ", 5 | 3, " ", 5 ^ 3, " ", ~5, "\n");

20 2 1 7 6 18446744073709551610

The last column is the signed/unsigned behaviour of values and types at work: ~5 is all the bits of five inverted, which is -6 read as signed and 18446744073709551610 read as unsigned, and bitwise negation yields the unsigned flavour. There is no unsigned right shift >>>, and no <<<.

Because the operands are integers, applying a bitwise operator to a double converts it by truncation.

Equality and comparison

== performs coercion between numbers and strings, === does not:

let a = [1, 2];

print("1" == 1, " ", "1" === 1, " ", "3" < 4, "\n");
print(a == [1, 2], " ", a === a, " ", { a: 1 } == { a: 1 }, "\n");

true false true
false true false

Composite values are compared by identity, never by structure: two arrays holding the same elements are unequal, and the only way to compare contents is to write the loop yourself (or compare the %J renderings of both, which is cheaper to type but fragile).

Relational operators coerce a string operand to a number when compared against a number, as the "3" < 4 result shows. Comparison chaining is not the mathematical relation — it is two separate comparisons, exactly as in JavaScript:

print(1 < 2 < 3, " ", 3 > 2 > 1, "\n");

true false

1 < 2 yields true, which counts as 1 in 1 < 3, so the first expression is true. The second computes 3 > 2 → true → 1, and 1 > 1 is false. Write x > low && x < high.

Logical and nullish operators

||, && and ?? return one of their operands rather than a boolean, and all three short-circuit:

printf("[%s] [%s] [%s] [%s]\n", 0 || 1, true && 7, null ?? "default", "" ?? "default");

[1] [7] [default] []

|| and && test for truthiness, so 0 || 1 is 1; ?? tests only for null, so an empty string or a zero passes through untouched. That difference is the main reason to prefer ?? when reading values that may legitimately be zero.

Optional chaining reaches through values that may be missing:

let o = { a: { b: 2 } };
let p = null;

printf("[%s] [%s] [%s]\n", o.a.b, o.x?.y, p?.a?.b);

[2] [(null)] [(null)]

(The (null) renderings are what printf() makes of a missing string argument; with print() they would print as nothing.)

Reading a key an object does not have already gives null, so ?. matters only where a further dereference would fail — o.x.y raises a reference error because it dereferences null, while o.x?.y stops and yields null.

Assignment

Plain = assigns, and the compound forms cover every arithmetic, bitwise and logical operator:

let n = 5;

n += 3;
n **= 2;
n -= 8;
n /= 4;

printf("%d ", n);

let z = null;
z ??= 9;

let s = "";
s ||= "set";

printf("[%s] [%s]\n", z, s);

14 [9] [set]

Assignment is an expression, yielding the assigned value, which is why print(r = f()) works. The logical assignment operators are short-circuiting: x ||= y evaluates y only when x is falsy, so x ||= expensive() can be used as a lazy default.

Increment and increment-by exist in both prefix and postfix position:

let i = 0;

print(i++, " ", i, " ", ++i, " ", -i, "\n");

0 1 2 -2

delete removes a key from an object and reports whether anything went away. It applies to object keys only; deleting an array index raises an error, because an array has no removable gaps, and a named key of an array can be handled only by a metamethod the array's prototype carries (chapter 12):

let o = { a: 1, b: 2 };

print("a" in o, " ", delete o.a, " ", "a" in o, "\n");

true true false

in is true when the key exists on the object or anywhere along its prototype chain. The comma operator evaluates both sides and yields the right one; it is rarely worth the confusion.

Precedence

The table below is the order coded in the parser (include/ucode/internal/compiler.h), loosest first. Each row binds less tightly than the rows below it:

Two consequences are easy to trip over. Bitwise operators bind less tightly than comparison, so flags & FLAG == 0 parses as flags & (FLAG == 0) and does not test what you meant — parenthesise. And ** sits below unary, which is why -2 ** 2 is 4:

print(4 & 1 == 0, " ", (4 & 1) == 0, "\n");

0 true

print(1 + 2 * 3, " ", (1 + 2) * 3, " ", 2 * 3 ** 2, " ", 1 + 2 < 4 && true, "\n");

7 9 18 true

The conditional operator is right-associative, so a chain of them reads like nested ifs:

print(0 ? 1 : 2 ? 2 : 3, "\n");

2

Absent operators

Knowing what is not there saves time:

• No typeof and no instanceof. Use the type() builtin.
• No >>> or <<<.
• No throw; raise an exception with the die() builtin and catch it with try { … } catch (e) { … }.
• No new, no class, no super, no this in a class sense. Callable objects are built with a __call__ metamethod.
• No operator overloading of any kind, and no metamethod for arithmetic or comparison.
• No await, no generators, no yield, no arrow-function => currying beyond the single-arrow form.

Notes

• -0.0 is falsy and NaN != NaN. The globals NaN and Infinity exist (vm.c:150-151), alongside global, modules and REQUIRE_SEARCH_PATH.
• Because == coerces numbers and strings but composite values compare by identity, the safest habit is to write === everywhere and let the type errors tell you where a conversion was actually wanted.
• sprintf("%J", v) renders infinity as 1e309 and NaN as the string "NaN", so JSON output never contains the non-standard Infinity token (see types.c:1968-1973).

Control structures

ucode's control structures are the C family ones — if, while, for, switch — with a couple of differences worth knowing up front: for ... in iterates containers, switch compares strictly and falls through like C's, and every block-taking statement has a second spelling with a colon and a terminator keyword, designed for templates:

let ports = [22, 80, 443];

for (let p in ports) {
	if (p < 1024) {
		printf("%d is privileged\n", p);
	}
}

if (length(ports) == 0):
	print("nothing to do\n");
endif

22 is privileged
80 is privileged
443 is privileged

Truth and control flow

Every control structure tests its condition the same way, and the values that test false are null, false, the number 0 (0.0 included) and the empty string "". Everything else — including empty containers, the string "0", and objects — tests true:

for (let v in [0, 0.0, "", null, false, [], {}, "0", 1]) {
	printf("%J -> %s\n", v, v ? "true" : "false");
}

0 -> false
0.0 -> false
"" -> false
null -> false
false -> false
[ ] -> true
{ } -> true
"0" -> true
1 -> true

Because a condition is an ordinary expression, an assignment can stand in it. ucode has no "assignment inside a condition" warning, and no declarations are allowed there — if (let x = 5) is a syntax error:

let line = "hello";

if (line = "yes") {
	printf("assigned, and truish: %s\n", line);
}

assigned, and truish: yes

Conditional execution

The if statement takes a condition in parentheses, a block, and optional else if and else branches. When a branch is a single statement the braces may be left out — but then only that one statement belongs to the branch:

function grade(n) {
	if (n >= 90)
		return "A";
	else if (n >= 80)
		return "B";
	else
		return "C";
}

printf("%s %s %s\n", grade(95), grade(85), grade(10));

A B C

A conditional expression is available as ?:, and unlike if it accepts expressions only; it is covered in chapter 6.

Loops

while tests before each iteration; for has the C form, with an initializer, a condition and a post statement:

let i = 0;

while (i < 3) {
	printf("%d ", i);
	i++;
}

for (let j = 0, n = 3; j < n; j += 1) {
	printf("[%d]", j);
}

printf("\n");

0 1 2 [0][1][2]

The initializer of a for loop declares its variables in the loop's own scope, so j above is not visible after the loop, and the same name can be reused by a second loop. Any of the three for clauses may be empty; for (;;) loops until something breaks out of it:

let n = 0;

for (;;) {
	n++;

	if (n > 2) {
		break;
	}
}

printf("n=%d\n", n);

n=3

There is no do ... while — a loop whose body must run at least once is written as while (true) { ... } with a break, or as a for loop.

Iterating containers

for ... in walks a container. Its meaning depends on the kind of container, and on how many loop variables are declared:

for (let v in [10, 20]) {
	printf("%J ", v);
}

for (let i, v in [10, 20]) {
	printf("%d:%J ", i, v);
}

for (let k, v in { lan: "eth0", wan: "eth1" }) {
	printf("%s=%J ", k, v);
}

printf("\n");

10 20 0:10 1:20 lan="eth0" wan="eth1"

Strings are not iterable; index over them, or split() them first:

let s = "abc";

for (let i = 0; i < length(s); i++) {
	printf("%s ", substr(s, i, 1));
}

printf("\n");

for (let part in split("a:b:c", ":")) {
	printf("%s ", part);
}

printf("\n");

a b c
a b c

Walking an array keeps up with modifications made during the walk, because iteration works by index against the live array. Adding elements while iterating therefore extends the walk, and removing the element just visited makes the next iteration skip one:

let a = [1, 2, 3];
let seen = [];

for (let v in a) {
	push(seen, v);

	if (length(a) < 6) {
		push(a, v * 10);
	}
}

printf("seen=%J final=%J\n", seen, a);

seen=[ 1, 2, 3, 10, 20, 30 ] final=[ 1, 2, 3, 10, 20, 30 ]

Object walks take a snapshot of the key set as they go: a key deleted during the walk is simply not visited later, and adding keys during a walk is not something to rely on. When a loop both searches and edits, collect first and apply afterwards:

let m = { a: 1, b: 2 };

for (let k in m) {
	printf("visiting %s\n", k);

	if (k == "a") {
		delete m.b;
	}
}

printf("%J\n", m);

visiting a
{ "a": 1 }

break leaves the innermost loop, continue starts its next iteration. Both are checked statically: break must sit lexically inside a loop or a switch, and continue inside a loop, so neither can be used to escape from a callback — a return from the callback, or a flag variable, is the way to stop a walk that a function performs for you:

let found = null;

for (let v in [1, 2, 3, 4]) {
	if (v == 2) {
		found = v;
		break;
	}
}

printf("found=%J\n", found);

found=2

Loops have no labels, so leaving two loops at once needs a helper function (whose return exits all of them) or a condition on the outer loop:

function first_pair(list, test) {
	for (let a in list) {
		for (let b in list) {
			if (test(a, b)) {
				return [a, b];
			}
		}
	}

	return null;
}

printf("%J %J\n", first_pair([1, 2, 3], (a, b) => a * b > 4), first_pair([1, 2], (a, b) => false));

[ 2, 3 ] null

Switch

switch compares the subject against each case label with strict equality — the === comparison of chapter 6 — so a string label never matches a number subject. Execution enters at the matching label and runs on through the following labels until a break, which is C's fallthrough:

function describe(v) {
	let out = [];

	switch (v) {
		case 1:
			push(out, "one");
		case 2:
			push(out, "two");
			break;
		case "3":
			push(out, "three");
			break;
		default:
			push(out, "other");
	}

	return out;
}

printf("%J %J %J %J\n", describe(1), describe(2), describe("3"), describe(3));

[ "one", "two" ] [ "two" ] [ "three" ] [ "other" ]

default may appear anywhere among the labels and is itself subject to fallthrough, and several case labels may share one body by writing them consecutively:

function classify(v) {
	switch (v) {
		case 2: case 3: case 5: case 7:
			return "small prime";
		default:
			return "not a small prime";
	}
}

printf("%s %s\n", classify(5), classify(8));

small prime not a small prime

Inside a loop, break in a switch leaves the switch only, while continue skips to the next loop iteration — the loop is not affected by the switch ending:

let log = [];

for (let v in [1, 2, 3, 4]) {
	switch (v) {
		case 2:
			continue;
		case 3:
			break;
	}

	push(log, v);
}

printf("%J\n", log);

[ 1, 3, 4 ]

The alternative block syntax

Every block-taking statement except switch has an alternative spelling: a colon where the opening brace would be, and a terminator keyword where the closing brace would be. The terminators are endif, endwhile, endfor and endfunction, and if chains gain a single-word elif:

let x = 5;

if (x == 0):
	print("zero\n");
elif (x == 5):
	print("five\n");
else
	print("another value\n");
endif

let i = 0;

while (i < 2):
	printf("%d ", i);
	i++;
endwhile

for (let v in ["a", "b"]):
	printf("%s ", v);
endfor

function double(v):
	return v * 2;
endfunction

printf("\n%d\n", double(21));

five
0 1 a b
42

The statements inside such a block are ordinary statements and need their semicolons; it is only the braces that the colon and terminator replace. Note that else takes no colon, that switch has no alternative form, and that elif belongs to this syntax and cannot be used where braces are used — if (c) { … } elif (c2) { … } is a syntax error, and the braced chain is spelled else if.

The reason for the second syntax is templating. A template file interleaves markup with ucode delimited by {% … %}, in which braces already carry meaning, so the block statements are written with colons and terminators instead:

{% if (length(ifaces) > 0): %}
iface count: {{ length(ifaces) }}
{% else %}
no interfaces
{% endif %}

The template renderer itself is chapter 16; the block syntax is ordinary ucode and can be used in plain scripts, as above — most code uses braces, and mixing the two styles within one statement is not possible.

Functions

Functions are ordinary values in ucode. They can be stored in variables and containers, passed to and returned from other functions, and created at run time. There is a single callable kind — there are no classes, no constructors and no bound method objects — and three ways to write one: a declaration, a function expression and an arrow function:

function add(a, b) { return a + b; }

let sub = function (a, b) { return a - b; };
let mul = (a, b) => a * b;

printf("%J %J %J\n", add(1, 2), sub(5, 3), mul(3, 4));
printf("%s %s\n", type(add), type(mul));