Superglobals are variables and functions built into the language itself — you don't need to import any libraries to use them. All superglobals live in the $ namespace so they won't interfere with your own code.

• Variables
• Functions

Variables

$args: vec[str]

A vector of strings containing the program's command line arguments.

$filepath: str

A string containing the filepath of the script or module file.

$roots: vec[str]

A vector of strings containing the root directory paths that Pyro checks when attempting to import a module.

• Directory paths can end with an optional trailing slash.
• A single dot . indicates the current working directory.
• A single slash / indicates the system root directory.

$stderr: file

The program's standard error stream as a write-only file.

$stdin: file

The program's standard input stream as a read-only file.

$stdout: file

The program's standard output stream as a write-only file.

Functions

$(command: str) -> str

Runs a shell command and returns its output as a string.

Panics if the command cannot be found or if the command exits with a non-zero status code.

This is a convenience shortcut for the $shell() function which provides more control over input and output.

$bool(arg: any) -> bool

Converts arg to a bool.

• The values false and null are falsey, as is any err value.
• All other values are truthy.

$buf() -> buf
$buf(content: str) -> buf
$buf(size: i64, fill_value: i64|rune) -> buf

Creates a new byte buffer.

$clock() -> f64

Returns the number of seconds since the program was launched. This function is a wrapper around the C standard library's clock() function.

$debug(arg: any) -> str

Returns a string representing arg suitable for use in debugging.

• If arg is an f64, this function returns the shortest decimal representation that round-trips to the same f64 value.
• If arg has a :$debug() method, the output of this method will be returned.
• Otherwise, if arg has a :$str() method, the output of this method will be returned.
• Otherwise, the default string for arg will be returned.

$env(name: str) -> str|err
$env(name: str, value: any) -> bool

Gets or sets environment variables.

• If called with a single argument, returns the value of the environment variable name as a string. Returns an err if name is not defined.
• If called with two arguments, sets the environment variable name to value. Stringifies value if value is not already a string. (This is equivalent to calling $str() on value.) Returns true on success, false if the environment variable could not be set.

$eprint(arg: any) -> i64
$eprint(format_string: str, *args: any) -> i64

Prints to the standard error stream.

• Calling this function with a single argument is equivalent to calling $str() on that argument first and printing the resulting string.
• Calling this function with more than one argument is equivalent to calling $fmt() on those arguments first and printing the resulting string.

Returns the number of bytes written to the error stream.

This function will panic if a formatting error occurs or if the attempt to write to the error stream fails.

$eprintln() -> i64
$eprintln(arg: any) -> i64
$eprintln(format_string: str, *args: any) -> i64

Like $eprint() but adds a terminating newline.

$err() -> err
$err(message: any) -> err
$err(format_string: str, *args: any) -> err

Creates a new error.

$eval(expr: str) -> any

Compiles a string of Pyro code as an expression, executes it, and returns its value.

Panics if the argument is not a valid expression.

$exec(code: str) -> module
$exec(code: str, source_id: str) -> module
$exec(code: str, source_id: str, mod: module) -> module

Compiles and executes code as a string of Pyro code.

• If a source_id argument is specified, it will be used to identify the code in error messages.
• If a module argument is specified, the code will be executed in the context of that module. Otherwise, the code will be executed in the context of a new empty module.

Returns the module.

$exit(exit_code: i64)
$exit(error_message: any)

Instructs the program to exit.

• If the argument is an i64, exits with the argument as the exit code.
• Otherwise, stringifies the argument, prints the string to the standard error stream, then exits with a non-zero exit code.

$f64(arg: i64|rune|str) -> f64

Converts arg to a float. String arguments can contain underscores for readability.

$field(object: any, field_name: str) -> any

Gets a field value by name. Returns an err if the field does not exist.

(Allows access to both public and private fields.)

$fields(object: any) -> iter[str]

Returns an iterator over the object's public field names as strings.

$file(path: str) -> file
$file(path: str, mode: str) -> file

Creates a new file object.

$fmt(format_string: str, *args: any) -> str

Returns the new string created by interpolating the argument values into the format string — see the string formatting documentation for details.

$has_field(object: any, field_name: str) -> bool

Returns true if the object has a field called field_name.

$has_method(object: any, method_name: str) -> bool

Returns true if the object has a method called method_name.

$hash(arg: any) -> i64

Returns the argument's 64-bit hash value. Hash values are used for looking up entries in the builtin map and set types.

