Gengoscript Standard Library Reference¶

This page is the reference for the built-in std module and its namespaces.

For the language rules around imports, values, and types, see language.md.

Import¶

std := import("std")

std is always available via import("std") and is exposed as a struct-backed namespace object. Relative source imports use the same namespace model.

The entries below describe the public library surface. This page is intentionally reference-shaped: look up a function here once you already know which part of std you need.

std.io¶

std.io.println(...args)¶

• Prints arguments followed by a newline.
• Returns null.

std.io.print(...args)¶

• Prints arguments without a trailing newline.
• Returns null.

std.io.printf(fmt, ...args)¶

• fmt is string.
• Supported verbs: %v, %s, %d, %f, %t, %x, %X, %%.
• Errors:
• ArityMismatch when placeholder count and args differ
• TypeError when arg type does not match verb

std.io.sprintf(fmt, ...args)¶

• Like std.io.printf but returns the formatted string instead of printing it.
• Same verbs and error semantics as std.io.printf.

std.core¶

std.core.len(x)¶

• String: rune count (Unicode code points)
• Array/map/struct instance: element/field count
• Errors: TypeError on unsupported input

std.core.bytelen(s)¶

• String: UTF-8 byte count
• Errors: TypeError on unsupported input

std.core.append(arr, ...items)¶

• Returns new array with appended items
• Errors: TypeError if first arg is not array

std.core.error(msg)¶

• Creates first-class error value
• msg must be string

std.core.is_error(v)¶

• Returns true iff v is an error value

std.core.recover()¶

• Called inside a defer function during a panic unwind
• Returns the panic payload (an error value) and marks the panic as recovered
• Returns null if not unwinding or if already recovered

std.core.type_of(v)¶

• Returns stable runtime type name
• Plain scalars report names like int, float, bool, string, error, null
• Named values and struct instances report their declared type name

std.core.is_int(v)¶

• true for integral numbers and named integer values

std.core.is_float(v)¶

• true for non-integral numbers and named float values

std.core.is_string(v)¶

• true for strings and named string values

std.core.is_array(v)¶

• true for arrays and named array values

std.core.is_map(v)¶

• true for maps and named map values

std.core.is_struct(v)¶

• true for struct instances

std.core.is_null(v)¶

• true only for null

std.core.deep_equal(a, b)¶

• Structural equality for arrays, maps, struct instances, named values, variants, strings, and scalars
• Map comparison is by key/value content, not insertion order

std.core.clone(v)¶

• Deep clone for arrays, maps, struct instances, named values, variants, and strings
• Immutable scalar values are returned unchanged

std.core.gc()¶

• Triggers GC
• Returns null

std.core.gc_live_objects()¶

• Returns current live object count (number)

std.core.gc_stats()¶

• Returns map with keys:
• heap_used_bytes
• heap_size_bytes
• live_objects

std.conv¶

std.conv.to_int(x)¶

• Converts number/rune/boolean/string to integer-number (truncate)
• Errors: TypeError on invalid conversion

std.conv.to_float(x)¶

• Converts number/rune/boolean/string to float-number
• Errors: TypeError on invalid conversion

std.conv.to_bool(x)¶

• Truthy conversion to boolean

std.conv.to_string(x)¶

• Converts number/rune/boolean/null/string/error to string
• Errors: TypeError on unsupported input

std.string¶

std.string.split(s, sep)¶

• Splits s by sep
• Empty sep splits into UTF-8 runes

std.string.join(arr, sep)¶

• Joins array of strings with separator sep

std.string.trim(s)¶

• Trims leading and trailing ASCII whitespace

std.string.upper(s)¶

• Uppercases ASCII letters

std.string.lower(s)¶

• Lowercases ASCII letters

std.string.starts_with(s, prefix)¶

• Returns true iff s begins with prefix

std.string.ends_with(s, suffix)¶

• Returns true iff s ends with suffix

std.string.index_of(s, sub)¶

• Returns rune index of first occurrence, or -1

std.string.last_index_of(s, sub)¶

• Returns rune index of last occurrence, or -1

std.string.replace(s, old, new)¶

• Replaces all non-overlapping occurrences of old with new
• Empty old returns s unchanged

std.string.repeat(s, n)¶

• Returns s repeated n times
• n < 0 raises RangeError

std.string.split_once(s, sep)¶

• Returns (head, tail) split on the first occurrence of sep
• Returns (null, null) if sep is not present

std.string.contains(s, sub)¶

• Returns true if sub appears anywhere in s, else false
• Empty sub always returns true

std.string.builder()¶

• Creates mutable string builder with .write, .str, and .reset

std.math¶

std.math.abs(x)¶

• Absolute value of x

std.math.sqrt(x)¶

• Square root of x

std.math.floor(x) / std.math.ceil(x) / std.math.round(x)¶

• Floor, ceiling, nearest integer (half-away-from-zero)

std.math.sin(x) / std.math.cos(x) / std.math.tan(x)¶

• Trigonometric functions; argument in radians

std.math.log(x) / std.math.log2(x) / std.math.log10(x)¶

• Natural, base-2, and base-10 logarithms

std.math.pow(base, exp)¶

