lua_std/

io.rs

//! The input and output library.
//!
//! I/O operations come in two styles. The *simple* style uses implicit
//! default files: [`io.read`](read()) and [`io.write`](write()) operate on
//! the current input and output files, set with [`input`] and [`output`].
//! The *complete* style uses explicit [`file`](struct@file) handles
//! returned by [`open`], with the operations available as methods:
//!
//! ```lua
//! local f = assert(io.open("notes.txt", "r"))
//! for line in f:lines() do
//!   print(line)
//! end
//! f:close()
//! ```
//!
//! The library also provides three predefined handles: [`stdin`],
//! [`stdout`] and [`stderr`].

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

/// The standard input file handle.
///
/// ```lua
/// local line = io.stdin:read("l")
/// ```
pub static stdin: file = file;

/// The standard output file handle.
///
/// ```lua
/// io.stdout:write("hello\n")
/// ```
pub static stdout: file = file;

/// The standard error file handle.
///
/// ```lua
/// io.stderr:write("something went wrong\n")
/// ```
pub static stderr: file = file;

/// A handle to an open file.
///
/// File handles are full userdata values with a shared metatable, so
/// every operation is available in method form (`f:read(...)`). When a
/// file handle is collected without being closed, its finalizer closes
/// the file.
pub struct file;

impl file {
    /// Closes a file.
    ///
    /// # Return value
    ///
    /// True on success. Note that files are automatically closed when
    /// their handles are garbage collected, but that takes an
    /// unpredictable amount of time to happen.
    ///
    /// # Examples
    ///
    /// ```lua
    /// local f = assert(io.open("notes.txt"))
    /// print(f:read("a"))
    /// f:close()
    /// ```
    pub fn close(&self) -> boolean {
        todo!()
    }

    /// Flushes a file's output buffer.
    ///
    /// # Description
    ///
    /// Saves any written data to the file. Useful to make sure output is
    /// visible before the file is closed — for example, when writing a
    /// progress log that another process is watching.
    ///
    /// # Examples
    ///
    /// ```lua
    /// log:write("step 3 done\n")
    /// log:flush()
    /// ```
    ///
    /// # See also
    ///
    /// [`setvbuf`](file::setvbuf)
    pub fn flush(&self) {
        todo!()
    }

    /// Returns an iterator over the file's contents.
    ///
    /// # Parameters
    ///
    /// - **`···`**: read formats, as in [`read`](file::read) (default
    ///   `"l"`, read a line).
    ///
    /// # Return value
    ///
    /// An iterator function that, each time it is called, reads the file
    /// according to the given formats. When the iterator reaches the end
    /// of the file, it returns `nil`. Unlike [`io.lines`](lines()), this
    /// form does *not* close the file when the loop ends.
    ///
    /// # Examples
    ///
    /// ```lua
    /// local f = assert(io.open("data.txt"))
    /// for line in f:lines() do
    ///   print(line)
    /// end
    /// f:close()
    /// ```
    pub fn lines(&self, formats: Repeatable<string>) -> function {
        todo!()
    }

    /// Reads from a file.
    ///
    /// # Parameters
    ///
    /// - **`···`**: one or more read formats: `"n"` reads a numeral,
    ///   `"a"` reads the whole file from the current position, `"l"`
    ///   reads the next line dropping the newline (the default), `"L"`
    ///   reads the next line keeping the newline, and a number reads that
    ///   many bytes.
    ///
    /// # Return value
    ///
    /// For each format, a string or a number with the characters read,
    /// or `nil` if it cannot read data with that format (e.g. at end of
    /// file).
    ///
    /// # Examples
    ///
    /// ```lua
    /// local f = assert(io.open("data.txt"))
    /// local first = f:read("l")     -- one line
    /// local rest  = f:read("a")     -- everything else
    /// local n     = io.stdin:read("n")   -- a number from stdin
    /// ```
    ///
    /// # See also
    ///
    /// [`lines`](file::lines), [`io.read`](read())
    pub fn read(&self, formats: Repeatable<string>) -> Repeatable<any> {
        todo!()
    }