All Pyro values have a default hash value.

• For all builtin types, if A == B, then A and B have the same hash value.
• By default, if arg is an instance of a class, its hash value is simply its memory address.
• If arg is an instance of a class with a :$hash() method, this function returns the output of that method.

This function can return negative values. Think of the hash as a 64-bit bit-pattern. 50% of these patterns will convert to negative signed two's-complement integers.

$i64(arg: f64|rune|str) -> i64

Converts arg to an i64. Panics if the argument is out-of-range for an i64.

String arguments can contain underscores and can begin with 0b, 0o, or 0x to specify the base as binary, octal, or hexadecimal; otherwise the base is assumed to be 10.

$import(path: str) -> module

Imports path as a module, where path is a standard import path, e.g. "foo::bar::baz", or an arbitrary filepath ending in ".pyro".

Returns the imported module. Panics if path is invalid or if the attempt to load and execute the module fails.

Note that this function ignores the import statement's module cache — i.e. the $import() function will always load and execute the latest version of the specified module's code.

$input() -> str?
$input(prompt: str) -> str?

Reads the next line of input from the standard input stream and returns it as a string. Strips the terminating \n or \r\n if present.

Returns null if the end of the stream had already been reached.

If prompt is specified, this string will be printed to the standard output stream before reading the input.

$is_bool(arg: any) -> bool

Returns true if the argument is a bool.

$is_buf(arg: any) -> bool

Returns true if the argument is a buf.

$is_callable(arg: any) -> bool

Returns true if the argument is callable, i.e. is a function, method, class, or callable instance.

$is_class(arg: any) -> bool

Returns true if the argument is a class.

$is_enum_member(arg: any) -> bool

Returns true if the argument is an enum member.

$is_enum_member_of_type(arg: any, type: enum) -> bool

Returns true if the argument is a member of the specified enum type.

$is_enum_type(arg: any) -> bool

Returns true if the argument is an enum type.

$is_err(arg: any) -> bool

Returns true if the argument is an err.

$is_f64(arg: any) -> bool

Returns true if the argument is an f64.

$is_file(arg: any) -> bool

Returns true if the argument is a file.

$is_func(arg: any) -> bool

Returns true if the argument is a function.

$is_i64(arg: any) -> bool

Returns true if the argument is an i64.

$is_inf(arg: any) -> bool

Returns true if the argument is floating-point infinity (positive or negative).

$is_instance(arg: any) -> bool

Returns true if the argument is an instance of a class.

$is_instance_of_class(arg: any, class: class) -> bool

Returns true if the argument is an instance of the specified class or an instance of a subclass of the specified class.

$is_iter(arg: any) -> bool

Returns true if the argument is an instance of the builtin iter type.

$is_iterable(arg: any) -> bool

Returns true if the argument is iterable, i.e. has an :$iter() method that returns an iterator.

$is_iterator(arg: any) -> bool

Returns true if the argument is an iterator, i.e. has a :$next() method that returns the next item from a sequence.

$is_map(arg: any) -> bool

Returns true if the argument is a map.

$is_method(arg: any) -> bool

Returns true if the argument is a method.

$is_module(arg: any) -> bool

Returns true if the argument is a module.

$is_nan(arg: any) -> bool

Returns true if the argument is the floating-point value NaN.

$is_null(arg: any) -> bool

Returns true if the argument is null.

$is_obj(arg: any) -> bool

Returns true if the argument is a heap-allocated object.

$is_queue(arg: any) -> bool

Returns true if the argument a queue.

$is_rune(arg: any) -> bool

Returns true if the argument is a rune.

$is_set(arg: any) -> bool

Returns true if the argument is a set.

$is_stack(arg: any) -> bool

Returns true if the argument is a stack.

$is_str(arg: any) -> bool

Returns true if the argument is a str.

$is_tup(arg: any) -> bool

Returns true if the argument is a tup.

$is_vec(arg: any) -> bool

Returns true if the argument is a vec.

$iter(arg: iterator|iterable) -> iter

Creates a new iterator wrapper.

$map() -> map

Creates a new hash map.

$method(object: any, method_name: str) -> method|err

Gets a method by name. The returned method is bound to object. Returns an err if the method does not exist.

(Allows access to both public and private methods.)

$methods(object: any) -> iter[str]

Returns an iterator over the object's public method names as strings.

