Superglobals
Superglobals are available in all modules — 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
-
$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
. -
$buf() -> buf
$buf(content: str) -> buf
$buf(size: i64, fill_value: i64|char) -> buf
-
Creates a new
buf
object.- If called with zero arguments, creates a new empty buffer.
- If called with a single string argument, creates a new buffer containing a copy of the string's bytes.
-
If called with two arguments, creates a new buffer with the specified initial size and fill value, where
size
is a positive integer andvalue
is an integer value in the range[0, 255]
.
-
$char(arg: i64) -> char
-
Converts
arg
to achar
. Panics if the argument is out-of-range. -
$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 anf64
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.) -
If
-
$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 anerr
ifname
is not defined. -
If called with two arguments, sets the environment variable
name
tovalue
. Stringifiesvalue
ifvalue
is not already a string. (This is equivalent to calling$str()
onvalue
.) Returnstrue
on success,false
if the environment variable could not be set.
-
If called with a single argument, returns the value of the environment variable
-
$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.
-
Calling this function with a single argument is equivalent to calling
-
$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
err
object.- If called with no arguments, returns an error with an empty message string.
-
If called with a single argument, stringifies that argument and uses the result as the message string. (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.
-
$exec(code: str) -> mod
-
Executes a string of Pyro source code. The code is executed in the context of a new empty module.
Returns the new module.
-
$exit(code: i64)
-
Instructs the program to exit with the specified 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
object. Opens the underlying file stream using the C functionfopen()
. Panics on failure.If
mode
is not specified, it defaults to"r"
— i.e. open an existing file for reading. -
$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 calledfield_name
. -
$has_method(object: any, method_name: str) -> bool
-
Returns
true
if the object has a method calledmethod_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 ani64
. Panics if the argument is out-of-range for ani64
.String arguments can contain underscores and can begin with
0b
,0o
, or0x
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 abool
. -
$is_buf(arg: any) -> bool
-
Returns
true
if the argument is abuf
. -
$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 achar
. -
$is_class(arg: any) -> bool
-
Returns
true
if the argument is a class. -
$is_err(arg: any) -> bool
-
Returns
true
if the argument is anerr
. -
$is_f64(arg: any) -> bool
-
Returns
true
if the argument is anf64
. -
$is_file(arg: any) -> bool
-
Returns
true
if the argument is afile
. -
$is_func(arg: any) -> bool
-
Returns
true
if the argument is a function. -
$is_i64(arg: any) -> bool
-
Returns
true
if the argument is ani64
. -
$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 builtiniter
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 amap
. -
$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 valueNaN
. -
$is_null(arg: any) -> bool
-
Returns
true
if the argument isnull
. -
$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 aqueue
. -
$is_set(arg: any) -> bool
-
Returns
true
if the argument is aset
. -
$is_stack(arg: any) -> bool
-
Returns
true
if the argument is astack
. -
$is_str(arg: any) -> bool
-
Returns
true
if the argument is astr
. -
$is_tup(arg: any) -> bool
-
Returns
true
if the argument is atup
. -
$is_vec(arg: any) -> bool
-
Returns
true
if the argument is avec
. -
$iter(arg: iterator|iterable) -> iter
-
Wraps an iterator in an
iter
wrapper, adding automatic support for a set of chainable, lazily-evaluated utility methods.arg
can be either an iterator or an instance of an iterable type, e.g. a vector. -
$map() -> map
-
Creates a new
$map
object. -
$method(object: any, method_name: str) -> method|err
-
Gets a method by name. The returned method is bound to
object
. Returns anerr
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.
-
If called with a single argument and
-
$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.
-
Calling this function with a single argument is equivalent to calling
-
$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
object. -
$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 to0
,step
defaults to1
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
object. Ifarg
is iterable, initializes the new set by iterating over its values. -
$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 itsstderr
output as a string.If
input
is specified, its content will be written to the command'sstdin
. -
$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
object. -
$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 afile
object wrappingSTDERR
. -
If called with one argument, sets the standard error stream to
arg
.
-
If called with no arguments, returns the
-
$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 afile
object wrappingSTDIN
. -
If called with one argument, sets the standard input stream to
arg
.
-
If called with no arguments, returns the
-
$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 afile
object wrappingSTDOUT
. -
If called with one argument, sets the standard output stream to
arg
.
-
If called with no arguments, returns the
-
$str(arg: any) -> str
-
Stringifies the argument — i.e. returns its default string representation. If the argument has a
:$str()
method, the output of this method will be returned.Note that calling
$str()
on anf64
prints its value to 6 decimal digits of precision, stripping trailing zeros after the decimal point. -
$tup() -> tup
$tup(arg1: any, arg2: any, ...) -> tup
-
Creates a new
tup
object. The arguments provide the tuple's values. -
$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
vec
object.- If called with zero arguments, creates an empty vector.
- If called with a single iterable argument, fills the new vector by iterating over the argument.
- If called with two arguments, creates a vector with the specified initial size and fill value.
-
$write_file(path: str, content: str|buf) -> i64
-
Writes
content
to a new file, wherecontent
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.