diff options
author | 2011-07-03 16:49:10 +0800 | |
---|---|---|
committer | 2011-07-03 16:49:10 +0800 | |
commit | 6c8652270b3f350b8621f2923d23f3f265146d59 (patch) | |
tree | 5a2350002375061682eeee4dfa2b20313fd16a6f /src | |
parent | Utility: improve token printing (diff) | |
download | libbash-6c8652270b3f350b8621f2923d23f3f265146d59.tar.gz libbash-6c8652270b3f350b8621f2923d23f3f265146d59.tar.bz2 libbash-6c8652270b3f350b8621f2923d23f3f265146d59.zip |
Doc: improve documentation
Now make doxygen-doc doesn't show so many warnings. The documentation
for following things is not fixed: unit tests, private members, some
built-in constructors.
Diffstat (limited to 'src')
-rw-r--r-- | src/builtins/boolean_builtins.h | 2 | ||||
-rw-r--r-- | src/builtins/builtin_exceptions.h | 9 | ||||
-rw-r--r-- | src/common.h | 2 | ||||
-rw-r--r-- | src/core/bash_ast.h | 55 | ||||
-rw-r--r-- | src/core/bash_condition.h | 8 | ||||
-rw-r--r-- | src/core/divide_by_zero_error.h | 2 | ||||
-rw-r--r-- | src/core/function.h | 9 | ||||
-rw-r--r-- | src/core/illegal_argument_exception.h | 2 | ||||
-rw-r--r-- | src/core/interpreter.h | 166 | ||||
-rw-r--r-- | src/core/interpreter_exception.h | 2 | ||||
-rw-r--r-- | src/core/parse_exception.h | 2 | ||||
-rw-r--r-- | src/core/readonly_exception.h | 2 | ||||
-rw-r--r-- | src/core/runtime_exception.h | 2 | ||||
-rw-r--r-- | src/core/symbols.hpp | 34 | ||||
-rw-r--r-- | src/core/unsupported_exception.h | 2 | ||||
-rw-r--r-- | src/cppbash_builtin.h | 33 |
16 files changed, 223 insertions, 109 deletions
diff --git a/src/builtins/boolean_builtins.h b/src/builtins/boolean_builtins.h index fb7aca9..0d3db1a 100644 --- a/src/builtins/boolean_builtins.h +++ b/src/builtins/boolean_builtins.h @@ -17,7 +17,7 @@ along with libbash. If not, see <http://www.gnu.org/licenses/>. */ /// -/// \file boolean_builtins.cpp +/// \file boolean_builtins.h /// \brief implementations for the true and false builtins /// #ifndef LIBBASH_BUILTINS_BOOLEAN_BUILTINS_H_ diff --git a/src/builtins/builtin_exceptions.h b/src/builtins/builtin_exceptions.h index 7b45efc..e1a443a 100644 --- a/src/builtins/builtin_exceptions.h +++ b/src/builtins/builtin_exceptions.h @@ -49,8 +49,11 @@ protected: virtual ~loop_control_exception() {} public: + /// \brief the construtor + /// \param c the nested block counter explicit loop_control_exception(int c): count(c) {} + /// \brief rethrow the exception if the counter is greater than 1 void rethrow_unless_correct_frame() { if(count != 1) @@ -64,12 +67,15 @@ public: class continue_exception: public loop_control_exception { protected: + /// \brief rethrow the exception itself virtual void rethrow() { throw *this; } public: + /// \brief the constructor of the exception + /// \param c the nested block counter explicit continue_exception(int c): loop_control_exception(c) { if(c < 1) throw libbash::illegal_argument_exception("continue: argument should be greater than or equal to 1"); @@ -79,12 +85,15 @@ public: class break_exception: public loop_control_exception { protected: + /// \brief rethrow the exception itself virtual void rethrow() { throw *this; } public: + /// \brief the constructor of the exception + /// \param c the nested block counter explicit break_exception(int c): loop_control_exception(c) { if(c < 1) throw libbash::illegal_argument_exception("break: argument should be greater than or equal to 1"); diff --git a/src/common.h b/src/common.h index 537e8d8..7203f02 100644 --- a/src/common.h +++ b/src/common.h @@ -24,7 +24,9 @@ #ifndef LIBBASH_COMMON_H_ #define LIBBASH_COMMON_H_ +/// compiler hint for public symbols #define LIBBASH_API __attribute__((visibility("default"))) +/// compiler hint for hidden symbols #define LIBBASH_LOCAL __attribute__((visibility("hidden"))) #endif diff --git a/src/core/bash_ast.h b/src/core/bash_ast.h index 22635a1..fb42663 100644 --- a/src/core/bash_ast.h +++ b/src/core/bash_ast.h @@ -37,14 +37,19 @@ struct libbashLexer_Ctx_struct; struct libbashParser_Ctx_struct; struct libbashWalker_Ctx_struct; -typedef libbashWalker_Ctx_struct* plibbashWalker; class interpreter; +/// \class bash_ast +/// \brief customized unique_ptr for antlr objects. template<typename T> class antlr_pointer: public std::unique_ptr<T, std::function<void(T*)>> { + /// the constructor of base class typedef std::unique_ptr<T, std::function<void(T*)>> parent; public: + /// \brief constructor of antlr_pointer + /// \param p the pointer to the antlr objects, it should provide a method called 'free' + /// to free the memory antlr_pointer(T* p = 0) : parent(p, [](T* to_delete) { to_delete->free(to_delete); }) {}; }; @@ -61,54 +66,86 @@ class bash_ast: public boost::noncopyable antlr_pointer<ANTLR3_COMMON_TREE_NODE_STREAM_struct> nodes; std::function<pANTLR3_BASE_TREE(libbashParser_Ctx_struct*)> parse; - typedef std::unique_ptr<libbashWalker_Ctx_struct, std::function<void(plibbashWalker)>> walker_pointer; + typedef std::unique_ptr<libbashWalker_Ctx_struct, std::function<void(libbashWalker_Ctx_struct*)>> walker_pointer; void init_parser(const std::string& script, const std::string& script_path); walker_pointer create_walker(interpreter& walker); public: + /// \brief build AST from istream + /// \param source input source + /// \param p the parser rule for building the AST bash_ast(const std::istream& source, std::function<pANTLR3_BASE_TREE(libbashParser_Ctx_struct*)> p=parser_start); + /// \brief build AST from string + /// \param script_path input source + /// \param p the parser rule for building the AST bash_ast(const std::string& script_path, std::function<pANTLR3_BASE_TREE(libbashParser_Ctx_struct*)> p=parser_start); - static void walker_start(plibbashWalker tree_parser); + /// \brief the functor for walker start rule + /// \param tree_parser the pointer to the tree_parser + static void walker_start(libbashWalker_Ctx_struct* tree_parser); - static long walker_arithmetics(plibbashWalker tree_parser); + /// \brief the functor for walker arithmetics rule + /// \param tree_parser the pointer to the tree_parser + static long walker_arithmetics(libbashWalker_Ctx_struct* tree_parser); - static void call_function(plibbashWalker tree_parser, + /// \brief call a function that is defined in the AST + /// \param tree_parser the pointer to the tree_parser + /// \param index the function index + static void call_function(libbashWalker_Ctx_struct* tree_parser, ANTLR3_MARKER index); + /// \brief the functor for parser start rule + /// \param parser the pointer to the parser static pANTLR3_BASE_TREE parser_start(libbashParser_Ctx_struct* parser); + /// \brief the functor for parser arithmetics rule + /// \param parser the pointer to the parser static pANTLR3_BASE_TREE parser_arithmetics(libbashParser_Ctx_struct* parser); /// /// \brief interpret the script with a given interpreter - /// \param the interpreter object + /// \param walker the interpreter object + /// \param walk the walker rule to evaluate the AST /// \return the interpreted result template<typename Functor> - typename std::result_of<Functor(plibbashWalker)>::type + typename std::result_of<Functor(libbashWalker_Ctx_struct*)>::type interpret_with(interpreter& walker, Functor walk) { walker_pointer p_tree_parser = create_walker(walker); return walk(p_tree_parser.get()); } + /// + /// \brief use the start rule to interpret the script with a given interpreter + /// \param walker the interpreter object void interpret_with(interpreter& walker) { interpret_with(walker, walker_start); } + /// \brief get the dot graph for the AST + /// \return the dot graph std::string get_dot_graph(); + /// \brief get the string tree for the AST + /// \return the string tree std::string get_string_tree(); + /// \brief get parser tokens from a token stream + /// \param token_stream the token stream + /// \param token_mapper function that translates token numbers to token names + /// \return the parser tokens static std::string get_parser_tokens(antlr_pointer<ANTLR3_COMMON_TOKEN_STREAM_struct>& token_stream, - std::function<std::string(ANTLR3_UINT32)>); + std::function<std::string(ANTLR3_UINT32)> token_mapper); - std::string get_walker_tokens(std::function<std::string(ANTLR3_UINT32)>); + /// \brief get walker tokens from current AST + /// \param token_mapper function that translates token numbers to token names + /// \return the walker tokens + std::string get_walker_tokens(std::function<std::string(ANTLR3_UINT32)> token_mapper); }; #endif diff --git a/src/core/bash_condition.h b/src/core/bash_condition.h index e8e4096..1c4f26c 100644 --- a/src/core/bash_condition.h +++ b/src/core/bash_condition.h @@ -29,8 +29,16 @@ class interpreter; namespace internal { + /// \brief implementation for built-in test unary operation + /// \param the operator + /// \param the operand bool test_unary(char op, const std::string& target); + /// \brief implementation for built-in test binary operation + /// \param the operator + /// \param the first operand + /// \param the second operand + /// \param a reference to the interpreter object bool test_binary(const std::string& op, const std::string& lhs, const std::string& rhs, diff --git a/src/core/divide_by_zero_error.h b/src/core/divide_by_zero_error.h index 10603cc..59e0fcb 100644 --- a/src/core/divide_by_zero_error.h +++ b/src/core/divide_by_zero_error.h @@ -39,6 +39,8 @@ namespace libbash class LIBBASH_API divide_by_zero_error: public libbash::interpreter_exception { public: + /// \brief the constructor + /// \param err_msg the error message explicit divide_by_zero_error(const std::string& err_msg): libbash::interpreter_exception(err_msg){} }; diff --git a/src/core/function.h b/src/core/function.h index fcd0e91..92ae97c 100644 --- a/src/core/function.h +++ b/src/core/function.h @@ -17,7 +17,7 @@ along with libbash. If not, see <http://www.gnu.org/licenses/>. */ /// -/// \file function.hpp +/// \file function.h /// \brief implementation for function /// @@ -31,13 +31,20 @@ class bash_ast; class interpreter; +/// \class function +/// \brief bash function implementation class function { bash_ast& ast; ANTLR3_MARKER index; public: + /// \brief the constructor + /// \param ast_ the reference to the AST + /// \param i the function index function(bash_ast& ast_, ANTLR3_MARKER i): ast(ast_), index(i){} + /// \brief call the function + /// \param walker the reference to the interpreter object void call(interpreter& walker); }; diff --git a/src/core/illegal_argument_exception.h b/src/core/illegal_argument_exception.h index f67a9f6..847b6a8 100644 --- a/src/core/illegal_argument_exception.h +++ b/src/core/illegal_argument_exception.h @@ -39,6 +39,8 @@ namespace libbash class LIBBASH_API illegal_argument_exception: public libbash::interpreter_exception { public: + /// \brief the constructor + /// \param err_msg the error message explicit illegal_argument_exception(const std::string& err_msg): libbash::interpreter_exception(err_msg){} }; diff --git a/src/core/interpreter.h b/src/core/interpreter.h index b0cfda5..c623e86 100644 --- a/src/core/interpreter.h +++ b/src/core/interpreter.h @@ -36,6 +36,7 @@ #include "core/symbols.hpp" #include "cppbash_builtin.h" +/// \brief symbol table implementation typedef std::unordered_map<std::string, std::shared_ptr<variable>> scope; /// @@ -45,17 +46,14 @@ typedef std::unordered_map<std::string, std::shared_ptr<variable>> scope; class interpreter: public boost::noncopyable { - /// \var private::members /// \brief global symbol table for variables scope members; - /// \var private::function_definitions /// \brief global symbol table for functions std::unordered_map<std::string, function> functions; std::stack<bash_ast*> ast_stack; - /// \var private::local_members /// \brief local scope for function arguments, execution environment and /// local variables std::vector<scope> local_members; @@ -73,7 +71,6 @@ class interpreter: public boost::noncopyable // as bash implementation. std::map<char, bool> options; - /// \var private::status /// \brief the return status of the last command int status; @@ -107,6 +104,7 @@ class interpreter: public boost::noncopyable unsigned length) const; public: + /// bash option iterator typedef std::map<std::string, bool>::const_iterator option_iterator; /// @@ -118,17 +116,21 @@ public: interpreter& walker; public: + /// \brief construtor + /// \param w the reference to the interpreter object local_scope(interpreter& w): walker(w) { walker.local_members.push_back(scope()); } + /// \brief the destructor ~local_scope() { walker.local_members.pop_back(); } }; + /// \brief construtor interpreter(); /// @@ -174,11 +176,14 @@ public: return members.end(); } + /// \brief set current output stream + /// \param stream the pointer to the output stream void set_output_stream(std::ostream* stream) { _out = stream; } + /// \brief restore the current output stream to standard output stream void restore_output_stream() { _out = &std::cout; @@ -186,8 +191,8 @@ public: /// \brief resolve string/long variable, local scope will be /// checked first, then global scope - /// \param variable name - /// \param array index, use index=0 if it's not an array + /// \param name variable name + /// \param index array index, use index=0 if it's not an array /// \return the value of the variable, call default constructor if /// it's undefined template <typename T> @@ -201,8 +206,8 @@ public: } /// \brief resolve array variable - /// \param variable name - /// \param[out] vector that stores all array values + /// \param name variable name + /// \param[out] values vector that stores all array values template <typename T> bool resolve_array(const std::string& name, std::vector<T>& values) const { @@ -216,12 +221,13 @@ public: /// \brief check whether the value of the variable is null, return true /// if the variable is undefined - /// \param variable name + /// \param name variable name + /// \param index array index, use index=0 if it's not an array /// \return whether the value of the variable is null bool is_unset_or_null(const std::string& name, const unsigned index) const; /// \brief check whether the value of the variable is unset - /// \param variable name + /// \param name variable name /// \return whether the value of the variable is unset bool is_unset(const std::string& name) const { @@ -230,9 +236,9 @@ public: /// \brief update the variable value, raise libbash::interpreter_exception if /// it's readonly, will define the variable if it doesn't exist - /// \param variable name - /// \param new value - /// \param array index, use index=0 if it's not an array + /// \param name variable name + /// \param new_value new value + /// \param index array index, use index=0 if it's not an array /// \return the new value of the variable template <typename T> const T& set_value(const std::string& name, @@ -248,37 +254,36 @@ public: } /// \brief set the return status of the last command - /// \param the value of the return status + /// \param s the value of the return status void set_status(int s) { status = s; } /// \brief get the return status of the last command - /// \param the value of the return status int get_status(void) const { return status; } /// \brief unset a variable - /// \param the name of the variable + /// \param name the name of the variable void unset(const std::string& name); /// \brief unset a function - /// \param the name of the function + /// \param name the name of the function void unset_function(const std::string& name); /// \brief unset a array member - /// \param the name of the array - /// \param the index of the member + /// \param name the name of the array + /// \param index the index of the member void unset(const std::string& name, const unsigned index); /// \brief define a new global variable - /// \param the name of the variable - /// \param the value of the variable - /// \param whether it's readonly, default is false - /// \param whether it's null, default is false + /// \param name the name of the variable + /// \param value the value of the variable + /// \param readonly whether it's readonly, default is false + /// \param index whether it's null, default is false template <typename T> void define(const std::string& name, const T& value, @@ -289,10 +294,10 @@ public: } /// \brief define a new local variable - /// \param the name of the variable - /// \param the value of the variable - /// \param whether it's readonly, default is false - /// \param whether it's null, default is false + /// \param name the name of the variable + /// \param value the value of the variable + /// \param readonly whether it's readonly, default is false + /// \param index whether it's null, default is false template <typename T> void define_local(const std::string& name, const T& value, @@ -303,8 +308,8 @@ public: } /// \brief define a new function - /// \param the name of the function - /// \param the body index of the function + /// \param name the name of the function + /// \param body_index the body index of the function void define_function(const std::string& name, ANTLR3_MARKER body_index) { @@ -312,7 +317,7 @@ public: } /// \brief push current AST, used for function definition - /// \param current ast + /// \param ast the pointer to the current ast void push_current_ast(bash_ast* ast) { ast_stack.push(ast); @@ -325,24 +330,29 @@ public: } /// \brief make function call - /// \param function name - /// \param function arguments + /// \param name function name + /// \param arguments function arguments void call(const std::string& name, const std::vector<std::string>& arguments); /// \brief check if we have 'name' defined as a function - /// \param function name + /// \param name function name /// \return whether 'name' is a function bool has_function(const std::string& name) const { return functions.find(name) != functions.end(); } + /// \brief get all defined function names + /// \param[out] function_names the place to store the function names void get_all_function_names(std::vector<std::string>& function_names) const; /// \brief execute builtin - /// \param builtin name - /// \param builtin arguments + /// \param name builtin name + /// \param args builtin arguments + /// \param output the output stream + /// \param error the error stream + /// \param input the input stream /// \return the return value of the builtin int execute_builtin(const std::string& name, const std::vector<std::string>& args, @@ -359,8 +369,9 @@ public: } /// \brief perform ${parameter:−word} expansion - /// \param the name of the parameter - /// \param the value of the word + /// \param name the name of the parameter + /// \param value the value of the word + /// \param index the index of the paramter /// \return the expansion result const std::string do_default_expansion(const std::string& name, const std::string& value, @@ -371,8 +382,9 @@ public: } /// \brief perform ${parameter:=word} expansion - /// \param the name of the parameter - /// \param the value of the word + /// \param name the name of the parameter + /// \param value the value of the word + /// \param index the index of the paramter /// \return the expansion result const std::string do_assign_expansion(const std::string& name, const std::string& value, @@ -383,8 +395,9 @@ public: } /// \brief perform ${parameter:+word} expansion - /// \param the name of the parameter - /// \param the value of the word + /// \param name the name of the parameter + /// \param value the value of the word + /// \param index the index of the paramter /// \return the expansion result const std::string do_alternate_expansion(const std::string& name, const std::string& value, @@ -394,15 +407,19 @@ public: } /// \brief perform substring expansion - /// \param the offset of the substring + /// \param name the name of the parameter + /// \param offset the offset of the substring + /// \param index the index of the paramter /// \return the expansion result const std::string do_substring_expansion(const std::string& name, long long offset, const unsigned index) const; /// \brief perform substring expansion - /// \param the offset of the substring - /// \param the length of the substring + /// \param name the name of the parameter + /// \param offset the offset of the substring + /// \param length the length of the substring + /// \param index the index of the paramter /// \return the expansion result const std::string do_substring_expansion(const std::string& name, long long offset, @@ -410,61 +427,64 @@ public: const unsigned index) const; /// \brief perform subarray expansion - /// \param the offset of the subarray + /// \param name the name of the parameter + /// \param offset the offset of the subarray /// \return the expansion result const std::string do_subarray_expansion(const std::string& name, long long offset) const; /// \brief perform subarray expansion - /// \param the offset of the subarray - /// \param the length of the subarray + /// \param name the name of the parameter + /// \param offset the offset of the subarray + /// \param length the length of the subarray /// \return the expansion result const std::string do_subarray_expansion(const std::string& name, long long offset, int length) const; /// \brief perform replacement expansion - /// \param the name of the varaible that needs to be expanded - /// \param the function object used to perform expansion - /// \param array index, use index=0 if it's not an array + /// \param name the name of the varaible that needs to be expanded + /// \param replacer the function object used to perform expansion + /// \param index array index, use index=0 if it's not an array /// \return the expanded value std::string do_replace_expansion(const std::string& name, std::function<void(std::string&)> replacer, const unsigned index) const; /// \brief get the length of a string variable - /// \param the name of the variable + /// \param name the name of the variable + /// \param index the index of the variable /// \return the length std::string::size_type get_length(const std::string& name, const unsigned index=0) const; /// \brief get the length of an array - /// \param the name of the array + /// \param name the name of the array /// \return the length of the array variable::size_type get_array_length(const std::string& name) const; /// \brief get all array elements concatenated by space - /// \param the name of the array - /// \param[out] the concatenated string - void get_all_elements(const std::string&, std::string&) const; + /// \param name the name of the array + /// \param[out] result the concatenated string + void get_all_elements(const std::string& name, std::string& result) const; /// \brief get all array elements concatenated by the first character of IFS - /// \param the name of the array - /// \param[out] the concatenated string - void get_all_elements_IFS_joined(const std::string&, std::string&) const; + /// \param name the name of the array + /// \param[out] result the concatenated string + void get_all_elements_IFS_joined(const std::string& name, std::string& result) const; /// \brief implementation of word splitting - /// \param the value of the word - //. \param[out] the splitted result will be appended to output + /// \param word the value of the word + //. \param[out] output the splitted result will be appended to output void split_word(const std::string& word, std::vector<std::string>& output) const; /// \brief get the status of shell optional behavior - /// \param the option name + /// \param name the option name /// \return zero unless the name is not a valid shell option bool get_additional_option(const std::string& name) const; /// \brief set the status of shell optional behavior - /// \param the option name - /// \param[in] true if option is enabled, false otherwise + /// \param name the option name + /// \param[in] value true if option is enabled, false otherwise /// \return zero unless the name is not a valid shell option void set_additional_option(const std::string& name, bool value); @@ -484,34 +504,34 @@ public: } /// \brief evaluate arithmetic expression and return the result - /// \param the arithmetic expression + /// \param expression the arithmetic expression /// \return the evaluated result long eval_arithmetic(const std::string& expression); /// \brief perform expansion like ${var//foo/bar} - /// \param the value to be expanded - /// \param the pattern used to match the value - /// \param the replacement string + /// \param value the value to be expanded + /// \param pattern the pattern used to match the value + /// \param replacement the replacement string static void replace_all(std::string& value, const boost::xpressive::sregex& pattern, const std::string& replacement); /// \brief perform expansion like ${var%foo} - /// \param the value to be expanded - /// \param the pattern used to match the value + /// \param value the value to be expanded + /// \param pattern the pattern used to match the value static void lazy_remove_at_end(std::string& value, const boost::xpressive::sregex& pattern); /// \brief perform expansion like ${var/foo/bar} - /// \param the value to be expanded - /// \param the pattern used to match the value - /// \param the replacement string + /// \param value the value to be expanded + /// \param pattern the pattern used to match the value + /// \param replacement the replacement string static void replace_first(std::string& value, const boost::xpressive::sregex& pattern, const std::string& replacement); /// \brief remove trailing EOLs from the value - /// \param[in, out] the target + /// \param[in, out] value the target static void trim_trailing_eols(std::string& value); }; #endif diff --git a/src/core/interpreter_exception.h b/src/core/interpreter_exception.h index ea5a9ef..11f909f 100644 --- a/src/core/interpreter_exception.h +++ b/src/core/interpreter_exception.h @@ -38,6 +38,8 @@ namespace libbash class LIBBASH_API interpreter_exception: public std::runtime_error { public: + /// \brief the constructor + /// \param err_msg the error message explicit interpreter_exception(const std::string& err_msg): runtime_error(err_msg){} }; diff --git a/src/core/parse_exception.h b/src/core/parse_exception.h index 20860b4..6f19bff 100644 --- a/src/core/parse_exception.h +++ b/src/core/parse_exception.h @@ -39,6 +39,8 @@ namespace libbash class LIBBASH_API parse_exception: public libbash::interpreter_exception { public: + /// \brief the constructor + /// \param err_msg the error message explicit parse_exception(const std::string& err_msg): libbash::interpreter_exception(err_msg){} }; diff --git a/src/core/readonly_exception.h b/src/core/readonly_exception.h index 97964de..16d1106 100644 --- a/src/core/readonly_exception.h +++ b/src/core/readonly_exception.h @@ -39,6 +39,8 @@ namespace libbash class LIBBASH_API readonly_exception: public libbash::interpreter_exception { public: + /// \brief the constructor + /// \param err_msg the error message explicit readonly_exception(const std::string& err_msg): libbash::interpreter_exception(err_msg){} }; diff --git a/src/core/runtime_exception.h b/src/core/runtime_exception.h index da6fffa..ed87655 100644 --- a/src/core/runtime_exception.h +++ b/src/core/runtime_exception.h @@ -39,6 +39,8 @@ namespace libbash class LIBBASH_API runtime_exception: public libbash::interpreter_exception { public: + /// \brief the constructor + /// \param err_msg the error message explicit runtime_exception(const std::string& err_msg): libbash::interpreter_exception(err_msg){} }; diff --git a/src/core/symbols.hpp b/src/core/symbols.hpp index 8c6dec7..c535f8f 100644 --- a/src/core/symbols.hpp +++ b/src/core/symbols.hpp @@ -53,7 +53,7 @@ class converter<long>: public boost::static_visitor<long> { public: /// \brief converter for long value - /// \param the value to be converted + /// \param value the value to be converted /// \return the converted long long operator() (const long value) const { @@ -61,7 +61,7 @@ public: } /// \brief converter for string value - /// \param the value to be converted + /// \param value the value to be converted /// \return the converted long long operator() (const std::string& value) const { @@ -88,7 +88,7 @@ class converter<std::string>: { public: /// \brief converter for long value - /// \param the value to be converted + /// \param value the value to be converted /// \return the converted string std::string operator() (const long value) const { @@ -96,7 +96,7 @@ public: } /// \brief converter for string value - /// \param the value to be converted + /// \param value the value to be converted /// \return the converted string std::string operator() (const std::string& value) const { @@ -110,21 +110,19 @@ public: /// class variable { - /// \var private::name /// \brief variable name std::string name; - /// \var private::value /// \brief actual value of the variable. We put string in front of long /// because we want "" as default string value; Otherwise we /// will get "0". std::map<unsigned, boost::variant<std::string, long>> value; - /// \var private::readonly /// \brief whether the variable is readonly bool readonly; public: + /// size_type for array length typedef std::map<unsigned, boost::variant<std::string, long>>::size_type size_type; /// \brief retrieve variable name @@ -134,6 +132,11 @@ public: return name; } + /// \brief constructor + /// \param name the name of the variable + /// \param v the value of the variable + /// \param ro whether the variable is readonly + /// \param index the index of the variable, use 0 if it's not an array template <typename T> variable(const std::string& name, const T& v, @@ -146,6 +149,7 @@ public: /// \brief retrieve actual value of the variable, if index is out of bound, /// will return the default value of type T + /// \param index the index of the variable, use 0 if it's not an array /// \return the value of the variable template<typename T> T get_value(const unsigned index=0) const @@ -160,7 +164,7 @@ public: } /// \brief retrieve all values of the array - /// \param[out] vector that stores all array values + /// \param[out] all_values vector that stores all array values template<typename T> void get_all_values(std::vector<T>& all_values) const { @@ -173,9 +177,8 @@ public: /// \brief set the value of the variable, raise exception if it's readonly - /// \param the new value to be set - /// \param array index, use index=0 if it's not an array - /// \param whether to set the variable to null value, default is false + /// \param new_value the new value to be set + /// \param index array index, use index=0 if it's not an array template <typename T> void set_value(const T& new_value, const unsigned index=0) @@ -187,7 +190,7 @@ public: } /// \brief unset the variable, only used for array variable - /// \param the index to be unset + /// \param index the index to be unset void unset_value(const unsigned index) { if(readonly) @@ -197,7 +200,7 @@ public: } /// \brief get the length of a variable - /// \param the index of the variable, use 0 if it's not an array + /// \param index the index of the variable, use 0 if it's not an array /// \return the length of the variable std::string::size_type get_length(const unsigned index=0) const { @@ -233,7 +236,10 @@ public: } }; -// specialization for arrays +/// \brief the specialized constructor for arrays +/// \param name the variable name +/// \param value the variable value +/// \param ro whether the variable readonly template <> inline variable::variable<>(const std::string& name, const std::map<unsigned, std::string>& v, diff --git a/src/core/unsupported_exception.h b/src/core/unsupported_exception.h index 338b087..9920a5c 100644 --- a/src/core/unsupported_exception.h +++ b/src/core/unsupported_exception.h @@ -39,6 +39,8 @@ namespace libbash class LIBBASH_API unsupported_exception: public libbash::interpreter_exception { public: + /// \brief the constructor + /// \param err_msg the error message explicit unsupported_exception(const std::string& err_msg): libbash::interpreter_exception(err_msg){} }; diff --git a/src/cppbash_builtin.h b/src/cppbash_builtin.h index c42ee1a..04ff387 100644 --- a/src/cppbash_builtin.h +++ b/src/cppbash_builtin.h @@ -34,6 +34,7 @@ #include <boost/scoped_ptr.hpp> #include <boost/utility.hpp> +/// shortcut for the arguments of the constructor #define BUILTIN_ARGS std::ostream &out, std::ostream &err, std::istream &in, interpreter &walker class interpreter; @@ -46,9 +47,10 @@ class cppbash_builtin: public boost::noncopyable public: /// /// \brief Default constructor, sets default streams - /// \param outstream where to send standard output. Default: cout - /// \param errstream where to send standard error. Default: cerr - /// \param instream where to get standard input from. Default: stdin + /// \param out where to send standard output. Default: cout + /// \param err where to send standard error. Default: cerr + /// \param in where to get standard input from. Default: stdin + /// \param walker the interpreter object /// explicit cppbash_builtin(BUILTIN_ARGS); @@ -75,6 +77,14 @@ class cppbash_builtin: public boost::noncopyable /// std::istream& input_buffer() {return *_inp_stream;} + /// \brief execute the given builtin + /// \param builtin the builtin name + /// \param args the arguments + /// \param out where to send standard output. Default: cout + /// \param err where to send standard error. Default: cerr + /// \param in where to get standard input from. Default: stdin + /// \param walker the interpreter object + /// \return the return status of the builtin static int exec(const std::string& builtin, const std::vector<std::string>& args, BUILTIN_ARGS) @@ -85,8 +95,8 @@ class cppbash_builtin: public boost::noncopyable /// /// \brief check existence of the builtin - /// \param builtin name - /// \param whether it is a builtin + /// \param builtin builtin name + /// \return whether it is a builtin /// static bool is_builtin(const std::string& builtin) { @@ -111,21 +121,22 @@ class cppbash_builtin: public boost::noncopyable /// std::istream *_inp_stream; + /// + /// \var _walker + /// \brief reference to the interpreter object interpreter& _walker; - /// - /// \var builtins - /// \brief holds factories for creating instances of child classes - /// + /// holds factories for creating instances of child classes typedef std::map<std::string, boost::function< cppbash_builtin*(BUILTIN_ARGS) >> builtins_type; static builtins_type& builtins(); /// \brief transforms escapes in echo input - /// \param the target string - /// \param the place to write + /// \param string the target string + /// \param output the place to write void transform_escapes(const std::string &string, std::ostream& output) const; }; +/// shortcut for builtin constructor #define BUILTIN_CONSTRUCTOR(name) \ name ## _builtin(BUILTIN_ARGS) : cppbash_builtin(out, err, in, walker) {} |