lua-types/core/io.d.ts

TypeScript definitions for Lua standard library

// Based on https://www.lua.org/manual/5.3/manual.html#6.8

/** @noSelfInFile */

/**
 * The I/O library provides two different styles for file manipulation. The
 * first one uses implicit file handles; that is, there are operations to set a
 * default input file and a default output file, and all input/output operations
 * are over these default files. The second style uses explicit file handles.
 *
 * When using implicit file handles, all operations are supplied by table io.
 * When using explicit file handles, the operation io.open returns a file handle
 * and then all operations are supplied as methods of the file handle.
 *
 * The table io also provides three predefined file handles with their usual
 * meanings from C: io.stdin, io.stdout, and io.stderr. The I/O library never
 * closes these files.
 *
 * Unless otherwise stated, all I/O functions return nil on failure (plus an
 * error message as a second result and a system-dependent error code as a third
 * result) and some value different from nil on success. On non-POSIX systems,
 * the computation of the error message and error code in case of errors may be
 * not thread safe, because they rely on the global C variable errno.
 */
declare namespace io {
    /**
     * Equivalent to file:close(). Without a file, closes the default output file.
     */
    function close(file?: LuaFile): boolean;

    /**
     * Equivalent to io.output():flush().
     */
    function flush(): boolean;

    /**
     * When called with a file name, it opens the named file (in text mode), and
     * sets its handle as the default input file. When called with a file handle,
     * it simply sets this file handle as the default input file. When called
     * without parameters, it returns the current default input file.
     *
     * In case of errors this function raises the error, instead of returning an
     * error code.
     */
    function input(file?: string | LuaFile): LuaFile;

    /**
     * Opens the given file name in read mode and returns an iterator function
     * that works like file:lines(···) over the opened file. When the iterator
     * function detects the end of file, it returns no values (to finish the loop)
     * and automatically closes the file.
     *
     * The call io.lines() (with no file name) is equivalent to
     * io.input():lines("*l"); that is, it iterates over the lines of the default
     * input file. In this case it does not close the file when the loop ends.
     *
     * In case of errors this function raises the error, instead of returning an
     * error code.
     */
    function lines<T extends FileReadFormat[]>(
        filename?: string,
        ...formats: T
    ): LuaIterable<
        LuaMultiReturn<[] extends T ? [string] : { [P in keyof T]: FileReadFormatToType<T[P]> }>
    >;

    /**
     * This function opens a file, in the mode specified in the string mode. In
     * case of success, it returns a new file handle.
     *
     * The mode string can be any of the following:
     *
     * * "r": read mode (the default);
     * * "w": write mode;
     * * "a": append mode;
     * * "r+": update mode, all previous data is preserved;
     * * "w+": update mode, all previous data is erased;
     * * "a+": append update mode, previous data is preserved, writing is only
     *   allowed at the end of file.
     *
     * The mode string can also have a 'b' at the end, which is needed in some
     * systems to open the file in binary mode.
     */
    function open(
        filename: string,
        mode?: string
    ): LuaMultiReturn<[LuaFile] | [undefined, string, number]>;

    /**
     * Similar to io.input, but operates over the default output file.
     */
    function output(file?: string | LuaFile): LuaFile;

    /**
     * This function is system dependent and is not available on all platforms.
     *
     * Starts program prog in a separated process and returns a file handle that
     * you can use to read data from this program (if mode is "r", the default) or
     * to write data to this program (if mode is "w").
     */
    function popen(prog: string, mode?: 'r' | 'w'): LuaMultiReturn<[LuaFile] | [undefined, string]>;

    /**
     * Equivalent to io.input():read(···).
     */
    function read(): io.FileReadFormatToType<io.FileReadLineFormat> | undefined;
    function read<T extends io.FileReadFormat>(format: T): io.FileReadFormatToType<T> | undefined;
    function read<T extends io.FileReadFormat[]>(
        ...formats: T
    ): LuaMultiReturn<{ [P in keyof T]?: io.FileReadFormatToType<T[P]> }>;

    /**
     * Predefined file handle for standard error stream. The I/O library never closes this file.
     */
    const stderr: LuaFile;

    /**
     * Predefined file handle for standard input stream. The I/O library never closes this file.
     */
    const stdin: LuaFile;

    /**
     * Predefined file handle for standard output stream. The I/O library never closes this file.
     */
    const stdout: LuaFile;

    /**
     * In case of success, returns a handle for a temporary file. This file is
     * opened in update mode and it is automatically removed when the program
     * ends.
     */
    function tmpfile(): LuaFile;

    /**
     * Checks whether obj is a valid file handle. Returns the string "file" if obj
     * is an open file handle, "closed file" if obj is a closed file handle, or
     * nil if obj is not a file handle.
     */
    function type(obj: any): 'file' | 'closed file' | undefined;

