class: os

[11:21] static (extern: com.lehman.aussom.stdlib.AussomOs) extends: object

Represents a static external class providing access to operating system functionalities. The os class is used to run OS-level commands and retrieve their execution results, including success status and output. It offers a simple interface for interacting with the system's command line or shell.

Methods

exec (string OsCommand, bool LogToStdout = false)

Executes the provided OS command and returns a Map with the result. The map will contain a key 'success' with a boolean of true for success and false for failure. It also returns a key of 'result' with the text result from the command.
- @p OsCommand is a string with the command to run.
- @p LogToStdout is a bool with true to log to output and false to not.
- @r A map with the results.
execRaw (list OsCommand, bool LogToStdout = false)

Executes the provided OS command and returns a Map with the result. The map will contain a key 'success' with a boolean of true for success and false for failure. It also returns a key of 'result' with the text result from the command. The difference between this one and regular exec is that the reguarl one will execute /bin/sh -c or cmd.exe -c depending for Linux/Unix or Windows. With execRaw, the string passed gets sent all on it's own.
- @p OsCommand is a list of strings with the command to run.
- @p LogToStdout is a bool with true to log to output and false to not.
- @r A map with the results.
getEnv (string Name, Default = null)

Gets the value of an environment variable. Values recorded with setEnv take precedence over the real environment. When the variable is set in neither place, the provided default is returned.
- @p Name is a string with the environment variable name.
- @p Default is the value to return when the variable is not set. Defaults to null.
- @r A string with the value, or Default when the variable is not set.
getEnvs ()

Gets every environment variable as a map of name to value. Values recorded with setEnv are layered on top of the real environment.
- @r A map of environment variable names to string values.
hasEnv (string Name)

Checks whether an environment variable is set, in either the setEnv overlay or the real environment.
- @p Name is a string with the environment variable name.
- @r A bool with true when the variable is set and false when not.
setEnv (string Name, string Value)

Records an environment variable in a script-managed overlay. The overlay is reported by getEnv, getEnvs, and hasEnv, and is passed to the child processes started by exec, execRaw, and run. Java cannot change the JVM's own live environment, so this does not affect values read directly through the Java System.getenv API elsewhere in the process.
- @p Name is a string with the environment variable name.
- @p Value is a string with the value to record.
- @r null.
isWindows ()

Checks whether the current process is running on Windows.
- @r A bool with true on Windows and false otherwise.
isMac ()

Checks whether the current process is running on macOS.
- @r A bool with true on macOS and false otherwise.
isLinux ()

Checks whether the current process is running on Linux or another Unix-like that is not macOS.
- @r A bool with true on Linux and false otherwise.
isTty ()

Checks whether standard output is attached to an interactive terminal (a TTY). This is false when output is piped to a file or another process, which lets callers decide between a terminal UI and plain line-by-line logging.
- @r A bool with true when stdout is a terminal and false otherwise.
getOsType ()

Gets the platform name as a simple string.
- @r A string that is one of "windows", "mac", or "linux".
getTmpDir ()

Gets the system temporary-directory path.
- @r A string with the temporary-directory path.
run (Command, map Options = null)

Runs a command and returns a result map. Command may be a string, which is run through the platform shell (/bin/sh -c on Unix, cmd.exe /c on Windows), or a list of strings, which is run as an argument vector with no shell. Options is an optional map that may contain: "cwd" a string working directory for the command. "env" a map of environment overrides for the child. "stdin" a string fed to the command's standard input. "mergeStderr" a bool, true (the default) to merge standard error into stdout, false to capture it separately. "logToStdout" a bool, true to mirror output to the console. Defaults to false. The result map contains 'success' (bool), 'exitCode' (int), 'stdout' (string), and 'stderr' (string, empty when merged).
- @p Command is a string or a list of strings with the command.
- @p Options is an optional map of run options. Defaults to null.
- @r A map with the command result.
exit (int Code = 0)

Terminates the current process with the given exit code. Standard output and error are flushed first. This function does not return.
- @p Code is an int with the process exit code. Defaults to 0.
readLine (string Prompt = null)

Reads one line from standard input, without the trailing newline. Returns null at end of input. When a prompt is supplied it is written to standard output first.
- @p Prompt is an optional string written before reading. Defaults to null.
- @r A string with the line read, or null at end of input.
readAll ()

Reads all of standard input as a single string.
- @r A string with everything read from standard input.
out (string Text = "")

Writes text followed by a newline to standard output. This is a convenience wrapper over the console so a script can do its line input and output through os (os.readLine to read, os.out to write).
- @p Text is the string to write. Defaults to an empty string, which writes a blank line.
- @r null.
outErr (string Text = "")

Writes text followed by a newline to standard error. Use this for diagnostics that should not mix into the standard-output stream a script produces. Unlike the console's err logging call, this writes to the real standard-error stream with no prefix.
- @p Text is the string to write. Defaults to an empty string, which writes a blank line.
- @r null.
sprintf (string Format, ...)

Formats the arguments into the format string and returns the result, without writing anything. This is the string-building companion to printf and mirrors string.format for callers who prefer a C-style call. Placeholders use the same rules as string.format: {} for the next argument, {N} for a positional argument (0 based), and {name} for a named value from a map argument. Write '{{' or '}}' for a literal brace.
- @p Format is the format string.
- @p etc are the arguments referenced by the placeholders.
- @r A new formatted string.
printf (string Format, ...)

Writes a formatted string to standard output, with no trailing newline, so the format string controls any line breaks. This is the formatted-output companion to out. Placeholders use the same rules as string.format and sprintf.
- @p Format is the format string.
- @p etc are the arguments referenced by the placeholders.
- @r null.
_sprintf (string Format, list Args)

Backing formatter for sprintf and printf. Delegates to the string type's own formatter so the placeholder rules stay identical to string.format.
- @p Format is the format string.
- @p Args is a list of the arguments referenced by the placeholders.
- @r A new formatted string.