From fbef83ecb7516056345933823ce6c8d54cfd5cf4 Mon Sep 17 00:00:00 2001 From: Jason Turner Date: Sun, 22 May 2011 23:29:55 -0600 Subject: [PATCH] Final documentation for release 3.0.0 completed --- include/chaiscript/chaiscript.hpp | 88 ++++++++++++++++++++++++++++--- releasenotes.txt | 10 ++-- 2 files changed, 87 insertions(+), 11 deletions(-) diff --git a/include/chaiscript/chaiscript.hpp b/include/chaiscript/chaiscript.hpp index 13562e4..478aa82 100644 --- a/include/chaiscript/chaiscript.hpp +++ b/include/chaiscript/chaiscript.hpp @@ -18,9 +18,31 @@ /// /// 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. +/// Currently, all source control and project management aspects of ChaiScript occur on github. +/// +///
+/// +/// \sa chaiscript +/// \sa chaiscript::ChaiScript +/// \sa \ref LangKeywordRef +/// \sa \ref LangObjectSystemRef +/// \sa http://www.chaiscript.com +/// \sa http://www.github.com/ChaiScript/ChaiScript +/// +///
/// /// \section gettingstarted Getting Started +/// +/// \li \ref basics +/// \li \ref eval +/// \li \ref addingitems +/// \li \ref helpermacro +/// \li \ref pointerconversions +/// \li \ref baseclasses +/// \li \ref functionobjects +/// \li \ref threading +/// \li \ref exceptions +/// /// /// \subsection basics Basics /// @@ -303,14 +325,68 @@ /// ///
/// -/// function objects +/// \subsection functionobjects Function Objects +/// +/// Functions are first class objects in Chaiscript and ChaiScript supports automatic conversion +/// between ChaiScript functions and boost::function objects. +/// +/// \code +/// void callafunc(const boost::function &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 f = chai.eval >("dump_system"); +/// f(); // call the ChaiScript function dump_system, from C++ +/// } +/// \endcode +/// +///
+/// +/// \subsection threading 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. /// ///
+/// +/// \subsection exceptions Exception Handling /// -/// \sa chaiscript -/// \sa chaiscript::ChaiScript -/// \sa http://www.chaiscript.com -/// \sa http://www.github.com/ChaiScript/ChaiScript +/// Exceptions can be thrown in ChaiScript and caught in C++ or thrown in C++ and caught in +/// ChaiScript. +/// +/// \code +/// void throwexception() +/// { +/// throw std::runtime_error("err"); +/// } +/// +/// int main() +/// { +/// chaiscript::ChaiScript chai; +/// chai.add(chaiscript::fun(&throwexception), "throwexception"); +/// chai("try { throwexception(); } catch (e) { print(e.what()); }"); // prints "err" +/// +/// try { +/// chai("throw(1)"); +/// } catch (chaiscript::Boxed_Value bv) { +/// int i = chaiscript::boxed_cast(bv); +/// // i == 1 +/// } +/// } +/// \endcode /// \page LangObjectSystemRef ChaiScript Language Object Model Reference /// diff --git a/releasenotes.txt b/releasenotes.txt index 3d1afb4..638e482 100644 --- a/releasenotes.txt +++ b/releasenotes.txt @@ -3,19 +3,19 @@ Changes since 2.3.3 * Code simplifications * Fully integrate documentation with source code in doxygen style comments * Unit tests increased from 114 to 137 -* Automatic conversion between boost::function objects and ChaiScript functions **** +* Automatic conversion between boost::function objects and ChaiScript functions * Many bug fixes * Minor performance improvements * Namespace reorganization to make end user code more accessible * clang support * VisualStudio 2010 Support -* Support for C++ base classes and automatic upcasting **** +* Support for C++ base classes and automatic upcasting * Remove __ reserved identifiers * Better code organization to reduce #ifdefs * clanmills: command line options for chai eval * clanmills: parser cleanups and code reduction -* Function introspection and reflection **** -* Correct function dispatch order to account for base classes and provide a defined order of dispatch **** +* Function introspection and reflection +* Correct function dispatch order to account for base classes and provide a defined order of dispatch * Predictable object lifetime that emulates C++ stack lifetime * emarcotte: pkgconfig support * standardize on method/member naming and indentation @@ -23,4 +23,4 @@ Changes since 2.3.3 * Better support for const objects * Drastic reduction of runtime exceptions - making debug builds orders of magnitude faster * Support for platforms with no loadable module support -* Add helper macro for registering class **** +* Add helper macro for registering class