Squirrel

Sqrat 0.6 (Formerly "Scrat")
Documentation Here

Brief Description:

Sqrat is a C++ binding library for Squirrel, similar to SqPlus and SqBind. It models the underlying Squirrel API much more closely than other binding libraries, which gives it access to a wide array of features no other binding library has (like namespaces, constants and enumerations, etc) while still being easy to set-up and use.

Release Notes:

After going through several "get the bugs fixed fast" revisions with the help of Nairou, I've spent a bit more time trying to polish this release up a bit, tighten down some loose ends, and add some worthwhile features. I don't know that I would call this a "stable" release just yet, but it's certainly moved into "solid beta" territory.  If you haven't tried sqrat yet, or did and felt like it wasn't up to snuff, you'll want to give it another look!

Some highlights of this release:

• Support for Constants and Enumerations
• Added Default Virtual Machine support (prevents the need to pass a vm into every class/table/object)
• Better Squirrel Function support (calling squirrel functions from C++)
• Converted the documentation to HTML (much easier to read now)
• Re-organized the directory structure for ease of use and clarity (now you include "sqrat.h" rather than "scrat/scrat.h")
• Much more consistent behavior for variable get/set (supports std::string& correctly, for instance)

For future releases I'm planning on the following:

• Function and Operator overloading (trickier than it sounds)
• Class Attribute support
  
• Better documentation (function-by-function documentation, expanded usage samples, etc.)
• Unit tests and sample code distributed with the source.
• Conversion guide for SqPlus users

As always, I'd love any feedback that you have! Happy coding!

Quick update: I've just pushed out a minor new release (0.6, same link as above) that should make Sqrat compatible with GCC. Any of you out there who use GCC (or any compiler other than Visual Studio for that matter), I would love to hear if it's working for you now!

Thanks for the update! After looking at some of the examples you posted around here, I got Function working.

However, I'm having some trouble binding classes containing arrays. Is this supported? I created a simple test case to demonstrate the problem:

struct test {
    size_t values[3];
};

Sqrat::RootTable().Bind( "test",
    Sqrat::Class<test>()
        .Var( "values", test::values )
);

This results in the following error:

error C2597: illegal reference to non-static member 'test::values'


Also, I'm curious how one would go about binding classes that contain objects from other libraries. For example, I have a "transform" class, for representing 3D position/orientation, which uses a quaternion from the CML library. Is it possible to bind classes from external libraries, to allow Squirrel to read/write some of their internal values as C++ would, without modifying those libraries?

Another warning for you. I get one of these for every std::string& I pass into a squirrel function:

d:\dev\libraries\sqrat\include\sqratmembermethods.h(717) : warning C4239: nonstandard extension used : 'argument' : conversion from 'Sqrat::string' to 'std::basic_string<_Elem,_Traits,_Ax> '
        with
        [
            _Elem=char,
            _Traits=std::char_traits<char>,
            _Ax=std::allocator<char>
        ]
        A non-const reference may only be bound to an lvalue

It does work, so this warning isn't a show-stopper, but with it mentioning use of a "nonstandard extension" it might be important for the gcc folks.

Nairou:

I'm having some trouble binding classes containing arrays. Is this supported?

Unfortunatly no. In fact, I don't know of any binding libraries that DO support it. It's a tricky feature to get working right. I have it on my to-do list and will be looking into it for possible future releases, but I can't promise anything. Sorry!

Also, I'm curious how one would go about binding classes that contain objects from other libraries.

Just like you do any other value. The only real catch is that you have to bind a class before you use it as a member of another class. Doesn't matter if the class is one you created or not. For example, say you wanted to use DirectX's vectors in you code. It would look something like this:

//C++

class Mover {
public:
    D3DXVECTOR3 position;
    D3DXVECTOR3 velocity;
};

void BindMover(HSQUIRRELVM vm) {
    Class<D3DXVECTOR3> d3dVec3(vm);

    d3dVec3
        .Func<D3DXVECTOR3 (D3DXVECTOR3::*)( CONST D3DXVECTOR3& ) const>("_add", &D3DXVECTOR3::operator +)
        .Func<D3DXVECTOR3 (D3DXVECTOR3::*fopsub)( CONST D3DXVECTOR3& ) const>("_sub", &D3DXVECTOR3::operator -)
        .Func<D3DXVECTOR3 (D3DXVECTOR3::*fopunm)( ) const>("_unm", &D3DXVECTOR3::operator -)
        .Func("_mul", &D3DXVECTOR3::operator *)
        .Func("_div", &D3DXVECTOR3::operator /)
        .Func("_cmp", &D3DXVECTOR3::operator ==)
        .Var("x", &D3DXVECTOR3::x)
        .Var("y", &D3DXVECTOR3::y)
        .Var("z", &D3DXVECTOR3::z)
        ;
   
    Class<Mover> mover(vm);
   
    mover
        .Var("position", &Mover::position)
        .Var("velocity", &Mover::velocity)
        ;
       
    RootTable(vm).Bind("Mover", mover);
}