$panic(error_message: any)
$panic(format_string: str, *args: any)

Panics with the specified error message.

• If called with a single argument and error_message isn't already a string, it will be automatically stringified. (This is equivalent to calling $str() on the argument.)
• Calling this function with more than one argument is equivalent to calling $fmt() on those arguments first and using the result as the message string.

If the panic is unhandled, the error message will be printed to the standard error stream and the program will exit with a non-zero status code.

$print(arg: any) -> i64
$print(format_string: str, *args: any) -> i64

Prints to the standard output stream.

• Calling this function with a single argument is equivalent to calling $str() on that argument first and printing the resulting string.
• Calling this function with more than one argument is equivalent to calling $fmt() on those arguments first and printing the resulting string.

Returns the number of bytes written to the output stream.

This function will panic if a formatting error occurs or if the attempt to write to the output stream fails.

$println() -> i64
$println(arg: any) -> i64
$println(format_string: str, *args: any) -> i64

Like $print() but adds a terminating newline.

$queue() -> queue

Creates a new queue.

$range(stop: i64) -> iter[i64]
$range(start: i64, stop: i64) -> iter[i64]
$range(start: i64, stop: i64, step: i64) -> iter[i64]

Returns an integer iterator over the half-open interval [start, stop). start defaults to 0, step defaults to 1 if not specified.

$read_file(path: str) -> str

Reads the content of the file at path and returns it as a string.

Panics if the argument is invalid, if the file cannot be opened, if an I/O read error occurs, or if sufficient memory cannot be allocated for the string.

$run(path: str) -> tup[i64, buf, buf]
$run(path: str, args: vec[str]|tup[str]) -> tup[i64, buf, buf]
$run(path: str, args: vec[str]|tup[str], input: str|buf) -> tup[i64, buf, buf]

Runs an executable file.

• If path contains a / character, it will be treated as a filepath. Otherwise, the directories specified by the PATH environment variable will be searched for the named file.
• If an args vector or tuple is specified, its entries will be appended to the executable's argument list. (The executable's argument list automatically gets path as its first entry.) Arguments are passed directly to the executable and don't need to be shell-escaped.
• If an input string or buffer is specified, its content will be written to the executable's stdin stream.

Returns a three-item tuple containing the executable's exit code as an integer, its stdout output as a buffer, and its stderr output as a buffer. (Note that you can efficiently convert a buffer to a string using the buffer's :to_str() method.)

Returns a non-zero exit code and stderr error message if the executable file could not be found.

This function will panic if an OS error occurs while forking the process.

$rune(arg: i64) -> rune

Creates a new rune.

$set() -> set
$set(arg: iterable) -> set

Creates a new set.

$shell(command: str) -> tup[i64, buf, buf]
$shell(command: str, input: str|buf) -> tup[i64, buf, buf]

Runs a shell command.

• If an input string or buffer is specified, its content will be written to the command's stdin stream.
• Returns a three-item tuple containing the command's exit code as an integer, its stdout output as a buffer, and its stderr output as a buffer.
• This function will panic if an OS error occurs while forking the process.

Note that you can efficiently convert an output buffer to a string using the buffer's :to_str() method.

This function is equivalent to running:

/bin/sh -c <command>

Use the $run() function to run an executable file directly, bypassing the shell.

$sleep(time_in_seconds: i64|f64)

Suspends execution of the calling thread for the specified number of seconds. The duration can be specified in fractions of a second.

( Sleeps for at least the specified duration unless an OS interrupt occurs signalling an error. In this case the function will raise a panic. The actual time slept may be longer than the requested duration due to system latency. )

$stack() -> stack

Creates a new stack.

$str(arg: any) -> str

Creates a new string by stringifying the argument.

$tup(*args: any) -> tup

Creates a new tuple.

$type(arg: any) -> str

Returns the type of arg as a string, e.g. "i64", "f64", "vec", "map", "bool", etc.

• If arg is an instance of a class, this function returns the class name.
• If arg is an enum member, this function returns the enum name.

$vec() -> vec
$vec(arg: iterable) -> vec
$vec(size: i64, fill_value: any) -> vec

Creates a new vector.

$write_file(path: str, content: str|buf) -> i64

Writes content to a new file, where content is a string or a byte buffer. Returns the number of bytes written.

If a file already exists at path, that file will be overwritten.

Panics if the arguments are invalid, if the file cannot be opened for writing, or if an I/O write error occurs.