generic-library/ChaiScript
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Start porting of documentatation to markdown style

Browse Source
This commit is contained in:
Jason Turner
2014-04-13 19:16:51 -06:00
parent 825c28521e
commit fcc9bd9bbb
5 changed files with 283 additions and 266 deletions
Download Patch File Download Diff File Expand all files Collapse all files

485
include/chaiscript/chaiscript.hpp
View File

@@ -9,8 +9,8 @@
/// \mainpage /// @mainpage
/// <a href="http://www.chaiscript.com">ChaiScript</a> is a scripting language designed specifically for integration with C++. It provides /// [ChaiScript](http://www.chaiscript.com") 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. /// 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 /// The parts of the ChaiScript API that the average user will be concerned with are contained in the
@@ -18,42 +18,42 @@
/// ///
/// The end user parts of the API are extremely simple both in size and ease of use. /// 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 <a href="http://www.github.com/ChaiScript/ChaiScript">github</a>. /// Currently, all source control and project management aspects of ChaiScript occur on [github](http://www.github.com/ChaiScript/ChaiScript").
/// ///
/// <hr> /// ------------------------------------------------------------
/// ///
/// \sa chaiscript /// @sa chaiscript
/// \sa chaiscript::ChaiScript /// @sa chaiscript::ChaiScript
/// \sa ChaiScript_Language for Built in Functions /// @sa ChaiScript_Language for Built in Functions
/// \sa \ref LangGettingStarted /// @sa @ref LangGettingStarted
/// \sa \ref LangKeywordRef /// @sa @ref LangKeywordRef
/// \sa \ref LangInPlaceRef /// @sa @ref LangInPlaceRef
/// \sa \ref LangObjectSystemRef /// @sa @ref LangObjectSystemRef
/// \sa http://www.chaiscript.com /// @sa http://www.chaiscript.com
/// \sa http://www.github.com/ChaiScript/ChaiScript /// @sa http://www.github.com/ChaiScript/ChaiScript
/// ///
/// <hr> /// -----------------------------------------------------------
/// ///
/// \section gettingstarted API Getting Started /// @section gettingstarted API Getting Started
/// ///
/// \li \ref basics /// - @ref basics
/// \li \ref compiling /// - @ref compiling
/// \li \ref eval /// - @ref eval
/// \li \ref addingitems /// - @ref addingitems
/// \li \ref operatoroverloading /// - @ref operatoroverloading
/// \li \ref helpermacro /// - @ref add_class
/// \li \ref pointerconversions /// - @ref pointerconversions
/// \li \ref baseclasses /// - @ref baseclasses
/// \li \ref functionobjects /// - @ref functionobjects
/// \li \ref threading /// - @ref threading
/// \li \ref exceptions /// - @ref exceptions
/// ///
/// ///
/// \subsection basics Basics /// @subsection basics Basics
/// ///
/// Basic simple example: /// Basic simple example:
/// ///
/// \code /// ~~~~~~~{.cpp}
/// //main.cpp /// //main.cpp
/// #include <chaiscript/chaiscript.hpp> /// #include <chaiscript/chaiscript.hpp>
/// ///
@@ -69,111 +69,115 @@
/// ///
/// double d = chai.eval<double>("function(3, 4.75);"); /// double d = chai.eval<double>("function(3, 4.75);");
/// } /// }
/// \endcode /// ~~~~~~~
/// ///
/// <hr> /// ------------------------------------------------------
/// \subsection compiling Compiling ChaiScript Applications ///
/// @subsection compiling Compiling ChaiScript Applications
/// ///
/// ChaiScript is a header only library with only one dependecy: The /// ChaiScript is a header only library with only one dependecy: The
/// operating system provided dynamic library loader, which has to be specified on some platforms. /// operating system provided dynamic library loader, which has to be specified on some platforms.
/// ///
/// \subsubsection compilinggcc Compiling with GCC /// @subsubsection compilinggcc Compiling with GCC
/// ///
/// To compile the above application on a Unix like operating system (MacOS, Linux) with GCC you need to link /// To compile the above application on a Unix like operating system (MacOS, Linux) with GCC you need to link
/// the dynamic loader. For example: /// the dynamic loader. For example:
/// ///
/// \code /// ~~~~~~~~
/// gcc main.cpp -I/path/to/chaiscript/headers -ldl /// gcc main.cpp -I/path/to/chaiscript/headers -ldl
/// \endcode /// ~~~~~~~~
/// ///
/// Alternatively, you may compile without threading support. /// Alternatively, you may compile without threading support.
/// ///
/// \code /// ~~~~~~~~
/// gcc main.cpp -I/path/to/chaiscript/headers -ldl -DCHAISCRIPT_NO_THREADS /// gcc main.cpp -I/path/to/chaiscript/headers -ldl -DCHAISCRIPT_NO_THREADS
/// \endcode /// ~~~~~~~~
/// ///
/// <hr> /// ------------------------------------------
/// \subsection eval Evaluating Scripts ///
/// @subsection eval Evaluating Scripts
/// ///
/// Scripts can be evaluated with the () operator, eval method or eval_file method. /// Scripts can be evaluated with the () operator, eval method or eval_file method.
/// ///
/// \subsubsection parenoperator () Operator /// @subsubsection parenoperator () Operator
/// ///
/// operator() can be used as a handy shortcut for evaluating ChaiScript snippets. /// operator() can be used as a handy shortcut for evaluating ChaiScript snippets.
/// \code
/// chaiscript::ChaiScript chai;
/// chai("print(\"hello world\")");
/// \endcode
///
/// \sa chaiscript::ChaiScript::operator()(const std::string &)
/// ///
/// \subsubsection evalmethod Method 'eval' /// ~~~~~~~~{.cpp}
/// chaiscript::ChaiScript chai;
/// chai("print(@"hello world@")");
/// ~~~~~~~~
///
/// @sa chaiscript::ChaiScript::operator()(const std::string &)
///
/// @subsubsection evalmethod Method 'eval'
/// ///
/// The eval method is somewhat more verbose and can be used to get typesafely return values /// The eval method is somewhat more verbose and can be used to get typesafely return values
/// from the script. /// from the script.
/// ///
/// \code /// ~~~~~~~~{.cpp}
/// chaiscript::ChaiScript chai; /// chaiscript::ChaiScript chai;
/// chai.eval("callsomefunc()"); /// chai.eval("callsomefunc()");
/// int result = chai.eval<int>("1 + 3"); /// int result = chai.eval<int>("1 + 3");
/// // result now equals 4 /// // result now equals 4
/// \endcode /// ~~~~~~~~
/// ///
/// \sa chaiscript::ChaiScript::eval /// @sa chaiscript::ChaiScript::eval
/// ///
/// \subsubsection evalfilemethod Method 'eval_file' /// @subsubsection evalfilemethod Method 'eval_file'
/// ///
/// The 'eval_file' method loads a file from disk and executes the script in it /// The 'eval_file' method loads a file from disk and executes the script in it
/// ///
/// \code /// ~~~~~~~~{.cpp}
/// chaiscript::ChaiScript chai; /// chaiscript::ChaiScript chai;
/// chai.eval_file("myfile.chai"); /// chai.eval_file("myfile.chai");
/// std::string result = chai.eval_file<std::string>("myfile.chai") // extract the last value returned from the file /// std::string result = chai.eval_file<std::string>("myfile.chai") // extract the last value returned from the file
/// \endcode /// ~~~~~~~~
/// ///
/// \sa chaiscript::ChaiScript::eval_file /// @sa chaiscript::ChaiScript::eval_file
/// ///
/// <hr> /// --------------------------------------------------
/// \subsection addingitems Adding Items to ChaiScript ///
/// @subsection addingitems Adding Items to ChaiScript
/// ///
/// ChaiScript supports 4 basic things that can be added: objects, functions, type infos and Modules /// ChaiScript supports 4 basic things that can be added: objects, functions, type infos and Modules
/// ///
/// \subsubsection addingobjects Adding Objects /// @subsubsection addingobjects Adding Objects
/// ///
/// Named objects can be created with the chaiscript::var function. Note: adding a object /// Named objects can be created with the chaiscript::var function. Note: adding a object
/// adds it to the current thread scope, not to a global scope. If you have multiple /// adds it to the current thread scope, not to a global scope. If you have multiple
/// threads that need to access the same variables you will need to add them /// threads that need to access the same variables you will need to add them
/// separately for each thread, from the thread itself. /// separately for each thread, from the thread itself.
/// ///
/// \code /// ~~~~~~~~~{.cpp}
/// using namespace chaiscript; /// using namespace chaiscript;
/// ChaiScript chai; /// ChaiScript chai;
/// int i = 5; /// int i = 5;
/// chai.add(var(i), "i"); /// chai.add(var(i), "i");
/// chai("print(i)"); /// chai("print(i)");
/// \endcode /// ~~~~~~~~~
/// ///
/// Immutable objects can be created with the chaiscript::const_var function. /// Immutable objects can be created with the chaiscript::const_var function.
/// ///
/// \code /// ~~~~~~~~~{.cpp}
/// chai.add(const_var(i), "i"); /// chai.add(const_var(i), "i");
/// chai("i = 5"); // exception throw, cannot assign const var /// chai("i = 5"); // exception throw, cannot assign const var
/// \endcode /// ~~~~~~~~~
/// ///
/// Named variables can only be accessed from the context they are created in. /// 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 /// If you want a global variable, it must be const, and created with the
/// chaiscript::ChaiScript::add_global_const function. /// chaiscript::ChaiScript::add_global_const function.
/// ///
/// \code /// ~~~~~~~~~{.cpp}
/// chai.add_global_const(const_var(i), "i"); /// chai.add_global_const(const_var(i), "i");
/// chai("def somefun() { print(i); }; sumfun();"); /// chai("def somefun() { print(i); }; sumfun();");
/// \endcode /// ~~~~~~~~~
/// ///
/// \subsubsection addingfunctions Adding Functions /// @subsubsection addingfunctions Adding Functions
/// ///
/// Functions, methods and members are all added using the same function: chaiscript::fun. /// Functions, methods and members are all added using the same function: chaiscript::fun.
/// ///
/// \code /// ~~~~~~~~~{.cpp}
/// using namespace chaiscript; /// using namespace chaiscript;
/// ///
/// class MyClass { /// class MyClass {
@@ -190,26 +194,26 @@
/// chai.add(fun(&MyClass::memberdata), "memberdata"); /// chai.add(fun(&MyClass::memberdata), "memberdata");
/// chai.add(fun(&MyClass::method), "method"); /// chai.add(fun(&MyClass::method), "method");
/// chai.add(fun(&MyClass::staticmethod), "staticmethod"); /// chai.add(fun(&MyClass::staticmethod), "staticmethod");
/// \endcode /// ~~~~~~~~~
/// ///
/// Overloaded methods will need some help, to hint the compiler as to which overload you want: /// Overloaded methods will need some help, to hint the compiler as to which overload you want:
/// ///
/// \code /// ~~~~~~~~~{.cpp}
/// chai.add(fun<void (MyClass::*)()>(&MyClass::overloadedmethod), "overloadedmethod"); /// chai.add(fun<void (MyClass::*)()>(&MyClass::overloadedmethod), "overloadedmethod");
/// chai.add(fun<void (MyClass::*)(const std::string &)>(&MyClass::overloadedmethod), "overloadedmethod"); /// chai.add(fun<void (MyClass::*)(const std::string &)>(&MyClass::overloadedmethod), "overloadedmethod");
/// \endcode /// ~~~~~~~~~
/// ///
/// There are also shortcuts built into chaiscript::fun for binding up to the first two parameters of the function. /// There are also shortcuts built into chaiscript::fun for binding up to the first two parameters of the function.
/// ///
/// \code /// ~~~~~~~~~{.cpp}
/// MyClass obj; /// MyClass obj;
/// chai.add(fun(&MyClass::method, &obj), "method"); /// chai.add(fun(&MyClass::method, &obj), "method");
/// chai("method()"); // equiv to obj.method() /// chai("method()"); // equiv to obj.method()
/// chai.add(fun(&MyClass::method2, &obj, 3), "method2"); /// chai.add(fun(&MyClass::method2, &obj, 3), "method2");
/// chai("method2()"); // equiv to obj.method2(3) /// chai("method2()"); // equiv to obj.method2(3)
/// \endcode /// ~~~~~~~~~
/// ///
/// \subsubsection addingtypeinfo Adding Type Info /// @subsubsection addingtypeinfo Adding Type Info
/// ///
/// ChaiScript will automatically support any type implicitly provided to it in the form /// 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 /// of objects and function parameters / return types. However, it can be nice to let ChaiScript
@@ -219,27 +223,28 @@
/// ///
/// Continuing with the example "MyClass" from above: /// Continuing with the example "MyClass" from above:
/// ///
/// \code /// ~~~~~~~~{.cpp}
/// chai.add(user_type<MyClass>(), "MyClass"); /// chai.add(user_type<MyClass>(), "MyClass");
/// \endcode /// ~~~~~~~~
/// ///
/// \subsubsection addingmodules Adding Modules /// @subsubsection addingmodules Adding Modules
/// ///
/// Modules are holders for collections of ChaiScript registrations. /// Modules are holders for collections of ChaiScript registrations.
/// ///
/// \code /// ~~~~~~~~{.cpp}
/// ModulePtr module = get_sum_module(); /// ModulePtr module = get_sum_module();
/// chai.add(module); /// chai.add(module);
/// \endcode /// ~~~~~~~~
/// ///
/// \sa chaiscript::Module /// @sa chaiscript::Module
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \subsection operatoroverloading Operator Overloading ///
/// @subsection operatoroverloading Operator Overloading
/// ///
/// Operators are just like any other function in ChaiScript, to overload an operator, simply register it. /// Operators are just like any other function in ChaiScript, to overload an operator, simply register it.
/// ///
/// \code /// ~~~~~~~~{.cpp}
/// class MyClass { /// class MyClass {
/// MyClass operator+(const MyClass &) const; /// MyClass operator+(const MyClass &) const;
/// }; /// };
@@ -254,17 +259,18 @@
/// } /// }
/// ///
/// chai.add(fun(append_string_int), "+"); /// chai.add(fun(append_string_int), "+");
/// \endcode /// ~~~~~~~~
/// ///
/// \sa \ref addingfunctions /// @sa @ref addingfunctions
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \subsection helpermacro Class Helper Macro ///
/// @subsection add_class Class Helper Utility
/// ///
/// Much of the work of adding new classes to ChaiScript can be reduced with the help /// Much of the work of adding new classes to ChaiScript can be reduced with the help
/// of the CHAISCRIPT_CLASS helper macro. /// of the add_class helper utility.
/// ///
/// \code /// ~~~~~~~~{.cpp}
/// class Test /// class Test
/// { /// {
/// public: /// public:
@@ -277,30 +283,30 @@
/// ///
/// int main() /// int main()
/// { /// {
///
/// chaiscript::ModulePtr m = chaiscript::ModulePtr(new chaiscript::Module()); /// chaiscript::ModulePtr m = chaiscript::ModulePtr(new chaiscript::Module());
/// ///
/// CHAISCRIPT_CLASS( m, /// chaiscript::utility::add_class<chaiscript::Test>(*m,
/// Test, /// "Test",
/// (Test ()) /// { constructor<Test()>(),
/// (Test (const Test &)), /// constructor<Test(const Test &)>() },
/// ((function)) /// { {fun(&Test::function), "function"},
/// ((function2)) /// {fun(&Test::function2), "function2"},
/// ((function3)) /// {fun(&Test::function2), "function3"}
/// ((functionOverload)(std::string (Test::*)(double))) /// {fun(static_cast<std::string Test::*(double)>(&Test::functionOverload)), "functionOverload"}
/// ((functionOverload)(std::string (Test::*)(int))) /// {fun(static_cast<std::string Test::*(int)>(&Test::functionOverload)), "functionOverload"} }
/// ((operator=)) /// );
/// ); ///
/// ///
/// chaiscript::ChaiScript chai; /// chaiscript::ChaiScript chai;
/// chai.add(m); /// chai.add(m);
/// } /// }
/// \endcode /// ~~~~~~~~
/// ///
/// \sa \ref addingmodules /// @sa @ref addingmodules
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \subsection pointerconversions Pointer / Object Conversions ///
/// @subsection pointerconversions Pointer / Object Conversions
/// ///
/// As much as possible, ChaiScript attempts to convert between &, *, const &, const *, std::shared_ptr<T>, /// As much as possible, ChaiScript attempts to convert between &, *, const &, const *, std::shared_ptr<T>,
/// std::shared_ptr<const T>, std::reference_wrapper<T>, std::reference_wrapper<const T> and value types automatically. /// std::shared_ptr<const T>, std::reference_wrapper<T>, std::reference_wrapper<const T> and value types automatically.
@@ -310,7 +316,7 @@
/// ///
/// The take away is that you can pretty much expect function calls to Just Work when you need them to. /// The take away is that you can pretty much expect function calls to Just Work when you need them to.
/// ///
/// \code /// ~~~~~~~~{.cpp}
/// void fun1(const int *); /// void fun1(const int *);
/// void fun2(int *); /// void fun2(int *);
/// void fun3(int); /// void fun3(int);
@@ -350,18 +356,19 @@
/// chai("fun9(i)"); /// chai("fun9(i)");
/// chai("fun10(i)"); /// chai("fun10(i)");
/// } /// }
/// \endcode /// ~~~~~~~~
/// ///
/// See the unit test unittests/boxed_cast_test.cpp for a complete breakdown of the automatic casts that /// See the unit test unittests/boxed_cast_test.cpp for a complete breakdown of the automatic casts that
/// available and tested. /// available and tested.
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \subsection baseclasses Base Classes ///
/// @subsection baseclasses Base Classes
/// ///
/// ChaiScript supports handling of passing a derived class object to a function expecting a base class object. /// 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. /// For the process to work, the base/derived relationship must be registered with the engine.
/// ///
/// \code /// ~~~~~~~~{.cpp}
/// class Base {}; /// class Base {};
/// class Derived : public Base {}; /// class Derived : public Base {};
/// void myfunction(Base *b); /// void myfunction(Base *b);
@@ -375,16 +382,17 @@
/// chai.add(chaiscript::fun(&myfunction), "myfunction"); /// chai.add(chaiscript::fun(&myfunction), "myfunction");
/// chai("myfunction(d)"); /// chai("myfunction(d)");
/// } /// }
/// \endcode /// ~~~~~~~~
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// ///
/// \subsection functionobjects Function Objects ///
/// @subsection functionobjects Function Objects
/// ///
/// Functions are first class objects in Chaiscript and ChaiScript supports automatic conversion /// Functions are first class objects in Chaiscript and ChaiScript supports automatic conversion
/// between ChaiScript functions and std::function objects. /// between ChaiScript functions and std::function objects.
/// ///
/// \code /// ~~~~~~~~{.cpp}
/// void callafunc(const std::function<void (const std::string &)> &t_func) /// void callafunc(const std::function<void (const std::string &)> &t_func)
/// { /// {
/// t_func("bob"); /// t_func("bob");
@@ -400,11 +408,12 @@
/// std::function<void ()> f = chai.eval<std::function<void ()> >("dump_system"); /// std::function<void ()> f = chai.eval<std::function<void ()> >("dump_system");
/// f(); // call the ChaiScript function dump_system, from C++ /// f(); // call the ChaiScript function dump_system, from C++
/// } /// }
/// \endcode /// ~~~~~~~~
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// ///
/// \subsection threading Threading ///
/// @subsection threading Threading
/// ///
/// Thread safety is automatically handled within the ChaiScript system. Objects can be added /// 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 /// and scripts executed from multiple threads. For each thread that executes scripts, a new
@@ -414,16 +423,17 @@
/// ///
/// Disabling thread safety increases performance in many cases. /// Disabling thread safety increases performance in many cases.
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// ///
/// \subsection exceptions Exception Handling ///
/// @subsection exceptions Exception Handling
/// ///
/// \subsubsection exceptionsbasics Exception Handling Basics /// @subsubsection exceptionsbasics Exception Handling Basics
/// ///
/// Exceptions can be thrown in ChaiScript and caught in C++ or thrown in C++ and caught in /// Exceptions can be thrown in ChaiScript and caught in C++ or thrown in C++ and caught in
/// ChaiScript. /// ChaiScript.
/// ///
/// \code /// ~~~~~~~~{.cpp}
/// void throwexception() /// void throwexception()
/// { /// {
/// throw std::runtime_error("err"); /// throw std::runtime_error("err");
@@ -444,19 +454,19 @@
/// // i == 1 /// // i == 1
/// } /// }
/// } /// }
/// \endcode /// ~~~~~~~~
/// ///
/// \subsubsection exceptionsautomatic Exception Handling Automatic Unboxing /// @subsubsection exceptionsautomatic Exception Handling Automatic Unboxing
/// ///
/// As an alternative to the manual unboxing of exceptions shown above, exception specifications allow the user to tell /// 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. /// ChaiScript what possible exceptions are expected from the script being executed.
/// ///
/// Example: /// Example:
/// \code /// ~~~~~~~~{.cpp}
/// chaiscript::ChaiScript chai; /// chaiscript::ChaiScript chai;
/// ///
/// try { /// try {
/// chai.eval("throw(runtime_error(\"error\"))", chaiscript::exception_specification<int, double, float, const std::string &, const std::exception &>()); /// chai.eval("throw(runtime_error(@"error@"))", chaiscript::exception_specification<int, double, float, const std::string &, const std::exception &>());
/// } catch (const double e) { /// } catch (const double e) {
/// } catch (int) { /// } catch (int) {
/// } catch (float) { /// } catch (float) {
@@ -464,19 +474,19 @@
/// } catch (const std::exception &e) { /// } catch (const std::exception &e) {
/// // This is the one what will be called in the specific throw() above /// // This is the one what will be called in the specific throw() above
/// } /// }
/// \endcode /// ~~~~~~~~
/// ///
/// \sa chaiscript::Exception_Handler for details on automatic exception unboxing /// @sa chaiscript::Exception_Handler for details on automatic exception unboxing
/// \sa chaiscript::exception_specification /// @sa chaiscript::exception_specification
/// \page LangObjectSystemRef ChaiScript Language Object Model Reference /// @page LangObjectSystemRef ChaiScript Language Object Model Reference
/// ///
/// ///
/// ChaiScript has an object system built in, for types defined within the ChaiScript system. /// ChaiScript has an object system built in, for types defined within the ChaiScript system.
/// ///
/// \code /// ~~~~~~~~~
/// attr Rectangle::height /// attr Rectangle::height
/// attr Rectangle::width /// attr Rectangle::width
/// def Rectangle::Rectangle() { this.height = 10; this.width = 20 } /// def Rectangle::Rectangle() { this.height = 10; this.width = 20 }
@@ -485,67 +495,69 @@
/// var rect = Rectangle() /// var rect = Rectangle()
/// rect.height = 30 /// rect.height = 30
/// print(rect.area()) /// print(rect.area())
/// \endcode /// ~~~~~~~~~
/// ///
/// \sa \ref keywordattr /// @sa @ref keywordattr
/// \sa \ref keyworddef /// @sa @ref keyworddef
/// \page LangInPlaceRef ChaiScript Language In-Place Creation Reference /// @page LangInPlaceRef ChaiScript Language In-Place Creation Reference
/// \section inplacevector Vector /// @section inplacevector Vector
/// ///
/// \code /// ~~~~~~~~~
/// In-place Vector ::= "[" [expression ("," expression)*] "]" /// In-place Vector ::= "[" [expression ("," expression)*] "]"
/// \endcode /// ~~~~~~~~~
/// ///
/// \section inplacerangedvector Ranged Vector /// @section inplacerangedvector Ranged Vector
/// ///
/// \code /// ~~~~~~~~~
/// In-place Ranged Vector ::= "[" value ".." value "]" /// In-place Ranged Vector ::= "[" value ".." value "]"
/// \endcode /// ~~~~~~~~~
/// ///
/// Creates a vector over a range (eg. 1..10) /// Creates a vector over a range (eg. 1..10)
/// ///
/// \section inplacemap Map /// @section inplacemap Map
/// ///
/// \code /// ~~~~~~~~
/// In-place Map ::= "[" (string ":" expression)+ "]" /// In-place Map ::= "[" (string ":" expression)+ "]"
/// \endcode /// ~~~~~~~~
/// \page LangGettingStarted ChaiScript Language Getting Started /// @page LangGettingStarted ChaiScript Language Getting Started
/// ///
/// ChaiScript is a simple language that should feel familiar to anyone who knows /// ChaiScript is a simple language that should feel familiar to anyone who knows
/// C++ or ECMAScript (JavaScript). /// C++ or ECMAScript (JavaScript).
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \section chaiscriptloops Loops ///
/// @section chaiscriptloops Loops
/// ///
/// Common looping constructs exist in ChaiScript /// Common looping constructs exist in ChaiScript
/// ///
/// \code /// ~~~~~~~~
/// var i = 0; /// var i = 0;
/// while (i < 10) /// while (i < 10)
/// { /// {
/// // do something /// // do something
/// ++i; /// ++i;
/// } /// }
/// \endcode /// ~~~~~~~~
/// ///
/// \code /// ~~~~~~~~
/// for (var i = 0; i < 10; ++i) /// for (var i = 0; i < 10; ++i)
/// { /// {
/// // do something /// // do something
/// } /// }
/// \endcode /// ~~~~~~~~
/// ///
/// \sa \ref keywordfor /// @sa @ref keywordfor
/// \sa \ref keywordwhile /// @sa @ref keywordwhile
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \section chaiscriptifs Conditionals ///
/// @section chaiscriptifs Conditionals
/// ///
/// If statements work as expected /// If statements work as expected
/// ///
/// \code /// ~~~~~~~~
/// var b = true; /// var b = true;
/// ///
/// if (b) { /// if (b) {
@@ -555,103 +567,109 @@
/// } else { /// } else {
/// // or do this /// // or do this
/// } /// }
/// \endcode /// ~~~~~~~~
/// ///
/// \sa \ref keywordif /// @sa @ref keywordif
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \section chaiscriptfunctions Functions ///
/// @section chaiscriptfunctions Functions
/// ///
/// Functions are defined with the def keyword /// Functions are defined with the def keyword
/// ///
/// \code /// ~~~~~~~~
/// def myfun(x) { print(x); } /// def myfun(x) { print(x); }
/// ///
/// myfun(10); /// myfun(10);
/// \endcode /// ~~~~~~~~
/// ///
/// Functions may have "guards" which determine if which is called. /// Functions may have "guards" which determine if which is called.
/// ///
/// \code /// ~~~~~~~~
/// eval> def myfun2(x) : x < 10 { print("less than 10"); } /// eval> def myfun2(x) : x < 10 { print("less than 10"); }
/// eval> def myfun2(x) : x >= 10 { print("10 or greater"); } /// eval> def myfun2(x) : x >= 10 { print("10 or greater"); }
/// eval> myfun2(5) /// eval> myfun2(5)
/// less than 10 /// less than 10
/// eval> myfun2(12) /// eval> myfun2(12)
/// 10 or greater /// 10 or greater
/// \endcode /// ~~~~~~~~
/// ///
/// \sa \ref keyworddef /// @sa @ref keyworddef
/// \sa \ref keywordattr /// @sa @ref keywordattr
/// \sa \ref LangObjectSystemRef /// @sa @ref LangObjectSystemRef
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \section chaiscriptfunctionobjects Function Objects ///
/// @section chaiscriptfunctionobjects Function Objects
/// ///
/// Functions are first class types in ChaiScript and can be used as variables. /// Functions are first class types in ChaiScript and can be used as variables.
/// ///
/// \code /// ~~~~~~~~
/// eval> var p = print; /// eval> var p = print;
/// eval> p(1); /// eval> p(1);
/// 1 /// 1
/// \endcode /// ~~~~~~~~
/// ///
/// They can also be passed to functions. /// They can also be passed to functions.
/// ///
/// \code /// ~~~~~~~~
/// eval> def callfunc(f, lhs, rhs) { return f(lhs, rhs); } /// eval> def callfunc(f, lhs, rhs) { return f(lhs, rhs); }
/// eval> def dosomething(lhs, rhs) { print("lhs: ${lhs}, rhs: ${rhs}"); } /// eval> def dosomething(lhs, rhs) { print("lhs: ${lhs}, rhs: ${rhs}"); }
/// eval> callfunc(dosomething, 1, 2); /// eval> callfunc(dosomething, 1, 2);
/// lhs: 1, rhs: 2 /// lhs: 1, rhs: 2
/// \endcode /// ~~~~~~~~
/// ///
/// Operators can also be treated as functions by using the back tick operator. Building on the above example: /// Operators can also be treated as functions by using the back tick operator. Building on the above example:
/// ///
/// \code /// ~~~~~~~~
/// eval> callfunc(`+`, 1, 4); /// eval> callfunc(`+`, 1, 4);
/// 5 /// 5
/// eval> callfunc(`*`, 3, 2); /// eval> callfunc(`*`, 3, 2);
/// 6 /// 6
/// \endcode /// ~~~~~~~~
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \sa \ref LangKeywordRef ///
/// \sa ChaiScript_Language for Built in Functions /// @sa @ref LangKeywordRef
/// @sa ChaiScript_Language for Built in Functions
/// \page LangKeywordRef ChaiScript Language Keyword Reference /// @page LangKeywordRef ChaiScript Language Keyword Reference
/// ///
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \section keywordattr attr ///
/// @section keywordattr attr
/// Defines a ChaiScript object attribute /// Defines a ChaiScript object attribute
/// ///
/// \code /// ~~~~~~~~
/// Attribute Definition ::= "attr" class_name "::" attribute_name /// Attribute Definition ::= "attr" class_name "::" attribute_name
/// \endcode /// ~~~~~~~~
/// ///
/// \sa \ref LangObjectSystemRef /// @sa @ref LangObjectSystemRef
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \section keywordbreak break ///
/// @section keywordbreak break
/// Stops execution of a looping block. /// Stops execution of a looping block.
/// ///
/// \code /// ~~~~~~~~
/// Break Statement ::= "break" /// Break Statement ::= "break"
/// \endcode /// ~~~~~~~~
/// ///
/// \sa \ref keywordfor /// @sa @ref keywordfor
/// \sa \ref keywordwhile /// @sa @ref keywordwhile
/// ///
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \section keyworddef def ///
/// @section keyworddef def
/// Begins a function or method definition /// Begins a function or method definition
/// ///
/// \code /// ~~~~~~~~
/// Function Definition ::= [annotation + CR/LF] "def" identifier "(" [arg ("," arg)*] ")" [":" guard] block /// Function Definition ::= [annotation + CR/LF] "def" identifier "(" [arg ("," arg)*] ")" [":" guard] block
/// Method Definition ::= [annotation + CR/LF] "def" class_name "::" method_name "(" [arg ("," arg)*] ")" [":" guard] block /// Method Definition ::= [annotation + CR/LF] "def" class_name "::" method_name "(" [arg ("," arg)*] ")" [":" guard] block
/// \endcode /// ~~~~~~~~
/// ///
/// annotation: meta-annotation on function, currently used as documentation. Optional. /// annotation: meta-annotation on function, currently used as documentation. Optional.
/// identifier: name of function. Required. /// identifier: name of function. Required.
@@ -667,50 +685,56 @@
/// Method definitions for known types extend those types with new methods. This includes C++ and ChaiScript defined types. /// Method definitions for known types extend those types with new methods. This includes C++ and ChaiScript defined types.
/// Method definitions for unknown types implicitly define the named type. /// Method definitions for unknown types implicitly define the named type.
/// ///
/// \sa \ref LangObjectSystemRef /// @sa @ref LangObjectSystemRef
/// ///
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \section keywordelse else ///
/// \sa \ref keywordif /// @section keywordelse else
/// @sa @ref keywordif
/// ///
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \section keywordfor for ///
/// \code /// @section keywordfor for
/// ~~~~~~~~
/// For Block ::= "for" "(" [initial] ";" stop_condition ";" loop_expression ")" block /// For Block ::= "for" "(" [initial] ";" stop_condition ";" loop_expression ")" block
/// \endcode /// ~~~~~~~~
/// This loop can be broken using the \ref keywordbreak command. /// This loop can be broken using the @ref keywordbreak command.
/// ///
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \section keywordfun fun ///
/// @section keywordfun fun
/// Begins an anonymous function declaration (sometimes called a lambda). /// Begins an anonymous function declaration (sometimes called a lambda).
/// ///
/// \code /// ~~~~~~~~
/// Lambda ::= "fun" "(" [variable] ("," variable)* ")" block /// Lambda ::= "fun" "(" [variable] ("," variable)* ")" block
/// \endcode /// ~~~~~~~~
/// ///
/// \b Examples: /// _Example_
/// ///
/// \code /// ~~~~~~~~
/// // Generate an anonymous function object that adds 2 to its parameter /// // Generate an anonymous function object that adds 2 to its parameter
/// var f = fun(x) { x + 2; } /// var f = fun(x) { x + 2; }
/// \endcode /// ~~~~~~~~
/// ///
/// \sa \ref keyworddef for more details on ChaiScript functions /// @sa @ref keyworddef for more details on ChaiScript functions
/// ///
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \section keywordif if ///
/// @section keywordif if
/// Begins a conditional block of code that only executes if the condition evaluates as true. /// Begins a conditional block of code that only executes if the condition evaluates as true.
/// \code /// ~~~~~~~~
/// If Block ::= "if" "(" condition ")" block /// If Block ::= "if" "(" condition ")" block
/// Else If Block ::= "else if" "(" condition ")" block /// Else If Block ::= "else if" "(" condition ")" block
/// Else Block ::= "else" block /// Else Block ::= "else" block
/// \endcode /// ~~~~~~~~
/// \b Example: ///
/// \code /// _Example_
///
/// ~~~~~~~~
/// if (true) { /// if (true) {
/// // do something /// // do something
/// } else if (false) { /// } else if (false) {
@@ -718,35 +742,38 @@
/// } else { /// } else {
/// // otherwise do this /// // otherwise do this
/// } /// }
/// \endcode /// ~~~~~~~~
/// ///
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \section keywordtry try ///
/// \code /// @section keywordtry try
/// ~~~~~~~~
/// Try Block ::= "try" block /// Try Block ::= "try" block
/// ("catch" ["(" variable ")"] [":" guards] block)+ /// ("catch" ["(" variable ")"] [":" guards] block)+
/// ["finally" block] /// ["finally" block]
/// \endcode /// ~~~~~~~~
/// ///
/// \sa ChaiScript_Language::throw /// @sa ChaiScript_Language::throw
/// ///
/// <hr> /// -----------------------------------------------------------------------
/// \section keywordwhile while ///
/// @section keywordwhile while
/// ///
/// Begins a conditional block of code that loops 0 or more times, as long as the condition is true /// Begins a conditional block of code that loops 0 or more times, as long as the condition is true
/// ///
/// \code /// ~~~~~~~~
/// While Block ::= "while" "(" condition ")" block /// While Block ::= "while" "(" condition ")" block
/// \endcode /// ~~~~~~~~
/// This loop can be broken using the \ref keywordbreak command. ///
/// This loop can be broken using the @ref keywordbreak command.
/// \namespace chaiscript /// @namespace chaiscript
/// \brief Namespace chaiscript contains every API call that the average user will be concerned with. /// @brief Namespace chaiscript contains every API call that the average user will be concerned with.
/// \namespace chaiscript::detail /// @namespace chaiscript::detail
/// \brief Classes and functions reserved for internal use. Items in this namespace are not supported. /// @brief Classes and functions reserved for internal use. Items in this namespace are not supported.
#include "chaiscript_defines.hpp" #include "chaiscript_defines.hpp"