    /// Sets and gets the file position.
    ///
    /// # Parameters
    ///
    /// - **`whence`**: the base for the offset: `"set"` (the beginning
    ///   of the file), `"cur"` (the current position — the default), or
    ///   `"end"` (the end of the file).
    /// - **`offset`**: an offset in bytes from the base (default 0).
    ///
    /// # Return value
    ///
    /// The resulting file position, measured in bytes from the beginning
    /// of the file, or `nil` plus an error message on failure. The
    /// no-argument call `f:seek()` reads the current position without
    /// changing it, and `f:seek("end")` returns the file size.
    ///
    /// # Examples
    ///
    /// ```lua
    /// local size = f:seek("end")    -- file size in bytes
    /// f:seek("set")                 -- rewind to the start
    /// f:seek("cur", 16)             -- skip 16 bytes
    /// ```
    pub fn seek(&self, whence: option<string>, offset: option<number>) -> option<number> {
        todo!()
    }

    /// Sets the buffering mode for a file.
    ///
    /// # Parameters
    ///
    /// - **`mode`**: `"no"` (no buffering: output appears immediately),
    ///   `"full"` (output is flushed when the buffer fills or the file
    ///   is closed), or `"line"` (output is buffered until a newline is
    ///   written).
    /// - **`size`**: a hint for the buffer size, in bytes.
    ///
    /// # Examples
    ///
    /// ```lua
    /// log:setvbuf("line")    -- flush the log after every line
    /// ```
    ///
    /// # See also
    ///
    /// [`flush`](file::flush)
    pub fn setvbuf(&self, mode: string, size: option<number>) {
        todo!()
    }

    /// Writes to a file.
    ///
    /// # Parameters
    ///
    /// - **`···`**: strings or numbers to write. Other values must be
    ///   converted first (with [`tostring`](crate::tostring()) or
    ///   `string.format`).
    ///
    /// # Return value
    ///
    /// The file itself, so write calls can be chained; on error, `nil`
    /// plus an error message.
    ///
    /// # Examples
    ///
    /// ```lua
    /// f:write("x = "):write(42):write("\n")
    /// io.stdout:write("no newline is added")
    /// ```
    ///
    /// # See also
    ///
    /// [`io.write`](write())
    pub fn write(&self, values: Repeatable<any>) -> file {
        todo!()
    }
}

/// Closes a file, or the default output file.
///
/// # Parameters
///
/// - **`file`**: the file handle to close (default: the current default
///   output file).
///
/// # Return value
///
/// True on success. Equivalent to `file:close()`.
///
/// # Examples
///
/// ```lua
/// io.output("log.txt")
/// io.write("done\n")
/// io.close()               -- closes log.txt
/// ```
///
/// # See also
///
/// [`file::close`]
pub fn close(f: option<file>) -> boolean {
    todo!()
}

/// Flushes the default output file.
///
/// # Description
///
/// Saves any written data to the default output file. Equivalent to
/// `io.output():flush()`.
///
/// # Examples
///
/// ```lua
/// io.write("working...")
/// io.flush()               -- make it visible before a newline arrives
/// ```
///
/// # See also
///
/// [`file::flush`]
pub fn flush() {
    todo!()
}

/// Sets or gets the default input file.
///
/// # Parameters
///
/// - **`file`**: a file name to open in text mode, or an already open
///   file handle, to become the new default input file. When absent, the
///   function only queries.
///
/// # Return value
///
/// The current default input file. When setting, raises an error if the
/// file name cannot be opened.
///
/// # Examples
///
/// ```lua
/// io.input("data.txt")        -- read from data.txt from now on
/// print(io.read("l"))         -- first line of data.txt
/// io.input(io.stdin)          -- back to stdin
/// ```
///
/// # See also
///
/// [`output`], [`io.read`](read())
pub fn input(f: option<any>) -> file {
    todo!()
}

/// Iterates over the lines of a named file.
///
/// # Parameters
///
/// - **`filename`**: the file to open in read mode. When absent,
///   iterates over the default input file.
/// - **`···`**: read formats, as in [`file::read`] (default `"l"`).
///
/// # Return value
///
/// An iterator function. Unlike [`file::lines`], this form *closes the
/// file automatically* when the loop ends, when it fails, or when it is
/// interrupted by a `break` inside a generic for.
///
/// # Examples
///
/// ```lua
/// for line in io.lines("notes.txt") do
///   print(line)
/// end
/// ```
///
/// # See also
///
/// [`file::lines`], [`open`]
pub fn lines(filename: option<string>, formats: Repeatable<string>) -> function {
    todo!()
}