//Squirrel

m <- Mover();
m.velocity.x = 2.4;

would like to see:
-implementation of the class constructor with parameters instead default ctor
-control the number of parameters of functions / methods called from script (also types and default values if possible now)
-final adjust for class Function

thanx

I suggest this version of ctor with muiltiparameters
usage:

class XYZ{
public:
XYZ(){}
XYZ(int c,char a,wstring t){}
};

RootTable(vm).Bind(L"XYZ",
ImprovedClass&lt;XYZ>(vm)
.Ctor&lt;int,char,wstring>()
.Var(L"cc",&XYZ::cc)
);

with this classes (it can be combined with standart)

template&lt;class C>
class ImprovedAllocator :public DefaultAllocator&lt;C> {
static SQInteger setInstance(HSQUIRRELVM vm,C* instance)
{
sq_setinstanceup(vm, 1, instance);
sq_setreleasehook(vm, 1, &Delete);
return 0;
}
public:
template &lt;typename A1>
static SQInteger New1(HSQUIRRELVM vm) {
return setInstance(vm, new C(
Var&lt;A1>(vm, 2).value
));
}
template &lt;typename A1,typename A2>
static SQInteger New2(HSQUIRRELVM vm) {
return setInstance(vm, new C(
Var&lt;A1>(vm, 2).value,
Var&lt;A2>(vm, 3).value
));
}
template &lt;typename A1,typename A2,typename A3>
static SQInteger New2(HSQUIRRELVM vm) {
return setInstance(vm, new C(
Var&lt;A1>(vm, 2).value,
Var&lt;A2>(vm, 3).value,
Var&lt;A3>(vm, 4).value
));
}
//and other
};


template&lt;class C, class A = ImprovedAllocator&lt;C> >
class ImprovedClass :public Class&lt;C,A>{
Class& BindConstructor(SQFUNCTION method){
HSQOBJECT& classObj = ClassType&lt;C>::ClassObject();
sq_pushobject(vm, classObj);
sq_pushstring(vm,_SC("constructor"), -1);
sq_newclosure(vm, method, 0);
sq_newslot(vm, -3, false);
sq_pop(vm, 1);
return *this;
}
public:
// Create a new table
ImprovedClass(HSQUIRRELVM v = DefaultVM::Get(), bool createClass = true) : Class(v,createClass) {}
template&lt;class A1>
Class& Ctor() {
return BindConstructor(A::template New1&lt;A1>);
}
template&lt;class A1,class A2>
Class& Ctor() {
return BindConstructor(A::template New2&lt;A1,A2>);
}
template&lt;class A1,class A2,class A3>
Class& Ctor() {
return BindConstructor(A::template New2&lt;A1,A2,A3>);
}
//and other
};

-implementation of the class constructor with parameters instead default ctor

