From 9a5d814c406619e7e696f7dc1b52977d6a829343 Mon Sep 17 00:00:00 2001 From: Richard Braun Date: Tue, 30 May 2006 00:15:20 +0000 Subject: Documentation improvement. --- Makefile | 6 +- main_cli.cc | 8 ++ main_gui.cc | 8 ++ mtx.doxygen | 2 +- mtxdivbyzeroexception.h | 6 ++ mtxentry.h | 14 +++ mtxexception.h | 6 ++ mtxexpression.cc | 19 ++-- mtxexpression.h | 123 ++++++++++++++++++++++- mtxhistory.h | 39 ++++++++ mtxlanguage.cc | 4 +- mtxlanguage.h | 81 +++++++++++++--- mtxmatrix.cc | 2 +- mtxmatrix.h | 225 ++++++++++++++++++++++++++++++++++++++++++- mtxsingularmatrixexception.h | 6 ++ mtxsymbol.h | 134 ++++++++++++++++++++++++-- mtxvalue.h | 45 ++++++++- mtxwindow.h | 15 +++ 18 files changed, 691 insertions(+), 52 deletions(-) diff --git a/Makefile b/Makefile index a3d4194..37d62bf 100644 --- a/Makefile +++ b/Makefile @@ -25,9 +25,11 @@ BINARIES = $(CLI_BINARY) $(GUI_BINARY) DOXYGEN = doxygen DOXYGEN_CONF = mtx.doxygen -.PHONY: clean-doc clean +.PHONY: bin all clean-doc clean -all: $(BINARIES) +bin: $(BINARIES) + +all: bin doc $(CLI_BINARY): $(CLI_OBJECTS) $(CC) -o $(CLI_BINARY) $(CLI_OBJECTS) $(CLI_LIBS) diff --git a/main_cli.cc b/main_cli.cc index 2ef13c0..cb98444 100644 --- a/main_cli.cc +++ b/main_cli.cc @@ -18,6 +18,14 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ +/** + * \file main_cli.cc + * \brief CLI interface implementation. + * + * Implements a command line interface (CLI) to the mtx engine. The CLI is + * based on libreadline. + */ + #include #include #include diff --git a/main_gui.cc b/main_gui.cc index 61c45c1..0c5e2b6 100644 --- a/main_gui.cc +++ b/main_gui.cc @@ -18,6 +18,14 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ +/** + * \file main_gui.cc + * \brief GUI interface implementation. + * + * Implements a graphical user interface (GUI) to the mtx engine. The GUI is + * based on libgtkmm2. + */ + #include #include diff --git a/mtx.doxygen b/mtx.doxygen index 5b4e7f3..58b602d 100644 --- a/mtx.doxygen +++ b/mtx.doxygen @@ -22,7 +22,7 @@ TAB_SIZE = 8 ALIASES = OPTIMIZE_OUTPUT_FOR_C = NO OPTIMIZE_OUTPUT_JAVA = NO -BUILTIN_STL_SUPPORT = NO +BUILTIN_STL_SUPPORT = YES DISTRIBUTE_GROUP_DOC = NO SUBGROUPING = YES EXTRACT_ALL = YES diff --git a/mtxdivbyzeroexception.h b/mtxdivbyzeroexception.h index e6e1cdf..1bb6a4e 100644 --- a/mtxdivbyzeroexception.h +++ b/mtxdivbyzeroexception.h @@ -25,6 +25,12 @@ #define MTX_DIVBYZERO_EXCEPTION_MESSAGE "division by zero" +/** + * Division by zero exception class. + * + * This class exists so that division by zero errors can be handled + * separately from other errors. + */ class MtxDivByZeroException: public MtxException { public: diff --git a/mtxentry.h b/mtxentry.h index ebe876a..1159933 100644 --- a/mtxentry.h +++ b/mtxentry.h @@ -27,11 +27,25 @@ #include "mtxhistory.h" #include "mtxlanguage.h" +/** + * GUI user input object. + */ class MtxEntry: public Gtk::Entry { private: + /** + * Pointer to the MtxLanguage object, used to get/set variables. + */ MtxLanguage *language; + + /** + * Pointer to the parent window. + */ MtxWindow *window; + + /** + * Object used to implement command line history. + */ MtxHistory history; protected: diff --git a/mtxexception.h b/mtxexception.h index f185404..03b8957 100644 --- a/mtxexception.h +++ b/mtxexception.h @@ -25,9 +25,15 @@ #define MTX_EXCEPTION_DEFAULT_MESSAGE "undefined mtx exception" +/** + * Base class for mtx exceptions. + */ class MtxException: public std::exception { protected: + /** + * Address of message returned by what(). + */ const char *message; public: diff --git a/mtxexpression.cc b/mtxexpression.cc index 10f2b1b..3c39ae2 100644 --- a/mtxexpression.cc +++ b/mtxexpression.cc @@ -33,10 +33,7 @@ using namespace std; /* - * Each line of the array indicates a level of precedence. Lines must - * be ordered in reverse order of precedence, e.g. = has low precedence, - * so it is placed in first line. Operators of same precedence must have - * the same associativity (this is never checked). + * See mtxexpression.h. */ struct mtx_operator MtxExpression::operators[][6] = { @@ -229,11 +226,9 @@ MtxExpression::MtxExpression(MtxLanguage *language, if (!((function == MTXEXPRESSION_FUNCTION_ADDITION || function == MTXEXPRESSION_FUNCTION_SUBTRACTION) && first_operand.empty())) - expressions.push_back(new MtxExpression(language, first_operand, - silent)); + expressions.push_back(new MtxExpression(language, first_operand)); - expressions.push_back(new MtxExpression(language, second_operand, - silent)); + expressions.push_back(new MtxExpression(language, second_operand)); } else if (lexical_elements[0] == "[" && lexical_elements.back() == "]") @@ -246,7 +241,7 @@ MtxExpression::MtxExpression(MtxLanguage *language, lexical_elements.erase(lexical_elements.begin()); lexical_elements.erase(lexical_elements.end() - 1); - parseMatrix(lexical_elements, symbols, rows, columns, silent); + parseMatrix(lexical_elements, symbols, rows, columns); rationals = new MtxRational[rows * columns]; i = 0; @@ -318,7 +313,7 @@ MtxExpression::freeMatrix(vector &symbols) const void MtxExpression::parseMatrix(const mtx_expression_t &lexical_elements, vector &symbols, - size_t &rows, size_t &columns, bool silent) const + size_t &rows, size_t &columns) const { mtx_expression_t::const_iterator iterator; size_t p_level, b_level, tmp_columns; @@ -365,7 +360,7 @@ MtxExpression::parseMatrix(const mtx_expression_t &lexical_elements, tmp_columns = 0; } - symbols.push_back(new MtxExpression(language, tmp, silent)); + symbols.push_back(new MtxExpression(language, tmp)); tmp.clear(); } @@ -400,7 +395,7 @@ MtxExpression::parseMatrix(const mtx_expression_t &lexical_elements, else if (tmp_columns != columns) MATRIX_DIMENSIONS_ERROR(symbols); - symbols.push_back(new MtxExpression(language, tmp, silent)); + symbols.push_back(new MtxExpression(language, tmp)); } if (symbols.size() != (rows * columns)) diff --git a/mtxexpression.h b/mtxexpression.h index 25eed22..16051b6 100644 --- a/mtxexpression.h +++ b/mtxexpression.h @@ -32,6 +32,10 @@ #define MTXEXPRESSION_OPERATOR_NULL \ {NULL, MTXEXPRESSION_FUNCTION_NULL, MTXEXPRESSION_ASSOCIATIVITY_NULL} +/** + * \enum mtx_function_id + * \brief ID of a function/operator (e.g. assignment, addition). + */ enum mtx_function_id { MTXEXPRESSION_FUNCTION_NULL, @@ -46,6 +50,10 @@ enum mtx_function_id MTXEXPRESSION_FUNCTION_DIVIDE_ASSIGN }; +/** + * \enum mtx_operator_associativity + * \brief Associativity of an operator. + */ enum mtx_operator_associativity { MTXEXPRESSION_ASSOCIATIVITY_NULL, @@ -53,46 +61,153 @@ enum mtx_operator_associativity MTXEXPRESSION_LEFT_TO_RIGHT }; +/** + * An operator. + */ struct mtx_operator { + /** + * Operator string as entered by the user. + */ char *str; + + /** + * ID of the operator. + */ enum mtx_function_id id; + + /** + * Associativity of the operator. + */ enum mtx_operator_associativity associativity; }; +/** + * An expression. + * + * All language expressions that are not atomic symbols (e.g. "a" or "2") + * are expressions which consist of a function/operator and one or more + * arguments. These arguments are in turn MtxExpression or MtxSymbol + * objects. MtxExpression objects are always nodes in the tree of symbols, + * whereas MtxSymbol objects are always leaves. + */ class MtxExpression: public MtxSymbol { private: + /** + * Function/operator compiled in this expression. + */ enum mtx_function_id function; + + /** + * Vector of arguments. + */ std::vector expressions; + + /** + * True if silent. + * + * A silent expression is an expression ended with the ';' character. + * Engine users should not display silent expressions. This property + * is propagated to underlying expressions and symbols. + * + * @see isSilent() + */ bool silent; + /** + * Find an operator in the vector of lexical elements. + * + * This method uses the \a operators array to look for operators by + * order of precedence. + * + * @param lexical_elements vector of strings in which to look for an + * operator + * @param str operator string as entered by the user to look for + * @see operators + * @see rfindOperator() + */ mtx_expression_t::iterator findOperator(mtx_expression_t &lexical_elements, const char *str); + + /** + * Find an operator in the vector of lexical elements in reverse order. + * + * @see findOperator(). + */ mtx_expression_t::reverse_iterator rfindOperator(mtx_expression_t &lexical_elements, const char *str); + + /** + * Free the pointers stored in the given vector of symbols. + * + * Mainly used after parsing a matrix is done or failed. + */ void freeMatrix(std::vector &symbols) const; + + /** + * Parse the given lexical elements and extract symbols and expressions + * from it to create the list of elements that will be used to create a + * matrix. An exception is thrown if the syntax doesn't comply with + * the matrix creation syntax. + * + * @param lexical_elements vector of strings to parse + * @param symbols vector of symbols/expressions updated by this method + * @param rows number of rows found + * @param columns number of columns found + */ void parseMatrix(const mtx_expression_t &lexical_elements, std::vector &symbols, - size_t &rows, size_t &columns, bool silent) const; + size_t &rows, size_t &columns) const; - /* + /** + * Multidimensional array of supported operators. + * + * Each line of the array indicates a level of precedence. Lines must + * be ordered in reverse order of precedence, e.g. = has low precedence, + * so it is placed in first line. Operators of same precedence must have + * the same associativity (this is never checked). + * * XXX There are at most 5 operators for the same precedence (+ a null - * entry to indicate end of list). + * entry to indicate end of list), so the second dimension is 6. */ static struct mtx_operator operators[][6]; + + /** + * Return true if the given string matches an operator. + */ static bool isOperator(const std::string &str); public: + /** + * Create an expression from a set of lexical elements. + * + * @param language address of the MtxLanguage object used to get/set + * variables + * @param lexical_elements vector of lexical elements + * @param silent see silent + * @see silent + */ MtxExpression(MtxLanguage *language, mtx_expression_t &lexical_elements, - bool silent); + bool silent = false); + virtual ~MtxExpression(); virtual MtxSymbol getSymbol(bool create = false, bool fail_if_special = true) const; virtual std::string getName() const; virtual MtxValue * getValue() const; virtual std::string toString() const; + + /** + * Return the silent member. + * + * As MtxExpression objects are always nodes, and there is always a node + * on top of a leaf, it is not necessary to propagate the silent property + * to underlying objects. When the engine calls isSilent(), it always get + * a return value from the first node it is calling the function on. + * That's why MtxSymbol objects don't have a silent property. + */ virtual bool isSilent() const; }; diff --git a/mtxhistory.h b/mtxhistory.h index e3d3abc..ee2e2d7 100644 --- a/mtxhistory.h +++ b/mtxhistory.h @@ -24,17 +24,56 @@ #include #include +/** + * Object implementing history support. + * + * Mainly used for command line history. + */ class MtxHistory { private: + /** + * Vector of strings handled. + */ std::vector strings; + + /** + * Iterator pointing to the current string. + */ std::vector::iterator offset; public: + /** + * Default constructor. + */ MtxHistory(); + + /** + * Add a string at the end of the vector of strings. + * + * The offset is automatically set to this string. + */ void addString(const std::string &string); + + /** + * Return string at current offset. + * + * Return an empty string if offset points at the end of the vector. + */ std::string getString() const; + + /** + * Decrement offset. + * + * If offset is already set to the first string, nothing is done. + */ void previousString(); + + /** + * Increment offset. + * + * If offset is already set to the end of the vector, nothing is done. + */ void nextString(); }; diff --git a/mtxlanguage.cc b/mtxlanguage.cc index fbaf6b8..623db7c 100644 --- a/mtxlanguage.cc +++ b/mtxlanguage.cc @@ -201,7 +201,7 @@ MtxLanguage::parseExpressions(const mtx_expression_t &lexical_elements) if (!tmp.empty()) { if (*iterator == ",") - expressions.push_back(new MtxExpression(this, tmp, false)); + expressions.push_back(new MtxExpression(this, tmp)); else if (*iterator == ";") expressions.push_back(new MtxExpression(this, tmp, true)); @@ -245,7 +245,7 @@ MtxLanguage::parseExpressions(const mtx_expression_t &lexical_elements) throw MtxException("syntax error, missing ]"); if (!tmp.empty()) - expressions.push_back(new MtxExpression(this, tmp, false)); + expressions.push_back(new MtxExpression(this, tmp)); return expressions; } diff --git a/mtxlanguage.h b/mtxlanguage.h index 78eebf0..d95b20a 100644 --- a/mtxlanguage.h +++ b/mtxlanguage.h @@ -27,57 +27,116 @@ #include "mtx.h" #include "mtxsymbol.h" +/** + * \def MTXLANGUAGE_VALUES_INDEX + * \brief Index of the lexical group of values in lexical groups array. + */ #define MTXLANGUAGE_VALUES_INDEX 0 + +/** + * \def MTXLANGUAGE_OPERATORS_INDEX + * \brief Index of the lexical group of operators in lexical groups array. + */ #define MTXLANGUAGE_OPERATORS_INDEX 1 + +/** + * \def MTXLANGUAGE_OPERATORS_MAX_LENGTH + * \brief Maximum length of the string representation of an operator. + */ #define MTXLANGUAGE_OPERATORS_MAX_LENGTH 2 + +/** + * \def MTXLANGUAGE_ANS_VARIABLE + * \brief name of the automatic variable \a ans + */ #define MTXLANGUAGE_ANS_VARIABLE "ans" +/** + * Main language object used as interface between user and engine. + */ class MtxLanguage { private: + /** + * Vector of known variables. + * + * @see getSymbols() + */ std::vector symbols; - /* - * Return the lexical group of the character, or throw an exception if - * the character isn't registered. + /** + * Return the lexical group of the given character. + * + * Throw an exception if the character isn't registered. */ size_t findGroup(char c) const; - /* + /** + * Check a lexical element. + * * Throw an exception if the lexical element is invalid. */ void checkLexicalElement(const std::string &lexical_element) const; - /* + /** + * Lexical analysis. + * * Return a vector of the lexical elements of the given expression. An * exception is thrown if an invalid character is present. */ mtx_expression_t parseLexicalElements(const std::string &expression) const; - /* + /** + * Compile a set of lexical elements into expressions. + * * Parse the given lexical elements and compile them in a vector of - * expressions. An exception is thrown if an error occurs. + * expressions. An MtxException exception is thrown if an error occurs. */ std::vector parseExpressions(const mtx_expression_t &lexical_elements); - /* + /** * Release the memory referenced by the pointers in the given vector. */ void freeExpressions(std::vector &expressions); - /* - * Array of groups of lexical elements, e.g. + and = are in the same + /** + * Array of groups of lexical elements. E.g. + and = are in the same * group. */ static char *lexical_groups[]; - static size_t operators_index; public: + /** + * Default constructor. + */ MtxLanguage(); + + /** + * Parse the given expression into a set of results. + * + * This is the main interface between the user and the engine. + * The caller should catch MtxException exceptions. + */ std::vector parse(const std::string &expression); + + /** + * Set a named variable. + */ void setSymbol(const MtxSymbol &symbol); + + /** + * Get a variable from its name. + */ MtxSymbol getSymbol(const std::string &name) const; + + /** + * Return a copy of the vector of symbols. + * + * Mainly used to list all registered variables. + * + * @see symbols. + */ std::vector getSymbols() const; }; diff --git a/mtxmatrix.cc b/mtxmatrix.cc index 32e6bef..ab23d69 100644 --- a/mtxmatrix.cc +++ b/mtxmatrix.cc @@ -431,7 +431,7 @@ MtxMatrix::l_inverted() const new_matrix = getIdentityMatrix(rows); /* - * Skip first line as we're working on a unit lower matrix. + * Skip first line as we're working on a unit lower triangular matrix. */ for (i = 1; i < rows; i++) for (j = 0; j < i; j++) diff --git a/mtxmatrix.h b/mtxmatrix.h index 8f70bb2..e2f8c10 100644 --- a/mtxmatrix.h +++ b/mtxmatrix.h @@ -27,30 +27,157 @@ #include "mtxvalue.h" #include "mtxrational.h" +/** + * A matrix. + * + * This class allows to create matrices which consist of an array of + * MtxRational objects, the number of rows, the number of columns, and + * the length of the array which is rows * columns. + */ class MtxMatrix: public MtxValue { private: + /** + * Array of rationals. + */ MtxRational *rationals; + + /** + * The length of the array of rationals. + * + * It is maintained internally to avoid computing rows * columns. + * + * @see getLength() + */ size_t length; + + /** + * Number of rows. + * + * @see getRows() + */ size_t rows; + + /** + * Number of columns. + * + * @see getColumns() + */ size_t columns; + /** + * Throw an MtxException exception if the rows of the current matrix and + * the rows of the given matrix differ. + * + * This check if performed mainly before augmenting matrices. + * + * @see checkDimensions() + */ void checkRows(const MtxMatrix &matrix) const; + + /** + * Check that both dimensions of the current matrix and the given matrix + * match. + * + * A MtxException exception is thrown if one of the dimensions differ. + * Mainly used for addition like operations. + * + * @see checkRows() + */ void checkDimensions(const MtxMatrix &matrix) const; + + /** + * Check compatibility of the current matrix with the given matrix. + * + * Two matrices are compatible if the number of columns of the first + * is equal to the number of rows of the second. If matrices are not + * compatible, an MtxException exception is raised. Mainly used for + * matrix multiplication. + */ void checkCompatibility(const MtxMatrix &matrix) const; + + /** + * Check that the current matrix is a square matrix. + * + * Throw an MtxException exception if the number of rows differs from + * the number of columns. Mainly used for LU decomposition. + */ void checkSquare() const; + + /** + * Add two rows. + * + * @param dst_row the index of the row which is updated + * @param src_row the index of the row which is added to dst_row + * @param rational a coefficient which is applied to each element of + * src_row before addition + */ void addRows(size_t dst_row, size_t src_row, const MtxRational &rational); + + /** + * Subtract two rows. + * + * @param dst_row the index of the row which is updated + * @param src_row the index of the row which is subtracted from dst_row + * @param rational a coefficient which is applied to each element of + * src_row before subtraction + */ void subtractRows(size_t dst_row, size_t src_row, const MtxRational &rational); + + /** + * Multiply a row by a rational. + * + * @param row the index of the row which is updated + * @param rational a coefficient which is applied to each element of + * row + */ void multiplyRow(size_t row, const MtxRational &rational); + + /** + * Divide a row by a rational. + * + * @param row the index of the row which is updated + * @param rational a coefficient which inverse is applied to each element + * of row + */ void divideRow(size_t row, const MtxRational &rational); + + /** + * Switch two rows. + * + * @param r1 the index of the first row + * @param r2 the index of the second row + */ void switchRows(size_t r1, size_t r2); + + /** + * Inverse the current matrix if this matrix is a unit lower triangular + * matrix. + * + * Used for inversion of matrices. + */ MtxMatrix l_inverted() const; + + /** + * Inverse the current matrix if this matrix is an upper triangular matrix. + * + * Used for inversion of matrices. + */ MtxMatrix u_inverted() const; public: + /** + * Default constructor. + */ MtxMatrix(); + + /** + * Create a matrix from an array of rationals, the number of rows and the + * number of columns. The caller must ensure coherent values are passed. + */ MtxMatrix(MtxRational *rationals, size_t rows, size_t columns); + MtxMatrix(const MtxMatrix &matrix); virtual ~MtxMatrix(); @@ -59,6 +186,14 @@ class MtxMatrix: public MtxValue /* * Some operators are available for easiness. */ + + /** + * Return the address of the line at requested index. + * + * NULL is returned if index is invalid. Usage example : + * MtxRational r; + * r = matrix[1][2]; + */ MtxRational * operator[](size_t index) const; MtxMatrix operator+() const; MtxMatrix operator-() const; @@ -80,36 +215,118 @@ class MtxMatrix: public MtxValue friend std::ostream & operator<<(std::ostream &cout, const MtxMatrix &matrix); + /** + * Return length. + * + * @see length + */ size_t getLength() const; + + /** + * Return number of rows. + * + * @see rows + */ size_t getRows() const; + + /** + * Return number of columns. + * + * @see columns + */ size_t getColumns() const; + + /** + * Normalize each rational of the matrix. + */ MtxMatrix & normalize(); + + /** + * Return the transpose of the matrix. + */ MtxMatrix transpose() const; + + /** + * Return the current matrix augmented with the given matrix. + */ MtxMatrix augmented(const MtxMatrix &matrix) const; + + /** + * Apply an LU decomposition. + * + * @param L set to the unit lower triangular matrix + * @param U set to the upper triangular matrix + */ void luDecomposition(MtxMatrix &L, MtxMatrix &U) const; + + /** + * Return the determinant. + */ MtxRational determinant() const; + + /** + * Return the inverted matrix. + */ MtxMatrix inverted() const; - /* - * Return a string representation of the matrix, in which values are - * aligned, seperated by white spaces, and framed with [()] characters. + /** + * Return a string representation of the matrix. + * + * If float_string is true, matrix elements are returned in floating + * point representation, otherwise, they are returned in fractional + * representation. + * + * @param float_string control rendering of the matrix elements + * @see toString() + * @see toFloatString() */ std::string toString(bool float_string) const; + + /** + * Return a string representation of the matrix. + * + * Similar to toString(false). + * + * @see toString(bool float_string) const + * @see toFloatString() + */ virtual std::string toString() const; + + /** + * Return a string representation of the matrix. + * + * Similar to toString(true). + * + * @see toString(bool float_string) const + * @see toString() + */ std::string toFloatString() const; /* * See mtxvalue.h. */ MTXVALUE_CLONE_METHOD_DECLARATION(MtxMatrix); - virtual MtxValue * add(const MtxValue *value) const; virtual MtxValue * subtract(const MtxValue *value) const; virtual MtxValue * multiply(const MtxValue *value) const; virtual MtxValue * divide(const MtxValue *value) const; virtual MtxValue * opposite() const; + /** + * Return a zero matrix. + * + * @param rows number of rows of the zero matrix + * @param columns number of columns of the zero matrix + */ static MtxMatrix getZeroMatrix(size_t rows, size_t columns); + + /** + * Return an identity matrix. + * + * Note that an identity matrix is a square matrix. + * + * @param n dimension of identity matrix + */ static MtxMatrix getIdentityMatrix(size_t n); }; diff --git a/mtxsingularmatrixexception.h b/mtxsingularmatrixexception.h index 64cf003..bc9df63 100644 --- a/mtxsingularmatrixexception.h +++ b/mtxsingularmatrixexception.h @@ -25,6 +25,12 @@ #define MTX_SINGULARMATRIX_EXCEPTION_MESSAGE "matrix is singular" +/** + * Singular matrix exception class. + * + * This class exists so that singular matrix errors can be handled + * separately from other errors. + */ class MtxSingularMatrixException: public MtxException { public: diff --git a/mtxsymbol.h b/mtxsymbol.h index 3178377..ab54b5e 100644 --- a/mtxsymbol.h +++ b/mtxsymbol.h @@ -28,61 +28,175 @@ #include "mtxvalue.h" #include "mtxlanguage.h" +/** + * A structure representing a special name. + * + * Special names are e.g. "about" or "exit". They have a special meaning + * and are associated to a function. They should never be used as variable + * names or normal function names. + */ struct mtx_special_name { + /** + * The special name. + */ char *name; + + /** + * Pointer to a function implementing the action associated to the special + * name. + */ std::string (*function)(const MtxSymbol *); }; +/** + * A symbol. + * + * Symbols are named or temporary values in the language engine. + * E.g. in the expression "a + 2", both \a a and \a 2 are symbols. + */ class MtxSymbol { private: + /** + * Name of the symbol. An unnamed symbol is considered temporary. + */ std::string name; + + /** + * The value associated to the symbol. + */ MtxValue *value; + + /** + * If true, the symbol is special. I.e. it is created from a special name. + * When a special symbol is returned by the engine, the engine user should + * not display the "name = " string that usually prefixes the string + * representation of the value, so that the output of the commands + * associated to special names is unaltered when displayed. + * + * @see setSpecial() + * @see isSpecial() + */ bool special; - /* - * Set the member named special according to the value of the symbol name. + /** + * Set the special member according to the name of the symbol. + * + * @see special + * @see isSpecial() */ void setSpecial(); - /* + /** * Return the index of the struct special_name entry which name matches - * the symbol name. + * the symbol name. The special member must be true, or this method will + * raise an MtxException exception. */ size_t getSpecial() const; - /* + /** * List of special names and function pointers associated to them. - * Don't call it if special is false. */ static struct mtx_special_name special_names[]; protected: - /* - * This is the address of the MtxLanguage object used to retreive - * global symbols. The copy constructor and operator = must not - * duplicate the content of this pointer. + /** + * Address of the MtxLanguage object used to retreive global symbols. + * + * The copy constructor and operator = must not duplicate the content + * of this pointer. */ MtxLanguage *language; public: + /** + * Default constructor. + * + * A symbol created with this constructor is unusable, as it doesn't + * have any link to an MtxLanguage object. The language object is needed + * to get and set named symbols from the global variable namespace of the + * language engine. + */ MtxSymbol(); + + /** + * Create a named variable. + * + * The value doesn't always need to be stored in the object itself, as + * it will be retreived from the MtxLanguage object. + */ MtxSymbol(MtxLanguage *language, const std::string &name); + + /** + * Create a temporary object. + */ MtxSymbol(MtxLanguage *language, const MtxValue &value); + + /** + * Create a named symbol with a value. + */ MtxSymbol(MtxLanguage *language, const std::string &name, const MtxValue &value); + MtxSymbol(const MtxSymbol &symbol); virtual ~MtxSymbol(); + MtxSymbol & operator=(const MtxSymbol &symbol); + + /** + * Return a copy of the symbol. + * + * This method is actually where execution takes place. + * + * @param create if the symbol is a nonexistent named variable, create it + * @param fail_if_special if the symbol is special, raise an exception + */ virtual MtxSymbol getSymbol(bool create = false, bool fail_if_special = true) const; + + /** + * Return the name of the symbol. + */ virtual std::string getName() const; + + /** + * Set the name of the symbol. The symbol becomes a named variable if it + * was unnamed. It will be registered in the MtxLanguage object when + * getSymbol() is called. + */ void setName(const std::string &name); + + /** + * Return the address of the underlying value associated to the symbol. + * + * This address can be NULL if no value was associated. + */ virtual MtxValue * getValue() const; + + /** + * Return the string representation of the underlying value. + */ virtual std::string toString() const; + + /** + * This method should never be used on a MtxSymbol object. + * + * @see MtxExpression + */ virtual bool isSilent() const; + + /** + * Return the special member. + * + * @see special + * @see setSpecial() + */ bool isSpecial() const; + + /** + * Return the address of the associated MtxLanguage object. + */ MtxLanguage * getLanguage() const; }; diff --git a/mtxvalue.h b/mtxvalue.h index e5b3e8a..a4e297d 100644 --- a/mtxvalue.h +++ b/mtxvalue.h @@ -23,12 +23,16 @@ #include -/* - * These two macros allow easy implementation of the clone() method of - * derived classes. +/** + * \def MTXVALUE_CLONE_METHOD_DECLARATION + * \brief Allows easy decleration of clone() method in derived classes. */ #define MTXVALUE_CLONE_METHOD_DECLARATION(type) virtual type * clone() const +/** + * \def MTXVALUE_CLONE_METHOD + * \brief Allows easy implementation of clone() method in derived classes. + */ #define MTXVALUE_CLONE_METHOD(type) \ type * \ type::clone() const \ @@ -39,21 +43,52 @@ type::clone() const \ return new_object; \ } +/** + * Abstract class for values used by the engine. + */ class MtxValue { public: virtual ~MtxValue(); + + /** + * Return a string representation of the value. + */ virtual std::string toString() const = 0; - /* - * Create a copy of the derived object and return its address. + /** + * Create a copy of the object and return its address. */ virtual MtxValue * clone() const = 0; + /** + * Add the current value with the given value and return the address of + * the result. This result must be deleted by the caller. + */ virtual MtxValue * add(const MtxValue *value) const = 0; + + /** + * Subtract the given value from the current value and return the address + * of the result. This result must be deleted by the caller. + */ virtual MtxValue * subtract(const MtxValue *value) const = 0; + + /** + * Multiply the current value by the given value and return the address + * of the result. This result must be deleted by the caller. + */ virtual MtxValue * multiply(const MtxValue *value) const = 0; + + /** + * Divide the current value by the given value and return the address + * of the result. This result must be deleted by the caller. + */ virtual MtxValue * divide(const MtxValue *value) const = 0; + + /** + * Return a pointer to the opposite of the value. + * This pointer must be deleted by the caller. + */ virtual MtxValue * opposite() const = 0; }; diff --git a/mtxwindow.h b/mtxwindow.h index 1dcb8f1..b689f41 100644 --- a/mtxwindow.h +++ b/mtxwindow.h @@ -30,6 +30,9 @@ #define MTXWINDOW_PROMPT ">> " +/** + * Main GUI object. + */ class MtxWindow: public Gtk::Window { private: @@ -41,7 +44,15 @@ class MtxWindow: public Gtk::Window Glib::RefPtr buffer; Glib::RefPtr tag; Glib::RefPtr mark; + + /** + * Single line input box, used to get commands from user. + */ MtxEntry entry; + + /** + * Pointer to the MtxLanguage object, used to get/set variables. + */ MtxLanguage *language; void on_menu_help_about(); @@ -49,6 +60,10 @@ class MtxWindow: public Gtk::Window public: MtxWindow(MtxLanguage *language); virtual ~MtxWindow(); + + /** + * Add the given text to the text view of the window. + */ void addText(const std::string &text); }; -- cgit v1.2.3