-- xtra LuaDirector
-- v0.4 (c) 2016 Valentin Schmidt
new object me, *namespace
dofile object me, string luaFile
dostring object me, any luaCode

LuaDirector Xtra allows to script Director applications (completely or
partially) in Lua. When the xtra is initialized (by calling 'new'), it looks for
a file called "main.lua" next to the current projector. If "main.lua" exists,
it's automatically loaded and run. Alternatively you can also load lua scripts
manually by calling dofile().

A loaded lua script (like main.lua) can of course load arbitrary other lua
scripts or binary lua extensions (DLLs) using the standard 'require' function.

Director's DOM objects and core functions are available inside Lua, either in
the root namespace - if xtra("LuaDirector").new() was called without optional
namespace argument - or in a separate namespace, if a namespace string ("e.g.
"director") was passed to new().

The following Director DOM objects are supported in Lua (note: those core
objects are case-sensitive in Lua, so they have to be specified as all
lower-case):

  _global
  _key
  _mouse
  _movie
  _player
  _sound
  _system

The following Lingo objects are supported in Lua:

  castlib
  member
  sprite
  window
  xtra

Integers, floats and strings are directly translated to the corresponding Lingo
data type and v.v.
Lua's nil is translated to Lingo's <Void> and v.v.
Lua's boolean type true/false is translated to 1/0 in Lingo.
Lua tables with numeric index starting at 1 are translated to Lingo lists, all
other tables to property lists.

In addition, the following Lingo data types are supported in Lua:

  bytearray
  color
  date
  point
  rect
  symbol
  vector

Director event handlers (prepareMovie, startMovie, exitFrame, mouseDown etc.)
are created in Lua by assigning them as keys to the special 'on' object (or e.g.
'director.on' if "director" was specified as namespace):

on.exitFrame = function ()
  _movie.go(_movie.frame)
end


Finally, the following 5 global (or namespace, see above) functions are
available in Lua. Functions apply() and call() allow to call arbitrary functions
of arbitrary objects, and thereby also allow to use (e.g. asset specific)
functions that are not made available by Director Lua objects.


----------------------------------------
write (string message)
----------------------------------------

Allows to write directly to Director's Message Window. Similar to put(), but
without adding a newline charcater automatically (newline can still be forced 
by adding '\r' to your lua string).

Usage:
======

write('aaa')
write('bbb')
-- aaabbb


----------------------------------------
apply (string handler, object target, table arguments)
----------------------------------------

Usage:
======

apply('put', _movie, {123, 456}) -- equivalent to put(123, 456)
-- 123 456


----------------------------------------
call (string handler [, arg1, arg2, ...])
----------------------------------------

call('put', 123, 456) -- equivalent to put(123, 456) and apply example above
-- 123 456

put(call('do', 'return 42'))
-- 42


----------------------------------------
callsafe (string handler)
----------------------------------------

Allows to call safely into Director's event loop. If you e.g. want to quit the
program, using _movie.halt() doesn't work and results in a crash. For tasks that
mess with Director's core message loop, you have to use callsafe() instead.

In contrast to apply() and call(), this function is asynchronous, and therefor
can't return any result value.

Usage:
======

callsafe('halt')


----------------------------------------
errorName (integer errorNumber)
----------------------------------------

Returns a descriptive error name for specified Lingo error number.

Usage:
======

local res, err = _player.doesntExist()
if err~=0 then
  put(errorName(err))
end
-- "HandlerNotDefined"

local res, err = call("do", "return 1/0")
if err~=0 then
  put(errorName(err))
end
-- "BadParam"


Debugging LuaDirector projects
==============================

Lua related errors can be debugged by standard Lua means.

When calling Director related functions/methods, errors fail silently. But any such
call also returns an additional errorNumber (Note: Lua allows to return multiple
values from function calls), which you can check, and if it's not 0 (=no error),
translate to a descriptive error name by calling errorName() (see above).