lua_std/

os.rs

//! The operating system library.
//!
//! Operating system facilities: the clock, dates and times, environment
//! variables, file management and process control.

use crate::{any, boolean, number, option, string, table};

/// Returns the CPU time used by the program.
///
/// # Return value
///
/// An approximation of the amount in seconds of CPU time used by the
/// program, as returned by the underlying ISO C function `clock`. Useful
/// for benchmarking.
///
/// # Examples
///
/// ```lua
/// local t0 = os.clock()
/// for i = 1, 1e7 do end
/// print(os.clock() - t0)    --> 0.031  (elapsed CPU seconds)
/// ```
///
/// # See also
///
/// [`time`], [`difftime`]
pub fn clock() -> number {
    todo!()
}

/// Formats a date and time.
///
/// # Parameters
///
/// - **`format`**: a format string following the ISO C function
///   `strftime` (default `"%c"`, the full date and time). A leading
///   `"!"` formats in UTC instead of local time. The special format
///   `"*t"` (or `"!*t"`) requests a table instead of a string.
/// - **`time`**: the time to format, as returned by [`time`] (default:
///   the current time).
///
/// # Return value
///
/// A string with the formatted date, or, for the `"*t"` formats, a table
/// with fields `year`, `month` (1–12), `day` (1–31), `hour` (0–23),
/// `min` (0–59), `sec` (0–61 due to leap seconds), `wday` (weekday,
/// 1–7, Sunday is 1), `yday` (day of the year, 1–366), and `isdst`
/// (daylight saving flag, a boolean).
///
/// # Examples
///
/// ```lua
/// print(os.date("%Y-%m-%d"))          --> 2026-09-03
/// print(os.date("!%H:%M UTC"))        --> 18:45 UTC
/// local t = os.date("*t")
/// print(t.year, t.month, t.day)       --> 2026   9   3
/// ```
///
/// # See also
///
/// [`time`], [`difftime`]
pub fn date(format: option<string>, time: option<number>) -> any {
    todo!()
}

/// Returns the difference between two times.
///
/// # Parameters
///
/// - **`t2`**: the later time, as returned by [`time`].
/// - **`t1`**: the earlier time.
///
/// # Return value
///
/// The difference, in seconds, from time `t1` to time `t2`, as a float.
/// On POSIX, Windows and most other systems this is exactly `t2 - t1`.
///
/// # Examples
///
/// ```lua
/// local before = os.time()
/// -- ... some slow work ...
/// print(os.difftime(os.time(), before))    --> 2.0
/// ```
///
/// # See also
///
/// [`time`], [`clock`]
pub fn difftime(t2: number, t1: number) -> number {
    todo!()
}

/// Runs a shell command.
///
/// # Parameters
///
/// - **`command`**: the command passed to the operating system shell.
///   When absent, the function instead reports whether a shell is
///   available.
///
/// # Return value
///
/// A boolean that is true when the command terminated successfully,
/// followed by the string `"exit"` (the command ended normally) or
/// `"signal"` (it was terminated by a signal) and the return status.
/// When called without a command, returns only a boolean indicating
/// whether a shell is available.
///
/// # Examples
///
/// ```lua
/// print(os.execute("exit 0"))    --> true   exit   0
/// print(os.execute("exit 3"))    --> nil    exit   3
/// print(os.execute())            --> true   (a shell exists)
/// ```
///
/// # See also
///
/// [`io::popen`](crate::io::popen)
pub fn execute(command: option<string>) -> (boolean, string, number) {
    todo!()
}

/// Terminates the host program.
///
/// # Parameters
///
/// - **`code`**: true for a successful exit (the default), false for a
///   failure exit, or a numeric return code.
/// - **`close`**: when true, closes the Lua state before exiting,
///   running finalizers and to-be-closed variables.
///
/// # Description
///
/// Calls the ISO C function `exit` to terminate the host program. This
/// function never returns.
///
/// # Examples
///
/// ```lua
/// if not config_ok then
///   io.write("bad configuration\n")
///   os.exit(1)
/// end
/// ```
pub fn exit(code: option<any>, close: option<boolean>) {
    todo!()
}

