root/trunk/lua/state.d

/*******************************************************************************

    copyright:      Copyright (c) 2008 Matthias Walter. All rights reserved

    authors:        Matthias Walter, Andreas Hollandt, Clemens Hofreither

*******************************************************************************/

module lua.state;

private import lua.lua, lua.lualib, lua.lauxlib;
private import lua.buffer, lua.mixins, lua.error, lua.data, lua.utils;

version (Tango)
{
    private import tango.stdc.stdio : fputs, stdout;
}

version (Phobos)
{
    private import std.string : fputs, stdout;
}

/*******************************************************************************

    LuaStandardLibraries defines Constants for the different modules, which
    add basic functionality to a state. They can be OR'ed together to combine
    them.

    Use it as an argument to LuaState.openLibraries to select them.

*******************************************************************************/

public enum LuaStandardLibraries : int
{
    BASE = 0,
    TABLE = 1,
    STRING = 2,
    MATH = 4,
    OS = 8,
    IO = 16,
    DEBUG = 32,
    PACKAGE = 64,
    SAFE = BASE | TABLE | STRING | MATH | OS | PACKAGE,
    ALL = BASE | TABLE | STRING | MATH | OS | PACKAGE | IO | DEBUG
}

/*******************************************************************************

    LuaType defines Constants for the different Lua-internal types.

*******************************************************************************/

public enum LuaType : int
{
    NONE = LUA_TNONE,
    NIL = LUA_TNIL,
    NUMBER = LUA_TNUMBER,
    BOOL = LUA_TBOOLEAN,
    STRING = LUA_TSTRING,
    TABLE = LUA_TTABLE,
    FUNCTION = LUA_TFUNCTION,
    USERDATA = LUA_TUSERDATA,
    THREAD = LUA_TTHREAD,
    LIGHTUSERDATA = LUA_TLIGHTUSERDATA
}

/*******************************************************************************

    LuaGarbageCollectorCommand defines Commands for the LuaState.gc function,
    which controls the garbage collector of a LuaState.

*******************************************************************************/

public enum LuaGarbageCollectorCommand : int
{
    STOP = LUA_GCSTOP,
    RESTART = LUA_GCRESTART,
    COLLECT = LUA_GCCOLLECT,
    COUNT = LUA_GCCOUNT,
    STEP = LUA_GCSTEP,
    SET_PAUSE = LUA_GCSETPAUSE,
    SET_STEP_MULTIPLIER = LUA_GCSETSTEPMUL
}

/// Type of Function with C-linkage which can interface to Lua directly.

alias lua_CFunction LuaCFunction;

/// Type of Integers in Lua

alias lua_Integer LuaInteger;

/// Type of Floats in Lua

alias lua_Number LuaNumber;

/// Registration struct for registering C-linkage functions with Lua

struct LuaRegistry
{
    char[] name;
    LuaCFunction cfunction;
    int category;
}

/// Delegate type for redirecting Lua's stdout to the D host program.

alias void delegate (char[] output) LuaPrint;

/*******************************************************************************

    LuaState wraps a Lua state which keeps the whole state of the Lua
    interpreter. It is thread-safe, as there are no global variables in the
    C library and no unsynchronized static variables in the D wrapper.

    Nearly all of the standard Lua functions are wrapped or reimplemented
    somehow. There are the following exceptions:

    The panic function cannot be changed, which is due to the longjmp
    implementation of the Lua library. Thus you should always use protected
    calls as an initial call to Lua code. If you still want the application
    to panic then, you simply do not catch the exceptions thrown by this
    call, which should terminate your application. Thus, there is no
    wrapper for the lua_atpanic function.

    Also, you cannot set a user-supplied allocation function. As Lua has
    its own garbage collector and all other C variables are directly
    freed by the wrapper classes, this is unnecessary. Thus, there is also
    no wrapper for lua_setallocf and lua_getallocf.

    Some string manipulation/construction routines are not wrapped, because
    this is more easily done in D directly or using the standard library of
    your choice. This has impact on lua_pushfstring, lua_pushvfstring and
    luaL_gsub.

*******************************************************************************/

