root/trunk/minid/bind.d

/******************************************************************************
This module contains scary template stuff to make it possible to wrap D functions,
classes, and structs and expose them as functions and types in MiniD.

License:
Copyright (c) 2008 Jarrett Billingsley

This software is provided 'as-is', without any express or implied warranty.
In no event will the authors be held liable for any damages arising from the
use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it freely,
subject to the following restrictions:

    1. The origin of this software must not be misrepresented; you must not
    claim that you wrote the original software. If you use this software in a
    product, an acknowledgment in the product documentation would be
    appreciated but is not required.

    2. Altered source versions must be plainly marked as such, and must not
    be misrepresented as being the original software.

    3. This notice may not be removed or altered from any source distribution.
******************************************************************************/

module minid.bind;

import tango.core.Traits;
import tango.core.Tuple;
import Utf = tango.text.convert.Utf;

import minid.ex;
import minid.interpreter;
import minid.types;
import minid.utils;

/**
Wraps a module.  This registers a custom module loader in the global modules.customLoaders
table of the given thread.  The members will not actually be wrapped until the module is imported
the first time.

Template Params:
    name = The name of the module, in dotted form (like "foo.bar.baz").  This is the name that will
        be used to import it.

    Members = A variadic list of things to declare in this module.  These will be declared as module
        globals, just as if you declared them globals in MiniD.  Supported member types include
        WrapFunc, WrapNamespace, WrapValue, and WrapType.

Params:
    t = This module's loader will be added into the global modules.customLoaders table accessible
        from this thread.
*/
public void WrapModule(char[] name, Members...)(MDThread* t)
{
    pushGlobal(t, "modules");
    field(t, -1, "customLoaders");

    newFunction(t, function uword(MDThread* t, uword numParams)
    {
        commonNamespace!(name, true, Members)(t);
        return 0;
    }, name);

    fielda(t, -2, name);
    pop(t, 2);
}

/**
Wraps any number of values into the global namespace accessible from the given thread.  This is
the root global namespace, outside of any modules.  Works just like WrapModule otherwise.
Supported member types include WrapFunc, WrapNamespace, WrapValue, and WrapType.

The wrapped values are immediately loaded into the global namespace.
*/
public void WrapGlobals(Members...)(MDThread* t)
{
    commonNamespace!("", true, Members)(t);
}

private void commonNamespace(char[] name, bool isModule, Members...)(MDThread* t)
{
    static if(!isModule)
        newNamespace(t, name);

    foreach(i, member; Members)
    {
        static if(is(typeof(member.isFunc)))
            newFunction(t, &member.WrappedFunc, member.Name);
        else static if(is(typeof(member.isNamespace)))
            commonNamespace!(member.Name, false, member.Values)(t);
        else static if(is(typeof(member.isValue)))
            superPush(t, member.Value);
        else static if(is(typeof(member.isType)))
            member.init!(name)(t);
        else static if(isModule)
            static assert(false, "Invalid member type '" ~ member.stringof ~ "' in wrapped module '" ~ name ~ "'");
        else
            static assert(false, "Invalid member type '" ~ member.stringof ~ "' in wrapped namespace '" ~ name ~ "'");

        static if(isModule)
            newGlobal(t, member.Name);
        else
            fielda(t, -2, member.Name);
    }
}

/**
Wraps a static function - that is, a function that doesn't have a 'this' parameter.  These four
template specializations allow you to fine-tune how the function is to be wrapped.

The first specialization takes just an alias to a function.  In this case, the first overload
of the function (if any) will be wrapped and the name of the function in MiniD will be the same
as in D.

The second specialization allows you to explicitly specify a function signature to choose, in the
case that the function you're wrapping is overloaded.  The signature should be a function type that
matches the signature of the overload you want to wrap.  In this case, though, the name in MiniD
will still be the name of the D function.

The third specialization allows you to rename the function without explicitly selecting an overload.

The fourth specialization allows you to both select an overload and give it the name that should
be used in MiniD.  This is the form you'll probably be using most often with overloaded D functions.

If you use one of the two forms where you explicitly specify the function signature, the resulting
wrapped function will only accept exactly as many parameters as are specified in the signature.
Otherwise, the wrapped function will be allowed to have optional parameters.
*/
public struct WrapFunc(alias func)
{
    const bool isFunc = true;
    const char[] Name = NameOfFunc!(func);
    mixin WrappedFunc!(func, Name, typeof(&func), false);
}

/// ditto
public struct WrapFunc(alias func, funcType)
{
    const bool isFunc = true;
    const char[] Name = NameOfFunc!(func);
    mixin WrappedFunc!(func, Name, funcType, true);
}

/// ditto
public struct WrapFunc(alias func, char[] name)
{
    const bool isFunc = true;
    const char[] Name = name;
    mixin WrappedFunc!(func, Name, typeof(&func), false);
}