7
include/chaiscript/chaiscript_defines.hpp
View File

@@ -1,7 +1,7 @@
// This file is distributed under the BSD License. // This file is distributed under the BSD License.
// See "license.txt" for details. // See "license.txt" for details.
// Copyright 2009-2012, Jonathan Turner (jonathan@emptycrate.com) // Copyright 2009-2012, Jonathan Turner (jonathan@emptycrate.com)
// and Jason Turner (jason@emptycrate.com) // Copyright 2009-2014, Jason Turner (jason@emptycrate.com)
// http://www.chaiscript.com // http://www.chaiscript.com
#ifndef CHAISCRIPT_DEFINES_HPP_ #ifndef CHAISCRIPT_DEFINES_HPP_
@@ -16,6 +16,11 @@
#define CHAISCRIPT_WINDOWS #define CHAISCRIPT_WINDOWS
#endif #endif
#if defined(__GNUC__) && __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 8)
/// Currently only g++>=4.8supports this natively
/// \todo Make this support other compilers when possible
#define CHAISCRIPT_HAS_THREAD_LOCAL
#endif
#ifdef CHAISCRIPT_HAS_DECLSPEC #ifdef CHAISCRIPT_HAS_DECLSPEC
#define CHAISCRIPT_MODULE_EXPORT extern "C" __declspec(dllexport) #define CHAISCRIPT_MODULE_EXPORT extern "C" __declspec(dllexport)

