* [gentoo-commits] proj/libbash:master commit in: src/, src/core/, src/builtins/
@ 2011-07-03 20:21 Petteri Räty
0 siblings, 0 replies; only message in thread
From: Petteri Räty @ 2011-07-03 20:21 UTC (permalink / raw
To: gentoo-commits
commit: 6c8652270b3f350b8621f2923d23f3f265146d59
Author: Mu Qiao <qiaomuf <AT> gentoo <DOT> org>
AuthorDate: Sun Jul 3 08:49:10 2011 +0000
Commit: Petteri Räty <betelgeuse <AT> gentoo <DOT> org>
CommitDate: Sun Jul 3 08:49:10 2011 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/libbash.git;a=commit;h=6c865227
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.
---
src/builtins/boolean_builtins.h | 2 +-
src/builtins/builtin_exceptions.h | 9 ++
src/common.h | 2 +
src/core/bash_ast.h | 55 +++++++++--
src/core/bash_condition.h | 8 ++
src/core/divide_by_zero_error.h | 2 +
src/core/function.h | 9 ++-
src/core/illegal_argument_exception.h | 2 +
src/core/interpreter.h | 166 ++++++++++++++++++--------------
src/core/interpreter_exception.h | 2 +
src/core/parse_exception.h | 2 +
src/core/readonly_exception.h | 2 +
src/core/runtime_exception.h | 2 +
src/core/symbols.hpp | 34 ++++---
src/core/unsupported_exception.h | 2 +
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) {}
^ permalink raw reply related [flat|nested] only message in thread
only message in thread, other threads:[~2011-07-03 20:21 UTC | newest]
Thread overview: (only message) (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2011-07-03 20:21 [gentoo-commits] proj/libbash:master commit in: src/, src/core/, src/builtins/ Petteri Räty
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox