OBJECTIVE LUA
                                 =============

                               Alpha release 0.1
                               © 2009 David Given
                                  2009-10-05

INTRODUCTION
============

Objective Lua is a experimental system that welds the Objective C class
semantics on top of Lua. It works by translating Objective Lua code into
standard Lua code on-the-fly. As such it is completely portable and completely
compatible with your existing Lua system.

The Objective Lua language is very nearly a pure superset of standard Lua,
adding syntactic structures the provide:

  - a formal class declaration system
  - Objective C [object method: argument] syntax for calling methods
  - exception handling
  
In this package, you get:

  - the Objective Lua translator and run time
  - a minimal class library
  - full documentation
  - a test suite
  - the oldot autodocumentation tool, used to generate the API docs
  
Objective Lua is an experiment and is unfinished. However, it is currently in
a sufficiently working state to be useful for writing real programs. I would
recommend against it, however, as there is no guarantee that the APIs,
semantics, or even syntax are stable. Please see the disclaimer further down
this document.



INSTALLATION
============

You need the lpeg Lua addon module. This is available from:

  http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html
  
If you want to use the oldot autodocumentation tool, you will also need the
markdown module:

  http://luaforge.net/projects/markdown
  
If you're on a Debian-alike, you can install both of these with the following
command:

  apt-get install liblua5.1-markdown0 liblua5.1-lpeg2

Once you've done this, all you need do is to add the olua directory to your Lua
path. Objective Lua contains no C code, and nothing needs to be compiled.

You can try Objective Lua locally by starting your Lua interpreter and then
entering:

  package.path = package.path .. ";?/init.lua"



USING
=====

To use Objective Lua, simply do:

  require 'olua'
  
...from your program. You can now require any Objective Lua modules and they
will be automatically translated and loaded.

Note that the main program itself cannot contain Objective Lua code! However,
there is a tool supplied that will load and run Objective Lua programs:

  ./oluarun example.olua
  
If you want to see the translated code, oluac is a very crude utility that
will do this. Be aware that the translated code is not intended to be human-
readable, and indeed, isn't:

  ./oluac example.olua



DOCUMENTATION
=============

The Objective Lua language and API is extensively, but concisely, documented.
See the doc directory. Most of the documentation is built automatically using
the oldot tool; if you change the standard library or add your own classes,
you can run:

  ./rebuild-documentation
  
...and it'll get regenerated. If you do this, please also run the test suite:

  ./run-tests
    


DISCLAIMER
==========

Objective Lua is EXPERIMENTAL SOFTWARE!

It is ALPHA!

DO NOT USE IT for ANYTHING!

If bad stuff happens DO NOT BLAME ME because YOU HAVE BEEN WARNED!



LEGAL STUFF
===========

Objective Lua is © 2009 David Given. It is distributable under the conditions
laid out by the MIT open source license. You can find a copy in the file
COPYING.


REVISION HISTORY
================

Objective Lua 0.1: 2009-12-16: first release as a serious program.
Objective Lua 0.0.1: 2009-10-05: first toy release.