class LuaState
{
    /// Wrapper Lua state
    private lua_State* state_;

    /// Writer delegate, the Lua stdout
    private LuaPrint write_;
    
    /// Whether the LuaState was created as a sub-thread of another state by calling newThread().
    private bool is_thread_state_;

    /// Constant to pass instead of a number of expected results, if this number is unknown.
    public const int MULTIPLE_RETURN_VALUES = LUA_MULTRET;

    /*******************************************************************************

        Constructs a state with an optional printer delegate. If the latter is
        null, stdout is not redirected.

        Params:
        write = Optional printer delegate.

        Remarks:
        Replaces lua_open, lua_newstate and luaL_newstate.

     *******************************************************************************/

    public this (LuaPrint write = null)
    {
        this.state_ = lua_open ();
        this.write_ = (write is null) ? &writeDefault : write;

        openLibraries (LuaStandardLibraries.BASE);

        LuaState.states[this.state_] = this;
    }

    /*******************************************************************************

        Internal Constructor for Lua thread creation.

        Params:
        write = Printer delegate
        state = Lua state

    *******************************************************************************/

    private this (LuaPrint write, lua_State* state)
    {
        this.write_ = write;
        this.state_ = state;

        LuaState.states[this.state_] = this;
    }

    /*******************************************************************************

        Destructor

        Remarks:
        Replaces lua_close.

    *******************************************************************************/

    private ~this ()
    {
        LuaState.states.remove (this.state_);

        // bugfix by Clemens:
        // states which represent child threads may not be destroyed
        if (!is_thread_state_)
        {
            lua_close (this.state_);
        }
    }

    /*******************************************************************************

        Returns:
        The internal wrapped lua_State object.

        Remarks:
        If you really need to use this function, please contact the author. For
        most functionality there should be a corresponding wrapper function.

    *******************************************************************************/

    public lua_State* state ()
    {
        return this.state_;
    }

    /*******************************************************************************

        Opens the specified standard libraries and adds their functionality to this state.
        See the LuaStandardLibraries enum for possible choices.

        Params:
        categories = choice of standard libraries

        Remarks:
        Replaces luaL_openlibs.

    *******************************************************************************/

    public LuaState openLibraries (LuaStandardLibraries categories = LuaStandardLibraries.ALL)
    {
        static LuaRegistry[] lualibs = [
             { "", &luaopen_base, LuaStandardLibraries.BASE },
             { LUA_TABLIBNAME, &luaopen_table, LuaStandardLibraries.TABLE },
             { LUA_IOLIBNAME, &luaopen_io, LuaStandardLibraries.IO },
             { LUA_OSLIBNAME, &luaopen_os, LuaStandardLibraries.OS },
             { LUA_STRLIBNAME, &luaopen_string, LuaStandardLibraries.STRING },
             { LUA_MATHLIBNAME, &luaopen_math, LuaStandardLibraries.MATH },
             { LUA_DBLIBNAME, &luaopen_debug, LuaStandardLibraries.DEBUG },
             { LUA_LOADLIBNAME, &luaopen_package, LuaStandardLibraries.PACKAGE }
        ];

        openLibraries (lualibs, categories);

        registerFunction ("print", &print);

        return this;
    }

    /*******************************************************************************

        Opens all of the given libraries, which match the given categories bits,
        and adds their functionality to this state.

        Params:
        libraries = Array of possible libraries
        categories = Choice to open. Default is -1, which opens all.

    *******************************************************************************/

    public LuaState openLibraries (LuaRegistry[] libraries, int categories = -1)
    {
        foreach (LuaRegistry reg; libraries)
        {
            if (reg.category == 0 || (reg.category & categories) != 0)
            {
                openLibrary (reg.name, reg.cfunction);
            }
        }
        return this;
    }

    /*******************************************************************************

        Opens one library, adding its functionality to this state. The
        registration function must take the library name as its only
        argument.

        Params:
        library_name = Name of the library
        registration_function = C-linkage function to call for registration

    ******************************************************************************/