/// ditto
public struct WrapFunc(alias func, char[] name, funcType)
{
    const bool isFunc = true;
    const char[] Name = name;
    mixin WrappedFunc!(func, Name, funcType, true);
}

/**
Wraps a bunch of values into a namespace object.  This works virtually the same as WrapModule,
except that it's meant to be used as a member of something like WrapModule.  Legal member
types include WrapFunc, WrapValue, WrapNamespace, and WrapType.
*/
public struct WrapNamespace(char[] name, members...)
{
    const bool isNamespace = true;
    const char[] Name = name;
    alias members Values;
}

/**
Wraps a single value and gives it a name.  Despite the fact that the value parameter is
variadic, it is restricted to exactly one item.  It's variadic just so it can accept any
value type.
*/
public struct WrapValue(char[] name, value...)
{
    static assert(Value.length == 1 && isExpressionTuple!(Value), "WrapValue - must have exactly one expression");
    const bool isValue = true;
    const char[] Name = name;
    alias value Value;
}

/**
Wraps a class or struct type.  This supports wrapping constructors (or static opCall for structs),
methods, properties (though they will be $(B functions) in MiniD), and arbitrary values.  That means
the valid member types are WrapCtors, WrapMethod, WrapProperty, and WrapValue.

Template Params:
    Type = The class or struct type to be wrapped.
    
    name = The name that will be given to the type in MiniD.
    
    Members = The members of the type.
*/
public struct WrapType(Type, char[] name = NameOfType!(Type), Members...)
{
    // Why did I restrict this, again?
//  static assert(!is(Type == Object), "Wrapping Object is not allowed");

    static assert(is(Type == class) || is(Type == struct), "Cannot wrap type " ~ Type.stringof);

    const bool isType = true;
    const char[] Name = name;
    const char[] typeName = NameOfType!(Type);
    alias GetCtors!(Members) Ctors;
    static assert(Ctors.length <= 1, "Cannot have more than one WrapCtors instance in wrapped type parameters for type " ~ typeName);

    static if(Ctors.length == 1)
    {
        // alias Ctors[0].Types blah; doesn't parse right
        alias Ctors[0] DUMMY;
        alias DUMMY.Types CleanCtors;
    }
    else
        alias Tuple!() CleanCtors;

    private static word init(char[] moduleName)(MDThread* t)
    {
        getWrappedClass(t, typeid(Type));

        if(!isNull(t, -1))
            throwException(t, "Native type " ~ typeName ~ " cannot be wrapped more than once");

        pop(t);

        static if(is(Type == class))
        {
            alias BaseTypeTupleOf!(Type)[0] BaseClass;

            static if(!is(BaseClass == Object))
                auto base = getWrappedClass(t, typeid(BaseClass));
            else
                auto base = pushNull(t);

            newClass(t, base, name);
        }
        else
            pushStructClass!(Type, moduleName, name)(t);

        static if(moduleName.length == 0)
            const TypeName = name;
        else
            const TypeName = moduleName ~ "." ~ name;

        foreach(i, member; Members)
        {
            static if(is(typeof(member.isMethod)))
            {
                auto f = &WrappedMethod!(member.Func, member.FuncType, Type, TypeName, member.explicitType);
                newFunction(t, f, name ~ "." ~ member.Name);
                fielda(t, -2, member.Name);
            }
            else static if(is(typeof(member.isProperty)))
            {
                auto f = &WrappedProperty!(member.Func, member.FuncType, Type, TypeName);
                newFunction(t, f, name ~ "." ~ member.Name);
                fielda(t, -2, member.Name);
            }
            else static if(is(typeof(member.isCtors)))
            {
                // ignore
            }
            else static if(is(typeof(member.isValue)))
            {
                superPush(t, member.Value);
                fielda(t, -2, member.Name);
            }
            else
                static assert(false, "Invalid member type '" ~ member.stringof ~ "' in wrapped type '" ~ typeName ~ "'");
        }

        newFunction(t, &constructor!(TypeName), name ~ ".constructor");
        fielda(t, -2, "constructor");
        
        newFunction(t, &allocator, name ~ ".allocator");
        setAllocator(t, -2);

        setWrappedClass(t, typeid(Type));
        return stackSize(t) - 1;
    }

    private static uword allocator(MDThread* t, uword numParams)
    {
        newInstance(t, 0, 1);

        dup(t);
        pushNull(t);
        rotateAll(t, 3);
        methodCall(t, 2, "constructor", 0);
        return 1;
    }

