Extended Api

wiki

While it is true that a complete POSIX binding would allow Lua programs to be written for many platforms, it is also true that at least one major platform (Windows) would be left out. It is neither easy nor clean to attempt to graft a POSIX-like API on top of Windows.

Here is brief list and description of known libraries, APIs and systems:

• ExtensionProposal

This API is meant to provide a more complete programming environment for stand-alone Lua programs on today's popular operating systems (Windows, MacOSX and POSIX platforms).

• [lposix]

A more-or-less straight-forward POSIX binding.

• [LuaFileSystem]

LuaFileSystem offers a portable way to access the underlying directory structure and file attributes.

• LuaSys? [1]:

File I/O and file system; serial communication; sockets; event notification mechanism (recently added IOCP); win32 stuff: registry, event, service; etc.

• FileSystemOperations outlines libraries specifically for file system operations, ignoring more general operation systems related functions.

--

Following is a comparison of the ExtensionProposal API with [lposix] and [LuaFileSystem].

Comparison

Environment

-- get environment variable
os.getenv           posix.getenv

-- set/unset environment variable
os.setenv           posix.putenv
                    posix.setenv
                    posix.unsetenv

-- sleep (pause without consuming CPU)
os.sleep            posix.sleep
--[[
    os.sleep specifies that the implementation provide sub-second
    resolution if available.  posix.sleep provides only second resolution.
--]]

-- system information
                    posix.ctermid
                    posix.errno
                    posix.pathconf
                    posix.sysconf
                    posix.ttyname
                    posix.uname

Directories

-- get/set current directory
os.currentdir       posix.getcwd        lfs.currentdir
os.chdir            posix.chdir         lfs.chdir

-- create/delete directories
os.mkdir            posix.mkdir         lfs.mkdir
os.remove           posix.rmdir         lfs.rmdir
--[[
    In both "ex" and POSIX systems, os.remove() will remove any directory
    entry: both files (non-directories) and empty subdirectories.
    The Lua 5.1 reference says that the standard os.remove() function will
    remove a directory, but in fact the Microsoft MSVCRT implementation
    of the C remove() function (on which os.remove() is based) will not
    remove directories.
--]]

-- POSIX directory routines
                    posix.link
                    posix.unlink
                    posix.mkfifo
                    posix.readlink
                    posix.symlink

Directory entries

-- list directory
os.dir              posix.files         lfs.dir
                    posix.dir

-- get file attributes
os.dirent           posix.stat          lfs.attributes
--[[
    The "ex" os.dir() iterator returns a table of directory entry
    attributes including the name, while the posix.files() and lfs.dir()
    iterators return entry names only.

    The best comparison of these three functions is via example:
--]]
  require"ex"
  for e in os.dir() do
    print(e.name, e.size)
  end

  require"lfs"
  for name in lfs.dir() do
    if name~="." and name~=".." then
      print(name, lfs.attributes(name).size)
    end
  end

  require"posix"
  for name in posix.files() do
    if name~="." and name~=".." then
      print(name, posix.stat(name, "size"))
    end
  end
--[[
    os.dir() elides any "." and ".." names while lfs.dir(),
    posix.dir() and posix.files() include them.
    
    posix.dir() is not an iterator; it returns a table with all entry names.
--]]

-- set file attributes
                    posix.utime         lfs.touch
                    posix.chmod
                    posix.chown
--[[
    The "ex" API says only that the os.dirent() table can be extended
    with OS-specific attribute values.  It would not be unreasonable
    to add file date information to the standard fields:
--]]
  local age = os.difftime(os.time(), e.modified)
  e.modified = os.time() -- touch a file

-- Check permissions
                    posix.access

File I/O

-- file locking
file:lock                               lfs.lock
file:unlock                             lfs.unlock

-- create anonymous pipe
io.pipe

Process control

-- spawn process
os.spawn            posix.fork
proc:wait           posix.exec
                    posix.wait
--[[
    os.spawn supports redirection for standard I/O streams (in,
    out, err) while lposix does not provide full integration with
    POSIX-style descriptors and therefore does not provide a bind
    for the POSIX dup() interface.
--]]

-- signal a process
                    posix.kill

-- process information
                    posix.getprocessid
                    posix.getgroup
                    posix.getlogin
                    posix.getpasswd
                    posix.setgid
                    posix.setuid
                    posix.times
                    posix.umask

Note that the "ex" API was based (in part) on LuaFileSystem and its implementations use some code from it.

Comments

How does ExtensionProposal compare with StandardLibraries and http://luaforge.net/projects/stdlib/ ? -- DavidManura

StandardLibraries appears to be a set of modules written in pure Lua. None of the modules (so far) appear to provide facilities not present in C, but instead provide a set of standard libraries for reuse. It may be that the result of an extended API should belong as part of stdlib. -- MarkEdgar

If you need an extended API right now, you can use Python's via LunaticPython:

> py = require "python"
> os = py.import("os")
> =os.listdir('.')
['lua.exe', 'lua51.dll', 'luac.exe']

--DavidManura