**********************************************************************
* Author  : Brian Maher <maherb at brimworks dot com>
* Library : lua_archive - Lua 5.1 interface to libarchive
*
* The MIT License
* 
* Copyright (c) 2009 Brian Maher
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
* 
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
* 
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
**********************************************************************

To use this library, you need libarchive, get it here:
     http://code.google.com/p/libarchive/

To build this library, you need CMake, get it here:
    http://www.cmake.org/cmake/resources/software.html

Loading the library:

    If you built the library as a loadable package
        [local] archive = require 'archive'

    If you compiled the package statically into your application, call
    the function "luaopen_archive(L)". It will create a table with the
    archive functions and leave it on the stack.

-- archive functions --

major, minor, patch = archive.version()

    returns numeric major, minor, and patch versions from the archive
    library.

write = archive.write {
    compression     = "gzip",
    format          = "pax-restricted",
    options         = "compression-level=9,sha1",
    block_size      = 10240,
    last_block_size = 1,
    writer          = function(archive_write, string)
        if ( nil == string ) then
           fh:close()
        else
           fh:write(string)
           return #string
        end
    end,
}

    Generate an archive.  All parameters are optional except for the
    writer parameter.  The writer is called with nil when EOF is
    reached, otherwise it is called with a string to be written, and
    it is currently a requirement to return the number of bytes
    written (libarchive has this API, so I preserved it).  The
    archive_write is the instance of the "archive{write}" object
    requesting to write data.

    Returns an "archive{write}" object with these functions that are used to
    create your archive:

    write:header(archive_entry)

        Append a new file entry to the archive.  archive_entry must be
        an "archive{entry}" object (see  below for how to create one).

    write:data(string)

        Append the file contents for the last file entry created.

    write:close()

       Be sure to clean-up the resources and close the underlying file
       handle.  Due to the nature of the underlying implementation, it
       will take two rounds of GC to autmoatically collect an object
       that was not closed.

read = archive.read {
    reader = function(archive_read)
        return fh:read(10000)
    end,
    -- TODO: document other options.
}

    Reads an archive.  All parameters are optional except for the
    reader function that returns nil on EOF, otherwise it returns the
    bytes read from the archive file.  The archive_read parameter is
    the instance of the "archive{read}" object that is requesting to
    read some bytes.

    Returns an "archive{read}" object with these functions used to
    read the archive:

    archive_header = read:next_header()

        Reads the next header entry from the archive, or nil if there
        are no more files in the archive.

    string = read:data()

        Reads a buffer of data from the file for which we just got the
        header for (must call next_header() at least once before
        calling this).  Returns nil if there is no more data to read
        from this file entry (but there may still be more file
        entries!).

    read:close()

       Be sure to clean-up the resources and close the underlying file
       handle.  Due to the nature of the underlying implementation, it
       will take two rounds of GC to autmoatically collect an object
       that was not closed.

entry = archive.entry {
    sourcepath = <string>,
    pathname = <string>,
    mode = <number>,
    dev = <number>,
    ino = <number>,
    nlink = <number>,
    uid = <number>,
    uname = <string>,
    gid = <number>,
    gname = <string>,
    atime = { <number>, <number> },
    mtime = { <number>, <number> },
    ctime = { <number>, <number> },
    birthtime = { <number>, <number> },
    size = <number>,
    fflags = <string>,
}

    Create a new archive entry.  If passed in a sourcepath, then all
    relevant fields will be initialized with the results of lstat().
    Each field is then iterated over, calling the appropriate set
    method mentioned below.

    Returns an "archive{entry}" object with the following methods:

    path = entry:sourcepath()
    entry:sourcepath(path)

        Get/set the 'sourcepath', note that this field is not saved to
        the archive and is not even used by libarchive, but exists as
        a convenience.  Also note that the special logic of
        initializing from the resuls of lstat() only applies to the
        constructor and does not apply to the setter here.

    path = entry:pathname()
    entry:pathname(path)

         Get/set the 'pathname'.  You pretty much always want this to
         be a relative path... otherwise people get mad.

    number = entry:mode()
    entry:mode(number)

         Get/set the 'mode' as a raw number.  A certain part of this
         field is the file type and another part is the permissions.
         TODO: provide better support for manipulating the mode?

    number = entry:dev()
    number = entry:rdev()
    entry:dev(number)
    entry:rdev(number)

        Get/set the 'dev' or 'rdev' field (so far, I've not seen
        'rdev' field be preserved... so I'm not sure exactly what it
        does).

    number = entry:ino()
    entry:ino(number)

        Get/set the 'ino' field.  This is used to uniquely identify a
        file on a given device (if ino + dev is the same, they must be
        the same file).

    number = entry:nlink()
    entry:nlink(number)

        Get/set the number of hardlinks.

    number = entry:uid()
    entry:uid(number)

        Get/set the user identifier that owns this file.

    string = entry:uname()
    entry:uname(string)

        Get/set the user name that owns this file.  Note that it is a
        good idea to resolve the uid to a uname when archiving in case
        the system on which you read the archive does not have a
        matching uid.  This resolution is not autmoatically done with
        the sourcepath constructor field, but this might be done
        automatically in the future?

    number = entry:gid()
    entry:gid(number)

        Get/set the group identifier that owns this file.

    string = entry:gname()
    entry:gname(string)

        Get/set the group name that owns this file.  Again, it is a
        good idea to resolve gid to gname.

    (seconds, microseconds) = entry:atime()
    entry:atime(seconds, microseconds)
    (seconds, microseconds) = entry:mtime()
    entry:mtime(seconds, microseconds)
    (seconds, microseconds) = entry:ctime()
    entry:ctime(seconds, microseconds)
    (seconds, microseconds) = entry:birthtime()
    entry:birthtime(seconds, microseconds)

        Get/set the "access"/"modified"/"creation"/"birth" time of the
        file.  The microseconds field is optional and may be nil.

    number = entry:size()
    entry:size(number)

        Get/set the size of the file represented by the entry.

    string = entry:fflags()
    entry:fflags(string)

        Get/set the "fflags", these are special attributes of the
        file (like archive,dump,nosappnd).

######################################################################
# TODO: disk API!  Way to easily traverse the filesystem?

write = archive.write_disk {
    options = "secure-nodotdot,secure-symlinks,no-overwrite",    
}

    Generate on-disk representation of an archive, by handling the
    various events when parsing an archive.

    write:header(archive.entry)

        Create a file on disk for this archive entry.

    write:data("data to append to archive entry")

        Append data to the last file header created on disk.

    write:close()

       Be sure to clean-up the resources and close the underlying file
       handle.

read = archive.disk_read {
    -- TODO: Various options...
    events = {
        header = function(events, archive.entry),
        data   = function(events, string_data),
        close  = function(events), -- Called on EOF.
    }
}

    Read files and file entries from disk.    

    read("path/on/disk/to/file.txt" [, "location/in/archive/file.txt"])

    read(nil) -- For EOF

        Call it with the location of a file on disk and trigger the
        header and data events.  Call with nil to trigger the close
        event.

        You may optionally specify the location of the entry as you
        want it stored in an archive.  Helpful if you are using
        absolute paths, but want the archive to store relative paths.