    static if(CleanCtors.length == 0)
    {
        static if(is(Type == class))
            static assert(is(typeof(new Type())), "Cannot call default constructor for class " ~ typeName ~ "; please wrap a constructor explicitly");
        else
            static assert(is(typeof(Type())), "Cannot call default constructor for struct " ~ typeName ~ "; please wrap a constructor explicitly");

        private static uword constructor(char[] FullName)(MDThread* t, uword numParams)
        {
            checkInstParam(t, 0, FullName);

            static if(is(Type == class))
            {
                auto obj = new Type();
                pushNativeObj(t, obj);
                setExtraVal(t, 0, 0);
                setWrappedInstance(t, obj, 0);
            }
            else
            {
                pushNativeObj(t, new StructWrapper!(Type)(Type()));
                setExtraVal(t, 0, 0);
            }

            return 0;
        }
    }
    else
    {
        private static uword constructor(char[] FullName)(MDThread* t, uword numParams)
        {
            checkInstParam(t, 0, FullName);

            static if(is(Type == class))
            {
                static if(is(typeof(new Type())))
                    const minArgs = 0;
                else
                    const minArgs = ParameterTupleOf!(CleanCtors[0]).length;
            }
            else
            {
                static if(is(typeof(Type())))
                    const minArgs = 0;
                else
                    const minArgs = ParameterTupleOf!(CleanCtors[0]).length;
            }

            const maxArgs = ParameterTupleOf!(CleanCtors[$ - 1]).length;

            if(numParams < minArgs)
                throwException(t, "At least " ~ minArgs.stringof ~ " parameter" ~ (minArgs == 1 ? "" : "s") ~ " expected, not {}", numParams);

            if(numParams > maxArgs)
                numParams = maxArgs;

            static if(minArgs == 0)
            {
                if(numParams == 0)
                {
                    static if(is(Type == class))
                    {
                        auto obj = new Type();
                        pushNativeObj(t, obj);
                        setExtraVal(t, 0, 0);
                        setWrappedInstance(t, obj, 0);
                    }
                    else
                    {
                        pushNativeObj(t, new StructWrapper!(Type)(Type()));
                        setExtraVal(t, 0, 0);
                    }

                    return 0;
                }
            }

            static if(is(Type == class))
                const Switch = CtorCases!(CleanCtors);
            else
                const Switch = StructCtorCases!(CleanCtors);

            mixin(Switch);

            auto buf = StrBuffer(t);

            buf.addChar('(');

            if(numParams > 0)
            {
                pushTypeString(t, 1);
                buf.addTop();

                for(uword i = 2; i <= numParams; i++)
                {
                    buf.addString(", ");
                    pushTypeString(t, i);
                    buf.addTop();
                }
            }

            buf.addChar(')');
            buf.finish();
            throwException(t, "Parameter list {} passed to constructor does not match any wrapped constructors", getString(t, -1));
        }
    }
}

/**
D doesn't really provide any facilities for introspecting class constructors, so you'll have to specify
to the binding library the signatures of the constructors to expose.  You'll also have to do it for structs.
There can be at most one WrapCtors inside a WrapType, but since you specify as many constructors as you
want all at once, it doesn't matter.  The constructor signatures should be function types; the return type
is ignored, and only the parameter types are significant.  

Unlike wrapping other functions, a form of overloading is allowed for constructors.  That is, you can have
a constructor that takes (int) and another that takes (float), wrap them as two separate types, and they
will be correctly dispatched when the type is instantiated in MiniD.  This also means that the usual
implicit conversion from int to float that happens when calling other functions will not happen when calling
constructors.
*/
public struct WrapCtors(T...)
{
    static assert(T.length > 0, "WrapCtors must be instantiated with at least one type");
    const bool isCtors = true;
    alias Unique!(QSort!(SortByNumParams, T)) Types;
}

/**
Wraps a method of a class or struct type.  The argument to this template will look like "A.foo" for a given
type "A".  Other than the fact that it's a method (and therefore takes 'this'), this works pretty much
exactly the same as WrapFunction, including the differences between the multiple specializations.
*/
public struct WrapMethod(alias func)
{
    const bool isMethod = true;
    const char[] Name = NameOfFunc!(func);
    const bool explicitType = false;
    alias func Func;
    alias typeof(&func) FuncType;
}

/// ditto
public struct WrapMethod(alias func, char[] name)
{
    const bool isMethod = true;
    const char[] Name = name;
    const bool explicitType = false;
    alias func Func;
    alias typeof(&func) FuncType;
}

/// ditto
public struct WrapMethod(alias func, funcType)
{
    const bool isMethod = true;
    const char[] Name = NameOfFunc!(func);
    const bool explicitType = true;
    alias func Func;
    alias funcType FuncType;
}

/// ditto
public struct WrapMethod(alias func, char[] name, funcType)
{
    const bool isMethod = true;
    const char[] Name = name;
    const bool explicitType = true;
    alias func Func;
    alias funcType FuncType;
}

