os

A collection of utilities for working with the operating system.

command

|program: String| -> Command

Creates a new Command, which supports executing external programs in separate processes.

Builder methods allow configuration of properties like command arguments or environment variables before spawning the program in a new process.

Example

os.command('ls')
  .args('/tmp', '-al')
  .wait_for_output()
  .stdout()
# -> ...

name

|| -> String

Returns a string containing the name of the current operating system, e.g. "linux", "macos", "windows", etc.

process_id

|| -> Number

Returns the ID associated with the current process.

start_timer

|| -> Timer

Returns a timer that can be used to measure how much time has passed while a script is running.

Example

t = os.start_timer()

# ...after some time...
print "Time taken: ${t.elapsed()}s"

t2 = os.start_timer()
print "Seconds between then and now: ${t2 - t}"

time

|| -> DateTime

Returns a DateTime set to the current time, using the local timezone.

|timestamp: Number| -> DateTime

Returns a DateTime set to the provided timestamp in seconds, using the local timezone.

|timestamp: Number, offset: Number| -> DateTime

Returns a DateTime set to the provided timestamp in seconds, using an offset in seconds.

Example

now = os.time()
# e.g. 2021-12-11 21:51:14

now.year()
# e.g. 2021

now.hour()
# e.g. 21

now.timestamp()
# e.g. 1639255874.53419

Command

See os.command

Command.args

|Command, args...| -> Command

Adds the given arguments to the command, and returns the command.

Example

os.command('ls')
  .args('/tmp', '-al')
  .wait_for_output()
  .stdout()
# -> ...

Command.current_dir

|Command, path: String| -> Command

Sets the command's working directory, and returns the command.

Example

os.command('ls')
  .current_dir('/tmp')
  .wait_for_output()
  .stdout()
# -> ...

Command.env

|Command, key: String, value: String| -> Command

Sets an environment variable, and returns the command.

Example

assert os.command('env')
  .env 'FOO', '123'
  .wait_for_output()
  .stdout()
  .contains 'FOO=123'

Command.env_clear

|Command| -> Command

Clears all environment variables for the command, and returns the command.

This prevents the command from inheriting any environment variables from the parent process.

Example

assert os.command('env')
  .env_clear()
  .wait_for_output()
  .stdout()
  .is_empty()

Command.env_remove

|Command, key: String| -> Command

Removes the environment variable matching the given key, and returns the command.

Example

assert os.command('env')
  .env_clear()
  .env 'FOO', '123'
  .env_remove 'FOO'
  .wait_for_output()
  .stdout()
  .is_empty()

Command.stdin

|Command, stream_config: String| -> Command

Configures the command's stdin stream.

Valid values of stream_config are:

• inherit: the stream will be inherited from the parent process.
• piped: a pipe will be created to connect the parent and child processes.
• null: the stream will be ignored.

The default stream behavior is inherit when the command is used with spawn or wait_for_exit, and piped when used with wait_for_output.

Command.stdout

|Command, stream_config: String| -> Command

Configures the command's stdout stream.

See Command.stdin for valid values of stream_config.

Command.stderr

|Command, stream_config: String| -> Command

Configures the command's stderr stream.

See Command.stdin for valid values of stream_config.

Command.spawn

|Command| -> Child

Executes the command, returning the command's Child process.

Example

spawned = os.command('ls')
  .stdout('piped')
  .spawn()

spawned
  .wait_for_output()
  .stdout()
# -> ...

Command.wait_for_output

|Command| -> CommandOutput

Executes the command and waits for it to exit, returning its captured output.

Example

os.command('ls').wait_for_output().stdout()
# -> ...

Command.wait_for_exit

|Command| -> Number or Null

Executes the command and waits for it to exit, returning its exit code if the command exited normally, or Null if it was interrupted.

Example

os.command('ls').wait_for_exit()
# -> 0

CommandOutput

Contains captured output from a command, and information about how the command exited.

See Command.wait_for_output and Child.wait_for_output.

CommandOutput.exit_code

|CommandOutput| -> Number or Null

Returns the command's exit code if available.

CommandOutput.success

|CommandOutput| -> Bool

Returns true if the command exited successfully.

CommandOutput.stdout

|CommandOutput| -> String or Null

Returns the contents of the command's stdout stream if it contains valid unicode, or null otherwise.

See also

• CommandOutput.stdout_bytes

CommandOutput.stderr

|CommandOutput| -> String or Null

Returns the contents of the command's stderr stream if it contains valid unicode, or null otherwise.

CommandOutput.stdout_bytes

|CommandOutput| -> Iterator

Returns an iterator that yields the bytes contained in the command's stdout stream.

CommandOutput.stderr_bytes

|CommandOutput| -> Iterator

Returns an iterator that yields the bytes contained in the command's stderr stream.

Child

A handle to a child process, see Command.spawn.

Child.stdin

|Child| -> File

Returns the child process's stdin standard input stream as a File that supports write operations.

Example

spawned = os.command('cat')
  .stdin 'piped'
  .spawn()

stdin = spawned.stdin()
stdin.write_line 'hello'
stdin.write_line 'one two three'

spawned.wait_for_output().stdout()
# -> hello
# -> one two three

Child.stdout

|Child| -> File

Returns the child process's stdout standard output stream as a File that supports read operations.

Calling this function will prevent the stream from being included in wait_for_output.

Child.stderr

|Child| -> File

Returns the child process's stderr standard error stream as a File that supports read operations.

Calling this function will prevent the stream from being included in wait_for_output.

Child.has_exited

|Child| -> Bool

Returns true without blocking if the child process has exited, and false otherwise.

Child.wait_for_output

|Child| -> CommandOutput

Closes all input and output streams, waits for the command to exit, and then returns the captured output.

Note that if the stdout or stderr streams were manually retrieved via Child.stdout/Child.stderr then they won't be included in the captured output.

Child.wait_for_exit

|Child| -> Number or Null

Closes all input and output streams, waits for the command to exit, and then returns the command's exit code if available.

DateTime

See os.time.

DateTime.year

|DateTime| -> Number

Returns the year component of the provided DateTime.

DateTime.month

|DateTime| -> Number

Returns the month component of the provided DateTime.

DateTime.day

|DateTime| -> Number

Returns the day component of the provided DateTime.

DateTime.hour

|DateTime| -> Number

Returns the hour component of the provided DateTime.

DateTime.minute

|DateTime| -> Number

Returns the minute component of the provided DateTime.

DateTime.nanosecond

|DateTime| -> Number

Returns the nanosecond component of the provided DateTime.

DateTime.timestamp

|DateTime| -> Number

Returns the number of seconds since 00:00:00 UTC on January 1st 1970.

DateTime.timezone_offset

|DateTime| -> Number

Returns the DateTime's timezone offset in seconds.

DateTime.timestamp_string

|DateTime| -> String

Returns a string representing the DateTime's timezone offset in seconds.

Timer

See os.start_timer.

Timer.@- (subtract)

|Timer, Timer| -> Number

Returns the time difference in seconds between two timers.

Example

t1 = os.start_timer()
t2 = os.start_timer()
# t2 was started later than t1, so the time difference is positive
assert (t2 - t1) > 0
# t1 was started earlier than t2, so the time difference is negative
assert (t1 - t2) < 0

Timer.elapsed

|Timer| -> Number

Returns the number of seconds that have elapsed since the timer was started.

Example

t = os.start_timer()

# ...after some time...
print "Time taken: ${t.elapsed()}s"