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