Last updated: 2026-11-15

U
Undergraduate level
APL
Applied / Methodological โ€” Knowledge with a 5โ€“10 year half-life โ€” stable practice

Functions, Calls and Parameters in PatLang 2.0

For new readers

PatLang 2.0 checks every call. A call must pass exactly as many arguments as the function or closure takes; a named call that gets it wrong is refused before the program runs, and a closure call that gets it wrong stops the program at that call. This page covers the call rules, what a function gives back when it has no return, how includes and undeclared names behave, why global variables were removed, and how to shape a function's parameters so that calls stay readable.

The rules are section 1.13 of PatLang's values-and-memory specification. In v1 a missing argument arrived as unit and an extra one was dropped, on every engine and with no message. Mistakes of that kind went unnoticed for a long time: takes none in v1 declared a parameter named none, and the padding of missing arguments hid it.v1 silently dropped args, hiding bugs for years

Exactly the arguments a function takes FoundationalKnowledge that endures for decades โ€” core principles

A call gives a function exactly as many arguments as it takes. Naming the function with the wrong number is an error when the program is compiled, naming the function and both numbers:

make a function called area takes w, h returns a
  return w * h
end
print(area(3))
v2 error: area takes 2 arguments, given 1

The interpreter lowers a program through the same front end before it runs any of it, so it refuses this program too, printing error: area takes 2 arguments, given 1 and exiting with code 1 before the first line runs.

A closure knows how many parameters it takes. Called with the wrong number, through a variable, apply, send, parallel_map or the start of a thread, it stops the program as a failed precondition of the closure, with exit code 3:exit 3 means a runtime check failed, not just a compile error

let f = |a, b| { return a + b }
print(f(1, 2))
print(f(1))
3
contract violation: precondition failed in a closure: it takes 2 arguments, given 1

A closure is called with at most 8 arguments, and a call with more is refused when compiling. There are no optional parameters and no defaults.

rest and takes none FoundationalKnowledge that endures for decades โ€” core principles

A last parameter named rest takes any further arguments, as a list. Fewer arguments than the parameters before it is still too few. The rule holds however the function is called, closures and threads included:

make a function called total takes first, rest returns t
  let t = first
  let i = 0
  while i < list_len(rest) do
    let t = t + rest[i]
    let i = i + 1
  end
  return t
end
print(total(1))
print(total(1, 2, 3, 4))

let k = |a, rest| { return [a, rest] }
print(k(1))
print(k(1, 2, 3))
print(thread_result(thread_spawn(k, 1, 2)))
1
10
[1, []]
[1, [2, 3]]
[1, [2]]

A function declared takes none, or with no takes at all, has no parameters, and none is never a parameter's name.

What a function, a block and a program give Applied / MethodologicalKnowledge with a 5โ€“10 year half-life โ€” stable practice

  • A function that ends without return gives the value of its last statement. An expression gives its value and a let the value it bound.
  • An if or a while gives the value of the last statement it ran, or unit if it ran none, and a function with no statements gives unit.
  • A program's top-level statements give their value as a function's body does, and nothing prints it. A program writes only what it prints. pat printed the value of a program's last top-level expression, and v2 does not.
make a function called greeting takes none returns g
  "hello"
end
make a function called sign takes n returns s
  if n < 0 then
    "negative"
  else
    "non-negative"
  end
end
print(greeting())
print(sign(0 - 4))
42
hello
negative

The 42 on the last line is the program's value, and it prints nothing.

Names, includes and the runtime's functions Applied / MethodologicalKnowledge with a 5โ€“10 year half-life โ€” stable practice

  • An undeclared name in a call compiles, and stops the program when the call is reached, with host fn 'NAME' not found and exit code 72. The lines before it have run. This holds in every build, WebAssembly's included, whatever arguments the call passes.
  • A bare name that nothing defines, used as a value, is an error. v1 read some of these as their own text.
  • unit is the unit value unless the program binds the name itself, as a parameter or with let.
  • Includes. A file reached by several includes is included once, by its normalised path, before the files that include it.
  • Shadowing the runtime. A program may define a function with a name the runtime has. The program's calls reach its own function, directly, from a closure or by name, and the runtime goes on using its own. Two of a program's files defining one name is an error, naming it, and nothing of the program runs.

No globals: state travels as a value FoundationalKnowledge that endures for decades โ€” core principles

