The Standard Library

Core Runtime Services

The most commonly used built-in service classes are:

• Console
• Process
• Task
• Channel

For filesystem and file I/O, use the lib/io library:

• intern io/Path
• intern io/Directory
• intern io/Text_File
• intern io/Binary_File

Together with the scalar and collection classes, they form the everyday standard environment of Nex programs.

Other important shipped libraries include:

• data/Byte_Array
• math/Random, for random numbers that can be repeated from a seed
• time/Date_Time
• time/Duration
• text/Regex
• net/Http_Client
• net/Http_Server

Console I/O

Console supports interactive text programs.

Every program and REPL session has one already, predeclared as console. Should you need your own:

let con: Console := create Console

Useful operations:

• print(msg)
• print_line(msg)
• flush()
• read_line(prompt?)
• error(msg)
• read_integer()
• read_real()

Example:

console.print_line("What is your name?")
let name: String := console.read_line()
console.print_line("Hello, " + name)

File Access

Filesystem operations live in the io library.

Path is the main entry point for filesystem probing and convenience file operations.

Construction:

intern io/Path

let p: Path := create Path.make("notes.txt")

Useful operations:

• exists()
• is_file()
• is_directory()
• size()
• modified_time()
• read_text()
• write_text(text)
• append_text(text)
• copy_to(target)
• move_to(target)
• delete()
• delete_tree()

Example:

intern io/Path

let src: Path := create Path.make("notes.txt")
src.write_text("line 1")
src.append_text("\nline 2")

let copy: Path := create Path.make("notes_copy.txt")
src.copy_to(copy)
print(copy.read_text())

let moved: Path := create Path.make("notes_moved.txt")
copy.move_to(moved)
print(moved.exists())
print(moved.size())
print(moved.modified_time())

For sequential text and binary access, use Text_File and Binary_File. A Binary_File reads and writes bytes as an Array[Byte], so writer.write("ABC".to_bytes()) writes three bytes and reader.read_all() returns them as Byte values.

If your code is directory-oriented, use Directory as a thin wrapper over Path.

intern io/Path
intern io/Directory

let root_path: Path := create Path.make("tmp")
if root_path.exists() then
  root_path.delete_tree()
end

let root: Directory := create Directory.make("tmp")
root.create_tree()

let data: Directory := root.child_dir("data")
data.create_tree()

let file: Path := data.child_path("items.txt")
file.write_text("one\ntwo")

let backup: Directory := root.child_dir("backup")
data.copy_to(backup)
print(backup.exists())

print(root.directories().length)
print(data.files().length)

intern io/Path
intern io/Text_File

let path: Path := create Path.make("notes.txt")
let writer: Text_File := create Text_File.open_write(path)
writer.write_line("alpha")
writer.write_line("beta")
writer.close()

Use file routines at the boundary of the system. Core logic should usually operate on strings, arrays, maps, and classes rather than on filesystem objects directly.

Process Information

The predeclared program (of type Program) describes the running program.

Useful operations:

• arguments — the words after the script name, as an Array[String]
• env(name) — an environment variable, or "" when it is not set
• has_env(name)
• working_directory — the folder the program was started from; build relative file paths from it
• pid
• exit(code)

Example:

print(program.arguments)
print(program.env("HOME"))
print(program.working_directory + "/notes.txt")

The older Process class (create Process) also offers getenv(name), like program.env, and command_line(), the same list as program.arguments.

Tasks and Channels

Use spawn to start concurrent work and Channel[T] to move values between tasks.

let jobs: Channel[String] := create Channel[String].with_capacity(2)

let worker: Task := spawn do
  let item := jobs.receive
  print("worker saw " + item)
end

jobs.send("compile docs")
worker.await

Channels can be buffered or unbuffered. Unbuffered channels synchronize sender and receiver directly; buffered channels allow a limited number of queued values. select lets one task wait on several channel operations at once.

Time And Scheduling

Use time/Date_Time and time/Duration for UTC timestamps, scheduling offsets, and log formatting.

intern time/Duration
intern time/Date_Time

let started_at: Date_Time := create Date_Time.now()
let next_run: Date_Time := started_at.add(create Duration.minutes(15))
let weekly_cutoff: Date_Time := started_at.add(create Duration.weeks(1))

print("started at " + started_at.format_iso())
print("month=" + started_at.month_name())
print("weekday=" + started_at.weekday())
print("weekday-name=" + started_at.weekday_name())
print("day-of-year=" + started_at.day_of_year())
print("next run at " + next_run.truncate_to_hour().format_iso())
print("weekly cutoff " + weekly_cutoff.truncate_to_day().format_iso())

This is a better fit for logging and scheduling code than manually building timestamp strings.

Pattern Matching And Text Cleanup

