From 0d238b1617a4447616939fb28c0155c648a288b0 Mon Sep 17 00:00:00 2001 From: Jason Turner Date: Sat, 2 Apr 2011 20:52:49 -0600 Subject: [PATCH] Documentation updates and namespace reorg for docs. --- include/chaiscript/chaiscript.hpp | 4 +- include/chaiscript/dispatchkit/bootstrap.hpp | 1 + .../dispatchkit/boxed_pod_value.hpp | 7 +- .../chaiscript/dispatchkit/boxed_value.hpp | 8 +- .../chaiscript/dispatchkit/dispatchkit.hpp | 7 ++ include/chaiscript/dispatchkit/type_info.hpp | 4 +- .../chaiscript/language/chaiscript_common.hpp | 80 ++++++++-------- .../chaiscript/language/chaiscript_engine.hpp | 4 +- .../chaiscript/language/chaiscript_eval.hpp | 92 ++++++++++--------- .../chaiscript/language/chaiscript_parser.hpp | 2 + include/chaiscript/utility/utility.hpp | 1 + 11 files changed, 107 insertions(+), 103 deletions(-) diff --git a/include/chaiscript/chaiscript.hpp b/include/chaiscript/chaiscript.hpp index da1e4e5..1a6cecd 100644 --- a/include/chaiscript/chaiscript.hpp +++ b/include/chaiscript/chaiscript.hpp @@ -27,8 +27,10 @@ /// \namespace chaiscript -/// The chaiscript namespace contains every API call that the average user will be concerned with. +/// \brief Every API call that the average user will be concerned with. +/// \namespace chaiscript::detail +/// \brief Classes and functions reserved for internal use. Items in this namespace are not supported. #include "dispatchkit/dispatchkit.hpp" #include "dispatchkit/bootstrap.hpp" diff --git a/include/chaiscript/dispatchkit/bootstrap.hpp b/include/chaiscript/dispatchkit/bootstrap.hpp index 529ca02..7bd30d0 100644 --- a/include/chaiscript/dispatchkit/bootstrap.hpp +++ b/include/chaiscript/dispatchkit/bootstrap.hpp @@ -16,6 +16,7 @@ namespace chaiscript { + /// \brief Classes and functions useful for bootstrapping of ChaiScript and adding of new types namespace bootstrap { namespace detail diff --git a/include/chaiscript/dispatchkit/boxed_pod_value.hpp b/include/chaiscript/dispatchkit/boxed_pod_value.hpp index 57b5266..215eba0 100644 --- a/include/chaiscript/dispatchkit/boxed_pod_value.hpp +++ b/include/chaiscript/dispatchkit/boxed_pod_value.hpp @@ -16,11 +16,8 @@ namespace chaiscript { - - /** - * Object which attempts to convert a Boxed_Value into a generic - * POD type and provide generic POD type operations - */ + + /// \brief Represents any numeric type, generically. Used internally for generic operations between POD values class Boxed_POD_Value { public: diff --git a/include/chaiscript/dispatchkit/boxed_value.hpp b/include/chaiscript/dispatchkit/boxed_value.hpp index 490f9c8..dc2aff8 100644 --- a/include/chaiscript/dispatchkit/boxed_value.hpp +++ b/include/chaiscript/dispatchkit/boxed_value.hpp @@ -23,12 +23,8 @@ namespace chaiscript { - /** - * Boxed_Value is the main tool of the dispatchkit. It allows - * for boxed / untyped containment of any C++ object. It uses - * boost::any internally but also provides user access the underlying - * stored type information - */ + /// \brief A wrapper for holding any valid C++ type. All types in ChaiScript are Boxed_Value objects + /// \sa chaiscript::boxed_cast class Boxed_Value { public: diff --git a/include/chaiscript/dispatchkit/dispatchkit.hpp b/include/chaiscript/dispatchkit/dispatchkit.hpp index 94d22f0..69e80c7 100644 --- a/include/chaiscript/dispatchkit/dispatchkit.hpp +++ b/include/chaiscript/dispatchkit/dispatchkit.hpp @@ -26,8 +26,14 @@ #include "dynamic_object.hpp" #include "../chaiscript_threading.hpp" + +/// \namespace chaiscript::dispatch +/// \brief Classes and functions specific to the runtime dispatch side of ChaiScript. Some items may be of use to the end user. + namespace chaiscript { + /// \brief Holds a collection of ChaiScript settings which can be applied to the ChaiScript runtime. + /// Used to implement loadable module support. class Module { public: @@ -109,6 +115,7 @@ namespace chaiscript } }; + /// Convenience typedef for Module objects to be added to the ChaiScript runtime typedef boost::shared_ptr ModulePtr; namespace detail diff --git a/include/chaiscript/dispatchkit/type_info.hpp b/include/chaiscript/dispatchkit/type_info.hpp index 733d926..da9a601 100644 --- a/include/chaiscript/dispatchkit/type_info.hpp +++ b/include/chaiscript/dispatchkit/type_info.hpp @@ -31,9 +31,7 @@ namespace chaiscript }; } - /** - * compile time deduced information about a type - */ + /// \brief Compile time deduced information about a type class Type_Info { public: diff --git a/include/chaiscript/language/chaiscript_common.hpp b/include/chaiscript/language/chaiscript_common.hpp index 25dc690..f0a557a 100644 --- a/include/chaiscript/language/chaiscript_common.hpp +++ b/include/chaiscript/language/chaiscript_common.hpp @@ -14,9 +14,7 @@ namespace chaiscript { typedef ModulePtr (*Create_Module_Func)(); - /** - * Types of AST nodes available to the parser and eval - */ + /// Types of AST nodes available to the parser and eval class AST_Node_Type { public: enum Type { Error, Int, Float, Id, Char, Str, Eol, Fun_Call, Inplace_Fun_Call, Arg_List, Variable, Equation, Var_Decl, @@ -43,9 +41,7 @@ namespace chaiscript } } - /** - * Convenience type for file positions - */ + /// \brief Convenience type for file positions struct File_Position { int line; int column; @@ -58,6 +54,8 @@ namespace chaiscript typedef boost::shared_ptr AST_NodePtr; + + /// \brief Classes which may be thrown during error cases when ChaiScript is executing. namespace exception { /** @@ -99,9 +97,8 @@ namespace chaiscript } - /** - * The struct that doubles as both a parser ast_node and an AST node - */ + + /// \brief Struct that doubles as both a parser ast_node and an AST node. struct AST_Node : boost::enable_shared_from_this { public: const std::string text; @@ -171,50 +168,49 @@ namespace chaiscript }; - - - - namespace detail + namespace eval { - /** - * Special type for returned values - */ - struct Return_Value { - Boxed_Value retval; - - Return_Value(const Boxed_Value &t_return_value) : retval(t_return_value) { } - }; - - /** - * Special type indicating a call to 'break' - */ - struct Break_Loop { - Break_Loop() { } - }; - - /// Creates a new scope then pops it on destruction - struct Scope_Push_Pop + namespace detail { - Scope_Push_Pop(chaiscript::detail::Dispatch_Engine &t_de) - : m_de(t_de) + /** + * Special type for returned values + */ + struct Return_Value { + Boxed_Value retval; + + Return_Value(const Boxed_Value &t_return_value) : retval(t_return_value) { } + }; + + /** + * Special type indicating a call to 'break' + */ + struct Break_Loop { + Break_Loop() { } + }; + + /// Creates a new scope then pops it on destruction + struct Scope_Push_Pop { - m_de.new_scope(); - } + Scope_Push_Pop(chaiscript::detail::Dispatch_Engine &t_de) + : m_de(t_de) + { + m_de.new_scope(); + } - ~Scope_Push_Pop() - { - m_de.pop_scope(); - } + ~Scope_Push_Pop() + { + m_de.pop_scope(); + } - private: + private: // explicitly unimplemented copy and assignment Scope_Push_Pop(const Scope_Push_Pop &); Scope_Push_Pop& operator=(const Scope_Push_Pop &); chaiscript::detail::Dispatch_Engine &m_de; - }; - + }; + } } } diff --git a/include/chaiscript/language/chaiscript_engine.hpp b/include/chaiscript/language/chaiscript_engine.hpp index 309bef2..16364bf 100644 --- a/include/chaiscript/language/chaiscript_engine.hpp +++ b/include/chaiscript/language/chaiscript_engine.hpp @@ -219,6 +219,8 @@ namespace chaiscript typedef boost::shared_ptr Loadable_Module_Ptr; } + + /// \brief The main object that the ChaiScript user will use. class ChaiScript { mutable chaiscript::detail::threading::shared_mutex m_mutex; @@ -248,7 +250,7 @@ namespace chaiscript return Boxed_Value(); } } - catch (const detail::Return_Value &rv) { + catch (const chaiscript::eval::detail::Return_Value &rv) { return rv.retval; } } diff --git a/include/chaiscript/language/chaiscript_eval.hpp b/include/chaiscript/language/chaiscript_eval.hpp index fee19bc..5e59d7f 100644 --- a/include/chaiscript/language/chaiscript_eval.hpp +++ b/include/chaiscript/language/chaiscript_eval.hpp @@ -13,27 +13,29 @@ namespace chaiscript { - /** - * Helper function that will set up the scope around a function call, including handling the named function parameters - */ - template - const Boxed_Value eval_function (Eval_System &t_ss, const AST_NodePtr &t_node, const std::vector &t_param_names, const std::vector &t_vals) { - detail::Scope_Push_Pop spp(t_ss); - - for (unsigned int i = 0; i < t_param_names.size(); ++i) { - t_ss.add_object(t_param_names[i], t_vals[i]); - } - - try { - return t_node->eval(t_ss); - } catch (const detail::Return_Value &rv) { - return rv.retval; - } - } - - + /// \brief Classes and functions that are part of the runtime eval system namespace eval { + namespace detail + { + /** + * Helper function that will set up the scope around a function call, including handling the named function parameters + */ + static const Boxed_Value eval_function(chaiscript::detail::Dispatch_Engine &t_ss, const AST_NodePtr &t_node, const std::vector &t_param_names, const std::vector &t_vals) { + chaiscript::eval::detail::Scope_Push_Pop spp(t_ss); + + for (unsigned int i = 0; i < t_param_names.size(); ++i) { + t_ss.add_object(t_param_names[i], t_vals[i]); + } + + try { + return t_node->eval(t_ss); + } catch (const detail::Return_Value &rv) { + return rv.retval; + } + } + } + struct Binary_Operator_AST_Node : public AST_Node { public: Binary_Operator_AST_Node(const std::string &t_ast_node_text = "", int t_id = AST_Node_Type::Bitwise_Xor, const boost::shared_ptr &t_fname=boost::shared_ptr(), int t_start_line = 0, int t_start_col = 0, int t_end_line = 0, int t_end_col = 0) : @@ -101,7 +103,7 @@ namespace chaiscript Id_AST_Node(const std::string &t_ast_node_text = "", int t_id = AST_Node_Type::Id, const boost::shared_ptr &t_fname=boost::shared_ptr(), int t_start_line = 0, int t_start_col = 0, int t_end_line = 0, int t_end_col = 0) : AST_Node(t_ast_node_text, t_id, t_fname, t_start_line, t_start_col, t_end_line, t_end_col), m_value(get_value(t_ast_node_text)) - { } + { } virtual ~Id_AST_Node() {} virtual Boxed_Value eval_internal(chaiscript::detail::Dispatch_Engine &t_ss) { @@ -485,7 +487,7 @@ namespace chaiscript } return Boxed_Value(Proxy_Function(new dispatch::Dynamic_Proxy_Function - (boost::bind(&eval_function, boost::ref(t_ss), this->children.back(), t_param_names, _1), + (boost::bind(chaiscript::eval::detail::eval_function, boost::ref(t_ss), this->children.back(), t_param_names, _1), static_cast(numparams), this->children.back()))); } @@ -499,7 +501,7 @@ namespace chaiscript virtual Boxed_Value eval_internal(chaiscript::detail::Dispatch_Engine &t_ss){ const size_t num_children = this->children.size(); - detail::Scope_Push_Pop spp(t_ss); + chaiscript::eval::detail::Scope_Push_Pop spp(t_ss); for (size_t i = 0; i < num_children; ++i) { try { @@ -510,7 +512,7 @@ namespace chaiscript return retval; } } - catch (const chaiscript::detail::Return_Value &) { + catch (const chaiscript::eval::detail::Return_Value &) { throw; } } @@ -552,19 +554,19 @@ namespace chaiscript boost::shared_ptr guard; if (guardnode) { guard = boost::shared_ptr - (new dispatch::Dynamic_Proxy_Function(boost::bind(&eval_function, - boost::ref(t_ss), guardnode, - t_param_names, _1), static_cast(numparams), guardnode)); + (new dispatch::Dynamic_Proxy_Function(boost::bind(chaiscript::eval::detail::eval_function, + boost::ref(t_ss), guardnode, + t_param_names, _1), static_cast(numparams), guardnode)); } try { const std::string & l_function_name = this->children[0]->text; const std::string & l_annotation = this->annotation?this->annotation->text:""; t_ss.add(Proxy_Function - (new dispatch::Dynamic_Proxy_Function(boost::bind(&eval_function, - boost::ref(t_ss), this->children.back(), - t_param_names, _1), static_cast(numparams), this->children.back(), - l_annotation, guard)), l_function_name); + (new dispatch::Dynamic_Proxy_Function(boost::bind(chaiscript::eval::detail::eval_function, + boost::ref(t_ss), this->children.back(), + t_param_names, _1), static_cast(numparams), this->children.back(), + l_annotation, guard)), l_function_name); } catch (const exception::reserved_word_error &e) { throw exception::eval_error("Reserved word used as function name '" + e.word() + "'"); @@ -582,7 +584,7 @@ namespace chaiscript virtual Boxed_Value eval_internal(chaiscript::detail::Dispatch_Engine &t_ss) { bool cond; - detail::Scope_Push_Pop spp(t_ss); + chaiscript::eval::detail::Scope_Push_Pop spp(t_ss); try { cond = boxed_cast(this->children[0]->eval(t_ss)); @@ -607,7 +609,7 @@ namespace chaiscript } return Boxed_Value(); } - + }; struct If_AST_Node : public AST_Node { @@ -663,7 +665,7 @@ namespace chaiscript virtual Boxed_Value eval_internal(chaiscript::detail::Dispatch_Engine &t_ss){ bool cond; - detail::Scope_Push_Pop spp(t_ss); + chaiscript::eval::detail::Scope_Push_Pop spp(t_ss); try { if (this->children.size() == 4) { @@ -845,7 +847,7 @@ namespace chaiscript virtual Boxed_Value eval_internal(chaiscript::detail::Dispatch_Engine &t_ss){ Boxed_Value retval; - detail::Scope_Push_Pop spp(t_ss); + chaiscript::eval::detail::Scope_Push_Pop spp(t_ss); try { retval = this->children[0]->eval(t_ss); @@ -1013,9 +1015,9 @@ namespace chaiscript boost::shared_ptr guard; if (guardnode) { guard = boost::shared_ptr - (new dispatch::Dynamic_Proxy_Function(boost::bind(&eval_function, - boost::ref(t_ss), guardnode, - t_param_names, _1), static_cast(numparams), guardnode)); + (new dispatch::Dynamic_Proxy_Function(boost::bind(chaiscript::eval::detail::eval_function, + boost::ref(t_ss), guardnode, + t_param_names, _1), static_cast(numparams), guardnode)); } try { @@ -1025,10 +1027,10 @@ namespace chaiscript if (function_name == class_name) { t_ss.add(Proxy_Function (new dispatch::detail::Dynamic_Object_Constructor(class_name, Proxy_Function - (new dispatch::Dynamic_Proxy_Function(boost::bind(&eval_function, - boost::ref(t_ss), this->children.back(), - t_param_names, _1), static_cast(numparams), this->children.back(), - l_annotation, guard)))), function_name); + (new dispatch::Dynamic_Proxy_Function(boost::bind(chaiscript::eval::detail::eval_function, + boost::ref(t_ss), this->children.back(), + t_param_names, _1), static_cast(numparams), this->children.back(), + l_annotation, guard)))), function_name); } else { @@ -1040,10 +1042,10 @@ namespace chaiscript } t_ss.add(Proxy_Function (new dispatch::detail::Dynamic_Object_Function(class_name, Proxy_Function - (new dispatch::Dynamic_Proxy_Function(boost::bind(&eval_function, - boost::ref(t_ss), this->children.back(), - t_param_names, _1), static_cast(numparams), this->children.back(), - l_annotation, guard)), ti)), function_name); + (new dispatch::Dynamic_Proxy_Function(boost::bind(chaiscript::eval::detail::eval_function, + boost::ref(t_ss), this->children.back(), + t_param_names, _1), static_cast(numparams), this->children.back(), + l_annotation, guard)), ti)), function_name); } } diff --git a/include/chaiscript/language/chaiscript_parser.hpp b/include/chaiscript/language/chaiscript_parser.hpp index 985cf22..035e3ec 100644 --- a/include/chaiscript/language/chaiscript_parser.hpp +++ b/include/chaiscript/language/chaiscript_parser.hpp @@ -16,8 +16,10 @@ namespace chaiscript { + /// \brief Classes and functions used during the parsing process. namespace parser { + /// \brief Classes and functions internal to the parsing process. Not supported for the end user. namespace detail { enum Alphabet diff --git a/include/chaiscript/utility/utility.hpp b/include/chaiscript/utility/utility.hpp index 2748930..80c8c5a 100644 --- a/include/chaiscript/utility/utility.hpp +++ b/include/chaiscript/utility/utility.hpp @@ -55,6 +55,7 @@ namespace chaiscript { + /// \brief Classes and functions which provide general utility to the end user. namespace utility { inline std::string class_name_translator(const std::string &t_name)