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: tup[str]

A tuple 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.

Functions

$(command: str) -> str

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

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|char) -> buf

Creates a new byte buffer.

$char(arg: i64) -> char

Creates a new character.

$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 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.

Note that calling $debug() on an f64 prints its value to 17 decimal digits of precision, stripping trailing zeros after the decimal point. (17 is the minimum number of decimal digits required to guarantee that any two distinct 64-bit floats have distinct representations.)

$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.

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

Executes a string of Pyro source code.

• If called with a single argument, executes the code in the context of a new empty module.
• If called with two arguments, executes the code in the context of the specified 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.

$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.

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

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

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

Creates a new file.

$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.

( This function can return negative values. Think of the hash as the 64-bit bit-pattern itself. 50% of these patterns will convert to negative signed integers. )

$i64(arg: f64|char|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.

$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_char(arg: any) -> bool

Returns true if the argument is a char.

$is_class(arg: any) -> bool

Returns true if the argument is a class.

$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(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_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.

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

Creates a new set.

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

Runs a shell command.

Returns a three-item tuple containing the command's exit code as an integer, its stdout output as a string, and its stderr output as a string.

If input is specified, its content will be written to the command's stdin.

$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.

$stderr() -> file
$stderr(arg: file)

Gets or sets the standard error stream.

• If called with no arguments, returns the file object representing the standard error stream. By default, this is a file object wrapping STDERR.
• If called with one argument, sets the standard error stream to arg.

$stdin() -> file
$stdin(arg: file)

Gets or sets the standard input stream.

• If called with no arguments, returns the file object representing the standard input stream. By default, this is a file object wrapping STDIN.
• If called with one argument, sets the standard input stream to arg.

$stdout() -> file
$stdout(arg: file)

Gets or sets the standard output stream.

• If called with no arguments, returns the file object representing the standard output stream. By default, this is a file object wrapping STDOUT.
• If called with one argument, sets the standard output stream to arg.

$str(arg: any) -> str

Creates a new string by stringifying the argument.

$tup() -> tup
$tup(arg1: any, arg2: any, ...) -> tup

Creates a new tuple.

$type(arg: any) -> str

Returns the type of arg as a string.

$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.