Use text/Regex when string operations alone are too weak for validation, token extraction, or cleanup.

intern text/Regex

let word: Regex := create Regex.compile_with_flags("[a-z]+", "i")
print(word.matches("Nex"))
print(word.find("123 Nex 456"))
print(word.find_all("one two THREE"))

let comma: Regex := create Regex.compile(",")
print(comma.split("a,b,c"))
print(word.replace("v1 test v2", "#"))

This is useful for:

• validating input formats
• extracting tokens from mixed text
• splitting delimited text
• performing cleanup and rewrite passes

Keep regex usage near parsing and validation boundaries. Higher-level domain logic should usually work on already structured values.

HTTP and Network Services

The net library provides client and server building blocks when a Nex program needs to talk over HTTP.

intern net/Http_Client

let client: Http_Client := create Http_Client.make()
let sample: Http_Response := create Http_Response.make(
  200,
  "ok",
  {"content-type": "text/plain"}
)

print(sample.status())
print(sample.body())

For server-side code, Http_Server and related request/response classes let a program register handlers and return structured responses. This is host-backed functionality, so exact behavior can differ between runtimes.

Collections as Library Foundations

Much of the practical “standard library” feel of Nex comes from Array, Map, and Set.

Use arrays for:

• ordered sequences
• stacks and queues
• accumulation of results

Use maps for:

• lookups by key
• counters and tables
• grouped data

Use sets for:

• membership tests
• removing duplicates
• set algebra such as union and intersection

These classes are generic and work with user-defined classes just as naturally as with built-in scalar values.

intern data/Byte_Array

let buf: Byte_Array := create Byte_Array.make(4)
buf.set(0, 200u8)
buf.set(3, 65u8)
print(buf.get(0))              -- 200
print(buf)                     -- Byte_Array([200, 0, 0, 65])
print(buf.slice(2, 4))         -- Byte_Array([0, 65])
print(buf.to_hex())            -- "c8000041"
across buf as b do
  print(b)                     -- each b is a Byte
end

intern data/Byte_Array
import java.security.MessageDigest

let input: Byte_Array := create Byte_Array.from_array("abc".to_bytes())
let digest: Any := nil
with "java" do
  let md := MessageDigest.getInstance("SHA-256")
  digest := md.digest(input.to_java())
end
let out: Byte_Array := create Byte_Array.from_java(digest)
print(out.length())                 -- 32
print(out.slice(0, 4).to_array())   -- [186, 120, 22, 191]

Cursors and across

The across loop depends on cursor types behind the scenes:

• ArrayCursor
• StringCursor
• MapCursor
• SetCursor
• Byte_Array_Cursor, returned by Byte_Array.cursor(); its items are Bytes

You will usually not construct these directly. Each is a Cursor[T], and every collection that hands one out is an Iterable[T]; that is what makes one iteration form work uniformly across strings, arrays, sets, maps, and classes of your own (Section 15.8).

Library Design Advice

Use the runtime library in layers.

At the core:

• plain functions
• classes with contracts
• arrays, maps, and sets

At the edge:

• console I/O
• files
• environment access
• imported host-platform code

This separation keeps the program testable and helps contracts remain meaningful.

Result and Option

Two small sum-type libraries handle the recurring shapes of “success or failure” and “present or absent.” Both are loaded with intern and both are documented in full in the language reference.

data/Result provides Result[T, E] — either Ok carrying a value of type T, or Err carrying an error of type E:

intern data/Result

let r: Result[Integer, String] := create Ok[Integer, String].make(42)
print(r.unwrap_or(0))     -- 42

match r of
  Ok(value)  then print(value)
  Err(error) then print(error)
end

Query and unwrap are methods: is_ok, is_err, unwrap_or. Transformations are free functions, since each introduces a new type: result_map (map the success value), result_and_then (chain a fallible step, short-circuiting on the first error), and result_map_err (convert the error type).

data/Option provides Option[T] — either Some carrying a value, or None. It is a typed, exhaustively-checked alternative to a detachable ?T, with methods is_some, is_none, get_or, and the combinators option_map, option_and_then, option_filter.

intern data/Option

let o: Option[Integer] := create Some[Integer].make(10)
print(o.get_or(0))        -- 10

Both run on the JVM interpreter and compiled backends. (The combinator functions do not yet run under the generated-JavaScript backend.)

What Is Not Here

Nex does not try to ship a huge standard library inside the tutorial material. The core design assumes that:

• the language itself stays compact
• built-in services cover common educational and practical needs
• larger integration needs are handled through intern and import

That is what Chapter 24 is for. The standard library is enough to be productive, but it is not meant to be the whole world.

Quick Reference

For the complete, up-to-date method reference — covering built-in functions, scalar types, collection types, cursor types, system classes, and all shipped libraries — see the Nex Reference.