/// Reads an environment variable.
///
/// # Parameters
///
/// - **`varname`**: the name of the environment variable.
///
/// # Return value
///
/// The value of the process environment variable `varname`, or `nil` if
/// the variable is not defined.
///
/// # Examples
///
/// ```lua
/// print(os.getenv("HOME"))          --> /home/ana
/// print(os.getenv("NO_SUCH_VAR"))   --> nil
/// ```
pub fn getenv(varname: string) -> option<string> {
    todo!()
}

/// Deletes a file.
///
/// # Parameters
///
/// - **`filename`**: the name of the file (or empty directory, on POSIX
///   systems) to delete.
///
/// # Return value
///
/// True on success; in case of errors, `nil` plus an error message and
/// an error code.
///
/// # Examples
///
/// ```lua
/// local ok, err = os.remove("old.log")
/// if not ok then print("could not remove:", err) end
/// ```
///
/// # See also
///
/// [`rename`]
pub fn remove(filename: string) -> option<boolean> {
    todo!()
}

/// Renames a file or directory.
///
/// # Parameters
///
/// - **`oldname`**: the current name.
/// - **`newname`**: the new name.
///
/// # Return value
///
/// True on success; in case of errors, `nil` plus an error message and
/// an error code.
///
/// # Examples
///
/// ```lua
/// assert(os.rename("draft.txt", "final.txt"))
/// ```
///
/// # See also
///
/// [`remove`]
pub fn rename(oldname: string, newname: string) -> option<boolean> {
    todo!()
}

/// Sets the current locale of the program.
///
/// # Parameters
///
/// - **`locale`**: a system-dependent locale name. `""` selects the
///   native environment locale, `"C"` the standard C locale, and `nil`
///   only queries the current locale.
/// - **`category`**: which category to change: `"all"` (the default),
///   `"collate"`, `"ctype"`, `"monetary"`, `"numeric"` or `"time"`.
///
/// # Return value
///
/// The name of the new locale, or `nil` if the request cannot be
/// honoured.
///
/// # Examples
///
/// ```lua
/// print(os.setlocale("C"))    --> C
/// ```
pub fn setlocale(locale: option<string>, category: option<string>) -> option<string> {
    todo!()
}

/// Returns the current time, or converts a date table to a time.
///
/// # Parameters
///
/// - **`table`**: a table describing a local date, with mandatory fields
///   `year`, `month` and `day`, and optional fields `hour` (default 12),
///   `min`, `sec` (default 0) and `isdst`.
///
/// # Return value
///
/// A time value, whose meaning depends on the system — on POSIX and
/// Windows, the number of seconds since the epoch. When called without
/// arguments, the current time. The returned value can be used with
/// [`date`] and [`difftime`].
///
/// # Examples
///
/// ```lua
/// print(os.time())    --> 1788806700
/// print(os.time({ year = 2026, month = 9, day = 3 }))
/// --> 1788782400
/// ```
///
/// # See also
///
/// [`date`], [`difftime`], [`clock`]
pub fn time(t: option<table>) -> number {
    todo!()
}

/// Returns a name usable for a temporary file.
///
/// # Return value
///
/// A string with a file name that can be used for a temporary file. The
/// file must be explicitly opened before use and explicitly removed when
/// no longer needed. When possible, prefer
/// [`io::tmpfile`](crate::io::tmpfile), which removes the file
/// automatically when the program ends.
///
/// # Examples
///
/// ```lua
/// local name = os.tmpname()
/// print(name)    --> /tmp/lua_Fx3kzM
/// ```
///
/// # See also
///
/// [`io::tmpfile`](crate::io::tmpfile)
pub fn tmpname() -> string {
    todo!()
}