The Fly standard library is organised in namespaces. Import a namespace with import, then call its functions through the namespace's last segment (import fly.str → str.len(...)). const parameters are read-only inputs; the return value is assigned directly at the call site.
This reference documents the library shipped with Fly 0.14.9. Every public function of std/lib is listed with the signature it has in the source.
Conventions and guarantees
Calling style. Import the namespace and use the short prefix. Classes, structs and enums are imported by name (import fly.data.List). A fully qualified call such as fly.str.len(...) is not the convention.
Reporting failure. The library does not yet report failure in one uniform way. Each function documents its own, and it is one of these:
| Convention | Meaning | Modules |
|---|---|---|
| Sentinel result | a value that cannot be a success: fd < 0, 0, "", an empty buffer, a null handle | fly.os.fs, fly.os.io, fly.os.env, fly.net, fly.net.tls |
bool result | true on success | socket options, HTTP downloads, archive extraction |
int errOut parameter | set to 0 on success, otherwise a documented code | fly.codec, fly.json, fly.targz |
| Zero value | a missing element reads as 0 / "" / null | fly.data |
fail | the language's own error model | fly.assert |
A function never aborts the process on an ordinary failure; always test the result before using it.
Ownership. A returned string is yours and is released automatically. A returned struct is a value. A returned class instance, or an opaque pointer handle, must be released with the matching free/close function named in its section.
Handles. Several modules hand out an opaque pointer (JSON values, poll sets, multipart builders, tar readers, argument lists) or a long (sockets). They are not type-checked: passing a handle to a function of another module compiles. Keep each handle with the module that created it.
Text. A string is a sequence of bytes. Lengths, indices and case conversion are byte-oriented and ASCII-only; UTF-8 text passes through unchanged but is not interpreted.
Thread safety. Unless a section says otherwise, nothing in the library is safe to share between threads without a fly.sync lock.
See Conformance for the security-relevant limits of individual modules.
fly.str
String utilities. Transform functions return a heap-allocated string — the caller is responsible for freeing it.
import fly.strConversion
convert
public string convert(const int src)
Returns the decimal string representation of src.
string s = str.convert(42) // s = "42"convertL
public string convertL(const long src)
Returns the decimal string representation of a 64-bit long. convert takes an int only.
string s = str.convertL(5000000000) // s = "5000000000"
Query
len
public int len(const string src)
Returns the number of characters in src.
isEmpty
public bool isEmpty(const string src)
Returns true if src has zero length.
equals
public bool equals(const string a, const string b)
Returns true if a and b are identical.
equalsIgnoreCase
public bool equalsIgnoreCase(const string a, const string b)
Returns true if a and b are equal ignoring case.
contains
public bool contains(const string src, const string sub)
Returns true if sub appears anywhere in src.
startsWith
public bool startsWith(const string src, const string prefix)
Returns true if src begins with prefix.
endsWith
public bool endsWith(const string src, const string suffix)
Returns true if src ends with suffix.
indexOf
public int indexOf(const string src, const string sub)
Returns the index of the first occurrence of sub in src, or -1 if not found.
lastIndexOf
public int lastIndexOf(const string src, const string sub)
Returns the index of the last occurrence of sub in src, or -1 if not found.
count
public int count(const string src, const string sub)
Returns the number of non-overlapping occurrences of sub in src.
Example:
import fly.str
void main() {
string msg = "Hello, Fly!"
int length = str.len(msg) // length = 11
bool empty = str.isEmpty(msg) // empty = false
bool found = str.contains(msg, "Fly") // found = true
}
Bytes
byteAt
public byte byteAt(const string s, const int i)
The i-th byte of s. The public way to read string bytes without calling fly.llvm directly.
byte b = str.byteAt("abc", 1) // b = 98 ('b')fromBytes
public string fromBytes(const pointer ptr, const int size)
Builds a string value from a raw buffer and a byte length. Takes ownership of the buffer: the string frees it, so the caller must not free it as well.
string s = str.fromBytes(buf, n)
Characters
Fly has no character type: a character is a string of one character. A
string is a sequence of bytes (len, byteAt, substring, indexOf count
bytes); its text is UTF-8, and these functions count characters — Unicode
code points, 1 to 4 bytes each — from 0.15.0. A byte that does not start a valid
UTF-8 sequence (a stray continuation byte, an overlong form, a surrogate, a value
past 10FFFF, a truncated sequence) is one character of one byte, read as U+FFFD.
public int charCount(const string s) // number of characters
public string charAt(const string s, const int i) // character i as a string ("" past the end)
public List<string> chars(const string s) // every character, in order
public int charCode(const string s, const int i) // code point of character i (-1 past the end)
public string fromCharCode(const int cp) // the character with that code point
public bool isUtf8(const string s) // every byte part of a valid sequence?
public string reverse(const string s) // characters in reverse order
public string padLeft(const string s, const int width, const string fill)
public string padRight(const string s, const int width, const string fill)
charAt and charCode scan the string from the start (UTF-8 has no fixed
width): to visit every character, iterate over chars(s). padLeft and
padRight count characters: str.padLeft("7", 3, "0") is "007"; a fill of
several characters is repeated and cut to the width; an empty fill changes
nothing.
List<string> cs = str.chars("caf\u{E9}") // "c", "a", "f", "é"
int i = 0
while i < (int)cs.size() {
string c = cs.get(i)
i = i + 1
}Split, join, compare, search
public List<string> split(const string s, const string sep)
public string join(const List<string> parts, const string sep)
public int compare(const string a, const string b)
public int indexOfFrom(const string src, const string sub, const int from)
public string replaceFirst(const string src, const string from, const string to)
splitkeeps empty parts ("a,,b"→"a","","b";""→ one empty part); an emptysepsplits into characters.joinputssepbetween each two parts.comparereturns-1,0or1, byte by byte — for UTF-8 text, the order of the code points; a prefix sorts first.indexOfFromisindexOfstarting at bytefrom.replaceFirstreplaces only the first occurrence (replacereplaces all).
Parsing
public long toLong(const string s, int errOut)
public int toInt(const string s, int errOut)
The decimal integer s spells: an optional sign, then digits, nothing else (no
blanks). errOut: 0 ok, 1 not a number, 2 out of the range of the type;
on an error the result is 0.
int e = 0
int port = str.toInt("8080", e) // 8080, e = 0
int bad = str.toInt("80a", e) // 0, e = 1
Floating-point parsing and formatting (
toDouble, adouble→stringconversion) are not in the standard library yet.
Transform
toUpper
public string toUpper(const string src)
Returns an upper-case copy of src.
toLower
public string toLower(const string src)
Returns a lower-case copy of src.
trim
public string trim(const string src)
Returns a copy of src with leading and trailing whitespace removed.
trimLeft
public string trimLeft(const string src)
Returns a copy of src with leading whitespace removed.
trimRight
public string trimRight(const string src)
Returns a copy of src with trailing whitespace removed.
substring
public string substring(const string src, const int start, const int end)
Returns the substring of src from index start (inclusive) to end (exclusive).
replace
public string replace(const string src, const string from, const string to)
Returns a copy of src with all occurrences of from replaced by to.
repeat
public string repeat(const string src, const int count)
Returns src repeated count times.
concat
public string concat(const string a, const string b)
Returns the concatenation of a and b.
Example:
import fly.str
void main() {
string result = str.concat("Hello, ", "Fly!") // result = "Hello, Fly!"
result = str.toUpper(result) // result = "HELLO, FLY!"
}
fly.math
Mathematical functions and a random-number generator (xoshiro256**).
import fly.mathTypes
public struct fly_rng {
ulong s0
ulong s1
ulong s2
ulong s3
}
State for the xoshiro256** PRNG. Initialise with randSeed before use.
Base
absI / absF
public long absI(const long x)
public double absF(const double x)
Absolute value for integers and floats.
sign
public int sign(const double x)
Returns 1 if x > 0, -1 if x < 0, 0 if x == 0.
minI / minF
public long minI(const long a, const long b)
public double minF(const double a, const double b)
Returns the smaller of a and b.
maxI / maxF
public long maxI(const long a, const long b)
public double maxF(const double a, const double b)
Returns the larger of a and b.
clampI / clampF
public long clampI(const long x, const long lo, const long hi)
public double clampF(const double x, const double lo, const double hi)
Clamps x to the range [lo, hi].
gcd
public long gcd(const long a, const long b)
Greatest common divisor of a and b.
lcm
public long lcm(const long a, const long b)
Least common multiple of a and b.
divmod
public void divmod(const long a, const long b, long out_q, long out_r)
Writes quotient into out_q and remainder into out_r.
Wrapping arithmetic
From 0.15.0 an integer +, - or * whose result does not fit its type stops the
program (see the Language Reference §8.3.1). Code that wants two's-complement
wrapping — hashes, checksums, pseudo-random generators — asks for it with these
functions: the result is the exact one reduced modulo 2^bits.
public int wrapAdd(const int a, const int b) // also wrapSub, wrapMul
public uint wrapAddU(const uint a, const uint b) // also wrapSubU, wrapMulU
public long wrapAddL(const long a, const long b) // also wrapSubL, wrapMulL
public ulong wrapAddUL(const ulong a, const ulong b) // also wrapSubUL, wrapMulULint r = math.wrapAdd(2147483647, 1) // -2147483648
h = math.wrapMulL(h ^ c, 1099511628211) // FNV-1a step
Trigonometry
public double sin(const double x)
public double cos(const double x)
public double tan(const double x)
public double asin(const double x)
public double acos(const double x)
public double atan(const double x)
public double atan2(const double y, const double x)
public double sinh(const double x)
public double cosh(const double x)
public double tanh(const double x)
public double hypot(const double a, const double b)toRadians / toDegrees
public double toRadians(const double x)
public double toDegrees(const double x)
Convert between degrees and radians.
Exponential & Logarithms
public double sqrt(const double x)
public double cbrt(const double x)
public double pow(const double base, const double exp)
public double exp(const double x)
public double exp2(const double x)
public double log(const double x)
public double log2(const double x)
public double log10(const double x)
public double logN(const double x, const double n)
logN computes log base n of x.
Rounding
public double floor(const double x)
public double ceil(const double x)
public double round(const double x)
public double trunc(const double x)
public double roundTo(const double x, const int n)
roundTo(x, n) rounds x to n decimal places (negative n rounds to tens, hundreds, …).
Classification
isNaN / isInf / isFinite
public bool isNaN(const double x)
public bool isInf(const double x)
public bool isFinite(const double x)approxEqual
public bool approxEqual(const double a, const double b, const double epsilon)
Returns true if |a − b| ≤ epsilon.
copySign
public double copySign(const double x, const double y)
Returns x with the sign of y.
Bitwise
public bool isPow2(const long n)
public long nextPow2(const long n)
public int popcount(const long n)
public int leadingZeros(const long n)
public int trailingZeros(const long n)
Random (xoshiro256**)
randSeed
public void randSeed(fly_rng rng, const ulong seed)
Seeds the RNG state from seed using SplitMix64.
rngNext
public ulong rngNext(fly_rng rng)
Advances the RNG and returns the next raw 64-bit value (also updates rng).
randFloat
public double randFloat(fly_rng rng)
Returns a uniformly distributed double in [0, 1).
randInt
public long randInt(fly_rng rng, const long a, const long b)
Returns a uniformly distributed integer in [a, b].
randNormal
public double randNormal(fly_rng rng, const double mu, const double sigma)
Returns a sample from the normal distribution N(μ, σ) using Box-Muller.
Special functions
public double fma(const double a, const double b, const double c)
public double lerp(const double a, const double b, const double t)
public double saturate(const double x)
public long factorialI(const int n)
public double factorialF(const int n)
public long comb(const long n, const long k)
public long perm(const long n, const long k)
public double erf(const double x)
public double erfc(const double x)
public double gamma(const double x)
public double asinh(const double x)
public double acosh(const double x)
public double atanh(const double x)
fma(a, b, c) = a*b + c (fused multiply-add).
lerp(a, b, t) = a*(1−t) + b*t.
saturate(x) clamps x to [0, 1].
Example:
import fly.math
void main() {
fly_rng rng = new fly_rng()
math.randSeed(rng, 42)
double v = math.randFloat(rng) // v in [0, 1)
long n = math.randInt(rng, 1, 10) // n in [1, 10]
double s = math.sqrt(2.0) // s ≈ 1.4142
}
fly.mem
Raw memory operations and typed read/write primitives. Addresses, sizes and
offsets are all pointer — the pointer-width unsigned integer — never long.
import fly.mem
fly.memis unsafe by nature: nothing checks that an address is valid, that an offset stays inside the block, or that a block is freed once. Prefer thefly.datacontainers andstringin application code. It is also the only raw-memory module user code may call: from 0.15.0fly.llvmandfly.runtimeare reserved to the standard library (Language Reference §10.4), so searching a program forfly.memfinds all of its unsafe code.
Allocation
alloc
public pointer alloc(const pointer size)
Allocates size bytes and returns the address. The memory is not zeroed.
realloc
public pointer realloc(const pointer ptr, const pointer newSize)
Resizes the block at ptr to newSize bytes and returns its (possibly new) address.
free
public void free(const pointer ptr, const pointer size)
Releases a block obtained from alloc or realloc. size is the size of the block.
isNull
public bool isNull(const pointer ptr)
Returns true when ptr is the null address.
Bulk operations
public void copy(const pointer dst, const pointer src, const pointer size)
public void move(const pointer dst, const pointer src, const pointer size)
public void zero(const pointer dst, const pointer size)
public int compare(const pointer a, const pointer b, const pointer size)
copy— copiessizebytes; the ranges must not overlap (memcpy).move— copiessizebytes; the ranges may overlap (memmove).zero— setssizebytes to zero.compare— comparessizebytes; returns0when equal, otherwise a negative or positive value according to the first differing byte (memcmp).
Typed reads
public byte readByte(const pointer ptr, const pointer offset)
public short readShort(const pointer ptr, const pointer offset)
public int readInt(const pointer ptr, const pointer offset)
public long readLong(const pointer ptr, const pointer offset)
public pointer readPtr(const pointer ptr, const pointer offset)
Read a value at ptr + offset. Offsets are in bytes. readPtr reads a
pointer-sized address, so an address stored in a buffer stays typed pointer
end to end.
Typed writes
public void writeByte(const pointer ptr, const pointer offset, const byte val)
public void writeShort(const pointer ptr, const pointer offset, const short val)
public void writeInt(const pointer ptr, const pointer offset, const int val)
public void writeLong(const pointer ptr, const pointer offset, const long val)
public void writePtr(const pointer ptr, const pointer offset, const pointer val)
Example:
import fly.mem
void main() {
pointer buf = mem.alloc(16)
mem.zero(buf, 16)
mem.writeInt(buf, 0, 42)
mem.writeLong(buf, 8, 7)
int a = mem.readInt(buf, 0) // 42
long b = mem.readLong(buf, 8) // 7
mem.free(buf, 16)
}
fly.os.env
Process environment, command-line arguments, working directory, and process control.
import fly.os.envTypes
public struct StringArray {
long items
int count
}
A heap-allocated array of Fly strings returned by functions that produce variable-length string lists.
Environment variables
get
public string get(const string key)
Returns the value of environment variable key, or an empty string if not set.
set
public void set(const string key, const string value)
Sets key to value, overwriting any existing value.
del
public void del(const string key)
Removes key from the environment. No-op if not present. Named del from 0.15.0
(it was delete, a keyword from 0.15.0).
all
public StringArray all()
Returns all environment variables as "KEY=VALUE" strings.
stringArrayFree
public void stringArrayFree(StringArray a)
Releases every string of a and the slot array itself, then empties it, so a second call is harmless. Use it on what all, argsGet, path.glob, path.comp and io.readLines return.
allCount
public pointer allCount()
Returns the number of environment variables currently set.
expand
public string expand(const string s)
Replaces $VAR and ${VAR} references in s with their values. Unknown variables expand to an empty string. The result grows as needed, and a variable name may be of any length.
Working directory
cwdGet
public string cwdGet()
Returns the current working directory path.
cwdSet
public void cwdSet(const string path)
Changes the current working directory to path.
Arguments & system info
argsGet
public StringArray argsGet()
Returns all command-line arguments (args[0] is the executable path).
argsCount
public pointer argsCount()
Returns the number of command-line arguments (including argv[0]).
hostname
public string hostname()
Returns the system hostname, or an empty string on failure.
osname
public string osname()
Returns the OS name, e.g. "linux" or "darwin".
arch
public string arch()
Returns the host CPU architecture, e.g. "x86_64" or "aarch64". Empty string on failure.
kernel · kernelVersion
public string kernel()
public string kernelVersion()
kernel returns the kernel release (e.g. "7.0.0-22-generic"); kernelVersion returns the kernel's version banner. Empty string on failure.
endianness
public string endianness()
Returns "little" or "big", the byte order of the host, determined at run time.
platform
public string platform()
Returns one line describing the host — OS, architecture, kernel release and version, hostname and byte order — as space-separated key=value fields. Built on the functions above.
exePath
public string exePath()
Returns the absolute path of the running executable, resolved independently of argv[0]. Empty string on failure. Prefer it to argsGet() index 0, which is the raw argv[0] and may be a bare name.
exit
public void exit(const int code)
Terminates the process with the given exit code. Never returns.
fly.os.fs
File system operations.
import fly.os.fsTypes
public struct File {
int fd
byte flags
}
An open OS file descriptor. Obtain via open(), create(), or openOpts(); release via close().
public struct Stat {
ulong size
ulong mtime_sec
ulong mtime_nsec
uint mode
int is_file
int is_dir
int is_symlink
}
File metadata. Times are Unix epoch seconds/nanoseconds.
public struct DirEntry {
string name
Stat stat
}
A single directory entry with its basename and metadata.
public struct DirEntries {
long items
ulong len
ulong cap
}
A heap-allocated array of DirEntry values.
Open / close
open
public File open(const string path)
Opens path for reading (O_RDONLY). Check .fd >= 0 on the returned File for success.
create
public File create(const string path)
Creates or truncates path for writing (O_WRONLY|O_CREAT|O_TRUNC, mode 0644).
openOpts
public File openOpts(const string path, const int flags, const int perm)
Opens path with explicit flags and permission bits (follow open(2) conventions).
close
public void close(File f)
Closes the file descriptor of f.
sync
public void sync(File f)
Calls fsync on f, flushing OS buffers to persistent storage.
Read / write (path-based)
read
public fly.os.io.Buf read(const string path)
Reads the entire file at path into a heap-allocated Buf. The returned Buf has size == 0 if the file is empty or missing.
readStr
public string readStr(const string path)
Reads the entire file at path and returns its contents as a string.
write
public void write(const string path, fly.os.io.Buf data, const int perm)
Writes data to path, creating or truncating the file.
writeStr
public void writeStr(const string path, const string content, const int perm)
Writes string content to path, creating or truncating the file.
append
public void append(const string path, fly.os.io.Buf data, const int perm)
Appends data to path, creating the file if needed.
appendStr
public void appendStr(const string path, const string content, const int perm)
Appends string content to path, creating the file if needed.
Binary read / write
readStr and writeStr go through the platform CRT in text mode. On
Windows that means a read collapses \r\n into \n and stops at a 0x1A
byte, and a write expands every \n into \r\n. For source text that is
harmless; for a tarball, an image or any other byte-exact payload it is silent
corruption. These two switch the descriptor to binary mode before a single byte
moves, and are ordinary text I/O on POSIX, where nothing is translated.
readBytes
public string readBytes(const string path)
Reads the whole file verbatim — no newline translation, no early stop at
0x1A. Empty when the file is empty or missing.
writeBytes
public void writeBytes(const string path, const string content, const int perm)
Writes content verbatim, with no newline translation. Use this for any
payload that is not source text.
Seek
seekTo
public long seekTo(File f, const long offset, const int whence)
Moves the file offset. whence: 0=SEEK_SET, 1=SEEK_CUR, 2=SEEK_END. Returns the new offset.
seekPos
public long seekPos(File f)
Returns the current file offset (SEEK_CUR with offset 0).
Metadata
stat / lstat
public Stat stat(const string path)
public Stat lstat(const string path)
stat follows symlinks; lstat reports the symlink itself.
size
public ulong size(const string path)
Returns the byte size of the file. Returns 0 if the file does not exist.
exists
public bool exists(const string path)
Returns true if path exists (any file type).
isFile / isDir
public bool isFile(const string path)
public bool isDir(const string path)
File operations
truncate
public void truncate(const string path, const long size)
Truncates the file to exactly size bytes (extends with null bytes if shorter).
chmod
public void chmod(const string path, const int mode)
Changes the permission bits of path (e.g. 0644 = 420).
del
public void del(const string path)
Removes the file or empty directory at path. Named del from 0.15.0 (it was
delete, a keyword from 0.15.0).
copy
public void copy(const string src, const string dst)
Copies the file at src to dst (creates or truncates dst, mode 0644).
move / rename
public void move(const string src, const string dst)
public void rename(const string src, const string dst)
Renames src to dst (aliases for rename(2)).
Directory operations
dirCreate
public void dirCreate(const string path, const int perm)
Creates a single directory. Fails if any parent is missing.
dirCreateAll
public void dirCreateAll(const string path, const int perm)
Creates path and all missing parent directories (mkdir -p).
dirDelete
public void dirDelete(const string path)
Removes an empty directory.
dirDeleteAll
public void dirDeleteAll(const string path)
Removes path and all its contents recursively (rm -rf).
dirRead
public DirEntries dirRead(const string path)
Returns all entries in the directory at path.
dirEntriesFree
public void dirEntriesFree(DirEntries d)
Releases every entry name and the entry array of what dirRead returned, then empties d, so a second call is harmless.
Symlinks & temporary files
symlinkCreate
public void symlinkCreate(const string target, const string link)
Creates a symbolic link link pointing to target.
symlinkRead
public string symlinkRead(const string path)
Returns the target of the symbolic link at path.
tempFile
public string, File tempFile(const string dir, const string pattern)
Creates a temporary file in dir using pattern as a name template. Returns the path and an open File.
tempDir
public string tempDir(const string dir, const string pattern)
Creates a temporary directory. Returns its path.
fly.os.io
Byte-stream I/O interfaces and utilities.
import fly.os.ioTypes
public struct Buf {
long ptr
ulong size
ulong cap
}
A heap-allocated byte buffer. ptr points to the first byte; size is the number of valid bytes; cap is the total allocated capacity.
public interface Reader {
long read(Buf buf, const ulong n)
void close()
}
Sequential byte-stream source. read fills buf with up to n bytes and returns the count read; returns 0 at EOF.
public interface Writer {
long write(Buf buf, const ulong n)
void flush()
void close()
}
Sequential byte-stream sink. write sends up to n bytes from buf and returns the count written.
public class FileReader : Reader { int fd }
public class FileWriter : Writer { int fd }
public class BufReader : Reader { ... }
public class BufWriter : Writer { ... }
Constructor helpers
fileReader
public Reader fileReader(const int fd)
Wraps a raw OS file descriptor as a Reader.
fileWriter
public Writer fileWriter(const int fd)
Wraps a raw OS file descriptor as a Writer.
readerNew
public BufReader readerNew(Reader inner, const ulong cap)
Wraps inner in a BufReader with a cap-byte internal buffer.
writerNew
public BufWriter writerNew(Writer inner, const ulong cap)
Wraps inner in a BufWriter with a cap-byte internal buffer.
Buffered I/O
A BufReader / BufWriter is driven through the free functions below.
Call these functions, not the methods of
BufReader/BufWriter(available(),refill(),bufAt(),takeByte(),flush()…). Outsidefly.os.io, a direct method call on these classes reads the wrong state; the functions, and calls through theReader/Writerinterfaces, are correct.
bufRead
public long bufRead(BufReader r, Buf buf, const ulong n)
Reads up to n bytes from r into buf. Returns the number of bytes read, 0 at end of input.
bufReadLine
public string bufReadLine(BufReader r)
Reads one line and returns it without the trailing LF; a trailing CR is dropped too, so CRLF input works. Returns "" at end of input. A line may be longer than the buffer.
peek
public Buf peek(BufReader r, const ulong n)
Returns up to n buffered bytes without consuming them. The returned Buf borrows the reader's storage: it is valid only until the next read, fill or close, and must not be freed. A short result is normal; size 0 means end of input.
fill
public void fill(BufReader r)
Refills the internal buffer from the inner reader once every buffered byte has been consumed. Does nothing while data is still pending.
bufAvailable
public ulong bufAvailable(BufReader r)
Returns the number of bytes buffered and not yet consumed.
bufClose
public void bufClose(BufReader r)
Releases the read-ahead buffer and closes the inner reader.
bufWrite
public void bufWrite(BufWriter w, Buf buf)
Writes the valid bytes of buf into w, flushing to the inner writer as the internal buffer fills.
bufFlush
public void bufFlush(BufWriter w)
Drains the internal buffer into the inner writer.
bufWriterClose
public void bufWriterClose(BufWriter w)
Flushes anything pending, releases the buffer and closes the inner writer. Always close a BufWriter this way: bytes still buffered when it is dropped are lost.
writeNL
public void writeNL(Writer w)
Writes a single newline byte (0x0A) to w. From 0.15.0 a string literal can hold it too ("\n"); up to 0.14.x literals were raw and this function was the only way.
Read utilities
readAll
public Buf readAll(Reader r)
Reads from r until EOF and returns all data in a freshly allocated Buf. A read that reports an error (a negative count) ends the loop like EOF does.
bufFree
public void bufFree(Buf b)
Releases a Buf's memory and empties it, so a second call is harmless. Every Buf returned by readAll, readExact, peek or fs.read owns its bytes.
A Reader, Writer, BufReader or BufWriter object cannot be released from Fly: there is no way to free a class handle. close (or bufClose / bufWriterClose) gives back the internal buffer and the descriptor, which is everything but the handle itself.
readLine
public string readLine(Reader r)
Reads bytes until '\n' or EOF and returns the line content (without the trailing newline).
readExact
public Buf readExact(Reader r, const ulong n)
Reads exactly n bytes, looping over short reads.
Neither readAll nor a bare read can frame a length-delimited message on a
stream that never ends: readAll waits for EOF, and a read is allowed to return
fewer bytes than asked for. The returned Buf's size is the only sentinel — a
size below n means EOF (or an error) arrived first.
readLines
public fly.os.env.StringArray readLines(Reader r)
Reads all lines from r until EOF and returns them as a StringArray.
Binary mode
setBinaryMode
public bool setBinaryMode(const int fd)
Stops the platform CRT from translating this descriptor's bytes; a no-op on
POSIX, where nothing is translated. Returns false on error.
On Windows the UCRT opens descriptors in text mode: reads collapse \r\n into
\n and stop at a 0x1A byte, writes expand every \n into \r\n. Any
byte-exact protocol must call this on its descriptors first — a
Content-Length: framed stream over stdio is destroyed without it. For files,
use fs.readBytes / fs.writeBytes, which do this themselves.
Write utilities
writeAll
public bool writeAll(Writer w, Buf buf)
Writes all bytes of buf to w. Returns true on success. A FileWriter loops over short writes and reports a failed write as -1, so a write that did not go through comes back as false here.
writeString
public bool writeString(Writer w, const string s)
Writes the bytes of string s to w. Returns true on success.
Copy utilities
copy
public long copy(Reader src, Writer dst)
Copies all bytes from src to dst until EOF. Returns the total byte count.
copyN
public long copyN(Reader src, Writer dst, const ulong n)
Copies at most n bytes from src to dst. Returns the actual count.
pipe
public long pipe(Reader pipe_r, Writer pipe_w)
Alias for copy.
Console output
print / printLn
public void print(const string s)
public void printLn(const string s)
Write s to stdout. printLn appends a newline.
printErr / printErrLn
public void printErr(const string s)
public void printErrLn(const string s)
Write s to stderr. printErrLn appends a newline.
Example:
import fly.os.fs
import fly.os.io
void main() {
fly.os.fs.File f = fs.open("notes.txt")
Reader r = io.fileReader(f.fd)
string line = io.readLine(r)
io.printLn(line)
r.close()
}
fly.os.path
Path manipulation utilities.
import fly.os.pathComposition
join
public string join(const string base, const string comp)
Joins base and comp with exactly one / separator.
joinN
public string joinN(fly.os.env.StringArray parts)
Joins the segments of parts left to right with join: joinN of {"a", "b", "c"} is join(join("a", "b"), "c"). An empty array gives "". The array is only read — its strings stay the caller's to release.
absolute
public string absolute(const string path)
Returns the absolute form of path (resolves relative to the current working directory).
normalize
public string normalize(const string path)
Resolves . and .. components and removes duplicate separators. A .. a RELATIVE path cannot resolve is kept ("../a" stays "../a", "a/../../b" becomes "../b"); at the root of an absolute path it is dropped ("/../a" is "/a").
normalizeInPlace
public void normalizeInPlace(string path)
Normalizes path in place (modifies the string directly).
rel
public string rel(const string base, const string target)
Returns the relative path from base to target. Both are normalized first, and "." counts as the empty relative path, so rel(".", "a") is "a".
Decomposition
basename
public string basename(const string path)
Returns the last path component (filename with extension).
dirname
public string dirname(const string path)
Returns all but the last path component.
ext
public string ext(const string path)
Returns the file extension including the leading dot, or an empty string. A dot that STARTS the basename marks a hidden file rather than an extension, so ext(".bashrc") is empty and stem(".bashrc") is ".bashrc".
stem
public string stem(const string path)
Returns the filename without extension.
split
public string, string split(const string path)
Returns (dirname, basename) as two values.
splitExt
public string, string splitExt(const string path)
Returns (stem, ext) as two values.
comp
public fly.os.env.StringArray comp(const string path)
Returns all path components as a StringArray.
compCount
public int compCount(const string path)
Returns the number of path components.
sep
public byte sep()
Returns the platform path separator byte (/ on Unix).
Predicates
isAbsolute / isRelative
public bool isAbsolute(const string path)
public bool isRelative(const string path)isFile / isDir / isSym
public bool isFile(const string path)
public bool isDir(const string path)
public bool isSym(const string path)
Glob & pattern matching
glob
public fly.os.env.StringArray glob(const string pattern)
Returns all paths matching the glob pattern.
globCount
public int globCount(const string pattern)
Returns the count of paths matching pattern.
match
public bool match(const string pattern, const string name)
Returns true if name matches the glob pattern.
fly.os.proc
Spawning child processes. No shell is involved: the program is executed
directly with an argument vector, so nothing here depends on /bin/sh — which
does not exist on Windows — and no argument needs quoting.
import fly.os.procTypes
An ArgList is an opaque pointer handle, not a class: a header-declared
class carrying a generic does not survive the archive boundary intact. Build it
with argsNew, fill it with argsAdd, release it with argsFree. Pass 0 for
a command that takes no arguments.
Argument lists
argsNew
public pointer argsNew()
Allocates an empty ArgList and returns its handle.
argsAdd
public void argsAdd(const pointer h, const string a)
Appends a copy of a to the list, growing it if needed.
argsFree
public void argsFree(const pointer h)
Releases the list and every string it owns.
Execution
exec
public int exec(const string path, const pointer h)
Spawns path with argv[0] = path followed by the ArgList arguments (h may
be 0), inherits the environment and waits. Returns the child's exit code
(0–255), 128 + signo if it was killed by a signal, or -1 if the spawn
failed.
run
public int run(const string path)
Convenience: exec with no extra arguments.
execCapture
public int execCapture(const string path, const pointer h, const string outPath)
Like exec, but the child's stdout is redirected to outPath (created and
truncated); the caller reads the file afterwards. Same return contract as
exec.
stderr is inherited, not discarded — a failing command's diagnostics reach the user instead of vanishing.
import fly.os.proc
import fly.os.fs
void main() {
pointer args = proc.argsNew()
proc.argsAdd(args, "rev-parse")
proc.argsAdd(args, "HEAD")
int rc = proc.execCapture("git", args, "head.txt")
proc.argsFree(args)
if rc == 0 {
string sha = fs.readStr("head.txt")
}
}
fly.os.time
Wall clock, monotonic clock, durations, and date formatting.
import fly.os.timeTypes
public struct Time {
long sec
long nsec
}
An absolute point in time (seconds + nanoseconds since the Unix epoch). Negative values represent times before 1970.
public struct Duration {
long nsec
}
An elapsed time interval stored as a nanosecond count.
Current time
now
public Time now()
Returns the current wall-clock time (UTC, Unix epoch).
monotonic
public Time monotonic()
Returns the current monotonic clock value. Use for measuring elapsed time.
nowSec
public long nowSec()
Returns the current Unix timestamp in seconds.
Arithmetic
since
public Duration since(Time t)
Returns the Duration elapsed since t (i.e., now − t).
diff
public Duration diff(Time a, Time b)
Returns b − a. Negative if b is before a.
add
public Time add(Time t, Duration d)
Returns t advanced by duration d.
compare
public int compare(Time a, Time b)
Returns -1 if a < b, 0 if equal, 1 if a > b.
Conversions
unix / unixNano
public long unix(Time t)
public long unixNano(Time t)
Returns the Unix timestamp in seconds or nanoseconds.
fromUnix / fromUnixNano
public Time fromUnix(const long sec)
public Time fromUnixNano(const long nsec)
Constructs a Time from a Unix timestamp.
Duration helpers
durationSecs / durationMillis / durationMicros
public long durationSecs(Duration d)
public long durationMillis(Duration d)
public long durationMicros(Duration d)
Returns the duration as seconds, milliseconds, or microseconds.
durationFormat
public string durationFormat(Duration d)
Returns a human-readable string such as "1h2m3s".
durationFormatNsec
public string durationFormatNsec(const long nsec)
Same as durationFormat but takes a raw nanosecond count.
Formatting & parsing
format
public string format(Time t, const string pattern)
Formats t using a Go-style reference-time pattern. Recognised tokens:
| Token | Meaning |
|---|---|
2006 | 4-digit year |
01 | month (zero-padded) |
02 | day (zero-padded) |
15 | hour (24 h) |
04 | minute |
05 | second |
All other bytes are emitted verbatim.
formatSec
public string formatSec(const long sec, const string pattern)
Formats a raw Unix timestamp (seconds) using the same pattern tokens.
parse
public Time parse(const string s, const string pattern)
Parses a date/time string s according to pattern. Unrecognised bytes are skipped.
parseToSec
public long parseToSec(const string s, const string pattern)
Same as parse, but returns the result as a Unix timestamp in seconds.
Sleep
sleep
public void sleep(Duration d)
Suspends execution for at least the duration d. Returns immediately if d ≤ 0.
Example:
import fly.os.time
void main() {
Time t0 = time.now()
Duration ms100 = new Duration()
ms100.nsec = 100000000
time.sleep(ms100)
Duration elapsed = time.since(t0)
string s = time.durationFormat(elapsed) // e.g. "100ms"
}
fly.sync
Thread primitives: threads, mutexes, read-write mutexes, wait groups, once guards, and semaphores.
import fly.syncThread
public struct Thread { int id }spawnThread
public Thread spawnThread(const pointer fn, const pointer arg, const ulong stack)
Starts fn(arg) in a new OS thread. fn is the address of the entry function and arg the single address-sized argument it receives. stack = 0 uses the default stack size (1 MiB). Thread.id is -1 when the thread could not be created.
Threads are detached: there is no join. To wait for workers, have each one call wgDone on a shared WaitGroup and call wgWait in the spawning thread.
Mutex
public struct Mutex { long state }
A simple spin/sleep mutual-exclusion lock. Each primitive here keeps its state in a small heap slot; the matching …Free gives it back once no thread can touch the primitive any more, and clears the handle so freeing twice is a no-op.
public Mutex newMutex()
public void mutexLock(Mutex m)
public void mutexUnlock(Mutex m)
public bool mutexTryLock(Mutex m)
public void mutexFree(Mutex m)
RWMutex
public struct RWMutex { long state; long waiters }
A read-write lock: multiple concurrent readers or one exclusive writer.
public RWMutex newRWMutex()
public void rwmutexRlock(RWMutex rw)
public void rwmutexRunlock(RWMutex rw)
public void rwmutexWlock(RWMutex rw)
public void rwmutexWunlock(RWMutex rw)
public void rwMutexFree(RWMutex rw)
WaitGroup
public struct WaitGroup { long state }
Waits for a collection of goroutine-like tasks to finish.
public WaitGroup newWaitGroup()
public void wgAdd(WaitGroup wg, const int n)
public void wgDone(WaitGroup wg)
public void wgWait(WaitGroup wg)
public void waitGroupFree(WaitGroup wg)
wgAdd(wg, n) increments the counter by n. wgDone decrements by 1. wgWait blocks until the counter reaches 0.
Once
public struct Once { long state }
Runs an initialisation block exactly once, regardless of concurrent calls.
public Once newOnce()
public bool onceAcquire(Once o)
public void onceRelease(Once o)
public void onceFree(Once o)
Usage pattern:
if sync.onceAcquire(o) {
// initialisation
sync.onceRelease(o)
}
Semaphore
public struct Semaphore { long state }
A counting semaphore.
public Semaphore newSemaphore(const int initial)
public void semaphoreAcquire(Semaphore s)
public void semaphoreRelease(Semaphore s)
public bool semaphoreTryAcquire(Semaphore s)
public void semaphoreFree(Semaphore s)
fly.data
Generic containers. Every container is a generic class: it lives on the
heap and is released by calling its free() method.
import fly.data.List // one class by name …
import fly.data.Map
import fly.data.* // … or all of them| Class | Structure | Complexity |
|---|---|---|
List<T> | growable contiguous array | append O(1) amortised, index O(1), remove O(n) |
Stack<T> | growable array, LIFO | push/pop O(1) amortised |
Queue<T> | ring buffer, FIFO | enqueue/dequeue O(1) amortised |
Deque<T> | ring buffer, both ends | push/pop at either end O(1) amortised |
Set<T> | hash set, open addressing | add/has/remove O(1) average |
Map<K, V> | hash map, open addressing | put/get/has/remove O(1) average |
Tree<K, V> | unbalanced binary search tree, ordered by key | O(log n) average, O(n) when keys arrive sorted |
Wrapper<T> | single-value holder | — |
Rules common to all containers
Ownership. What a container does with an element depends on the element type:
| Element type | On insert | On remove / clear / free |
|---|---|---|
string | the container stores its own copy | the copy is released |
numbers, bool, enums | copied by value | nothing to release |
| class instances, arrays | the reference is stored | nothing — the object stays yours to free() |
Sizes and indices are pointer, the pointer-width unsigned integer. A
negative index cannot exist.
Missing elements return the zero value. get with an out-of-range index or
an absent key, and pop/peek/dequeue on an empty container, return the zero
value of the element type (0, "", null) — they do not fail. Test with
size(), isEmpty() or has() when a zero value is also a legitimate element.
set and remove with an out-of-range index or absent key do nothing.
Keys. Set, Map and Tree work with integer and string keys. Strings
compare byte-wise; integers compare as signed values.
Thread safety. None. Guard a shared container with a fly.sync mutex.
After free() a container is empty and may be reused or freed again.
List
public class List<T> {
public List()
public void add(const T val)
public T get(const pointer idx)
public void set(const pointer idx, const T val)
public pointer size()
public void remove(const pointer idx)
public void clear()
public void free()
}
A List can be iterated with for … in:
import fly.os.io
import fly.data.List
void main() {
List<string> names = new List<string>()
names.add("apple")
names.add("banana")
names.set(1, "cherry")
for name in names {
io.printLn(name)
}
string first = names.get(0) // "apple"
names.remove(0) // "cherry" is now at index 0
names.free()
}
Stack
public class Stack<T> {
public Stack()
public void push(const T val)
public T pop()
public T peek()
public bool isEmpty()
public pointer size()
public void free()
}
Queue
public class Queue<T> {
public Queue()
public void enqueue(const T val)
public T dequeue()
public T peek()
public bool isEmpty()
public pointer size()
public void free()
}
Deque
public class Deque<T> {
public Deque()
public void pushBack(const T val)
public void pushFront(const T val)
public T popFront()
public T popBack()
public T peekFront()
public T peekBack()
public bool isEmpty()
public pointer size()
public void free()
}
Set
public class Set<T> {
public Set()
public void add(const T key)
public bool has(const T key)
public void remove(const T key)
public pointer size()
public void free()
}
Adding a key that is already present leaves the set unchanged.
Map
public class Map<K, V> {
public Map()
public void put(const K key, const V val)
public V get(const K key)
public bool has(const K key)
public void remove(const K key)
public pointer size()
public void free()
}
put on an existing key replaces its value. The table grows when it is three
quarters full. Strings are hashed with 32-bit FNV-1a and integers by their
value, with no per-process seed — do not key a Map or Set on untrusted input
in a long-running server.
import fly.data.Map
void main() {
Map<string, int> ages = new Map<string, int>()
ages.put("ada", 36)
ages.put("ada", 37) // replaces
if ages.has("ada") {
int a = ages.get("ada") // 37
}
int missing = ages.get("bob") // 0 — indistinguishable from a stored 0
ages.free()
}
Tree
An ordered map: keys are kept in sorted order.
public class Tree<K, V> {
public Tree()
public void put(const K key, const V val)
public V get(const K key)
public bool has(const K key)
public void remove(const K key)
public pointer size()
public void free()
}
The tree is not self-balancing. Inserting keys in ascending or descending
order produces a degenerate tree in which every operation is linear. Use Map
unless you need ordering and your keys arrive in no particular order.
Wrapper<T>
A single-value holder — a mutable box for one T.
public class Wrapper<T> {
public Wrapper(T v)
public T get()
public void set(T v)
}import fly.data.Wrapper
void main() {
Wrapper<int> counter = new Wrapper<int>(42)
counter.set(counter.get() + 1)
int n = counter.get() // 43
}
Not yet available
Map, Set and Tree cannot be iterated and do not expose their keys. There
is no sort, search (contains/indexOf), insertion at an index, or slicing.
These are planned — see the roadmap.
fly.codec
Text encodings. Pure Fly, no FFI. Every decoder reports failure through an
errOut parameter rather than by returning an empty string — decoding an empty
input legitimately yields "".
import fly.codecBase64
base64Encode
public string base64Encode(const string s)
RFC 4648 §4: the +/ alphabet, = padded. Returns "" only for empty input.
base64Decode
public string base64Decode(const string s, int errOut)
Accepts either alphabet and optional padding. errOut: 0 ok, 1 bad
character (whitespace included), 2 impossible length, 3 non-zero leftover
bits.
base64UrlEncode
public string base64UrlEncode(const string s)
RFC 4648 §5: the -_ alphabet, no padding — safe in a URL path, a query
value or a JWT segment.
base64UrlDecode
public string base64UrlDecode(const string s, int errOut)
The inverse; identical to base64Decode, which already accepts both alphabets.
Percent-encoding
percentEncode
public string percentEncode(const string s)
Escapes everything outside the RFC 3986 unreserved set except the URL
structure characters (/ : ? # [ ] @ ! $ & ' ( ) * + , ; =), so a whole path or
URL passes through intact. Never fails.
percentEncodeComponent
public string percentEncodeComponent(const string s)
Escapes the reserved characters too, leaving only A-Za-z0-9 and - . _ ~.
This is what a single query value or path segment needs: a / or &
inside one must not be read as structure. Never fails.
percentDecode
public string percentDecode(const string s, int errOut)
The inverse of both encoders, accepting hex escapes in either case. errOut:
0 ok, 2 a truncated escape at the end of the input, 4 a % not followed
by two hex digits.
A + is left alone rather than turned into a space: that substitution
belongs to application/x-www-form-urlencoded, not to percent-encoding, and
applying it here would corrupt any path or JSON body containing a plus.
Hex
hexEncode
public string hexEncode(const string s)
Two lowercase hex characters per byte. Never fails.
hexDecode
public string hexDecode(const string s, int errOut)
The inverse, accepting either case. errOut: 0 ok, 1 a non-hex character,
2 an odd length.
fly.hash
SHA-256 and CRC-32, in pure Fly.
import fly.hashsha256Hex
public string sha256Hex(const string data)
The bare 64-character lowercase hex digest of a string's bytes.
sha256String
public string sha256String(const string data)
"sha256:<hex>" — the prefixed form the lockfile and the registry protocol use.
sha256File
public string sha256File(const string path)
"sha256:<hex>" of a file's contents; "" when the file is missing. Reads the
file in binary mode, so the digest is the same on every platform.
sha256Verify
public bool sha256Verify(const string path, const string expected)
true when the file hashes to expected ("sha256:<hex>"). A missing file
hashes to "" and therefore never matches.
crc32
public uint crc32(const string data)
The CRC-32 of a string's bytes. Empty input is 0.
crc32Hex
public string crc32Hex(const string data)
The CRC-32 as 8 lowercase hex characters.
fly.json
A JSON reader and writer.
import fly.json
A value is an opaque handle (pointer), not a class. Ownership is a tree:
freeValue releases a value and everything below it, and a value handed to
add/put is adopted by its parent — never free it yourself afterwards.
parse reports failure through errOut, using codes 301–310 (301 bad
literal, 302 unexpected byte, 303 unterminated string, 304 bad escape,
305 bad array element, 306 missing object key, 307 missing :, 308 bad
object member, 309 malformed \u, 310 unpaired surrogate). The returned
handle is never 0: on error it is a partially-built tree the caller must
still free.
Numbers keep their raw source text — std has no string→double conversion yet — so
asNumberalways returns0.0. Read numbers withasInt, orasStringfor the literal.
Reading
parse
public pointer parse(const string src, int errOut)
JSON text → the root value.
kind
public int kind(const pointer v)
0 null, 1 bool, 2 number, 3 string, 4 array, 5 object; -1 for a
null handle.
isNull · isBool · isNumber · isString · isArray · isObject
public bool isNull(const pointer v)
public bool isBool(const pointer v)
public bool isNumber(const pointer v)
public bool isString(const pointer v)
public bool isArray(const pointer v)
public bool isObject(const pointer v)
Kind predicates.
asBool · asString · asInt · asNumber
public bool asBool(const pointer v)
public string asString(const pointer v)
public int asInt(const pointer v)
public double asNumber(const pointer v)
asString also returns a number's raw literal text. asInt takes the
integral part of that literal (a leading - is honoured, a fraction or exponent
ignored). Each returns the zero value for any other kind.
size · at
public int size(const pointer v)
public pointer at(const pointer v, const int i)
Array length, and element i — 0 when v is not an array or i is out of
range.
keyCount · keyAt · has · get
public int keyCount(const pointer v)
public string keyAt(const pointer v, const int i)
public bool has(const pointer v, const string key)
public pointer get(const pointer v, const string key)
Object members, in insertion order. get returns 0 when the key is absent
or v is not an object.
freeValue
public void freeValue(const pointer v)
Releases a value and everything below it. Safe on a null handle.
Building
newNull · newBool · newInt · newNumber · newString · newArray · newObject
public pointer newNull()
public pointer newBool(const bool b)
public pointer newInt(const int n)
public pointer newNumber(const string literal)
public pointer newString(const string s)
public pointer newArray()
public pointer newObject()
newNumber takes the literal text verbatim (std has no double→string
formatter). newString stores the value raw; escaping happens at write
time.
add
public void add(const pointer arr, const pointer child)
Appends child to an array, which adopts it. No-op when arr is not an
array.
put
public void put(const pointer obj, const string key, const pointer child)
Sets key on an object, which adopts the value. Replacing an existing key
keeps its original position and frees the old value.
Writing
write
public string write(const pointer v)
Compact serialization. A null handle writes null.
writePretty
public string writePretty(const pointer v, const int indent)
indent spaces per nesting level, newline-separated. indent <= 0 behaves
exactly like write.
escape · unescape
public string escape(const string s)
public string unescape(const string s, int errOut)
The JSON-escaped body of a string, without the surrounding quotes, and its
inverse. unescape decodes the full escape set including \uXXXX and surrogate
pairs (UTF-8 encoded); errOut is 0, 304, 309 or 310.
import fly.json
import fly.os.io
void main() {
pointer root = json.newObject()
json.put(root, "name", json.newString("fly"))
pointer tags = json.newArray()
json.add(tags, json.newString("lang"))
json.put(root, "tags", tags) // the object ADOPTS tags
string text = json.write(root) // {"name":"fly","tags":["lang"]}
io.printLn(text)
int err = 0
pointer back = json.parse(text, err)
io.printLn(json.asString(json.get(back, "name"))) // fly
json.freeValue(back)
json.freeValue(root) // frees tags too
}
A JSON document cannot be written as a Fly string literal: escapes are kept raw, so
"{\"a\":1}"is the literal characters{\"a\":1}and does not parse. Build documents with the constructors above, or read the text from a file or a socket.
fly.net
Blocking IPv4 sockets — TCP client and server, UDP datagrams, and poll sets.
import fly.net
This module declares no classes and no structs: every parameter and return
is a plain long/int/pointer/string, so the generated header is a flat
list of function signatures.
Errors are sentinels, not fail/handle. A socket is a long and
negative means invalid: every function that yields a socket returns < 0 on
failure, and every function that takes one treats a negative handle as an
immediate failure — an unchecked handle propagates harmlessly instead of
faulting.
Addresses are packed host-order ints: a<<24 | b<<16 | c<<8 | d, so
127.0.0.1 is 2130706433. There is no htons or inet_addr anywhere; the
network-order conversion happens inside the runtime.
IPv6 is not supported. Do not call the
fly.runtimesocket externs directly even though the header exports them — their signatures are platform-specific (a socket is anintfd on POSIX and a 64-bitSOCKETon Windows).
Addressing
ipv4
public int ipv4(const int a, const int b, const int c, const int d)
Packs four octets into an address; octets are masked to 0–255.
loopback · anyAddr
public int loopback()
public int anyAddr()
127.0.0.1 and 0.0.0.0 (the wildcard bind address).
ipToStr
public string ipToStr(const int addr)
"a.b.c.d" for a packed address. Never empty.
parseIp
public int parseIp(const string s)
Dotted-quad text → packed address; 0 when s is not one.
DNS and peers
resolve
public int resolve(const string host)
Host name or dotted-quad → packed IPv4; a literal address is parsed without a lookup.
resolveAll · addrCount · addrAt · addrFree
public pointer resolveAll(const string host)
public int addrCount(const pointer h)
public int addrAt(const pointer h, const int i)
public void addrFree(const pointer h)
Every IPv4 address for host as an opaque list; resolveAll returns 0 when
the name does not resolve. addrFree is safe on a null handle.
reverseDns
public string reverseDns(const int addr)
The host name registered for a packed address, or "".
peerAddr · peerPort
public int peerAddr(const long s)
public int peerPort(const long s)
The other end of a connected socket; 0 / -1 when not connected.
Socket lifecycle
socket
public long socket()
A blocking IPv4 TCP socket; < 0 on failure.
close
public void close(const long s)
Releases a socket. A negative handle is ignored.
shutdownWrite · shutdownBoth
public bool shutdownWrite(const long s)
public bool shutdownBoth(const long s)
Half-close the sending side so the peer sees EOF while this side can still read, or stop both directions.
Socket options
reuseAddr
public bool reuseAddr(const long s)
Allows rebinding a port still in TIME_WAIT. POSIX only.
setRecvTimeout · setSendTimeout
public bool setRecvTimeout(const long s, const int ms)
public bool setSendTimeout(const long s, const int ms)
Bound how long a blocking receive or send waits.
setNonBlocking
public bool setNonBlocking(const long s, const bool on)
When on, an operation that would block fails instead.
setNoDelay · setKeepAlive · setBroadcast
public bool setNoDelay(const long s, const bool on)
public bool setKeepAlive(const long s, const bool on)
public bool setBroadcast(const long s, const bool on)
TCP_NODELAY, SO_KEEPALIVE, and SO_BROADCAST (required before a datagram
socket may send to a broadcast address).
setLinger
public bool setLinger(const long s, const bool on, const int sec)
SO_LINGER: with on, close blocks for up to sec seconds while unsent data
drains.
setRecvBuf · setSendBuf
public bool setRecvBuf(const long s, const int bytes)
public bool setSendBuf(const long s, const int bytes)
Kernel buffer sizes; the OS may round the value.
sockError
public int sockError(const long s)
The socket's pending error code, cleared by reading it. 0 means none.
Server
bind · listen · accept
public bool bind(const long s, const int addr, const int port)
public bool listen(const long s, const int backlog)
public long accept(const long s)
port 0 requests an ephemeral port — read it back with localPort. accept
blocks and returns the new socket, < 0 on error.
localPort
public int localPort(const long s)
The port the socket is actually bound to, in host order; -1 on error.
listenOn
public long listenOn(const int addr, const int port, const int backlog)
socket + reuseAddr + bind + listen in one call.
Client
connect · connectTo
public bool connect(const long s, const int addr, const int port)
public long connectTo(const string host, const int port)
connectTo resolves, creates the socket and connects; < 0 on any failure.
Transfer
send · sendAll · sendStr
public long send(const long s, const pointer buf, const int n)
public bool sendAll(const long s, const pointer buf, const int n)
public bool sendStr(const long s, const string data)
send is one attempt and may write fewer bytes than asked; sendAll loops
until everything is out. Sending an empty string succeeds without touching the
socket.
recv · recvExact
public long recv(const long s, const pointer buf, const int n)
public long recvExact(const long s, const pointer buf, const int n)
recv is one blocking receive — 0 at EOF, < 0 on error. recvExact loops
over short reads; a result below n means EOF or an error arrived first.
recvStr · recvUpTo · recvAll
public string recvStr(const long s, const int max)
public string recvUpTo(const long s, const int limit)
public string recvAll(const long s)
One receive into a fresh string; read until EOF or limit bytes; read until EOF.
UDP
socketUdp
public long socketUdp()
A blocking IPv4 UDP socket; bind it with bind.
fromNew · fromAddr · fromPort · fromFree
public pointer fromNew()
public int fromAddr(const pointer from)
public int fromPort(const pointer from)
public void fromFree(const pointer from)
The 8-byte scratch that recvFrom fills with the sender's address and port.
sendTo · sendStrTo
public long sendTo(const long s, const pointer buf, const int n, const int addr, const int port)
public bool sendStrTo(const long s, const string data, const int addr, const int port)
One datagram to addr:port.
recvFrom · recvStrFrom
public long recvFrom(const long s, const pointer buf, const int n, const pointer from)
public string recvStrFrom(const long s, const int max, const pointer from)
One datagram, with the sender written into from.
Poll sets
Watch several sockets at once. A poll set is an opaque handle holding entries; each entry has an index that stays valid until a removal.
pollRead · pollWrite · pollErr · pollHup
public int pollRead() // 1
public int pollWrite() // 2
public int pollErr() // 4
public int pollHup() // 8
The event bits. pollErr and pollHup are always reported whether or not
they were requested.
pollNew · pollFree · pollCount
public pointer pollNew()
public void pollFree(const pointer ps)
public int pollCount(const pointer ps)
pollFree does not close the watched sockets — they belong to the caller.
pollAdd · pollSet · pollRemove
public int pollAdd(const pointer ps, const long s, const int events)
public bool pollSet(const pointer ps, const int i, const int events)
public bool pollRemove(const pointer ps, const int i)
pollAdd returns the new entry's index. pollRemove moves the last entry
into the hole, so indices after a removal are not stable.
pollSocketAt · pollEventsAt
public long pollSocketAt(const pointer ps, const int i)
public int pollEventsAt(const pointer ps, const int i)
What is registered at entry i.
pollWait · pollRevents · pollIsReady
public int pollWait(const pointer ps, const int timeoutMs)
public int pollRevents(const pointer ps, const int i)
public bool pollIsReady(const pointer ps, const int i, const int mask)
pollWait blocks until at least one socket is ready and returns how many are,
0 on timeout, -1 on error; then read each entry's pollRevents.
import fly.net
void main() {
long srv = net.listenOn(net.loopback(), 0, 8)
int port = net.localPort(srv)
long c = net.connectTo("127.0.0.1", port)
net.sendStr(c, "ping")
long conn = net.accept(srv)
string msg = net.recvStr(conn, 64) // "ping"
net.close(conn)
net.close(c)
net.close(srv)
}
fly.net.tls
TLS over a fly.net socket.
import fly.net.tls
Availability is a runtime fact, not a compile-time one — ask
tlsAvailable() before relying on any of this. A real backend is linked only
when the program was built with --tls; without it the
link picks up a no-op stub, so a program that never asked for TLS still links on
a machine with no libssl, and tlsAvailable() tells the truth instead of
failing mysteriously at handshake time.
| Platform | Backend with --tls |
|---|---|
| Linux | OpenSSL (1.1.0 or later) |
| Windows | Schannel |
| macOS | none — tlsAvailable() is false |
A connection is an opaque pointer, 0 = invalid.
Verification is on by default and is a per-connection parameter — there is no global switch. Turning it off accepts any certificate and defeats the point of TLS; it exists only for a host with a self-signed certificate you already trust by other means.
tlsAvailable
public bool tlsAvailable()
true when a real backend is linked into this program.
tlsConnect · tlsConnectOpts
public pointer tlsConnect(const string host, const int port)
public pointer tlsConnectOpts(const string host, const int port, const bool verify, const int timeoutMs)
Resolve, connect and handshake in one call. tlsConnect is tlsConnectOpts
with verification on and no timeout. Both return 0 on any failure, having
closed the socket they opened.
tlsWrap
public pointer tlsWrap(const long sock, const string sniHost, const bool verify)
Puts an already-connected socket into a TLS session. sniHost is sent as the
SNI server name and, when verify, checked against the certificate. The socket
becomes owned by the connection.
tlsSocket
public long tlsSocket(const pointer c)
The underlying socket, for use in a poll set; -1 for a null handle. Reading or
writing it directly would bypass the encryption.
tlsSend · tlsSendStr
public long tlsSend(const pointer c, const pointer buf, const int n)
public bool tlsSendStr(const pointer c, const string data)
One write. Unlike a raw socket this is either all of n or an error — the
record layer does not do short writes.
tlsRecv · tlsRecvStr · tlsRecvAll
public long tlsRecv(const pointer c, const pointer buf, const int n)
public string tlsRecvStr(const pointer c, const int max)
public string tlsRecvAll(const pointer c)
One blocking read (0 at a clean end of session, < 0 on error or timeout),
one read into a fresh string, or everything until the session ends.
tlsLastError
public int tlsLastError(const pointer c)
The backend's raw error code for the last failed operation, 0 when none. Not
translated.
tlsClose · tlsFree
public void tlsClose(const pointer c)
public void tlsFree(const pointer c)
tlsClose sends close_notify, releases the session and closes the socket.
tlsFree releases the session and leaves the socket open. Both are safe on a
null handle — and after either, the handle is dead.
fly.net.http
HTTP/1.1 over fly.net: parse a request, build a response, and a small
blocking client.
import fly.net.http
There are no Request/Response objects: every accessor takes the raw message and re-scans it. That keeps the whole parse/serialize surface pure string-in, string-out — testable without a socket.
CRLF trap: Fly string literals keep escapes raw, so
"\r\n"is four characters, not a line terminator. Build message text with the functions here rather than by hand.
Parsing a request
method · target · version · path · query
public string method(const string raw)
public string target(const string raw)
public string version(const string raw)
public string path(const string raw)
public string query(const string raw)
Request-line fields; "" when it is unparseable. target includes the query,
path is the part before ?.
header · contentLength
public string header(const string raw, const string name)
public int contentLength(const string raw)
Case-insensitive header lookup, value trimmed. contentLength is -1 when the
header is absent or not a number.
headerEnd · body · isComplete
public int headerEnd(const string raw)
public string body(const string raw)
public bool isComplete(const string raw)
Index of the first byte after the CRLFCRLF, the body, and whether the whole
message has arrived — isComplete is the receive loop's stop condition.
isChunked · dechunk · bodyDecoded
public bool isChunked(const string raw)
public string dechunk(const string body)
public string bodyDecoded(const string raw)
Chunked transfer coding. bodyDecoded is the one to reach for: it returns the
body with the transfer coding already removed.
queryParam
public string queryParam(const string raw, const string key)
The value of key in the query string; "" when absent.
Building a response
statusText
public string statusText(const int status)
The reason phrase for a status code; "Unknown" for anything unrecognised.
response · responseWith · responseConn
public string response(const int status, const string contentType, const string bodyStr)
public string responseWith(const int status, const string contentType, const string extraHeaders, const string bodyStr)
public string responseConn(const int status, const string contentType, const string extraHeaders, const bool keepAlive, const string bodyStr)
A complete HTTP/1.1 response. The first two send Connection: close;
responseConn chooses the disposition.
joinHeaders
public string joinHeaders(const string a, const string b)
Combines two header lines into one extraHeaders argument.
Building a request
buildRequest · buildRequestConn
public string buildRequest(const string method, const string targetPath, const string host, const string extraHeaders, const string bodyStr)
public string buildRequestConn(const string method, const string targetPath, const string host, const string extraHeaders, const string bodyStr, const bool keepAlive)
A complete request; buildRequest sends Connection: close, i.e. one exchange
per connection.
basicAuth
public string basicAuth(const string user, const string password)
The value for an Authorization header: "Basic " followed by the base64 of
user:password.
Reading a response
respStatus · respHeader · respBody
public int respStatus(const string raw)
public string respHeader(const string raw, const string name)
public string respBody(const string raw)
Status code (-1 when unparseable), case-insensitive header lookup, and body.
URLs and redirects
urlScheme · urlHost · urlPort · urlPath
public string urlScheme(const string url)
public string urlHost(const string url)
public int urlPort(const string url)
public string urlPath(const string url)
urlPort falls back to 80 for http and 443 for https; urlPath is "/"
when the URL has none.
isRedirect · resolveUrl · redirectTarget
public bool isRedirect(const int status)
public string resolveUrl(const string baseUrl, const string location)
public string redirectTarget(const string resp, const string baseUrl)
isRedirect is a 3xx carrying a Location worth following (304 is not).
resolveUrl makes an absolute URL from a Location value and the URL it came
from.
Multipart bodies
mpNew · mpContentType · mpAddField · mpAddFile · mpFinish · mpFree
public pointer mpNew(const string boundary)
public string mpContentType(const pointer h)
public void mpAddField(const pointer h, const string name, const string value)
public void mpAddFile(const pointer h, const string name, const string filename, const string contentType, const string content)
public string mpFinish(const pointer h)
public void mpFree(const pointer h)
A multipart/form-data builder. boundary must not occur in any part's
content. mpContentType gives the value for the request's Content-Type
header; mpFinish appends the closing delimiter and returns the body.
Client
exchange
public string exchange(const string host, const int port, const string rawRequest)
Connect, send one request, read the whole response, close.
get · getFollow · getStatus
public string get(const string url)
public string getFollow(const string url, const int maxHops)
public int getStatus(const string url)
GET a URL and return the body with the transfer coding removed, optionally
following up to maxHops redirects; or just the status code (-1 on failure).
download · postFile
public bool download(const string url, const string destPath)
public bool postFile(const string url, const string filePath, const string token)
GET a URL into a file (written in binary mode), and POST a file's contents as
application/octet-stream with an optional bearer token. A chunked response is
decoded before it is written, so the file holds the body and nothing else.
Keep-alive connections
connOpen · connExchange · connIsClosing · connClose
public long connOpen(const string host, const int port, const int timeoutMs)
public string connExchange(const long s, const string rawRequest)
public bool connIsClosing(const string resp)
public void connClose(const long s)
A connection intended for several exchanges. Check connIsClosing on each
response: it is true when the server will not accept another request.
HTTPS
httpsAvailable · httpsSupported
public bool httpsAvailable()
public bool httpsSupported()
httpsAvailable is the whole-client backend (WinHTTP on Windows);
httpsSupported is true when an https URL can be served at all, by
either that or fly.net.tls.
getSecure · getSecureStatus · downloadSecure · postFileSecure
public string getSecure(const string url)
public int getSecureStatus(const string url)
public bool downloadSecure(const string url, const string destPath)
public bool postFileSecure(const string url, const string filePath, const string token)
The https counterparts. The plain get/download/postFile above dispatch
to these automatically for an https URL.
When no backend is available an https URL fails rather than silently
downgrading to plaintext, and nothing falls back to an external tool.
import fly.net.http
void main() {
string body = http.get("http://example.com/v1/pkg")
int code = http.getStatus("http://example.com/v1/pkg") // 200
}
fly.targz
Gzip decompression (DEFLATE) and the ustar archive format — pure Fly, no FFI, no
platform branches. This is what removes tar from the package-manager path.
import fly.targz
Compression is deliberately not implemented: nothing in the toolchain produces archives, only consumes them.
Every entry point takes an errOut and the caller checks it rather than the
emptiness of the result — inflating an empty stream legitimately yields "".
| Code | Meaning |
|---|---|
| 1 | truncated input — the stream ended mid-symbol |
| 2 | not a gzip stream (bad magic) |
| 3 | unsupported gzip method or reserved flag |
| 4 | invalid DEFLATE block type |
| 5 | invalid Huffman code |
| 6 | a back-reference pointing before the start of the output |
| 7 | CRC-32 mismatch — the payload is corrupt |
| 8 | ISIZE mismatch — the payload is truncated |
| 9 | bad tar header checksum — not an ustar archive, or corrupt |
| 10 | an entry could not be written to disk |
| 11 | an entry whose path escapes the destination directory |
Decompression
isGzip
public bool isGzip(const string data)
true when the data starts with the gzip magic and names DEFLATE as its method.
Cheap enough to use as a dispatch test.
gunzip
public string gunzip(const string data, int errOut)
Decompresses a complete gzip member and verifies it: the CRC-32 catches corruption in transit and the ISIZE catches truncation, which a CRC alone would miss on a stream that happens to end at a block boundary.
inflate
public string inflate(const string data, int errOut)
Decompresses a raw DEFLATE stream, with no gzip or zlib wrapper.
Reading an archive
tarOpen · tarNext · tarFree
public pointer tarOpen(const string data)
public bool tarNext(const pointer h)
public void tarFree(const pointer h)
A reader over the archive bytes, owning its own copy. tarNext advances to the
next real entry — GNU long-name and pax extension records are consumed
rather than reported — and returns false at the end of the archive or on
error.
tarName · tarSize · tarType · tarIsFile · tarIsDir · tarData
public string tarName(const pointer h)
public long tarSize(const pointer h)
public int tarType(const pointer h)
public bool tarIsFile(const pointer h)
public bool tarIsDir(const pointer h)
public string tarData(const pointer h)
The current entry. tarType is the raw typeflag (48/0 regular, 53
directory, 50 symlink); the two predicates spare the caller the ASCII codes.
tarErr
public int tarErr(const pointer h)
0 while the archive reads cleanly, 9 once a header failed its checksum —
tarNext returning false means "end of archive" only when this is 0.
Extracting
safeName
public bool safeName(const string name)
Rejects any entry path that would write outside the destination: an absolute
path, a Windows drive-qualified path, or one containing a .. segment.
Archives arrive off the network from a package registry; without this check a
hostile — or merely careless — tarball can drop a file anywhere the compiler
can write.
extractTar · extractTarGz
public bool extractTar(const string data, const string destDir, int errOut)
public bool extractTarGz(const string archivePath, const string destDir, int errOut)
Unpack an in-memory ustar archive, or read a .tar.gz from disk, verify it and
unpack it — creating parent directories as needed and stopping at the first
problem. extractTarGz is the whole of what tar -xzf was being spawned for.
fly.log
Leveled logging with timestamps, an optional file sink, and the function-trace
hooks behind the compiler's --trace-calls
instrumentation.
import fly.log
import fly.log.LogLevel
Every line goes to stderr as YYYY-MM-DD HH:MM:SS [LEVEL] message;
setFile mirrors it into an append-mode file as well. A message prints when
its level's value is ≤ the configured threshold: ERROR passes every
threshold, TRACE only the most verbose one.
The threshold is lazy: the first emission (or getLevel/isOff) reads the
FLY_LOG_LEVEL environment variable — a level name in any case, or off
to silence everything; unset or unknown falls back to INFO. A program that
calls setLevel/setLevelName/setOff first wins, and the environment is
never consulted. So an instrumented binary is silent by default and turns
into a tracer with nothing but FLY_LOG_LEVEL=trace in the environment.
The call-depth indentation kept by the trace hooks is process-global and not thread-safe; tracing assumes a single-threaded program.
Levels
public enum LogLevel { ERROR, WARN, INFO, DEBUG, TRACE }
The severity ladder. .value runs 1 (ERROR) to 5 (TRACE); .name is
the tag printed between brackets.
setLevel
public void setLevel(const LogLevel level)
Sets the threshold. A message prints when its level's value is ≤ this one.
setLevelName
public void setLevelName(const string name)
setLevel by name, case-insensitive ("error"…"trace"); "off" behaves
like setOff. An unknown name is ignored.
setOff · isOff
public void setOff()
public bool isOff()
setOff silences every level — there is deliberately no OFF enum entry, so
"off" is a state, not a level. isOff reports it.
getLevel
public LogLevel getLevel()
The effective threshold (reading the environment first if nothing was set).
When isOff() it returns ERROR, the least verbose defined entry — check
isOff() to distinguish.
parseLevel · isLevelName
public LogLevel parseLevel(const string name)
public bool isLevelName(const string name)
Name → entry, case-insensitive; an unknown name parses to INFO.
isLevelName tells whether the name is one of the five entries.
setFile
public void setFile(const string path)
Mirrors every printed line into path, appending (the file is created on the
first write). The stderr sink stays active.
reset
public void reset()
Back to the pristine state: threshold unset (the next emission re-reads
FLY_LOG_LEVEL), depth zero, file sink off. Mainly for tests.
Messages
trace · debug · info · warn · err
public void trace(const string msg)
public void debug(const string msg)
public void info(const string msg)
public void warn(const string msg)
public void err(const string msg)
One function per level. The ERROR-level one is err, not error — error is
a reserved type keyword (the io.printErr precedent).
log.setLevel(LogLevel.DEBUG)
log.info("server listening") // 2026-07-31 15:00:27 [INFO] server listening
log.debug("cache warmed") // printed: DEBUG ≤ DEBUG
log.trace("byte-level detail") // filtered: TRACE > DEBUGCall tracing
The hooks --trace-calls injects at every function entry and exit. They are
ordinary public functions, so hand-written instrumentation can call them too.
All three print at TRACE with two spaces of indentation per call depth.
enter
public void enter(const string name)
Logs > name, then goes one level deeper.
exit · exitFail
public void exit(const string name)
public void exitFail(const string name)
One level back up, then < name — or <! name for a function left through an
unhandled fail.
The mangled symbols of these three functions are part of the compiler's ABI:
--trace-callsemits calls to them by symbol. Renaming them or changing their signatures breaks the instrumentation (the compiler's CodeGenTraceSuite pins the symbols).
fly.assert
Test assertion helpers. Every assertion takes a trailing code: when the check does not hold, the function fails with that code and a message naming the check and the values. Inside a suite the failing case is reported and the run continues with the next one; in a plain program the failure becomes the process exit code.
import fly.asserterrExit
public void errExit(const int code)
Exits the process with code unconditionally.
assertEqI
public void assertEqI(const int got, const int exp, const int code)
Asserts got == exp (integers).
assertEqL
public void assertEqL(const long got, const long exp, const int code)
Asserts got == exp (longs).
assertStr
public void assertStr(const string got, const string exp, const int code)
Asserts got == exp (strings).
assertNotEmpty
public void assertNotEmpty(const string s, const int code)
Asserts that s is not empty.
assertTrue / assertFalse
public void assertTrue(const bool b, const int code)
public void assertFalse(const bool b, const int code)assertGtI
public void assertGtI(const int got, const int threshold, const int code)
Asserts got > threshold.
assertApprox
public void assertApprox(const double got, const double exp, const int code)
Asserts |got − exp| ≤ 1e-9.
assertApproxEps
public void assertApproxEps(const double got, const double exp, const double eps, const int code)
Asserts |got − exp| ≤ eps.
assertNeI / assertNeL
public void assertNeI(const int got, const int notExp, const int code)
public void assertNeL(const long got, const long notExp, const int code)
Assert got != notExp (integers, longs).
assertStrNe
public void assertStrNe(const string got, const string notExp, const int code)
Asserts that the two strings differ.
assertEmpty
public void assertEmpty(const string s, const int code)
Asserts that s is empty.
assertEqP / assertNeP
public void assertEqP(const pointer got, const pointer exp, const int code)
public void assertNeP(const pointer got, const pointer notExp, const int code)
Assert that two addresses are equal / different. The addresses themselves are not printed in the failure message.
assertNull / assertNotNull
public void assertNull(const pointer p, const int code)
public void assertNotNull(const pointer p, const int code)
Assert that p is / is not the null address.
Example:
import fly.assert
import fly.str
void main() {
int n = str.len("hello")
assert.assertEqI(n, 5, 1) // passes
assert.assertTrue(n > 0, 2) // passes
}
fly.bridge
Experimental. Declarations for calling a function of a C library from Fly.
The surface below is what std/lib/bridge/clang.fly declares; it is not yet
covered by the stability expectations of the rest of the library.
import fly.bridge.CLang
import fly.bridge.Argspublic struct Args {}
public class CLang {
public CLang(const string libPath)
public void call(string sym, const Args args)
public void call(string sym, const Args args, int out)
public void call(string sym, const Args args, long out)
public void call(string sym, const Args args, float out)
public void call(string sym, const Args args, double out)
public void call(string sym, const Args args, bool out)
public void call(string sym, const Args args, pointer out)
}
Argsis the base of an argument pack: extend it with one field per C parameter, in order —struct OpenArgs : Args { string filename }.CLang(libPath)names the library.libPathmust be a string literal: the library is linked statically. One instance serves any number of symbols.call(sym, args[, out])invokes the C symbolsym, which must also be a string literal. The overload chosen by the type ofoutselects the C return type; the result is written intoout.
To link an existing native library into a program without fly.bridge, pass
--link-lib <name> to fly — see Command Line.