elimination of unused / outdated code and documentation cleanups.

Doxyfile.in

@@ -1357,7 +1357,7 @@ PERLMOD_MAKEVAR_PREFIX =
 # evaluate all C-preprocessor directives found in the sources and include 
 # files.
 
-ENABLE_PREPROCESSING   = YES
+ENABLE_PREPROCESSING   = NO
 
 # If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro 
 # names in the source code. If set to NO (the default) only conditional 

include/chaiscript/chaiscript_threading.hpp

@@ -23,20 +23,24 @@
 
 namespace chaiscript
 {
-  /// \internal
   namespace detail
   {
+    /// 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.
     namespace threading
     {
 
 #ifndef CHAISCRIPT_NO_THREADS
-      using boost::unique_lock;
+      using boost::unique_lock; 
       using boost::shared_lock;
       using boost::lock_guard;
       using boost::shared_mutex;
       using boost::recursive_mutex;
 
 
+      /// Typesafe thread specific storage. If threading is enabled, this class uses boost::thread_specific_ptr<T>. If
+      /// threading is not enabled, the class always returns the same data, regardless of which thread it is called from.
       template<typename T>
         class Thread_Storage
         {

include/chaiscript/dispatchkit/bad_boxed_cast.hpp

@@ -13,10 +13,11 @@ namespace chaiscript
 {
   namespace exception
   {
-    /**
+    /// \brief Thrown in the event that a Boxed_Value cannot be cast to the desired type
-     * class that is thrown in the event of a bad_boxed_cast. That is,
+    ///
-     * in the case that a Boxed_Value cannot be cast to the desired type
+    /// It is used internally during function dispatch and may be used by the end user.
-     */
+    ///
+    /// \sa chaiscript::boxed_cast
     class bad_boxed_cast : public std::bad_cast
     {
       public:
@@ -38,13 +39,14 @@ namespace chaiscript
 
         virtual ~bad_boxed_cast() throw() {}
 
+        /// \brief Description of what error occured
         virtual const char * what() const throw()
         {
           return m_what.c_str();
         }
 
-        Type_Info from;
+        Type_Info from; ///< Type_Info contained in the Boxed_Value
-        const std::type_info *to;
+        const std::type_info *to; ///< std::type_info of the desired (but failed) result type
 
       private:
         std::string m_what;

include/chaiscript/dispatchkit/bind_first.hpp

@@ -30,9 +30,14 @@
 
 namespace chaiscript
 {
-
   namespace detail
   { 
+    /// \brief Helper function for binding the first parameter of a class method pointer. Used in chaiscript::fun overloads
+    ///        that take 1 or 2 parameters to pre-bind to the function.
+    ///
+    /// \param[in] f method pointer to bind
+    /// \param[in] o object to bind as first parameter 
+    /// \returns a new boost::function object with one fewer parameters than the function passed in. 
     template<typename Ret, typename O, typename Class BOOST_PP_COMMA_IF(n) BOOST_PP_ENUM_PARAMS(n, typename Param) >
       boost::function<Ret (BOOST_PP_ENUM_PARAMS(n, Param))> 
       bind_first(Ret (Class::*f)(BOOST_PP_ENUM_PARAMS(n, Param)), const O &o)
@@ -40,13 +45,25 @@ namespace chaiscript
         return boost::bind(boost::mem_fn(f), o BOOST_PP_COMMA_IF(n) BOOST_PP_ENUM(n, param, _));
       }
 
+    /// \brief Helper function for binding the first parameter of a const class method pointer. Used in chaiscript::fun overloads
+    ///        that take 1 or 2 parameters to pre-bind to the function.
+    ///
+    /// \param[in] f method pointer to bind
+    /// \param[in] o object to bind as first parameter 
+    /// \returns a new boost::function object with one fewer parameters than the function passed in. 
     template<typename Ret, typename O, typename Class BOOST_PP_COMMA_IF(n) BOOST_PP_ENUM_PARAMS(n, typename Param) >
       boost::function<Ret (BOOST_PP_ENUM_PARAMS(n, Param))> 
-      bind_first(Ret (Class::*f)(BOOST_PP_ENUM_PARAMS(n, Param))const, const O &o)
+      bind_first(Ret (Class::*f)(BOOST_PP_ENUM_PARAMS(n, Param)) const, const O &o)
       {
         return boost::bind(boost::mem_fn(f), o BOOST_PP_COMMA_IF(n) BOOST_PP_ENUM(n, param, _));
       }
 
+    /// \brief Helper function for binding the first parameter of a function pointer. Used in chaiscript::fun overloads
+    ///        that take 1 or 2 parameters to pre-bind to the function.
+    ///
+    /// \param[in] f method pointer to bind
+    /// \param[in] o object to bind as first parameter 
+    /// \returns a new boost::function object with one fewer parameters than the function passed in. 
     template<typename Ret,typename O BOOST_PP_COMMA_IF(m) BOOST_PP_ENUM_PARAMS(m, typename Param) >
       boost::function<Ret (BOOST_PP_ENUM(n, param, Param))> 
       bind_first(Ret (*f)(BOOST_PP_ENUM_PARAMS(m, Param)), const O &o)
@@ -54,6 +71,12 @@ namespace chaiscript
         return boost::bind(f, o BOOST_PP_COMMA_IF(n) BOOST_PP_ENUM(n, param, _));
       }
 
+    /// \brief Helper function for binding the first parameter of a boost::function object. Used in chaiscript::fun overloads
+    ///        that take 1 or 2 parameters to pre-bind to the function.
+    ///
+    /// \param[in] f method pointer to bind
+    /// \param[in] o object to bind as first parameter 
+    /// \returns a new boost::function object with one fewer parameters than the function passed in. 
     template<typename Ret,typename O BOOST_PP_COMMA_IF(m) BOOST_PP_ENUM_PARAMS(m, typename Param) >
       boost::function<Ret (BOOST_PP_ENUM(n, param, Param))> 
       bind_first(const boost::function<Ret (BOOST_PP_ENUM_PARAMS(m, Param))> &f, const O &o)

include/chaiscript/dispatchkit/bootstrap.hpp

@@ -21,16 +21,14 @@ namespace chaiscript
     namespace detail
     {
 
-      /* Special helpers for generating generic "POD" type operators
+      /// \brief Assigns a POD value from a Boxed_POD_Value. Helps support operators between
-      * The POD operators are needed for general support of C++ POD
+      ///        disparate POD types.
-      * types without iterating out all possible combinations of operators
+      /// \param[in,out] p1 object to assign to
-      * (<, >, +, +=, *=, \=, -, <=, >=, ==) and types
+      /// \param[in] v Boxed_POD_Value to assign from
-      * (char, uint8_t, int8_t, uint16_t, int16_t...)
+      /// \returns Reference to p1, to support normal C assignment semantics
-      */
       template<typename P1>
-      P1 &assign_pod(P1 &p1, Boxed_POD_Value v)
+      P1 &assign_pod(P1 &p1, const Boxed_POD_Value &v)
       {
-
         if (v.isfloat)
         {
           return (p1 = P1(v.d));
@@ -39,6 +37,9 @@ namespace chaiscript
         }
       }
 
+      /// \brief Constructs a new POD value object from a Boxed_POD_Value
+      /// \param[in] v Boxed_POD_Value to copy into the new object
+      /// \returns The newly created object.
       template<typename P1>
       P1 construct_pod(Boxed_POD_Value v)
       {
@@ -50,6 +51,10 @@ namespace chaiscript
         }    
       }
 
+      /// \brief Performs a bitwise and assignment (&=) on the given object with the given Boxed_POD_Value
+      /// \param[in,out] p1 object to bitwise and assign to
+      /// \param[in] r Boxed_POD_Value to assign from
+      /// \returns Reference to p1, to support normal C assignment semantics
       template<typename P1>
       P1 &assign_bitwise_and_pod(P1 &p1, Boxed_POD_Value r)
       {
@@ -61,6 +66,10 @@ namespace chaiscript
         throw exception::bad_boxed_cast("&= only valid for integer types");
       }
 
+      /// \brief Performs a xor assignment (^=) on the given object with the given Boxed_POD_Value
+      /// \param[in,out] p1 object to xor assign to
+      /// \param[in] r Boxed_POD_Value to assign from
+      /// \returns Reference to p1, to support normal C assignment semantics
       template<typename P1>
       P1 &assign_xor_pod(P1 &p1, Boxed_POD_Value r)
       {
@@ -72,6 +81,10 @@ namespace chaiscript
         throw exception::bad_boxed_cast("^= only valid for integer types");
       }
 
+      /// \brief Performs a bitwise or assignment (|=) on the given object with the given Boxed_POD_Value
+      /// \param[in,out] p1 object to bitwise or assign to
+      /// \param[in] r Boxed_POD_Value to assign from
+      /// \returns Reference to p1, to support normal C assignment semantics
       template<typename P1>
       P1 &assign_bitwise_or_pod(P1 &p1, Boxed_POD_Value r)
       {
@@ -83,6 +96,10 @@ namespace chaiscript
         throw exception::bad_boxed_cast("&= only valid for integer types");
       }
 
+      /// \brief Performs an assign difference (-=) on the given object with the given Boxed_POD_Value
+      /// \param[in,out] p1 object to difference assign to
+      /// \param[in] r Boxed_POD_Value to assign from
+      /// \returns Reference to p1, to support normal C assignment semantics
       template<typename P1>
       P1 &assign_difference_pod(P1 &p1, Boxed_POD_Value r)
       {
@@ -94,6 +111,10 @@ namespace chaiscript
         }
       }
 
+      /// \brief Performs an assign shift left (<<=) on the given object with the given Boxed_POD_Value
+      /// \param[in,out] p1 object to assign shift left to
+      /// \param[in] r Boxed_POD_Value to assign from
+      /// \returns Reference to p1, to support normal C assignment semantics
       template<typename P1>
       P1 &assign_left_shift_pod(P1 &p1, Boxed_POD_Value r)
       {
@@ -106,6 +127,10 @@ namespace chaiscript
       }
 
 
+      /// \brief Performs an assign product (*=) on the given object with the given Boxed_POD_Value
+      /// \param[in,out] p1 object to assign product to
+      /// \param[in] r Boxed_POD_Value to assign from
+      /// \returns Reference to p1, to support normal C assignment semantics
       template<typename P1>
       P1 &assign_product_pod(P1 &p1, Boxed_POD_Value r)
       {
@@ -117,6 +142,10 @@ namespace chaiscript
         }
       }
 
+      /// \brief Performs an assign quotient (/=) on the given object with the given Boxed_POD_Value
+      /// \param[in,out] p1 object to assign quotient to
+      /// \param[in] r Boxed_POD_Value to assign from
+      /// \returns Reference to p1, to support normal C assignment semantics
       template<typename P1>
       P1 &assign_quotient_pod(P1 &p1, Boxed_POD_Value r)
       {
@@ -128,6 +157,10 @@ namespace chaiscript
         }
       }
 
+      /// \brief Performs an assign remainder (%=) on the given object with the given Boxed_POD_Value
+      /// \param[in,out] p1 object to assign remainder to
+      /// \param[in] r Boxed_POD_Value to assign from
+      /// \returns Reference to p1, to support normal C assignment semantics
       template<typename P1>
       P1 &assign_remainder_pod(P1 &p1, Boxed_POD_Value r)
       {
@@ -140,6 +173,10 @@ namespace chaiscript
       }
 
 
+      /// \brief Performs an assign shift right (>>=) on the given object with the given Boxed_POD_Value
+      /// \param[in,out] p1 object to assign shift right to
+      /// \param[in] r Boxed_POD_Value to assign from
+      /// \returns Reference to p1, to support normal C assignment semantics
       template<typename P1>
       P1 &assign_right_shift_pod(P1 &p1, Boxed_POD_Value r)
       {
@@ -151,7 +188,10 @@ namespace chaiscript
         throw exception::bad_boxed_cast(">>= only valid for integer types");
       }
 
-
+      /// \brief Performs an assign sum (+=) on the given object with the given Boxed_POD_Value
+      /// \param[in,out] p1 object to sum assign to
+      /// \param[in] r Boxed_POD_Value to assign from
+      /// \returns Reference to p1, to support normal C assignment semantics
       template<typename P1>
       P1 &assign_sum_pod(P1 &p1, Boxed_POD_Value r)
       {
@@ -165,6 +205,10 @@ namespace chaiscript
 
     }
 
+    /// \brief Add all comparison operators for the templated type. Used during bootstrap, also available to users.
+    /// \tparam T Type to create comparison operators for
+    /// \param[in,out] m module to add comparison operators to
+    /// \returns the passed in ModulePtr or the newly constructed one if the default params are used.
     template<typename T>
     ModulePtr opers_comparison(ModulePtr m = ModulePtr(new Module()))
     {
@@ -177,6 +221,12 @@ namespace chaiscript
       return m;
     }
 
+
+    /// \brief Add all arithmetic operators appropriate for integers for the templated type. 
+    ///        Used during bootstrap, also available to users.
+    /// \tparam T Type to create arithmetic operators for
+    /// \param[in,out] m module to add arithmetic operators to
+    /// \returns the passed in ModulePtr or the newly constructed one if the default params are used.
     template<typename T>
     ModulePtr opers_integer_arithmetic(ModulePtr m = ModulePtr(new Module()))
     {
@@ -209,6 +259,11 @@ namespace chaiscript
       return m;
     }
 
+    /// \brief Add all arithmetic operators appropriate for floating point numbers for the templated type. 
+    ///        Used during bootstrap, also available to users.
+    /// \tparam T Type to create arithmetic operators for
+    /// \param[in,out] m module to add arithmetic operators to
+    /// \returns the passed in ModulePtr or the newly constructed one if the default params are used.
     template<typename T>
     ModulePtr opers_float_arithmetic(ModulePtr m = ModulePtr(new Module()))
     {
@@ -226,9 +281,11 @@ namespace chaiscript
       return m;
     }
 
-    /**
+    /// \brief Adds a copy constructor for the given type to the given Model
-    * Add a copy constructor for type T
+    /// \param[in] type The name of the type. The copy constructor will be named "type".
-    */
+    /// \param[in,out] m The Module to add the copy constructor to
+    /// \tparam T The type to add a copy constructor for
+    /// \returns The passed in ModulePtr, or the newly constructed one if the default param is used
     template<typename T>
     ModulePtr copy_constructor(const std::string &type, ModulePtr m = ModulePtr(new Module()))
     {
@@ -236,9 +293,13 @@ namespace chaiscript
       return m;
     }
 
-    /**
+    /// \brief Adds default and copy constructors for the given type
-    * Add default and copy constructors for type T
+    /// \param[in] type The name of the type to add the constructors for.
-    */
+    /// \param[in,out] m The Module to add the basic constructors to
+    /// \tparam T Type to generate basic constructors for
+    /// \returns The passed in ModulePtr, or the newly constructed one if the default param is used
+    /// \sa copy_constructor
+    /// \sa constructor
     template<typename T>
     ModulePtr basic_constructors(const std::string &type, ModulePtr m = ModulePtr(new Module()))
     {
@@ -247,9 +308,10 @@ namespace chaiscript
       return m;
     }
 
-    /**
+    /// \brief Adds a constructor for a POD type 
-    * Add POD type constructor for type T. ie: T = type(POD)
+    /// \tparam T The type to add the constructor for
-    */
+    /// \param[in] T The name of the type
+    /// \param[in,out] m The Module to add the constructor to
     template<typename T>
     ModulePtr construct_pod(const std::string &type, ModulePtr m = ModulePtr(new Module()))
     {
@@ -257,16 +319,6 @@ namespace chaiscript
       return m;
     }
 
-    /**
-    * add user defined single parameter constructor for type T.
-    * T = type(const U &)
-    */
-    template<typename T, typename U>
-    ModulePtr constructor_overload(const std::string &type, ModulePtr m = ModulePtr(new Module()))
-    {
-      m->add(constructor<T (const U &)>(), type);
-      return m;
-    }
 
     /**
     * to_string function for internal use. Uses ostream operator<<
@@ -558,9 +610,9 @@ namespace chaiscript
       }
 
     public:
-      /**
+      /// \brief perform all common bootstrap functions for std::string, void and POD types
-      * perform all common bootstrap functions for std::string, void and POD types
+      /// \param[in,out] m Module to add bootstrapped functions to
-      */
+      /// \returns passed in ModulePtr, or newly created one if default argument is used
       static ModulePtr bootstrap(ModulePtr m = ModulePtr(new Module()))
       {
         m->add(user_type<void>(), "void");

include/chaiscript/language/chaiscript_engine.hpp

@@ -511,19 +511,6 @@ namespace chaiscript
     }
 
 
-    /**
-     * Helper for calling script code as if it were native C++ code
-     * example:
-     * boost::function<int (int, int)> f = build_functor(chai, "func(x, y){x+y}");
-     * \return a boost::function representing the passed in script
-     * \param[in] script Script code to build a function from
-     */
-    template<typename FunctionType>
-    boost::function<FunctionType> functor(const std::string &t_script)
-    {
-      return chaiscript::dispatch::functor<FunctionType>(eval(t_script));
-    }
-
     /**
      * Evaluate a string via eval method
      */

samples/example.cpp

@@ -115,7 +115,7 @@ int main(int /*argc*/, char * /*argv*/[]) {
   //Call bound version of do_callbacks
   chai("do_callbacks()");
 
-  boost::function<void ()> caller = chai.functor<void ()>("fun() { system.do_callbacks(\"From Functor\"); }");
+  boost::function<void ()> caller = chai.eval<boost::function<void ()> >("fun() { system.do_callbacks(\"From Functor\"); }");
   caller();
 
 
@@ -139,7 +139,7 @@ int main(int /*argc*/, char * /*argv*/[]) {
   //To do: Add examples of handling Boxed_Values directly when needed
 
   //Creating a functor on the stack and using it immediatly 
-  int x = chai.functor<int (int, int)>("fun (x, y) { return x + y; }")(5, 6);
+  int x = chai.eval<boost::function<int (int, int)> >("fun (x, y) { return x + y; }")(5, 6);
 
   log("Functor test output", boost::lexical_cast<std::string>(x));
 

src/main.cpp

@@ -52,10 +52,10 @@ void version(int){
   std::cout << "chai: compiled " << __TIME__ << " " << __DATE__ << std::endl;
 }
 
-bool throws_exception(const chaiscript::Proxy_Function &f)
+bool throws_exception(const boost::function<void ()> &f)
 {
   try {
-    chaiscript::dispatch::functor<void ()>(f)();
+    f();
   } catch (...) {
     return true;
   }
@@ -102,7 +102,7 @@ void interactive(chaiscript::ChaiScript& chai)
       //Then, we try to print the result of the evaluation to the user
       if (!val.get_type_info().bare_equal(chaiscript::user_type<void>())) {
         try {
-          std::cout << chai.functor<std::string (const chaiscript::Boxed_Value &bv)>("to_string")(val) << std::endl;
+          std::cout << chai.eval<boost::function<std::string (const chaiscript::Boxed_Value &bv)> >("to_string")(val) << std::endl;
         }
         catch (...) {} //If we can't, do nothing
       }

unittests/functor_creation_test.cpp

@@ -7,15 +7,15 @@ int main()
 
   chai.eval("def func() { print(\"Hello World\"); } ");
 
-  boost::function<void ()> f = chai.functor<void ()>("func");
+  boost::function<void ()> f = chai.eval<boost::function<void ()> >("func");
   f();
 
-  if (chai.functor<std::string (int)>("to_string")(6) != "6")
+  if (chai.eval<boost::function<std::string (int)> >("to_string")(6) != "6")
   {
     return EXIT_FAILURE;
   }
 
-  if (chai.functor<std::string (const chaiscript::Boxed_Value &)>("to_string")(chaiscript::var(6)) == "6")
+  if (chai.eval<boost::function<std::string (const chaiscript::Boxed_Value &)> >("to_string")(chaiscript::var(6)) == "6")
   {
     return EXIT_SUCCESS;
   } else {