• base raised to the power exp

std.math.min(a, b) / std.math.max(a, b)¶

• Minimum / maximum of two numbers

std.math.pi¶

• π ≈ 3.14159265358979… (constant)

std.math.e¶

• Euler's number ≈ 2.71828182845904… (constant)

std.math.inf¶

• Positive infinity (constant)

std.rand¶

std.rand.float()¶

• Uniform float in [0.0, 1.0)
• Auto-seeds from OS entropy on first call

std.rand.intn(n)¶

• Uniform int in [0, n)
• Errors: RangeError if n ≤ 0

std.rand.between(lo, hi)¶

• Uniform int in [lo, hi] inclusive
• Errors: RangeError if lo > hi

std.rand.seed(n)¶

• Seeds the global PRNG with n
• Useful for reproducible test sequences

std.rand.choice(arr)¶

• Returns a random element from arr
• Errors: RangeError on empty array, TypeError if not an array

std.json¶

std.json.parse(s)¶

• Parses a JSON string and returns the corresponding gengo value
• JSON null → null, booleans → bool, numbers → number, strings → string, arrays → array, objects → map
• Errors: TypeError on invalid JSON

std.json.stringify(v)¶

• Serializes a gengo value to a JSON string
• Arrays → JSON arrays, maps → JSON objects (string keys required), scalars → JSON primitives
• Non-serializable values (struct instances, closures, etc.) emit null
• Returns string

std.json.valid(s)¶

• Returns true if s is valid JSON, false otherwise

std.regexp¶

Backtracking NFA engine. All functions accept either a pattern string or a compiled regexp object returned by std.regexp.compile.

Supported syntax: . * + ? ^ $ | () [...] [^...] character ranges, \d \D \w \W \s \S shorthands.

Errors: InvalidRegexp on a malformed pattern.

std.regexp.match(pattern, s)¶

• Returns true if pattern matches anywhere in s

std.regexp.find(pattern, s)¶

• Returns the first matching substring, or null if not found

std.regexp.find_all(pattern, s)¶

• Returns array of all non-overlapping matches

std.regexp.replace(pattern, s, repl)¶

• Replaces first occurrence of pattern in s with repl; returns new string

std.regexp.split(pattern, s)¶

• Splits s at each match of pattern; returns array of strings

std.regexp.compile(pattern)¶

• Compiles pattern into a reusable regexp object
• The object supports method-call syntax: re.match(s), re.find(s), re.find_all(s), re.replace(s, repl), re.split(s)

std.template¶

Go-style text templates with {{ / }} delimiters.

std.template.render(src, data)¶

• Parses and executes src against data in one call
• Returns the rendered string
• Errors: InvalidTemplate on malformed template, TypeError on type mismatch

std.template.parse(src)¶

• Compiles src into a reusable Template object
• Errors: InvalidTemplate on malformed template

Template.execute(data)¶

• Executes a compiled template against data
• Returns the rendered string

std.template.valid(src)¶

• Returns true if src is a well-formed template, false otherwise

std.template.add_func(tmpl, name, fn)¶

• Registers a named function on a compiled template for use in {{call_fn}} tags
• Returns null

Syntax¶

Tag	Description
{{.field}}	Field/key access on current context
{{.a.b}}	Chained field access
{{.}}	Current context value
{{if .expr}}…{{end}}	Conditional block
{{if .expr}}…{{else}}…{{end}}	Conditional with else
{{with .expr}}…{{end}}	Scoped context block
{{/* comment */}}	Comment (emits nothing)

Note: range iteration is reserved syntax but not yet executed (v1 always takes the else/empty branch).

std.Time / std.time¶

std.Time is a named type over int. Raw value is milliseconds since Unix epoch, UTC. All arithmetic and comparison operators work through the underlying int.

std.time — constructors and utilities¶

Function	Returns	Notes
std.time.now()	std.Time	Current wall time
std.time.from_unix(sec)	std.Time	Integer seconds → Time
std.time.from_unix_ms(ms)	std.Time	Integer milliseconds → Time
std.time.parse(str, fmt)	std.Time	Errors: TypeError/RangeError on bad input

Duration constants (plain int, milliseconds): std.time.ms std.time.second std.time.minute std.time.hour std.time.day

Methods on std.Time¶

Method	Returns	Notes
.unix()	int	Whole seconds since epoch
.unix_ms()	int	Same as raw value
.parts()	map	Keys: year month day hour min sec ms weekday (0=Sunday)
.format(fmt)	string
.add_ms(n)	std.Time
.add_s(n)	std.Time
.add_m(n)	std.Time
.add_h(n)	std.Time
.sub(t2)	int	ms difference, may be negative
.before(t2)	bool
.after(t2)	bool
.equal(t2)	bool
.is_zero()	bool

Format verbs¶

Verb	Output	Verb	Output
%Y	year (4 digits)	%H	hour 00–23
%m	month 01–12	%M	minute 00–59
%d	day 01–31	%S	second 00–59
%L	millisecond 000–999	%A	weekday name
%a	short weekday	%B	month name
%b	short month	%%	literal %

parse accepts: %Y %m %d %H %M %S only. All times are UTC.