Introduction
============

This is a Lua binding for Dazuko.  See http://www.lua.org for
details on the Lua language.  "Lua is an extension programming
language designed to support general procedural programming with
data description facilities.  It also offers good support for
object-oriented programming, functional programming, and
data-driven programming. Lua is intended to be used as a
powerful, light-weight configuration language for any program
that needs one. Lua is implemented as a library, written in clean
C (that is, in the common subset of ANSI C and C++)."  Lua was
designed for easy integration into other applications and gets
heavily used in embedded systems and for scripting purposes in
editors, statistics or database software, game engines, and the
like.

This language binding was released under the BSD license.  The
original version was created by Gerhard Sittig.

Preparation
===========

You need the dazukoio.h header file and the libdazuko.a library
to build this extension.  If you have not done so before, run the
following command:

$ make -C ../library

Since lua was designed for embedding into other applications it
does not provide the "makefile makers" or "package management"
other scripting languages have.  So you may have to tweak the
Makefile a little to fit your needs.

Building the extension
======================

The libdazuko.c source file exports the Dazuko C library's
routines into Lua land while it's a very thin wrapper to provide
Lua style calling conventions but does not change the procedural
interface style of the library.  Build it with this command:

$ make libluadazuko.so

The dazuko.lua script wraps the C interface and provides an
object oriented access to the Dazuko functionality.  Just
"require" it in your application.

Testing the extension
=====================

The example.lua script demonstrates how to interface with Dazuko
by means of the 'libdazuko' module.  It gets a list of include
path specs to watch and dumps access details when file operations
take place.  The script will be stopped by hitting CTRL-C.  Start
it like this:

# lua example.lua `pwd -P`

Note that the script wants to register with Dazuko and needs
privileges to do so.

See the bottom of the example.lua script, it can interface with
Dazuko either in procedural style (libdazuko interface) or OO
style (dazuko.lua OO wrapper).

Embedding a lua access handler
==============================

The above approach is the classical "extension" for a programming
language: provide functionality by exporting it into its
namespace, making it accessible with the natural means of the
language.

A different approach was taken in the example.c source:  This C
program embeds a lua script (for example the config.lua file
which serves demonstration purposes).  The configuration as well
as the access handler can be of arbitrary complexity (set or
calculate values, access local or remote sources of information,
handle the access details in any way one could think of).

Invoke this example with the name of the script file to read and
the name of the configuration bundle to use:

# ./example config.lua cfg1
# ./example config.lua cfg2

TODO
====

There's rather little documentation.  But there is no real lack
since this extension is just a thin wrapper around the C library
which is well documented on the www.dazuko.org homepage.  The
only exception is the getaccess() routine which gets and returns
an access (after calling the handler) so the application can not
do too much wrong. :)  It cannot be stressed enough that accesses
ALWAYS SHOULD be returned to Dazuko -- even in read only mode.