Definitely on my short list of Todos. This is essentially the same problem as overloaded functions, so you should get them both at the same time. The problem is it doesn't work out quite as nicely as the sample code you showed (Although the interface could certainly be similar). There's a lot of work that goes into determining which variation of the function Squirrel is trying to call (since it's loosely typed), but I'll get there.

-control the number of parameters of functions / methods called from script (also types and default values if possible now)

I'm sorry, but I'm not sure if I understand this one. I think you're asking for function overloads? If so, see above. As for default values, I've been puzzling that one out for a while and can't think of a decent way to do it. There's some technical limitations on what I can pick up in the templates that would make it almost impossible to do. It's too bad, 'cause that would be a nice feature... :(

-final adjust for class Function

Okay, I've got to admit that I have no idea what this means. Sorry!

Thanks for your interest in Sqrat and for your suggestions!

Toji:

This is essentially the same problem as overloaded functions, so you should get them both at the same time.

in script ctor can be overloaded, but can be used only last ctor (same behavior has functions )
and I use code below in my project - it works fine

get this one http://lt.rv.ua/dev/sqratImpClass.h

Toji:

-control the number of parameters of functions / methods called from script (also types and default values if possible now)

when I bind function(class member) to script and than can call it from script with various quantity of parameters. I shoud enable checking of parameters quantity and rise an error when it is not equal

a patch wich allow implementation it http://lt.rv.ua/dev/nparams.patch

Toji:

-final adjust for class Function

Okay, I've got to admit that I have no idea what this means. Sorry!

first template of class Function hasn't this constructor Function(const Object& e, const SQChar* slot)

Thanks a lot!

Toji, I am very pleased with what I see... many thanks for your efforts so far. I would like to know: can native classes can be extended in script? I can't seem to get one to work. Also, can operator overrides and delegate functions such as _set/_get be bound?

juggernaut:

Toji, I am very pleased with what I see... many thanks for your efforts so far.

Thanks, coming from someone who's obviously been working with Squirrel for a while, that means a lot to me. :)

I would like to know: can native classes can be extended in script? I can't seem to get one to work.

I haven't had any problem with it so far. This trivial case works, and I've built a few fairly complex ones too. Is there a specific case that you're having trouble with?

// C++

class Base {
public:
void Jump() {
std::cout << "Base is Jumping!" << std::endl;
}
void Speak() {
std::cout << "Hello World from Base!" << std::endl;
}
};

RootTable(vm).Bind(_SC("Base"),
Class<Base>(vm)
.Func(_SC("Jump"), &Base::Jump)
.Func(_SC("Speak"), &Base::Speak)
);

// Squirrel

class Inherited extends Base {
function Speak() {
::print("Hello World from Inherited!\n");
}
}

b <- Base();
i <- Inherited();

b.Speak(); // Prints "Hllo World from Base!"
i.Speak(); // Prints "Hello World from Inherited!"

b.Jump(); // Prints "Base is Jumping!"
i.Jump(); // Prints "Base is Jumping!"

Also, can operator overrides and delegate functions such as _set/_get be bound?

Yes, although _get and _set are treated specially by Sqrat and overriding them in C++ will probably break your bindings. All other operators sould be fine, though. In an earlier post in this thread I have an example of binding a D3DXVECTOR that shows some operator overloading.

By adding keyword virtual to Base::Jump, the program asserts with an Unhandled exception when executed.

Also, I see no indication that parent constructors are getting fired and I can't seem to explicitly invoke them... If you add the following to Inherited:

constructor() {
Base.constructor();
::print("Inherited instance created\n");
}

... doesn't seem to work. Do I need to bind the Base class constructor and if so, how?

Thanks for pointing out the operator overload example - I don't know how managed to miss that. Can you go into a little more detail on how _get and _set are treated specially by Sqrat?

What compiler are you using? The virtual keyword is optional in this case but I can do it either way without issue. What I can't do (which surprised me) is call the base constructor from an inherited class. I know that was working in a previous version, so I'll have to go digging for the reason that it broke (all the more reason for me to finish implementing my regression tests...)

Oh, and BTW: The correct Squirrel syntax for that would be

::Base.constructor();

As for the _get and _set operators, squirrel will always overload them with a native function that does a table lookup against a set of variable getter/setters constructed by Class.Var(). It's the only way I know of to do native variable binding.

If you overloaded it in Squirrel and made sure to call the base method you should be okay, but overloading in in C++ would prevent any variable lookups bound by Sqrat. I suppose that could have some beneficial effects in the right circumstances, but as a general rule it's something to avoid.

I'll look into the constructor thing first chance I get. Thanks for pointing it out!

I'm using Microsoft Visual Studio 2009 express version 9.0.30729.1... but that doesn't seem to be the issue in the end. It looks like it all comes down to scope... once I put ::Base.constructor() in there, all of my problems went away - even the ability to call the base constructor (?!). I'm coming from a SqPlus build environment with an older version of Squirrel, so perhaps the scoping rules were previously a bit more liberal. But it should be pointed out that the "class Player extends Entity" example on the Squirrel website front page does not use the global scope resolution for the base class constructor call in the example either. Regardless, my immediate problems are solved for the time being. Thanks for your quick responses.

I tried to bind with Sqrat-0.6 .
But I have found several bugs for this.

• After binding Classes/Functions/Variables, the unnecessary objects are left behind to the stack of Squirrel. We must take much attention for stack traits on developping/using Binder libraries.
• Cannot call method appended at Squirrel script as members of the class to binded C++ Classes includes meta-methods[_add/_mul/...]. The hook getter [_get] should return false if the key is unknown.
  

Sqrat has not run correctly in my project yet.

Here is source code I modified.
http://knivez.homelinux.org/~spro/squirrel/sqrat-0.6-kanryu.zip