From 09925b567cf007332680db379ca64dafaaa28731 Mon Sep 17 00:00:00 2001 From: Chris Cromer Date: Mon, 20 Feb 2023 22:01:14 -0300 Subject: [PATCH] finish up comments --- src/ast/ast.h | 19 +++ src/ast/call_expression_ast.h | 46 +++++++ src/ast/error.h | 17 ++- src/ast/expression_ast.h | 16 ++- src/ast/function_ast.h | 35 ++++++ src/ast/number_expression_ast.h | 29 +++++ src/ast/prototype_ast.h | 47 ++++++- src/ast/variable_expression_ast.h | 32 ++++- src/lexer.h | 21 ++-- src/lib/include/obelisk.h | 6 +- src/lib/knowledge_base.h | 69 +++++----- src/lib/models/action.h | 9 +- src/lib/models/entity.h | 9 +- src/lib/models/error.h | 12 +- src/lib/models/fact.h | 24 ++-- src/lib/models/rule.h | 3 +- src/lib/models/suggest_action.h | 6 +- src/lib/models/verb.h | 3 +- src/main.h | 4 +- src/parser.h | 202 ++++++++++++++++++++++++++++-- 20 files changed, 492 insertions(+), 117 deletions(-) diff --git a/src/ast/ast.h b/src/ast/ast.h index 1002ace..94c0549 100644 --- a/src/ast/ast.h +++ b/src/ast/ast.h @@ -11,9 +11,28 @@ namespace obelisk { + /** + * @brief The LLVM context. + * + */ static std::unique_ptr TheContext; + + /** + * @brief The LLVM module. + * + */ static std::unique_ptr TheModule; + + /** + * @brief The LLVM IR builder. + * + */ static std::unique_ptr> Builder; + + /** + * @brief The LLVM named values. + * + */ static std::map NamedValues; } // namespace obelisk diff --git a/src/ast/call_expression_ast.h b/src/ast/call_expression_ast.h index 464a574..4913bd9 100644 --- a/src/ast/call_expression_ast.h +++ b/src/ast/call_expression_ast.h @@ -9,25 +9,71 @@ namespace obelisk { + /** + * @brief The call AST expression node used to call functions. + * + */ class CallExpressionAST : public ExpressionAST { private: + /** + * @brief The function being called. + * + */ std::string callee_; + + /** + * @brief The arguments passed to the function. + * + */ std::vector> args_; + /** + * @brief Get the callee. + * + * @return std::string Returns the name of the function being called. + */ std::string getCallee(); + + /** + * @brief Set the callee. + * + * @param[in] callee The name of the function. + */ void setCallee(std::string callee); + /** + * @brief Get the arguments being used by the function. + * + * @return std::vector> Returns an AST expression containing the args. + */ std::vector> getArgs(); + + /** + * @brief Set the arguments to be used by the function. + * + * @param[in] args The args to set. + */ void setArgs(std::vector> args); public: + /** + * @brief Construct a new CallExpressionAST object. + * + * @param[in] callee The function to call. + * @param[in] args The args to pass into the function. + */ CallExpressionAST(const std::string &callee, std::vector> args) : callee_(callee), args_(std::move(args)) { } + /** + * @brief Generate the calle IR code. + * + * @return llvm::Value* + */ llvm::Value *codegen() override; }; } // namespace obelisk diff --git a/src/ast/error.h b/src/ast/error.h index 1770f7f..dd990dc 100644 --- a/src/ast/error.h +++ b/src/ast/error.h @@ -7,8 +7,21 @@ namespace obelisk { - std::unique_ptr LogError(const char *Str); - llvm::Value *LogErrorV(const char *Str); + /** + * @brief Log an AST expression error. + * + * @param[in] str The error message. + * @return std::unique_ptr Returns the AST expression that caused the error. + */ + std::unique_ptr LogError(const char *str); + + /** + * @brief Log an AST value error. + * + * @param[in] str The error message. + * @return llvm::Value* Returns the AST value that caused the error. + */ + llvm::Value *LogErrorV(const char *str); } // namespace obelisk #endif diff --git a/src/ast/expression_ast.h b/src/ast/expression_ast.h index a77fff7..c1201a8 100644 --- a/src/ast/expression_ast.h +++ b/src/ast/expression_ast.h @@ -5,10 +5,24 @@ namespace obelisk { + /** + * @brief A generic AST expression which other expression will inherit from. + * + */ class ExpressionAST { public: - virtual ~ExpressionAST() = default; + /** + * @brief Destroy the ExpressionAST object. + * + */ + virtual ~ExpressionAST() = default; + + /** + * @brief Generate LLVM IR code based on the AST expression. + * + * @return llvm::Value* Returns the LLVM code value from the expression. + */ virtual llvm::Value *codegen() = 0; }; } // namespace obelisk diff --git a/src/ast/function_ast.h b/src/ast/function_ast.h index d9f433f..d4e28b1 100644 --- a/src/ast/function_ast.h +++ b/src/ast/function_ast.h @@ -8,22 +8,57 @@ namespace obelisk { + /** + * @brief A Funcion AST node. + * + */ class FunctionAST { private: + /** + * @brief The prototype of the function. + * + */ std::unique_ptr prototype_; + + /** + * @brief The body of the function. + * + */ std::unique_ptr body_; + /** + * @brief Get the prototype. + * + * @return std::unique_ptr Returns the prototype AST. + */ std::unique_ptr getPrototype(); + + /** + * @brief Set the prototype. + * + * @param[in] prototype Set the prototype. + */ void setPrototype(std::unique_ptr prototype); public: + /** + * @brief Construct a new FunctionAST object. + * + * @param[in] prototype The prototype of the function. + * @param[in] body The body of the function. + */ FunctionAST(std::unique_ptr prototype, std::unique_ptr body) : prototype_(std::move(prototype)), body_(std::move(body)) { } + /** + * @brief Generate LLVM IR code. + * + * @return llvm::Function* Returns the LLVM IR function code. + */ llvm::Function *codegen(); }; } // namespace obelisk diff --git a/src/ast/number_expression_ast.h b/src/ast/number_expression_ast.h index 874cb79..9ad9291 100644 --- a/src/ast/number_expression_ast.h +++ b/src/ast/number_expression_ast.h @@ -5,20 +5,49 @@ namespace obelisk { + /** + * @brief A number expression AST node. + * + */ class NumberExpressionAST : public ExpressionAST { private: + /** + * @brief The number. + * + */ double number_; + /** + * @brief Get the number. + * + * @return double Returns the number. + */ double getNumber(); + + /** + * @brief Set the number. + * + * @param[in] number The number. + */ void setNumber(double number); public: + /** + * @brief Construct a new NumberExpressionAST object. + * + * @param[in] number The number. + */ NumberExpressionAST(double number) : number_(number) { } + /** + * @brief Generate LLVM IR code for the number. + * + * @return llvm::Value* Returns the genrated IR code. + */ llvm::Value *codegen() override; }; } // namespace obelisk diff --git a/src/ast/prototype_ast.h b/src/ast/prototype_ast.h index f8f22a1..2df8225 100644 --- a/src/ast/prototype_ast.h +++ b/src/ast/prototype_ast.h @@ -8,30 +8,75 @@ namespace obelisk { + /** + * @brief The prototype AST node. + * + */ class PrototypeAST { private: + /** + * @brief The name of the prototype. + * + */ std::string name_; + /** + * @brief The arguments the protype accepts. + * + */ std::vector args_; + /** + * @brief Set the name of the prototype. + * + * @param[in] name The name. + */ void setName(const std::string& name); + + /** + * @brief Get the arguments the prototype accepts. + * + * @return std::vector Returns the arguments. + */ std::vector getArgs(); + + /** + * @brief Set the arguments the prototype accepts. + * + * @param[in] args The arguments. + */ void setArgs(std::vector args); public: + /** + * @brief Construct a new PrototypeAST object. + * + * @param[in] name The name of the prototype. + * @param[in] args The arguments the prototype accepts. + */ PrototypeAST(const std::string& name, std::vector args) : name_(name), args_(std::move(args)) { } + /** + * @brief Get the name of the prototype. + * + * @return const std::string& Returns the name of the prototype. + */ const std::string& getName() const { return name_; } + /** + * @brief Generate LLVM IR code for the prototype. + * + * @return llvm::Function* Returns IR code for the prototype. + */ llvm::Function* codegen(); }; -} //namespace obelisk +} // namespace obelisk #endif diff --git a/src/ast/variable_expression_ast.h b/src/ast/variable_expression_ast.h index 3b51f87..f6ba2b0 100644 --- a/src/ast/variable_expression_ast.h +++ b/src/ast/variable_expression_ast.h @@ -7,21 +7,51 @@ namespace obelisk { + /** + * @brief The variable expression AST node. + * + */ class VariableExpressionAST : public ExpressionAST { private: + /** + * @brief The name of the variable. + * + */ std::string name_; + + /** + * @brief Get the name of the variable. + * + * @return std::string Returns the name of the variable. + */ std::string getName(); + + /** + * @brief Set the name of the variable. + * + * @param[in] name The name of the variable. + */ void setName(const std::string name); public: + /** + * @brief Construct a new VariableExpressionAST object. + * + * @param[in] name The name of the variable. + */ VariableExpressionAST(const std::string &name) : name_(name) { } + /** + * @brief Generate the variable LLVM IR code. + * + * @return llvm::Value* Returns the generated IR code. + */ llvm::Value *codegen() override; }; -} //namespace obelisk +} // namespace obelisk #endif diff --git a/src/lexer.h b/src/lexer.h index 4562611..30741ca 100644 --- a/src/lexer.h +++ b/src/lexer.h @@ -56,22 +56,19 @@ namespace obelisk /** * @brief Comment the rest of the line. * - * @param[in] lastChar The char to check to see if it in the end of - * the line. + * @param[in] lastChar The char to check to see if it in the end of the line. */ void commentLine(int* lastChar); public: /** - * @brief These token represent recognized language keywords and - * language functionality. + * @brief These token represent recognized language keywords and language functionality. * */ enum Token { /** - * @brief End of file is returned when the source code is - * finished. + * @brief End of file is returned when the source code is finished. * */ kTokenEof = -1, @@ -82,8 +79,7 @@ namespace obelisk */ kTokenFact = -2, /** - * @brief A rule which is a relationship between a new fact a - * existing fact. + * @brief A rule which is a relationship between a new fact a existing fact. * */ kTokenRule = -3, @@ -137,16 +133,14 @@ namespace obelisk * @brief Gets the next token in the source code. * * @throws LexerException when an invalid token is found. - * @return int Returns a Token value or char if no known token was - * found. + * @return int Returns a Token value or char if no known token was found. */ int getToken(); /** * @brief Get the last identifier. * - * @return const std::string& Returns a string that contains the - * last found identifier. + * @return const std::string& Returns a string that contains the last found identifier. */ const std::string& getIdentifier(); @@ -194,8 +188,7 @@ namespace obelisk /** * @brief Return the exception's error message. * - * @return const char* Returns a string containing the error - * message. + * @return const char* Returns a string containing the error message. */ const char* what() const noexcept { diff --git a/src/lib/include/obelisk.h b/src/lib/include/obelisk.h index f379303..a73dc4c 100644 --- a/src/lib/include/obelisk.h +++ b/src/lib/include/obelisk.h @@ -1,15 +1,13 @@ #include /** - * @brief The obelisk namespace contains everything needed to compile obelisk. - * code. + * @brief The obelisk namespace contains everything needed to compile obelisk code. * */ namespace obelisk { /** - * @brief The obelisk library provides everything needed to consult the - * KnowledgeBase. + * @brief The obelisk library provides everything needed to consult the KnowledgeBase. * */ class Obelisk diff --git a/src/lib/knowledge_base.h b/src/lib/knowledge_base.h index ac463d2..b9a3368 100644 --- a/src/lib/knowledge_base.h +++ b/src/lib/knowledge_base.h @@ -18,8 +18,7 @@ namespace obelisk { /** - * @brief The KnowledgeBase class represents a collection of facts, rules, - * actions, and related language connectors. + * @brief The KnowledgeBase class represents a collection of facts, rules, actions, and related language connectors. * */ class KnowledgeBase @@ -46,8 +45,8 @@ namespace obelisk /** * @brief Enable foreign key functionality in the open database. * - * This must always be done when the connection is opened or it will - * not enforce the foreign key constraints. + * This must always be done when the connection is opened or it will not enforce the foreign key + * constraints. */ void enableForeignKeys(); @@ -62,8 +61,7 @@ namespace obelisk /** * @brief Construct a new KnowledgeBase object. * - * @param[in] filename The name of the file to save the knowledge - * base as. + * @param[in] filename The name of the file to save the knowledge base as. * @param[in] flags The flags to open the KnowledgeBase with. */ KnowledgeBase(const char* filename, int flags); @@ -71,8 +69,7 @@ namespace obelisk /** * @brief Construct a new KnowledgeBase object. * - * @param[in] filename The name of the file to save the knowledge - * base as. + * @param[in] filename The name of the file to save the knowledge base as. */ KnowledgeBase(const char* filename) : KnowledgeBase(filename, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE) @@ -89,103 +86,96 @@ namespace obelisk /** * @brief Add entities to the KnowledgeBase. * - * @param[in,out] entities The entities to add. If the insert is - * successful it will have a row ID, if not the ID will be 0. + * @param[in,out] entities The entities to add. If the insert is successful it will have a row ID, if not + * the ID will be 0. */ void addEntities(std::vector& entities); /** * @brief Add verbs to the KnowledgeBase. * - * @param[in,out] verbs The verbs to add. If the insert is - * successful it will have a row ID, if not the ID will be 0. + * @param[in,out] verbs The verbs to add. If the insert is successful it will have a row ID, if not the ID + * will be 0. */ void addVerbs(std::vector& verbs); /** * @brief Add actions to the KnowledgeBase. * - * @param[in,out] actions The actions to add. If the insert is - * successful it will have a row ID, if nto the ID will be 0. + * @param[in,out] actions The actions to add. If the insert is successful it will have a row ID, if nto the + * ID will be 0. */ void addActions(std::vector& actions); /** * @brief Add facts to the KnowledgeBase. * - * @param[in,out] facts The facts to add. If the insert is - * successful it will have a row ID, if not the ID will be 0. + * @param[in,out] facts The facts to add. If the insert is successful it will have a row ID, if not the ID + * will be 0. */ void addFacts(std::vector& facts); /** * @brief Add suggested actions to the KnowledgeBase. * - * @param[in,out] suggestActions The suggested actions to add. If - * the insert is successful it will have a row ID, if not the ID - * will be 0. + * @param[in,out] suggestActions The suggested actions to add. If the insert is successful it will have a + * row ID, if not the ID will be 0. */ void addSuggestActions(std::vector& suggestActions); /** * @brief Add rules to the KnowledgeBase. * - * @param[in,out] rules The rules to add. If the insert is successful it - * will have a row ID, if not the ID will be 0. + * @param[in,out] rules The rules to add. If the insert is successful it will have a row ID, if not the ID + * will be 0. */ void addRules(std::vector& rules); /** * @brief Get an Entity object based on the ID it contains. * - * @param[in,out] entity The Entity object should contain just the - * ID and the rest will be filled in. + * @param[in,out] entity The Entity object should contain just the ID and the rest will be filled in. */ void getEntity(obelisk::Entity& entity); /** * @brief Get a Verb object based on the ID it contains. * - * @param[in,out] verb The Verb object should contain just the ID - * and the rest will be filled in. + * @param[in,out] verb The Verb object should contain just the ID and the rest will be filled in. */ void getVerb(obelisk::Verb& verb); /** * @brief Get an Action based on the ID it contains. * - * @param[in] action The Action object should contain just the ID - * and the rest will be filled in. + * @param[in] action The Action object should contain just the ID and the rest will be filled in. */ void getAction(obelisk::Action& action); /** * @brief Get a Fact object based on the ID it contains. * - * @param[in,out] fact The Fact object should contain just the ID - * and the rest will be filled in. + * @param[in,out] fact The Fact object should contain just the ID and the rest will be filled in. */ void getFact(obelisk::Fact& fact); /** * @brief Get a SuggestAction based on the ID it contains. * - * @param[in,out] suggestAction The SuggestAction object should - * contain just the ID and the rest will be filled in. + * @param[in,out] suggestAction The SuggestAction object should contain just the ID and the rest will be + * filled in. */ void getSuggestAction(obelisk::SuggestAction& suggestAction); /** * @brief Get a Rule based on the ID it contains. * - * @param[in,out] rule The Rule object should contain just the ID - * and the rest will be filled in. + * @param[in,out] rule The Rule object should contain just the ID and the rest will be filled in. */ void getRule(obelisk::Rule& rule); /** - * @brief Check if a rule looks for this Fact, if so update its - * truth. + * @brief Check if a rule looks for this Fact, if so update its truth. * * @param[in,out] fact The Fact to check for existing rules. */ @@ -201,10 +191,8 @@ namespace obelisk /** * @brief Take a float and divide it into 2 floats. * - * This is useful to store doubles in SQLite since SQLite doesn't - * have a double type. - * Instead just store the 2 floats in the database. Then after - * selecting them combine them. + * This is useful to store doubles in SQLite since SQLite doesn't have a double type. Instead just store the + * 2 floats in the database. Then after selecting them combine them. * * @param[out] result1 The first float generated from the double. * @param[out] result2 The second float generated from the double. @@ -215,8 +203,7 @@ namespace obelisk /** * @brief Combines 2 separated floats back into a double. * - * This will recombine the separated floats from the getFloat - * method. + * This will recombine the separated floats from the getFloat method. * * @param[out] result The double generated from the combined floats. * @param[in] var1 The first float to combine. diff --git a/src/lib/models/action.h b/src/lib/models/action.h index 2d06c03..c45c536 100644 --- a/src/lib/models/action.h +++ b/src/lib/models/action.h @@ -8,8 +8,7 @@ namespace obelisk { /** - * @brief The Action model represents an action to take when a fact is true - * or false. + * @brief The Action model represents an action to take when a fact is true or false. * */ class Action @@ -108,16 +107,14 @@ namespace obelisk void setName(std::string name); /** - * @brief Select an Action from the datbase based on the object - * name. + * @brief Select an Action from the datbase based on the object name. * * @param[in] dbConnection The database connection to use. */ void selectByName(sqlite3* dbConnection); /** - * @brief Insert an Action into the KnowledgeBase based on the - * object's fields. + * @brief Insert an Action into the KnowledgeBase based on the object's fields. * * @param[in] dbConnection The database connection to use. */ diff --git a/src/lib/models/entity.h b/src/lib/models/entity.h index 3833f99..8f4ee1f 100644 --- a/src/lib/models/entity.h +++ b/src/lib/models/entity.h @@ -8,8 +8,7 @@ namespace obelisk { /** - * @brief The Entity model represents either a left or right side entity, - * typically used in facts and rules. + * @brief The Entity model represents either a left or right side entity, typically used in facts and rules. * */ class Entity @@ -108,16 +107,14 @@ namespace obelisk void setName(std::string name); /** - * @brief Select an Entity from the KnowledgeBase based on the object's - * name. + * @brief Select an Entity from the KnowledgeBase based on the object's name. * * @param[in] dbConnection The database connection to use. */ void selectByName(sqlite3* dbConnection); /** - * @brief Insert an Entity into the KnowledgeBase based on the object's - * fields. + * @brief Insert an Entity into the KnowledgeBase based on the object's fields. * * @param[in] dbConnection The database connection to use. */ diff --git a/src/lib/models/error.h b/src/lib/models/error.h index 86d0987..7e88a13 100644 --- a/src/lib/models/error.h +++ b/src/lib/models/error.h @@ -42,8 +42,7 @@ namespace obelisk /** * @brief Construct a new DatabaseException object. * - * @param[in] errorMessage The error message to describe the - * exception. + * @param[in] errorMessage The error message to describe the exception. */ DatabaseException(const std::string& errorMessage) : errorMessage_(errorMessage) @@ -72,8 +71,7 @@ namespace obelisk }; /** - * @brief Exception thrown if the string or blob size exceeds sqlite's - * limits. + * @brief Exception thrown if the string or blob size exceeds sqlite's limits. * */ class DatabaseSizeException : public obelisk::DatabaseException @@ -107,8 +105,7 @@ namespace obelisk }; /** - * @brief Exception thrown if there is not enough memory to perform the - * operation. + * @brief Exception thrown if there is not enough memory to perform the operation. * */ class DatabaseMemoryException : public obelisk::DatabaseException @@ -178,8 +175,7 @@ namespace obelisk /** * @brief Construct a new DatabaseConstraintException object. * - * @param[in] errorMessage The error message to send when the - * constraint is violated. + * @param[in] errorMessage The error message to send when the constraint is violated. */ DatabaseConstraintException(const std::string& errorMessage) { diff --git a/src/lib/models/fact.h b/src/lib/models/fact.h index cc16b06..1232224 100644 --- a/src/lib/models/fact.h +++ b/src/lib/models/fact.h @@ -10,8 +10,7 @@ namespace obelisk { /** - * @brief The Fact model represents truth in the releationship between two - * entities separated by a verb. + * @brief The Fact model represents truth in the releationship between two entities separated by a verb. * */ class Fact @@ -36,8 +35,7 @@ namespace obelisk obelisk::Entity rightEntity_; /** - * @brief The Verb that represents the relationship in the - * expression. + * @brief The Verb that represents the relationship in the expression. * */ obelisk::Verb verb_; @@ -79,10 +77,8 @@ namespace obelisk /** * @brief Construct a new Fact object. * - * @param[in] leftEntity The Entity on the left side of the - * expression. - * @param[in] rightEntity The Entity on the right side of the - * expression. + * @param[in] leftEntity The Entity on the left side of the expression. + * @param[in] rightEntity The Entity on the right side of the expression. * @param[in] verb The Verb separating the entities. * @param[in] isTrue Whether or not the fact is true. */ @@ -99,10 +95,8 @@ namespace obelisk * @brief Construct a new Fact object. * * @param[in] id The ID of the Fact in the KnowledgeBase. - * @param[in] leftEntity The Entity on the left side of the - * expression. - * @param[in] rightEntity The Entity on the right side of the - * expression. + * @param[in] leftEntity The Entity on the left side of the expression. + * @param[in] rightEntity The Entity on the right side of the expression. * @param[in] verb The Verb separating the entities. * @param[in] isTrue Whether or not the fact is true. */ @@ -198,8 +192,7 @@ namespace obelisk void setIsTrue(bool isTrue); /** - * @brief Select the Fact from the KnowledgeBase by IDs of the - * sub-objects. + * @brief Select the Fact from the KnowledgeBase by IDs of the sub-objects. * * @param[in] dbConnection The database connection to use. */ @@ -213,8 +206,7 @@ namespace obelisk void insert(sqlite3* dbConnection); /** - * @brief Update whether or not the fact is true in the - * KnowledgeBase. + * @brief Update whether or not the fact is true in the KnowledgeBase. * * @param[in] dbConnection The database connection. */ diff --git a/src/lib/models/rule.h b/src/lib/models/rule.h index 02f06fd..04d3efb 100644 --- a/src/lib/models/rule.h +++ b/src/lib/models/rule.h @@ -134,8 +134,7 @@ namespace obelisk void setReason(obelisk::Fact reason); /** - * @brief Select the Rule from the KnowledgeBase by IDs of the - * sub-objects. + * @brief Select the Rule from the KnowledgeBase by IDs of the sub-objects. * * @param[in] dbConnection The database connection to use. */ diff --git a/src/lib/models/suggest_action.h b/src/lib/models/suggest_action.h index e5e18b7..f6854e4 100644 --- a/src/lib/models/suggest_action.h +++ b/src/lib/models/suggest_action.h @@ -9,8 +9,7 @@ namespace obelisk { /** - * @brief The SuggestAction model representas the actions to take depending - * on if the Fact is true or false. + * @brief The SuggestAction model representas the actions to take depending on if the Fact is true or false. * */ class SuggestAction @@ -161,8 +160,7 @@ namespace obelisk void setFalseAction(obelisk::Action falseAction); /** - * @brief Select the SuggestAction from the KnowledgeBase by IDs of the - * sub-objects. + * @brief Select the SuggestAction from the KnowledgeBase by IDs of the sub-objects. * * @param[in] dbConnection The database connection to use. */ diff --git a/src/lib/models/verb.h b/src/lib/models/verb.h index 150e86f..2edc546 100644 --- a/src/lib/models/verb.h +++ b/src/lib/models/verb.h @@ -8,8 +8,7 @@ namespace obelisk { /** - * @brief The Verb model represents a verb which is used to connnect - * entities. + * @brief The Verb model represents a verb which is used to connnect entities. * */ class Verb diff --git a/src/main.h b/src/main.h index e3abfcb..3d79355 100644 --- a/src/main.h +++ b/src/main.h @@ -1,8 +1,7 @@ #include /** - * @brief The obelisk namespace contains everything needed to compile obelisk. - * code. + * @brief The obelisk namespace contains everything needed to compile obelisk code. * */ namespace obelisk @@ -38,6 +37,7 @@ Options: /** * @brief This is the main loop for obelisk. + * * This loop handles lexing and parsing of obelisk source code. * * @return int Returns EXIT_SUCCESS or EXIT_FAILURE. diff --git a/src/parser.h b/src/parser.h index 573fbdc..436fa13 100644 --- a/src/parser.h +++ b/src/parser.h @@ -18,16 +18,14 @@ namespace obelisk { /** - * @brief The Parser is responsible for analyzing the language's key words - * and taking action based on its analysis. + * @brief The Parser is responsible for analyzing the language's key words and taking action based on its analysis. * */ class Parser { private: /** - * @brief The Lexer object that the Parser is using to Parse a - * specific source file. + * @brief The Lexer object that the Parser is using to Parse a specific source file. * */ std::shared_ptr lexer_; @@ -45,69 +43,259 @@ namespace obelisk */ void setCurrentToken(int currentToken); + /** + * @brief Log errors from the LLVM parsing. + * + * @param[in] str The error message. + * @return std::unique_ptr Returns the AST expression that caused the error. + */ std::unique_ptr logError(const char* str); + + /** + * @brief Log errors from the LLVM parsing involving the prototypes. + * + * @param[in] str The error message. + * @return std::unique_ptr Returns the AST for the prototype. + */ std::unique_ptr logErrorPrototype(const char* str); + /** + * @brief The AST expression parser. + * + * @return std::unique_ptr Returns the parsed AST expression. + */ std::unique_ptr parseExpression(); + + /** + * @brief The AST number expression parser. + * + * @return std::unique_ptr Returns the parsed AST expression. + */ std::unique_ptr parseNumberExpression(); + + /** + * @brief The AST parenthesis expression parser. + * + * @return std::unique_ptr Returns the parsed AST expression. + */ std::unique_ptr parseParenthesisExpression(); + + /** + * @brief The AST identifier expression parser. + * + * @return std::unique_ptr Returns the parsed AST expression. + */ std::unique_ptr parseIdentifierExpression(); + + /** + * @brief The AST primary expression parser. + * + * @return std::unique_ptr Returns the parsed AST expression. + */ std::unique_ptr parsePrimary(); + + /** + * @brief The AST prototype parser. + * + * @return std::unique_ptr Returns the parsed AST prototype expression. + */ std::unique_ptr parsePrototype(); + + /** + * @brief The AST definition parser. + * + * @return std::unique_ptr Returns the parsed AST definition expression. + */ std::unique_ptr parseDefinition(); + + /** + * @brief The AST top level expression parser. + * + * @return std::unique_ptr Returns the parsed AST top level expression. + */ std::unique_ptr parseTopLevelExpression(); + + /** + * @brief The AST external definition parser. + * + * @return std::unique_ptr Returns the parsed AST external definition. + */ std::unique_ptr parseExtern(); + + /** + * @brief Parse a SuggestAction. + * + * @param[out] suggestAction The parsed SuggestAction. + */ void parseAction(obelisk::SuggestAction& suggestAction); + + /** + * @brief Parse a Rule. + * + * @param[out] rule The parsed Rule. + */ void parseRule(obelisk::Rule& rule); + + /** + * @brief Parse Facts. + * + * @param[out] facts The parsed Facts. + */ void parseFact(std::vector& facts); public: + /** + * @brief Construct a new Parser object. + * + * @param[in] lexer The lexer the parser uses to retrieve parts of the language. + */ Parser(std::shared_ptr lexer) : lexer_(lexer) { } + /** + * @brief Get the Lexer. + * + * @return std::shared_ptr Returns the current Lexer in use by the Parser. + */ std::shared_ptr getLexer(); + + /** + * @brief Set the Lexer to use during the parsing phase. + * + * @param[in] lexer The Lexer. + */ void setLexer(std::shared_ptr lexer); + /** + * @brief Gets the current token held inside the Lexer. + * + * @return int Returns the current token. + */ int getCurrentToken(); + /** + * @brief Instructs the Lexer to retrieve a new token. + * + * @return int Returns the next token. + */ int getNextToken(); - void handleDefinition(); - void handleExtern(); - void handleTopLevelExpression(); + /** + * @brief Parse the SuggestAction and then insert it into the KnowledgeBase. + * + * @param[in] kb The KnowledgeBase to insert the SuggestAction into. + */ void handleAction(std::unique_ptr& kb); + + /** + * @brief Parse the Rule and then insert it into the KnowledgeBase. + * + * @param[in] kb The KnowledgeBase to insert the Rule into. + */ void handleRule(std::unique_ptr& kb); + + /** + * @brief Parse the Fact and then insert it into the KnowledgeBase. + * + * @param[in] kb The KnowledgeBase to insert the Fact into. + */ void handleFact(std::unique_ptr& kb); + /** + * @brief Helper used to insert an Entity into the KnowledgeBase. + * + * @param[in] kb The KnowledgeBase to use. + * @param[in,out] entity The Entity to insert. It will contain the ID of the Entity after inserting it. + */ void insertEntity(std::unique_ptr& kb, obelisk::Entity& entity); + + /** + * @brief Helper used to insert a Verb into the KnowledgeBase. + * + * @param[in] kb The KnowledegeBase to use. + * @param[in,out] verb The Verb to insert. It will contain the ID of the Verb after inserting it. + */ void insertVerb(std::unique_ptr& kb, obelisk::Verb& verb); + + /** + * @brief Helper used to insert an Action into the KnowledgeBase. + * + * @param[in] kb The KnowledgeBase to use. + * @param[in,out] action The Action to insert. It will contain the ID of the Action after inserting it. + */ void insertAction(std::unique_ptr& kb, obelisk::Action& action); + + /** + * @brief Helper used to insert a Fact into the KnowledgeBase. + * + * @param[in] kb The KnowledgeBase to use. + * @param[in,out] fact The Fact to insert. It will contain the ID of the Fact after inserting it. + * @param[in] updateIsTrue If true, it will update the value of is_true in the KnowledgeBase if the Fact + * already exists. + */ void insertFact(std::unique_ptr& kb, obelisk::Fact& fact, bool updateIsTrue = false); + + /** + * @brief Helper used to insert a SuggestAction into the KnowledgeBase. + * + * @param[in] kb The KnowledgeBase to use. + * @param[in,out] suggestAction The SuggestAction to insert. It will contain the ID of the SuggestAction + * after inserting it. + */ void insertSuggestAction(std::unique_ptr& kb, obelisk::SuggestAction& suggestAction); + + /** + * @brief Helper usedto insert a Rule into the KnowledgeBase. + * + * @param[in] kb The KnowledgeBase to use. + * @param[in,out] rule The Rule to insert. It will contain the ID of the Rule after inserting it. + */ void insertRule(std::unique_ptr& kb, obelisk::Rule& rule); }; + /** + * @brief The exceptions thrown by the Parser. + * + */ class ParserException : public std::exception { private: + /** + * @brief The error message. + * + */ const std::string errorMessage_; public: + /** + * @brief Construct a new ParserException object. + * + */ ParserException() : errorMessage_("an unknown error ocurred") { } + /** + * @brief Construct a new ParserException object. + * + * @param[in] errorMessage The error message. + */ ParserException(const std::string& errorMessage) : errorMessage_(errorMessage) { } + /** + * @brief Return the error message as a C style string. + * + * @return const char* Returns the error message. + */ const char* what() const noexcept { return errorMessage_.c_str();