set_global, get_global, set_var and get("__vars", ...) are gone from v2. State a function needs is a parameter. Where a whole run needs shared state, as a test runner does, it travels as one explicit context object, created by the function that starts the run and handed to everything that needs it. The project's own Gherkin runner, lib/gherkin.patlang, works this way: expect(ctx, label, actual, expected), step(ctx, text, fname), run_feature(ctx, text), and each step function takes ctx. Underneath, lib/context.patlang keeps named values in hashed buckets (ctx_get, ctx_set, ctx_has, ctx_num, ctx_text, ctx_counter), and an unset name reads as false, 0 or "" by which accessor reads it.

The change was more than tidiness. The compiler's stages run on parallel threads, and state in a shared global table had already caused silent miscompiles when two workers raced on one counter. With no ambient state, what a function can reach is visible in its parameters, which is what lets the compiler run its jobs in any order and get the same bytes. A top-level when handler takes no arguments, so a program whose handlers need its context holds it in a named object (context_hold, context_held).no shared mutable state means pure functions

Shaping parameters Applied / MethodologicalKnowledge with a 5โ€“10 year half-life โ€” stable practice

Three or four parameters read well at a call site. Past that, a reader counts positions to know which value is which, and two arguments of the same type can be swapped without anything noticing. When a function wants more, the parameters usually belong together and should travel as one thing, and the choice between an object and a list turns on whether the callee may change what it is given.

An object suits parts that have names. A class gives each part a name and a default, and field defaults replace optional parameters: a caller sets only what differs. A constructor function states, once, what makes the group valid.

class Camera {
  field position = [0, 0, -5]
  field fov = 60
}

make a function called camera_new takes position, fov returns c
  require fov > 0
  let c = new("Camera")
  c.position = position
  c.fov = fov
  return c
end

make a function called view_width takes camera, distance returns w
  require type_of(camera) == "Camera"
  return 2 * distance * tan(camera.fov * 3.14159 / 360)
end

An object has identity, so a change the callee makes through it is seen by the caller. That suits a group the callee is meant to update, such as an accumulator or a context. A list is a value, and the callee cannot change the caller's copy; it suits a sequence of like items, or a short tuple whose order is obvious, such as [x, y, z] or [low, high]. A list of more than three or four positions, or of positions of different kinds, has outgrown that use and should become an object.shared mutable state is a classic trap

When a function needs many things, nest the groups the way the problem already divides: a scene holds a camera, its lights and its size, and a function deep in the work takes only the part it uses, view_width(scene.camera, d). Set nested objects in the constructor, not in a field default, or every instance shares the one the class made.

rest is for a varying number of arguments of one kind, such as total(1, 2, 3) or the arguments after thread_spawn's closure. Using it to carry a fixed set of different things by position hides what the arity check exists to catch.

Runtime functions new in v2 Ephemeral / ToolingKnowledge that evolves in months to a year โ€” check for updates

FunctionGives
exec_capture(cmd, rest)What the command wrote to standard output and to standard error.
exec_peak_memory(program, args)The program's output, with standard error added if it exited non-zero, and its peak working set in bytes, or -1.
exec_measured(program, args)Standard output, standard error, whether it exited 0, and the peak memory committed by it and every process it started, measured through a Windows job object.
cpu_count()The logical processors, at least 1.
cpu_times()[idle, busy] in milliseconds since the machine started, summed over processors; how busy it was between two readings is in their differences.
memory_status()[total, available] physical memory in bytes.
progress_report(text), progress_status()Keep and read back the program's latest status line.
list_dir(path)A directory's entries, sorted, subdirectories ending in /; [] for a path with no directory, as read_file gives "".
sed(command, input)A literal s/pattern/replacement/flags substitution.

Where a browser has no figures, cpu_times and memory_status give [-1, -1].

See also

Design by contract covers require and ensure, which the arity check reports through. Designing well-behaved PatLang programs and PatLang best practices cover program structure more broadly. Worlds, fibers and threads covers thread_spawn and fibers. What changed since v1 lists every change in one place.

Graduate Attributes

Modelled on this page

  • Critical Thinker: The removal of global variables is justified by citing specific concurrency bugs caused by race conditions.
  • Digitally Fluent: Guidance on selecting between objects and lists depends on whether the callee modifies the caller's data.
  • Confident Communicator: Advice on parameter structure is tailored to how readers visually parse function calls at the site.

University of Reading Graduate Attributes framework.