More documentation updates and additions to getting started guide

include/chaiscript/chaiscript.hpp

@@ -20,6 +20,262 @@
 ///
 /// Currently, all source control and project management aspects of ChaiScript occur on <a href="http://www.github.com">github</a>.
 ///
+/// \section gettingstarted Getting Started
+/// 
+/// \subsection basics Basics
+/// 
+/// Basic simple example:
+///
+/// \code
+/// #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);");
+/// } 
+/// \endcode
+///
+/// <hr>
+/// \subsection eval Evaluating Scripts
+///
+/// Scripts can be evaluated with the () operator, eval method or eval_file method.
+///
+/// \subsubsection parenoperator () Operator
+///
+/// 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'
+/// 
+/// The eval method is somewhat more verbose and can be used to get typesafely return values
+/// from the script.
+///
+/// \code
+/// chaiscript::ChaiScript chai;
+/// chai.eval("callsomefunc()");
+/// int result = chai.eval<int>("1 + 3");
+/// // result now equals 4
+/// \endcode
+///
+/// \sa chaiscript::ChaiScript::eval
+///
+/// \subsubsection evalfilemethod Method 'eval_file'
+/// 
+/// The 'eval_file' method loads a file from disk and executes the script in it
+/// 
+/// \code
+/// 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
+/// \endcode
+/// 
+/// \sa chaiscript::ChaiScript::eval_file
+///
+/// <hr>
+/// \subsection addingitems Adding Items to ChaiScript
+///
+/// ChaiScript supports 4 basic things that can be added: objects, functions, type infos and Modules
+///
+/// \subsubsection addingobjects Adding Objects
+///
+/// Named objects can be created with the #var function.
+/// 
+/// \code
+/// using namespace chaiscript;
+/// ChaiScript chai;
+/// int i = 5;
+/// chai.add(var(i), "i");
+/// chai("print(i)");
+/// \endcode
+///
+/// Immutable objects can be created with the chaiscript::const_var function.
+///
+/// \code
+/// chai.add(const_var(i), "i");
+/// chai("i = 5"); // exception throw, cannot assign const var
+/// \endcode
+/// 
+/// 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.
+///
+/// \code
+/// chai.add_global_const(const_var(i), "i");
+/// chai("def somefun() { print(i); }; sumfun();");
+/// \endcode
+/// 
+/// \subsubsection addingfunctions Adding Functions
+/// 
+/// Functions, methods and members are all added using the same function: chaiscript::fun.
+///
+/// \code
+/// 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");
+/// \endcode
+///
+/// Overloaded methods will need some help, to hint the compiler as to which overload you want:
+///
+/// \code
+/// chai.add(fun<void (MyClass::*)()>(&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.
+/// 
+/// \code
+/// 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)
+/// \endcode
+///
+/// \subsubsection addingtypeinfo 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:
+///
+/// \code
+/// chai.add(user_type<MyClass>(), "MyClass");
+/// \endcode
+///
+/// \subsubsection addingmodules Adding Modules
+/// 
+/// Modules are holders for collections of ChaiScript registrations.
+///
+/// \code
+/// ModulePtr module = get_sum_module();
+/// chai.add(module);
+/// \endcode
+/// 
+/// \sa chaiscript::Module
+/// 
+/// <hr>
+/// \subsection helpermacro 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.
+///
+/// \code
+/// 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);
+/// }
+/// \endcode
+/// 
+/// \sa \ref addingmodules
+///
+/// \subsection pointerconversions Pointer / Object Conversions
+///
+/// As much as possible, ChaiScript attempts to convert between &, *, const &, const *, boost::shared_ptr<T>,
+/// boost::shared_ptr<const T> and boost::reference_wrapand value types automatically.
+///
+/// If a 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.
+///
+/// \code
+/// 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> &);
+///
+/// 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("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)");
+/// }  add demo for reference_wrapper
+/// \endcode
+///
+/// See the unit test unittests/
+/// 
+/// base classes
+/// function objects
+///
+/// <hr>
+/// 
 /// \sa chaiscript
 /// \sa chaiscript::ChaiScript
 /// \sa http://www.chaiscript.com
@@ -28,7 +284,7 @@
 /// \page LangObjectSystemRef ChaiScript Language Object Model Reference
 ///
 ///
-/// ChaiScript supports 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

include/chaiscript/chaiscript_threading.hpp