    public LuaState openLibrary (char[] library_name, LuaCFunction registration_function)
    {
        pushCFunction (registration_function);
        pushString (library_name);
        call (false, 1, 0);

        return this;
    }

    /*******************************************************************************

        Internal method to pass the given data to the writer delegate.

        Params:
        data = Output to write.

    ******************************************************************************/

    private void write (char[] data)
    {
        this.write_ (data);
    }

    /*******************************************************************************

        Standard writer function, if none is specified in Constructor.

        Params:
        output = Output to write.

    ******************************************************************************/

    private void writeDefault (char[] output)
    {
        fputs (toStringz (output), stdout);
    }

    /*******************************************************************************

        Calls the C function with only one element in its stack, a LightUserdata,
        specified as an argument. It does not change the stack. All values
        returned by the function are discarded. For behavior on errors and the
        description of proctection schemes, see the other call method.
        
        Params:
        protection = whether this is a protected call.
        cfunction = Pointer to a C function.
        userdata = Pointer to C data.
        
        Remarks:
        Replaces lua_cpcall.

    ******************************************************************************/

    public LuaState call (bool protection, LuaCFunction cfunction, void* userdata)
    {
        pushCFunction (cfunction);
        pushLightUserdata (userdata);
        call (protection, 1, 0);

        return this;
    }

    /*******************************************************************************

        Method to call a Lua function, using the following protocol:

        First, the function to be called is pushed onto the stack; then, the
        arguments to the function are pushed in direct order; that is, the first
        argument is pushed first. Finally you call this method with
        the number of arguments that you pushed onto the stack and the expected
        number of return values. All arguments and the function value are popped
        from the stack when the function is called. The function results are
        pushed onto the stack when the function returns. The number of results is
        adjusted to the expected number, unless the latter is
        MULTIPLE_RETURN_VALUES, which is the default. In this case, all results
        from the function are pushed. Lua takes care that the returned values fit
        into the stack space. The function results are pushed onto the stack in
        direct order (the first result is pushed first), so that after the call
        the last result is on the top of the stack.

        There are two different protection schemes, which define behavior on
        errors:

        Protected calls catch errors inside the called function (and all further
        called functions) and throw according exceptions. Lua errors result in
        LuaCodeExceptions and exceptions in D routines which are correctly wrapped
        via the lua mixins result in LuaForwardExceptions.

        Unprotected calls do not catch errors, but quietly propagate them to the
        next protected call in the call stack. If there is no such protected call,
        the application panics, exiting with status 1 and an error message.

        The author of this library suggests the following rules for protection:

        1. If the called routine and its subroutines are really safe,
           use an unprotected call.
        2. If this call happens to be called as the first function on the Lua
           call stack, use a protected call.
        3. If this is not the first function on the call stack (e.g. in a library
           function called by some Lua code, which is called by a protected call)
           you have the choice. Unprotected calls should be slightly faster, but
           on error, a protected call would add one LuaForwardException to the
           exception stack, which may help to identify error sources.

        Params:
        protection = whether this is a protected call.
        arguments = number of function arguments on the stack. Default is 0
        results = expected number of return values. Default is a variable number.

        Remarks:
        Replaces lua_call and lua_pcall.

    ******************************************************************************/

    public LuaState call (bool protection, uint arguments = 0, int results = MULTIPLE_RETURN_VALUES)
    {
        if (protection)
        {
            int errors = lua_pcall (this.state_, arguments, results, 0);
            if (errors != 0)
            {
                char[] error = popString ();

                // parse the error string to extract the address of the exception
                char[] pointer_string = null;
                for (int start = error.length-6; start >= 0; start--)
                {
                    if (error[start .. start + 4] == "LFE=")
                    {
                        for (int end = start+5; end < error.length; end++)
                        {
                            if (error[end] == ';')
                            {
                                pointer_string = error[start+4 .. end];
                                break;
                            }
                        }
                        break;
                    }
                }

                if (pointer_string != null)
                {
                    void* p = cast (void*) string2int !(ulong) (pointer_string);
                    LuaForwardException e = LuaForwardException.exceptions[p];
                    LuaForwardException.exceptions.remove (p);
                    e.forward ("LuaState.call");
                    throw e;
                }
                else
                {
                    throw new LuaCodeException (error);
                }
            }
        }
        else
        {
            lua_call (this.state_, arguments, results);
        }

        return this;
    }