/// Opens a file.
///
/// # Parameters
///
/// - **`filename`**: the name of the file to open.
/// - **`mode`**: the open mode: `"r"` (read — the default), `"w"`
///   (write, truncating), `"a"` (append), or the update modes `"r+"`,
///   `"w+"`, `"a+"`. Any of them may be followed by `"b"` to open in
///   binary mode on systems where it matters.
///
/// # Return value
///
/// A new file handle, or, in case of errors, `nil` plus an error message
/// and a system-dependent error code. A common idiom wraps the call in
/// [`assert`](crate::assert) to turn a failed open into an error.
///
/// # Examples
///
/// ```lua
/// local f = assert(io.open("out.txt", "w"))
/// f:write("hello\n")
/// f:close()
/// ```
///
/// # See also
///
/// [`lines`], [`close`]
pub fn open(filename: string, mode: option<string>) -> option<file> {
    todo!()
}

/// Sets or gets the default output file.
///
/// # Parameters
///
/// - **`file`**: a file name or an open handle to become the new default
///   output file. When absent, the function only queries.
///
/// # Return value
///
/// The current default output file. Works like [`input`], but for
/// output.
///
/// # Examples
///
/// ```lua
/// io.output("log.txt")
/// io.write("logged\n")        -- goes to log.txt
/// io.output(io.stdout)        -- back to stdout
/// ```
///
/// # See also
///
/// [`input`], [`io.write`](write())
pub fn output(f: option<any>) -> file {
    todo!()
}

/// Starts a program and connects to it with a pipe.
///
/// # Parameters
///
/// - **`prog`**: the command to run in a separate process.
/// - **`mode`**: `"r"` to read the program's output (the default) or
///   `"w"` to write to the program's input.
///
/// # Return value
///
/// A file handle connected to the program, or `nil` plus an error
/// message. This function is system dependent and is not available on
/// all platforms.
///
/// # Examples
///
/// ```lua
/// local p = assert(io.popen("ls -1"))
/// for name in p:lines() do
///   print(name)
/// end
/// p:close()
/// ```
///
/// # See also
///
/// [`os::execute`](crate::os::execute)
pub fn popen(prog: string, mode: option<string>) -> option<file> {
    todo!()
}

/// Reads from the default input file.
///
/// # Parameters
///
/// - **`···`**: read formats, as in [`file::read`] (default `"l"`).
///
/// # Return value
///
/// The values read. Equivalent to `io.input():read(···)`.
///
/// # Examples
///
/// ```lua
/// io.write("what's your name? ")
/// local name = io.read("l")
/// print("hello, " .. name)
/// ```
///
/// # See also
///
/// [`file::read`], [`input`]
pub fn read(formats: Repeatable<string>) -> Repeatable<any> {
    todo!()
}

/// Returns a handle for a temporary file.
///
/// # Return value
///
/// A handle for a temporary file, opened in update mode and
/// automatically removed when the program ends.
///
/// # Examples
///
/// ```lua
/// local scratch = io.tmpfile()
/// scratch:write("intermediate data")
/// scratch:seek("set")
/// print(scratch:read("a"))    --> intermediate data
/// ```
///
/// # See also
///
/// [`os::tmpname`](crate::os::tmpname)
pub fn tmpfile() -> file {
    todo!()
}

/// Checks whether a value is a file handle.
///
/// # Parameters
///
/// - **`obj`**: any value.
///
/// # Return value
///
/// The string `"file"` if `obj` is an open file handle, `"closed file"`
/// if it is a closed file handle, or `nil` if it is not a file handle.
///
/// # Examples
///
/// ```lua
/// local f = assert(io.open("notes.txt"))
/// print(io.type(f))       --> file
/// f:close()
/// print(io.type(f))       --> closed file
/// print(io.type("hi"))    --> nil
/// ```
pub fn r#type(obj: any) -> option<string> {
    todo!()
}

/// Writes to the default output file.
///
/// # Parameters
///
/// - **`···`**: strings or numbers to write.
///
/// # Return value
///
/// The default output file. Equivalent to `io.output():write(···)`.
/// Unlike [`print`](crate::print), no separators or newline are added.
///
/// # Examples
///
/// ```lua
/// io.write("1 + 1 = ", 1 + 1, "\n")    --> 1 + 1 = 2
/// ```
///
/// # See also
///
/// [`file::write`], [`print`](crate::print)
pub fn write(values: Repeatable<any>) -> file {
    todo!()
}