/**
Wraps a D "property" as a MiniD $(B function).  Let me state that again: if you wrap a property named "x"
in D, you $(B will not) access it like "a.x" and "a.x = 5" in MiniD.  Instead it will work like "a.x()" 
and "a.x(5)".  (this may change.)  

The D "property" must be one or two functions (either just a getter or a getter/setter pair).  The setter,
if any exists, must be able to take one parameter that is the same type as the getter's return type.  
The setter may optionally return a value.

It doesn't matter whether you pass an alias to the setter or the getter to this; the library will figure
out which one you gave and which one it needs.  So if you have a property "x" of a type "A", it'll just
be WrapProperty!(A.x).

Oh, and, since this is another variety of function wrapping, the parameters here all do the same thing
as for WrapFunction and WrapMethod.
*/
public struct WrapProperty(alias func)
{
    const bool isProperty = true;
    const char[] Name = NameOfFunc!(func);
    const bool explicitType = false;
    alias func Func;
    alias typeof(&func) FuncType;
}

/// ditto
public struct WrapProperty(alias func, char[] name)
{
    const bool isProperty = true;
    const char[] Name = name;
    const bool explicitType = false;
    alias func Func;
    alias typeof(&func) FuncType;
}

/// ditto
public struct WrapProperty(alias func, funcType)
{
    const bool isProperty = true;
    const char[] Name = NameOfFunc!(func);
    const bool explicitType = true;
    alias func Func;
    alias typeof(&func) FuncType;
}

/// ditto
public struct WrapProperty(alias func, char[] name, funcType)
{
    const bool isProperty = true;
    const char[] Name = name;
    const bool explicitType = true;
    alias func Func;
    alias typeof(&func) FuncType;
}

/**
Given a TypeInfo instance of the desired class/struct type (that is, typeid(SomeType)), pushes
the corresponding wrapped MiniD class, or pushes null if the type has not been wrapped.

$(B You probably won't have to call this function under normal circumstances.)

Params:
    ti = The runtime TypeInfo instance of the desired type.
    
Returns:
    The stack index of the newly-pushed value.
*/
public word getWrappedClass(MDThread* t, TypeInfo ti)
{
    pushWrappedClasses(t);
    pushNativeObj(t, ti);

    if(!opin(t, -1, -2))
    {
        pop(t, 2);
        return pushNull(t);
    }

    idx(t, -2);
    insertAndPop(t, -2);
    return stackSize(t) - 1;
}

/**
Expects a class object on top of the stack, and sets it to be the MiniD class that corresponds
to the given runtime TypeInfo object.  The class object is not popped off the stack.

$(B You probably won't have to call this function under normal circumstances.)
*/
public void setWrappedClass(MDThread* t, TypeInfo ti)
{
    pushWrappedClasses(t);
    pushNativeObj(t, ti);
    dup(t, -3);
    idxa(t, -3);
    pop(t);
}

/**
Pushes the wrapped class table onto the stack.  If the wrapped class table for this VM
has not yet been created, creates it.

$(B You probably won't have to call this function under normal circumstances.)

Returns:
    The stack index of the newly-pushed table.
*/
public word pushWrappedClasses(MDThread* t)
{
    auto reg = getRegistry(t);
    pushString(t, "minid.bind.WrappedClasses");

    if(!opin(t, -1, -2))
    {
        newTable(t);
        swap(t);
        dup(t, -2);
        fielda(t, reg);
    }
    else
        field(t, reg);

    insertAndPop(t, -2);
    return stackSize(t) - 1;
}

/**
For a given D object instance, sets the MiniD instance at the given stack index to be
its corresponding object.  

$(B You probably won't have to call this function under normal circumstances.)

Params:
    o = The D object that should be linked to the given MiniD instance.
    idx = The stack index of the MiniD instance that should be linked to the given D object.
*/
public void setWrappedInstance(MDThread* t, Object o, word idx)
{
    pushWrappedInstances(t);
    pushNativeObj(t, o);
    pushWeakRef(t, idx);
    idxa(t, -3);
    pop(t);
}

/**
Assuming a valid wrapped class is on the top of the stack, this function will take a D object
and push the corresponding MiniD instance.  If a MiniD instance has already been created for
this object, pushes that instance; otherwise, this will create an instance and link it to this
D object.

$(B You probably won't have to call this function under normal circumstances.)

Params:
    o = The D object to convert to a MiniD instance.
    
Returns:
    The stack index of the newly-pushed instance.
*/
public word getWrappedInstance(MDThread* t, Object o)
{
    pushWrappedInstances(t);
    pushNativeObj(t, o);
    idx(t, -2);
    deref(t, -1);

    if(isNull(t, -1))
    {
        pop(t, 2);

        newInstance(t, -3, 1);
        pushNativeObj(t, o);
        setExtraVal(t, -1, 0);

        pushNativeObj(t, o);
        pushWeakRef(t, -2);

        idxa(t, -4);