    /**
     * Equivalent to io.output():write(···).
     */
    function write(...args: (string | number)[]): LuaMultiReturn<[LuaFile] | [undefined, string]>;

    type FileReadFormatToType<T> = T extends FileReadNumberFormat ? number : string;
}

interface LuaFile {
    /**
     * Closes file. Note that files are automatically closed when their handles
     * are garbage collected, but that takes an unpredictable amount of time to
     * happen.
     *
     * When closing a file handle created with io.popen, file:close returns the
     * same values returned by os.execute.
     */
    close(): boolean;

    /**
     * Saves any written data to file.
     */
    flush(): boolean;

    /**
     * Returns an iterator function that, each time it is called, reads the file
     * according to the given formats. When no format is given, uses "l" as a
     * default. As an example, the construction
     *
     * `for c in file:lines(1) do body end`
     *
     * will iterate over all characters of the file, starting at the current
     * position. Unlike io.lines, this function does not close the file when the
     * loop ends.
     *
     * In case of errors this function raises the error, instead of returning an
     * error code.
     */
    lines<T extends io.FileReadFormat[]>(
        ...formats: T
    ): LuaIterable<
        LuaMultiReturn<[] extends T ? [string] : { [P in keyof T]: io.FileReadFormatToType<T[P]> }>
    >;

    /**
     * Reads the file file, according to the given formats, which specify what to
     * read. For each format, the function returns a string or a number with the
     * characters read, or nil if it cannot read data with the specified format.
     * (In this latter case, the function does not read subsequent formats.) When
     * called without formats, it uses a default format that reads the next line
     * (see below).
     *
     * The available formats are
     *
     * * "n": reads a numeral and returns it as a float or an integer, following
     *   the lexical conventions of Lua. (The numeral may have leading spaces and
     *   a sign.) This format always reads the longest input sequence that is a
     *   valid prefix for a numeral; if that prefix does not form a valid numeral
     *   (e.g., an empty string, "0x", or "3.4e-"), it is discarded and the
     *   function returns nil.
     * * "a": reads the whole file, starting at the current position. On end of
     *   file, it returns the empty string.
     * * "l": reads the next line skipping the end of line, returning nil on end
     *   of file. This is the default format.
     * * "L": reads the next line keeping the end-of-line character (if present),
     *   returning nil on end of file.
     * * number: reads a string with up to this number of bytes, returning nil on
     *   end of file. If number is zero, it reads nothing and returns an empty
     *   string, or nil on end of file.
     *
     * The formats "l" and "L" should be used only for text files.
     */
    read(): io.FileReadFormatToType<io.FileReadLineFormat> | undefined;
    read<T extends io.FileReadFormat>(format: T): io.FileReadFormatToType<T> | undefined;
    read<T extends io.FileReadFormat[]>(
        ...formats: T
    ): LuaMultiReturn<{ [P in keyof T]?: io.FileReadFormatToType<T[P]> }>;

    /**
     * Sets and geionts the file position, measured from the beginning of the
     * file, to the posit given by offset plus a base specified by the string
     * whence, as follows:
     *
     * * "set": base is position 0 (beginning of the file);
     * * "cur": base is current position;
     * * "end": base is end of file;
     *
     * In case of success, seek returns the final file position, measured in bytes
     * from the beginning of the file. If seek fails, it returns nil, plus a
     * string describing the error.
     *
     * The default value for whence is "cur", and for offset is 0. Therefore, the
     * call file:seek() returns the current file position, without changing it;
     * the call file:seek("set") sets the position to the beginning of the file
     * (and returns 0); and the call file:seek("end") sets the position to the end
     * of the file, and returns its size.
     */
    seek(
        whence?: 'set' | 'cur' | 'end',
        offset?: number
    ): LuaMultiReturn<[number] | [undefined, string]>;

    /**
     * Sets the buffering mode for an output file. There are three available
     * modes:
     *
     * * "no": no buffering; the result of any output operation appears
     *   immediately.
     * * "full": full buffering; output operation is performed only when the
     *   buffer is full or when you explicitly flush the file (see io.flush).
     * * "line": line buffering; output is buffered until a newline is output or
     *   there is any input from some special files (such as a terminal device).
     *   For the last two cases, size specifies the size of the buffer, in bytes.
     *   The default is an appropriate size.
     */
    setvbuf(mode: 'no' | 'full' | 'line', size?: number): void;

    /**
     * Writes the value of each of its arguments to file. The arguments must be
     * strings or numbers.
     *
     * In case of success, this function returns file. Otherwise it returns nil
     * plus a string describing the error.
     */
    write(...args: (string | number)[]): LuaMultiReturn<[LuaFile] | [undefined, string]>;
}