    /*******************************************************************************

        Loads and runs the given string.

        Params:
        protection = whether this is a protected call. See LuaState.call
        code = Lua code to run.
        arguments = number of function arguments on the stack. Default is 0
        results = expected number of return values. Default is a variable number.
        chunk_name = Name of the code chunk.

        Remarks:
        Replaces luaL_dostring.

    ******************************************************************************/

    public LuaState doString (bool protection, char[] code, uint arguments = 0, int results = MULTIPLE_RETURN_VALUES, char[] chunk_name = null)
    {
        load (code, chunk_name);

        return call (protection, arguments, results);
    }

    /// ditto

    public LuaState doString (bool protection, char[] code, char[] chunk_name, uint arguments = 0, int results = MULTIPLE_RETURN_VALUES)
    {
        return doString (protection, code, arguments, results, chunk_name);
    }

    /*******************************************************************************

        Loads and runs the given file.

        Params:
        protection = whether this is a protected call. See LuaState.call
        filename = Lua file to run.
        arguments = number of function arguments on the stack. Default is 0
        results = expected number of return values. Default is a variable number.

        Remarks:
        Replaces luaL_dofile.

    ******************************************************************************/

    public LuaState doFile (bool protection, char[] filename, uint arguments = 0, int results = MULTIPLE_RETURN_VALUES)
    {
        loadFile (filename);

        return call (protection, arguments, results);
    }

    /*******************************************************************************

        If the object at the specified index has a metatable with the specified
        field, this method calls this field and passes the object as its only
        argument. In this case this function returns true and pushes the returned
        value onto the stack. If there is no metatable or no metamethod, this
        function returns false without pushing any value on the stack.

        Remarks:
        Replaces luaL_callmeta.

    ******************************************************************************/

    public bool callMeta (int index, char[] field)
    {
        return luaL_callmeta (this.state_, index, toStringz (field)) != 0;
    }

    /*******************************************************************************

        If the function argument is number, returns this number cast to an int.
        If this argument is absent or is nil, returns the default value.
        Otherwise, raises an error.

        Remarks:
        Replaces luaL_optint, luaL_optlong and luaL_optinteger.

    ******************************************************************************/

    public LuaInteger optInteger (uint argument, LuaInteger default_value)
    {
        return luaL_optint (this.state_, argument, default_value);
    }

    /*******************************************************************************

        If the function argument is number, returns this number.
        If this argument is absent or is nil, returns the default value.
        Otherwise, raises an error.

        Remarks:
        Replaces luaL_optnumber.

    ******************************************************************************/

    public LuaNumber optNumber (uint argument, LuaNumber default_value)
    {
        return luaL_optnumber (this.state_, argument, default_value);
    }

    /*******************************************************************************

        If the function argument is a string, returns this string. If this
        argument is absent or is nil, returns the default value. Otherwise,
        raises an error.

        Remarks:
        Replaces luaL_optlstring and luaL_optstring.

    ******************************************************************************/

    public char[] optString (uint argument, char[] default_value)
    {
        size_t len;
        char* ptr = luaL_optlstring (this.state_, argument, toStringz (default_value), &len);

        return ptr[0 .. len];
    }

    /*******************************************************************************

        Checks whether the function argument is a string and searches for this
        string in the array value_list. Returns the index in the array where the
        string was found. Raises an error if the argument is not a string or if
        the string cannot be found.

        If default_value is not null, the function uses default_value as a default
        value when there is no argument or if this argument is nil.

        This is a useful function for mapping strings to enums. (The usual
        convention in Lua libraries is to use strings instead of numbers to
        select options.)

        Remarks:
        Replaces luaL_checkoption.

    ******************************************************************************/

    public int checkOption (uint argument, char[][] value_list, char[] default_value = null)
    {
        char[] name = (default_value !is null) ? optString (argument, default_value) : checkString (argument);

        foreach (i, s; value_list)
        {
            if (s == name)
                return i;
        }

        throw new LuaCodeException ("Invalid option: '" ~ name ~ "'");
    }

