Get started with ilusm

Install

Grab a release from Download, unpack, and run ./ilusm from the project root. Pick your OS:

chmod +x ilusm
./ilusm tests/hello.ilu

chmod +x ilusm
./ilusm tests/hello.ilu

# PowerShell - use the shipped launcher
.\ilusm.ps1 tests\hello.ilu

Environment variables

VSCode

The syntax extension lives in the tarball under vscode-extension/ at the bundle root - open that folder in VSCode with Run Extension for local authoring, or pack it as a .vsix when you publish.

This guide walks you from a working install to writing real programs with the standard library. It assumes you have already run ./ilusm tests/hello.ilu and seen hello world. If you have not, read Install first.

Running a program

Every ilusm program is a .ilu file. You run it with the launcher:

ilusm yourfile.ilu
ilusm yourfile.ilu arg1 arg2 arg3

Variables and expressions

ilusm uses = for assignment. There is no let, var, or const.

x = 5
name = "ilusm"
pi = 3.14159
flag = tru
nothing = nil

Printing output

prn prints a value followed by a newline.

prn("hello")
prn(42)
prn(tru)
prn(nil)

Conditionals

x = 10

if x > 5:
  prn("big")
| prn("small")

# One-liner form
label = if x > 5: "big" | "small"
prn(label)

While loops

n = 0
whl n < 5:
  prn(n)
  n = n + 1

Functions

# One-line
add(a, b) = a + b
prn(add(3, 4))   # 7

# Multi-line
greet(name) =
  msg = "hello, " + name
  prn(msg)

greet("world")

Lists

xs = [1, 2, 3, 4, 5]
prn(xs[0])       # 1
prn(len(xs))     # 5
xs = xs + [6]    # append

Objects

person = {name: "alice", age: 30}
prn(person.name)   # alice
prn(person.age)    # 30

Importing the standard library

Use use to import a module. The name maps to lib/stdlib/<name>.ilu.

use txt
use trl

s = "hello, world"
prn(txt.upr(s))          # HELLO, WORLD
prn(txt.spl(s, ", "))    # ["hello" "world"]

Hello world + txt, trl, obs

The box below uses the same teaching shell as Loveshack (loops, prn, arithmetic). Full use txt / use trl / use obs behavior needs the native toolchain - start from Download and the samples above once ./ilusm runs.

Sandboxed eval (native)

Run untrusted code with a restricted capability set - native only, advanced use:

use sbx

# sbx.ilu(parent_env, path, caps, limits)
# caps = list of host syscall names the guest may call
# See lib/stdlib/sbx.ilu for full API

Core stdlib - first five modules

txt - text utilities

use txt

prn(txt.upr("hello"))              # HELLO
prn(txt.lwr("HELLO"))              # hello
prn(txt.spl("a,b,c", ","))         # ["a" "b" "c"]
prn(txt.has("foobar", "bar"))      # tru
prn(txt.sub("hello world", 6, 11)) # world
prn(txt.trm("  hello  "))          # hello

trl - list transforms

use trl

nums = [1, 2, 3, 4, 5]
doubled = trl.map(nums, \(x) x * 2)
evens   = trl.fil(nums, \(x) x % 2 == 0)
total   = trl.fld(nums, 0, \(acc, x) acc + x)

prn(doubled)   # [2 4 6 8 10]
prn(evens)     # [2 4]
prn(total)     # 15

mth - math

use mth

prn(mth.abs(-5))       # 5
prn(mth.sqrt(16))      # 4.0
prn(int(3.7))          # 3  (built-in truncation)
prn(mth.pow(2, 8))     # 256

jsn - JSON

use jsn

data = jsn.dec("{\"name\": \"ilusm\", \"count\": 42}")
prn(data.name)    # ilusm

out = jsn.enc({lang: "ilusm", stable: tru})
prn(out)

enc - encoding

use enc

b64 = enc.b64("hello world")
prn(b64)             # aGVsbG8gd29ybGQ=
prn(enc.ub4(b64))    # hello world

A complete small program

use fs
use txt
use trl

raw   = fs.rd("names.txt")
names = txt.spl(raw, ",")
upper = trl.map(names, \(n) txt.upr(n))
trl.eac(upper, \(n) prn(n))