ChaiScript: Main Page

ChaiScript is a scripting language designed specifically for integration with C++. It provides seamless integration with C++ on all levels, including shared_ptr objects, functors and exceptions.

The parts of the ChaiScript API that the average user will be concerned with are contained in the chaiscript namespace and the chaiscript::ChaiScript class.

The end user parts of the API are extremely simple both in size and ease of use.

Currently, all source control and project management aspects of ChaiScript occur on github.

See also:: chaiscript; chaiscript::ChaiScript; ChaiScript_Language for Built in Functions; ChaiScript Language Getting Started; ChaiScript Language Keyword Reference; ChaiScript Language In-Place Creation Reference; ChaiScript Language Object Model Reference; http://www.chaiscript.com; http://www.github.com/ChaiScript/ChaiScript

API Getting Started

Basics

Basic simple example:

 //main.cpp
 #include <chaiscript/chaiscript.hpp>
 
 double function(int i, double j)
 {
   return i * j;
 }

 int main()
 {
   chaiscript::ChaiScript chai;
   chai.add(&function, "function");

   double d = chai.eval<double>("function(3, 4.75);");
 }

Compiling ChaiScript Applications

ChaiScript is a header only library with only two dependecies. boost::threads (optional) and the operating system provided dynamic library loader, which has to be specified on some platforms.

Compiling with GCC

To compile the above application on a Unix like operating system (MacOS, Linux) with GCC you need to link both boost::threads and the dynamic loader. For example:

 gcc main.cpp -I/path/to/chaiscript/headers -ldl -lboost_threads

Alternatively, you may compile without threading support.

 gcc main.cpp -I/path/to/chaiscript/headers -ldl -DCHAISCRIPT_NO_THREADS

Evaluating Scripts

Scripts can be evaluated with the () operator, eval method or eval_file method.

() Operator

operator() can be used as a handy shortcut for evaluating ChaiScript snippets.

 chaiscript::ChaiScript chai;
 chai("print(\"hello world\")");

See also:: chaiscript::ChaiScript::operator()(const std::string &)

Method 'eval'

The eval method is somewhat more verbose and can be used to get typesafely return values from the script.

 chaiscript::ChaiScript chai;
 chai.eval("callsomefunc()");
 int result = chai.eval<int>("1 + 3");
 // result now equals 4

See also:: chaiscript::ChaiScript::eval

Method 'eval_file'

The 'eval_file' method loads a file from disk and executes the script in it

 chaiscript::ChaiScript chai;
 chai.eval_file("myfile.chai");
 std::string result = chai.eval_file<std::string>("myfile.chai") // extract the last value returned from the file

See also:: chaiscript::ChaiScript::eval_file

Adding Items to ChaiScript

ChaiScript supports 4 basic things that can be added: objects, functions, type infos and Modules

Adding Objects

Named objects can be created with the chaiscript::var function.

 using namespace chaiscript;
 ChaiScript chai;
 int i = 5;
 chai.add(var(i), "i");
 chai("print(i)");

Immutable objects can be created with the chaiscript::const_var function.

 chai.add(const_var(i), "i");
 chai("i = 5"); // exception throw, cannot assign const var

Named variables can only be accessed from the context they are created in. If you want a global variable, it must be const, and created with the chaiscript::ChaiScript::add_global_const function.

 chai.add_global_const(const_var(i), "i");
 chai("def somefun() { print(i); }; sumfun();");

Adding Functions

Functions, methods and members are all added using the same function: chaiscript::fun.

 using namespace chaiscript;
 
 class MyClass {
   public:
     int memberdata;
     void method();
     void method2(int);
     static void staticmethod();
     void overloadedmethod();
     void overloadedmethod(const std::string &);
 };
 
 ChaiScript chai;
 chai.add(fun(&MyClass::memberdata), "memberdata");
 chai.add(fun(&MyClass::method), "method");
 chai.add(fun(&MyClass::staticmethod), "staticmethod");

Overloaded methods will need some help, to hint the compiler as to which overload you want:

 chai.add(fun<void (MyClass::*)()>(&MyClass::overloadedmethod), "overloadedmethod"));
 chai.add(fun<void (MyClass::*)(const std::string &)>(&MyClass::overloadedmethod, "overloadedmethod"));

There are also shortcuts built into chaiscript::fun for binding up to the first two parameters of the function.

 MyClass obj;
 chai.add(fun(&MyClass::method, &obj), "method");
 chai("method()"); // equiv to obj.method()
 chai.add(fun(&MyClass::method2, &obj, 3), "method2");
 chai("method2()"); // equiv to obj.method2(3)

Adding Type Info

ChaiScript will automatically support any type implicitly provided to it in the form of objects and function parameters / return types. However, it can be nice to let ChaiScript know more details about the types you are giving it. For instance, the "clone" functionality cannot work unless there is a copy constructor registered and the name of the type is known (so that ChaiScript can look up the copy constructor).

Continuing with the example "MyClass" from above:

 chai.add(user_type<MyClass>(), "MyClass");

Adding Modules

Modules are holders for collections of ChaiScript registrations.

 ModulePtr module = get_sum_module();
 chai.add(module);

See also:: chaiscript::Module

Operator Overloading

Operators are just like any other function in ChaiScript, to overload an operator, simply register it.

 class MyClass {
   MyClass operator+(const MyClass &) const;
 };

 chai.add(fun(&MyClass::operator+), "+");

 std::string append_string_int(const std::string &t_lhs, int t_rhs)
 {
   return t_lhs + boost::lexical_cast<std::string>(t_rhs);
 }

 chai.add(fun(append_string_int), "+");

See also:: Adding Functions

Class Helper Macro