    /*******************************************************************************

        Raises a Lua error specified by the message argument. If the latter is
        null, this method takes the object on top of the stack as the error
        message. This method does a long jump, and therefore never returns.

        Params:
        message = The message to pass as the error code.

        Remarks:
        Replaces lua_error and luaL_error.

    ******************************************************************************/

    public int raiseError (char[] message = null)
    {
        if (message !is null)
        {
            pushString (message);
        }
        return lua_error (this.state_);
    }

    /*******************************************************************************

        Raises a Lua error due to a bad function argument, where the function
        name is taken from the call stack.

        bad argument #<argument> to <function> (<message>)

        This method does a long jump, and therefore never returns.

        Params:
        argument = Which argument is wrong or missing.
        message = The error message.

        Remarks:
        Replaces luaL_argerror.

    ******************************************************************************/

    public int argumentError (uint argument, char[] message)
    {
        return luaL_argerror (this.state_, argument, toStringz (message));
    }

    /*******************************************************************************

        Raises an error with a message like the following:

        <loc>: bad argument <argument> to '<func>' (<typename> expected, got <rt>)

        where loc is produced by LuaState.where, func is the name of the current
        function, and rt is the type name of the actual argument.

        This method does a long jump, and therefore never returns.

        Params:
        argument = Which argument is wrong or missing.
        typename = The expected type name.

        Remarks:
        Replaces luaL_typerror.

    ******************************************************************************/

    public int typeError (uint argument, char[] typename)
    {
        return luaL_typerror (this.state_, argument, toStringz (typename));
    }

    /*******************************************************************************

        Constructs a LuaBuffer and attaches it to this state.

        Returns:
        The constructed Lua buffer.

    *******************************************************************************/

    public LuaBuffer createBuffer ()
    {
        return new LuaBuffer (this);
    }

    /*******************************************************************************

        Dumps a function as a binary chunk. Receives a Lua function on the top
        of the stack and produces a binary chunk that, if loaded again, results
        in a function equivalent to the one dumped. As it produces parts of the
        chunk, dump call the delegate with the given data to write them.

        The value returned is the error code returned by the last call to the
        delegate; 0 means no errors.

        This method does not pop the Lua function from the stack.

        Params:
        dg = Writer delegate

        Remarks:
        Replaces lua_dump.

    *******************************************************************************/

    public int dump (int delegate (char[] data) dg)
    {
        return lua_dump (this.state_, &writer, &dg);
    }

    /*******************************************************************************

        Dumps a function as a binary chunk. It works exactly like the above dump
        method, but instead of passing the data to a delegate, it returns the
        complete result in one character array.

    *******************************************************************************/

    public char[] dump ()
    {
        char[] result = [];

        int dumper (char[] data)
        {
            result ~= data;
            return 0;
        }

        dump (&dumper);

        return result;
    }

    /*******************************************************************************

        Loads a Lua chunk. If there are no errors, load pushes the compiled
        chunk as a Lua function on top of the stack. Otherwise, it raises
        either a LuaCodeException, if the code cannot be compiled or a
        LuaFatalException on other errors.

        This function only loads a chunk; it does not run it. It automatically
        detects whether the chunk is text or binary, and loads it accordingly.

        The load method uses a user-supplied reader delegate to read the chunk,
        which must return either data or null when called. The latter means,
        that there is no further data to read.

        The chunk_name argument gives a name to the chunk, which is used for
        error messages and in debug information.
        
        ---
        auto L = new LuaState;
        L.doString (true, `
        function fac (n)
          if n == 0 then 
            return 1;
          else
            return n * fac(n-1);
          end
        end
        `);

        L.getGlobal ("fac"); // put function onto stack
        char[] data = L.dump (); // dump it
        L.pop (); // pop it
        L.load (data, "foo"); // reload function as chunk 'foo'
        L.setGlobal ("fac2"); // save it as the global function fac2
        ---

        Params:
        dg = Reader delegate
        chunk_name = Name of this chunk