2
include/chaiscript/chaiscript_stdlib.hpp
View File

@@ -11,7 +11,7 @@
#include "dispatchkit/bootstrap.hpp" #include "dispatchkit/bootstrap.hpp"
#include "dispatchkit/bootstrap_stl.hpp" #include "dispatchkit/bootstrap_stl.hpp"
/// \file /// @file
/// ///
/// This file generates the standard library that normal ChaiScript usage requires. /// This file generates the standard library that normal ChaiScript usage requires.

2
include/chaiscript/chaiscript_threading.hpp
View File

@@ -67,8 +67,6 @@ namespace chaiscript
#ifdef CHAISCRIPT_HAS_THREAD_LOCAL #ifdef CHAISCRIPT_HAS_THREAD_LOCAL
/// Typesafe thread specific storage. If threading is enabled, this class uses a mutex protected map. If /// Typesafe thread specific storage. If threading is enabled, this class uses a mutex protected map. If
/// threading is not enabled, the class always returns the same data, regardless of which thread it is called from. /// threading is not enabled, the class always returns the same data, regardless of which thread it is called from.
///
/// \todo move to thread_local when it exists
template<typename T> template<typename T>
class Thread_Storage class Thread_Storage
{ {

53
include/chaiscript/dispatchkit/boxed_value.hpp
View File

@@ -22,17 +22,14 @@ namespace chaiscript
class Boxed_Value class Boxed_Value
{ {
public: public:
/** /// used for explicitly creating a "void" object
* used for explicitly creating a "void" object
*/
struct Void_Type struct Void_Type
{ {
}; };
private: private:
/** /// structure which holds the internal state of a Boxed_Value
* structure which holds the internal state of a Boxed_Value /// \todo Get rid of Any and merge it with this, reducing an allocation in the process
*/
struct Data struct Data
{ {
Data(const Type_Info &ti, Data(const Type_Info &ti,
@@ -137,28 +134,22 @@ namespace chaiscript
}; };
public: public:
/** /// Basic Boxed_Value constructor
* Basic Boxed_Value constructor
*/
template<typename T> template<typename T>
explicit Boxed_Value(T t) explicit Boxed_Value(T t)
: m_data(Object_Data::get(t)) : m_data(Object_Data::get(t))
{ {
} }
/** /// Copy constructor - each copy shares the same data pointer
* Copy constructor - each copy shares the same data pointer
*/
Boxed_Value(const Boxed_Value &t_so) Boxed_Value(const Boxed_Value &t_so)
: m_data(t_so.m_data) : m_data(t_so.m_data)
{ {
} }
/** /// Unknown-type constructor
* Unknown-type constructor
*/
Boxed_Value() Boxed_Value()
: m_data(Object_Data::get()) : m_data(Object_Data::get())
{ {
} }
@@ -171,19 +162,15 @@ namespace chaiscript
std::swap(m_data, rhs.m_data); std::swap(m_data, rhs.m_data);
} }
/** /// Copy the values stored in rhs.m_data to m_data.
* copy the values stored in rhs.m_data to m_data /// m_data pointers are not shared in this case
* m_data pointers are not shared in this case
*/
Boxed_Value assign(const Boxed_Value &rhs) Boxed_Value assign(const Boxed_Value &rhs)
{ {
(*m_data) = (*rhs.m_data); (*m_data) = (*rhs.m_data);
return *this; return *this;
} }
/** /// shared data assignment, same as copy construction
* shared data assignment, same as copy construction
*/
Boxed_Value &operator=(const Boxed_Value &rhs) Boxed_Value &operator=(const Boxed_Value &rhs)
{ {
Boxed_Value temp(rhs); Boxed_Value temp(rhs);
@@ -196,9 +183,7 @@ namespace chaiscript
return m_data->m_type_info; return m_data->m_type_info;
} }
/** /// return true if the object is uninitialized
* return true if the object is uninitialized
*/
bool is_undef() const bool is_undef() const
{ {
return m_data->m_type_info.is_undef(); return m_data->m_type_info.is_undef();
@@ -254,19 +239,20 @@ namespace chaiscript
std::shared_ptr<Data> m_data; std::shared_ptr<Data> m_data;
}; };
/// \brief Creates a Boxed_Value. If the object passed in is a value type, it is copied. If it is a pointer, std::shared_ptr, or std::reference_type /// @brief Creates a Boxed_Value. If the object passed in is a value type, it is copied. If it is a pointer, std::shared_ptr, or std::reference_type
/// a copy is not made. /// a copy is not made.
/// \param t The value to box /// @param t The value to box
/// ///
/// Example: /// Example:
/// \code ///
/// ~~~{.cpp}
/// int i; /// int i;
/// chaiscript::ChaiScript chai; /// chaiscript::ChaiScript chai;
/// chai.add(chaiscript::var(i), "i"); /// chai.add(chaiscript::var(i), "i");
/// chai.add(chaiscript::var(&i), "ip"); /// chai.add(chaiscript::var(&i), "ip");
/// \endcode /// ~~~
/// ///
/// \sa \ref addingobjects /// @sa @ref addingobjects
template<typename T> template<typename T>
Boxed_Value var(T t) Boxed_Value var(T t)
{ {
@@ -339,6 +325,7 @@ namespace chaiscript
/// chai.add(chaiscript::const_var(Green), "Green"); /// chai.add(chaiscript::const_var(Green), "Green");
/// \endcode /// \endcode
/// ///
/// \todo support C++11 strongly typed enums
/// \sa \ref addingobjects /// \sa \ref addingobjects
template<typename T> template<typename T>
Boxed_Value const_var(const T &t) Boxed_Value const_var(const T &t)