# Module `std.io`

Additions to the core io module.

The module table returned by `std.io` also contains all of the entries from the core `io` module table. An hygienic way to import this module, then, is simply to override core `io` locally:

    local io = require "std.io"

## Functions

catdir (...) | Concatenate directory names into a path.
catfile (...) | Concatenate one or more directories and a filename into a path.
die (msg, ...) | Die with error.
dirname (path) | Remove the last dirsep delimited element from a path.
monkey_patch ([namespace=_G]) | Overwrite core `io` methods with `std` enhanced versions.
process_files (fn) | Process files specified on the command-line.
readlines ([file=io.input()]) | Read a file or file handle into a list of lines.
shell (c) | Perform a shell command and return its output.
slurp ([file=io.input()]) | Slurp a file handle.
splitdir (path) | Split a directory path into components.
warn (msg, ...) | Give warning with the name of program and file (if any).
writelines ([h=io.output()], ...) | Write values adding a newline after each.

## Types

fileprocessor (filename, i) | Signature of process_files callback function.

## Functions

Methods

catdir (...)
  Concatenate directory names into a path.

  ### Parameters:

  - ... string path components

  ### Returns:

  path without trailing separator

  ### See also:

  catfile

  ### Usage:

      dirpath = catdir ("", "absolute", "directory")

catfile (...)
  Concatenate one or more directories and a filename into a path.

  ### Parameters:

  - ... string path components

  ### Returns:

  string path

  ### See also:

  - catdir
  - splitdir

  ### Usage:

      filepath = catfile ("relative", "path", "filename")

die (msg, ...)
  Die with error. This function uses the same rules to build a message prefix as warn.

  ### Parameters:

  - msg string format string
  - ... additional arguments to plug format string specifiers

  ### See also:

  warn

  ### Usage:

      die ("oh noes! (%s)", tostring (obj))

dirname (path)
  Remove the last dirsep delimited element from a path.

  ### Parameters:

  - path string file path

  ### Returns:

  string a new path with the last dirsep and following truncated

  ### Usage:

      dir = dirname "/base/subdir/filename"

monkey_patch ([namespace=_G])
  Overwrite core `io` methods with `std` enhanced versions.

  Also adds readlines and writelines metamethods to core file objects.

  ### Parameters:

  - namespace table where to install global functions (default _G)

  ### Returns:

  table the `std.io` module table

  ### Usage:

      local io = require "std.io".monkey_patch ()

process_files (fn)
  Process files specified on the command-line. Each filename is made the default input source with `io.input`, and then the filename and argument number are passed to the callback function. In list of filenames, `-` means `io.stdin`. If no filenames were given, behave as if a single `-` was passed.

  ### Parameters:

  - fn fileprocessor function called for each file argument

  ### Usage:

       #! /usr/bin/env lua
       -- minimal cat command
       local io = require "std.io"
       io.process_files (function () io.write (io.slurp ()) end)

readlines ([file=io.input()])
  Read a file or file handle into a list of lines. The lines in the returned list are not `\n` terminated.

  ### Parameters:

  - file file or string file handle or name; if file is a file handle, that file is closed after reading (default io.input())

  ### Returns:

  list lines

  ### Usage:

      list = readlines "/etc/passwd"

shell (c)
  Perform a shell command and return its output.

  ### Parameters:

  - c string command

  ### Returns:

  string output, or nil if error

  ### See also:

  os.execute

  ### Usage:

      users = shell [[cat /etc/passwd | awk -F: '{print $1;}']]

slurp ([file=io.input()])
  Slurp a file handle.

  ### Parameters:

  - file file or string file handle or name; if file is a file handle, that file is closed after reading (default io.input())

  ### Returns:

  contents of file or handle, or nil if error

  ### See also:

  process_files

  ### Usage:

      contents = slurp (filename)

splitdir (path)
  Split a directory path into components. Empty components are retained: the root directory becomes `{"", ""}`.

  ### Parameters:

  - path path

  ### Returns:

  list of path components

  ### See also:

  catdir

  ### Usage:

      dir_components = splitdir (filepath)

warn (msg, ...)
  Give warning with the name of program and file (if any). If there is a global `prog` table, prefix the message with `prog.name` or `prog.file`, and `prog.line` if any. Otherwise if there is a global `opts` table, prefix the message with `opts.program` and `opts.line` if any. std.optparse:parse returns an `opts` table that provides the required `program` field, as long as you assign it back to `_G.opts`.

  ### Parameters:

  - msg string format string
  - ... additional arguments to plug format string specifiers

  ### See also:

  - std.optparse:parse
  - die

  ### Usage:

         local OptionParser = require "std.optparse"
         local parser = OptionParser "eg 0\nUsage: eg\n"
         _G.arg, _G.opts = parser:parse (_G.arg)
         if not _G.opts.keep_going then
           require "std.io".warn "oh noes!"
         end

writelines ([h=io.output()], ...)
  Write values adding a newline after each.

  ### Parameters:

  - h file open writable file handle; the file is not closed after writing (default io.output())
  - ... string or number values to write (as for write)

  ### Usage:

      writelines (io.stdout, "first line", "next line")

## Types

fileprocessor (filename, i)
  Signature of process_files callback function.

  ### Parameters:

  - filename string filename
  - i int argument number of filename

  ### Usage:

       local fileprocessor = function (filename, i)
         io.write (tostring (i) .. ":\n===\n" .. io.slurp (filename) .. "\n")
       end
       io.process_files (fileprocessor)

generated by LDoc 1.4.3 Last updated 2018-09-03 17:48:42