@@ -27,7 +27,7 @@ namespace chaiscript
   {
     /// If threading is enabled, then this namespace contains boost::thread classes.
     /// If threading is not enabled, then stubbed in wrappers that do nothing are provided.
-    /// This allows us to avoid #ifdef code in the sections that need thread safety.
+    /// This allows us to avoid \#ifdef code in the sections that need thread safety.
     namespace threading
     {
 

include/chaiscript/dispatchkit/boxed_value.hpp

@@ -281,6 +281,8 @@ namespace chaiscript
   /// chai.add(chaiscript::var(i), "i");
   /// chai.add(chaiscript::var(&i), "ip");
   /// \endcode
+  /// 
+  /// \sa \ref addingobjects
   template<typename T>
     Boxed_Value var(T t)
     {
@@ -352,6 +354,8 @@ namespace chaiscript
   /// chai.add(chaiscript::const_var(Red), "Red");
   /// chai.add(chaiscript::const_var(Green), "Green");
   /// \endcode
+  /// 
+  /// \sa \ref addingobjects
   template<typename T>
     Boxed_Value const_var(const T &t)
     {

include/chaiscript/dispatchkit/register_function.hpp

@@ -74,6 +74,8 @@ namespace chaiscript
   /// chaiscript::ChaiScript chai;
   /// chai.add(fun(f), "some_function");
   /// \endcode
+  /// 
+  /// \sa \ref addingfunctions
   template<typename T>
     Proxy_Function fun(const boost::function<T> &f)
     {
@@ -98,6 +100,8 @@ namespace chaiscript
   /// chai.add(fun(&MyClass::memberfunction), "memberfunction");
   /// chai.add(fun(&MyClass::memberdata), "memberdata");
   /// \endcode
+  /// 
+  /// \sa \ref addingfunctions
   template<typename T>
     Proxy_Function fun(T t)
     {
@@ -120,6 +124,8 @@ namespace chaiscript
   /// // Add function taking only one argument, an int, and permanently bound to "obj"
   /// chai.add(fun(&MyClass::memberfunction, boost::ref(obj)), "memberfunction"); 
   /// \endcode
+  /// 
+  /// \sa \ref addingfunctions
   template<typename T, typename Q>
     Proxy_Function fun(T t, const Q &q)
     {
@@ -144,6 +150,8 @@ namespace chaiscript
   /// // memberfunction() will be equivalent to obj.memberfunction(1)
   /// chai.add(fun(&MyClass::memberfunction, boost::ref(obj), 1), "memberfunction"); 
   /// \endcode
+  /// 
+  /// \sa \ref addingfunctions
   template<typename T, typename Q, typename R>
     Proxy_Function fun(T t, const Q &q, const R &r)
     {

include/chaiscript/language/chaiscript_engine.hpp

@@ -478,6 +478,8 @@ namespace chaiscript
     /// MyClass obj;
     /// chai.add(chaiscript::var(&obj), "obj"); // Add a pointer to a locally defined object
     /// \endcode
+    ///
+    /// \sa \ref addingitems
     template<typename T>
     ChaiScript &add(const T &t_t, const std::string &t_name)
     {

readme.txt

@@ -5,7 +5,7 @@ Release under the BSD license, see "license.txt" for details.
 
 [Introduction]
 
-ChaiScript is one of the first (and perhaps only) embedded scripting language designed from the ground up to directly target C++.  Being a native C++ application, it has some advantages over existing embedded scripting languages:
+ChaiScript is the only embedded scripting language designed from the ground up to directly target C++ and take advantage of modern C++ development techniques, working with the developer like he expects it to work.  Being a native C++ application, it has some advantages over existing embedded scripting languages:
 
 1) It uses a header-only approach, which makes it easy to integrate with existing projects.
 2) It maintains type safety between your C++ application and the user scripts.
@@ -19,13 +19,13 @@ ChaiScript requires a recent version of Boost (http://www.boost.org) to build.
 
 * Add the ChaiScript include directory to your project's header search path
 * Add "#include <chaiscript/chaiscript.hpp> to your source file
-* Instantiate the ChaiScript engine in your application.  For example, create a new engine with the name 'chai' like so: "chaiscript::ChaiScript_Engine chai"
+* Instantiate the ChaiScript engine in your application.  For example, create a new engine with the name 'chai' like so: "chaiscript::ChaiScript chai"
 
 Once instantiated, the engine is ready to start running ChaiScript source.  You have two main options for processing ChaiScript source: a line at a time using "chai.evaluate_string(string)" and a file at a time using "chai.evaluate_file(fname)"
 
-To make functions in your C++ code visible to scripts, they must be registered with the scripting engine.  To do so, call register_function:
+To make functions in your C++ code visible to scripts, they must be registered with the scripting engine.  To do so, call add:
 
-dispatchkit::register_function(chai.get_eval_engine(), &my_function, "my_function_name");
+chai.add(&my_function, "my_function_name");
 
 Once registered the function will be visible to scripts as "my_function_name"
 
@@ -33,4 +33,23 @@ Once registered the function will be visible to scripts as "my_function_name"
 
 ChaiScript is similar to ECMAScript (aka JavaScript(tm)), but with some modifications to make it easier to use.  For usage examples see the "samples" directory, and for more in-depth look at the language, the unit tests in the "unittests" directory cover the most ground.
 
-For example of how to register parts of your C++ application, see "example.cpp" in the "src" directory.
+For examples of how to register parts of your C++ application, see "example.cpp" in the "src" directory. Example.cpp is verbose and shows every possible way of working with the library. For further documentation generate the doxygen documentation in the build folder or see the website http://www.chaiscript.com.
+
+The shortest complete example possible follows:
+
+/// 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);");
+}

releasenotes.txt

@@ -0,0 +1,26 @@
+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 ****
+* 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 ****
+* 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 ****
+* Predictable object lifetime that emulates C++ stack lifetime
+* emarcotte: pkgconfig support
+* standardize on method/member naming and indentation
+* 64bit Visual Studio support
+* 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 ****