Much of the work of adding new classes to ChaiScript can be reduced with the help of the CHAISCRIPT_CLASS helper macro.

 class Test
 {
   public:
     void function() {}
     std::string function2() { return "Function2"; }
     void function3() {}
     std::string functionOverload(double) { return "double"; }
     std::string functionOverload(int) { return "int"; }
 };

 int main()
 {

   chaiscript::ModulePtr m = chaiscript::ModulePtr(new chaiscript::Module());

   CHAISCRIPT_CLASS( m, 
       Test,
       (Test ())
       (Test (const Test &)),
       ((function))
       ((function2))
       ((function3))
       ((functionOverload)(std::string (Test::*)(double)))
       ((functionOverload)(std::string (Test::*)(int)))
       ((operator=))
     );
 
   chaiscript::ChaiScript chai;
   chai.add(m);
 }

See also:: Adding Modules

Pointer / Object Conversions

As much as possible, ChaiScript attempts to convert between &, *, const &, const *, boost::shared_ptr<T>, boost::shared_ptr<const T>, boost::reference_wrapper<T>, boost::reference_wrapper<const T> and value types automatically.

If a chaiscript::var object was created in C++ from a pointer, it cannot be convered to a shared_ptr (this would add invalid reference counting). Const may be added, but never removed.

The take away is that you can pretty much expect function calls to Just Work when you need them to.

 void fun1(const int *);
 void fun2(int *);
 void fun3(int);
 void fun4(int &);
 void fun5(const int &);
 void fun5(boost::shared_ptr<int>);
 void fun6(boost::shared_ptr<const int>);
 void fun7(const boost::shared_ptr<int> &);
 void fun8(const boost::shared_ptr<const int> &);
 void fun9(boost::reference_wrapper<int>);
 void fun10(boost::reference_wrapper<const int>);

 int main()
 {
   using namespace chaiscript
   chaiscript::ChaiScript chai;
   chai.add(fun(fun1), "fun1");
   chai.add(fun(fun2), "fun2");
   chai.add(fun(fun3), "fun3");
   chai.add(fun(fun4), "fun4");
   chai.add(fun(fun5), "fun5");
   chai.add(fun(fun6), "fun6");
   chai.add(fun(fun7), "fun7");
   chai.add(fun(fun8), "fun8");
   chai.add(fun(fun9), "fun9");
   chai.add(fun(fun10), "fun10");

   chai("var i = 10;");
   chai("fun1(i)");
   chai("fun2(i)");
   chai("fun3(i)");
   chai("fun4(i)");
   chai("fun5(i)");
   chai("fun6(i)");
   chai("fun7(i)");
   chai("fun8(i)");
   chai("fun9(i)");
   chai("fun10(i)");
 }

See the unit test unittests/boxed_cast_test.cpp for a complete breakdown of the automatic casts that available and tested.

Base Classes

ChaiScript supports handling of passing a derived class object to a function expecting a base class object. For the process to work, the base/derived relationship must be registered with the engine.

 class Base {};
 class Derived : public Base {};
 void myfunction(Base *b);

 int main()
 {
   chaiscript::ChaiScript chai;
   chai.add(chaiscript::base_class<Base, Derived>());
   Derived d;
   chai.add(chaiscript::var(&d), "d");
   chai.add(chaiscript::fun(&myfunction), "myfunction");
   chai("myfunction(d)");
 }

Function Objects

Functions are first class objects in Chaiscript and ChaiScript supports automatic conversion between ChaiScript functions and boost::function objects.

 void callafunc(const boost::function<void (const std::string &)> &t_func)
 {
   t_func("bob");
 }
 
 int main()
 {
   chaiscript::ChaiScript chai;
   chai.add(chaiscript::fun(&callafunc), "callafunc");
   chai("callafunc(fun(x) { print(x); })"); // pass a lambda function to the registered function
                                            // which expects a typed boost::function

   boost::function<void ()> f = chai.eval<boost::function<void ()> >("dump_system");
   f(); // call the ChaiScript function dump_system, from C++
 }

Threading

Thread safety is automatically handled within the ChaiScript system. Objects can be added and scripts executed from multiple threads. For each thread that executes scripts, a new context is created and managed by the engine.

Thread safety can be disabled by defining CHAISCRIPT_NO_THREADS when using the library.

Disabling thread safety increases performance and removes the requirement for boost_threads.

Exception Handling

Exception Handling Basics

Exceptions can be thrown in ChaiScript and caught in C++ or thrown in C++ and caught in ChaiScript.

 void throwexception()
 {
   throw std::runtime_error("err");
 }
 
 int main()
 {
   // Throw in C++, catch in ChaiScript
   chaiscript::ChaiScript chai;
   chai.add(chaiscript::fun(&throwexception), "throwexception");
   chai("try { throwexception(); } catch (e) { print(e.what()); }"); // prints "err"
 
   // Throw in ChaiScript, catch in C++
   try {
     chai("throw(1)");
   } catch (chaiscript::Boxed_Value bv) {
     int i = chaiscript::boxed_cast<int>(bv);
     // i == 1
   }
 }

Exception Handling Automatic Unboxing

As an alternative to the manual unboxing of exceptions shown above, exception specifications allow the user to tell ChaiScript what possible exceptions are expected from the script being executed.

Example:

 chaiscript::ChaiScript chai;

 try {
   chai.eval("throw(runtime_error(\"error\"))", chaiscript::exception_specification<int, double, float, const std::string &, const std::exception &>());
 } catch (const double e) {
 } catch (int) {
 } catch (float) {
 } catch (const std::string &) {
 } catch (const std::exception &e) {
   // This is the one what will be called in the specific throw() above
 }

See also:: chaiscript::Exception_Handler for details on automatic exception unboxing; chaiscript::exception_specification

ChaiScript Documentation