From 23ab9122184feb0be0961fe4d86f0da983af0713 Mon Sep 17 00:00:00 2001 From: Chris Punches Date: Fri, 23 Jun 2017 02:08:45 -0400 Subject: [PATCH] doxygen style documentation started and reworked unit loader in Suite --- src/loaders/Conf.cpp | 29 ++++++++++---------- src/loaders/JSON_Loader.cpp | 52 +++++++++++++++++------------------ src/loaders/Suite.cpp | 54 +++++++++++++++++++++---------------- src/loaders/Suite.h | 3 +++ src/loaders/Unit.cpp | 4 ++- 5 files changed, 77 insertions(+), 65 deletions(-) diff --git a/src/loaders/Conf.cpp b/src/loaders/Conf.cpp index 2f4456d..e5a6113 100644 --- a/src/loaders/Conf.cpp +++ b/src/loaders/Conf.cpp @@ -1,18 +1,21 @@ #include "Conf.h" -class CONF_PLANPATH_INVALID: public std::runtime_error -{ -public: +/// CONF_PLANPATH_INVALID - Exception thrown when the Conf type can not load the supplied path for the Plan definition +/// file. +class CONF_PLANPATH_INVALID: public std::runtime_error { public: CONF_PLANPATH_INVALID(): std::runtime_error("conf: The supplied path for the plan definition file is invalid.") {} }; -class CONF_UNITSPATH_INVALID: public std::runtime_error -{ -public: +/// CONF_UNITSPATH_INVALID - Exception thrown when the Conf type can not load the supplied path for the Unit definition +/// files. +class CONF_UNITSPATH_INVALID: public std::runtime_error { public: CONF_UNITSPATH_INVALID(): std::runtime_error("conf: The supplied path for the unit definition file is invalid.") {} }; - +/// Conf::Conf - Constructor for Conf type. Loads the configuration for the application. +/// TODO Expand to detect when a directory path is supplied for units_path or plan_path and import all Tasks and Units. +/// +/// \param filename - The filename to load the configuration from. Conf::Conf( std::string filename ): JSON_Loader() { // load the conf file. @@ -25,12 +28,8 @@ Conf::Conf( std::string filename ): JSON_Loader() if (this->get_serialized(this->units_path, "units_path", true) != 0 ) { throw CONF_UNITSPATH_INVALID(); } }; -std::string Conf::get_plan_path() -{ - return this->plan_path.asString(); -} +/// Conf::get_plan_path - Retrieves the path to the Plan definition file from the application configuration file. +std::string Conf::get_plan_path() { return this->plan_path.asString(); } -std::string Conf::get_units_path() -{ - return this->units_path.asString(); -} +/// Conf::get_units_path - Retrieves the path to the Unit definition file from the application configuration file. +std::string Conf::get_units_path() { return this->units_path.asString(); } diff --git a/src/loaders/JSON_Loader.cpp b/src/loaders/JSON_Loader.cpp index 5a4f26a..0591e98 100644 --- a/src/loaders/JSON_Loader.cpp +++ b/src/loaders/JSON_Loader.cpp @@ -2,30 +2,32 @@ #include "helpers.h" #include -class JSON_Loader_NotReady: public std::runtime_error -{ -public: +/// JSON_Loader_NotReady - Exception thrown when a member function is called before data is populated. +class JSON_Loader_NotReady: public std::runtime_error { public: JSON_Loader_NotReady(): std::runtime_error("JSON_Loader: Tried to access JSON without actually populating JSON.") {} }; -class JSON_Loader_FileNotFound: public std::runtime_error -{ -public: +/// JSON_Loader_FileNotfound - Exception thrown when JSON_Loader can not find the file it is told to parse. +class JSON_Loader_FileNotFound: public std::runtime_error { public: JSON_Loader_FileNotFound(): std::runtime_error("JSON_Loader: The requested file could not be found.") {} }; -class JSON_Loader_InvalidJSON: public std::runtime_error -{ -public: +/// JSON_Loader_InvalidJSON - Exception thrown when JSON_Loader fails to parse the JSON provided. +class JSON_Loader_InvalidJSON: public std::runtime_error { public: JSON_Loader_InvalidJSON(): std::runtime_error("JSON_Loader: The JSON provided could not be parsed.") {} }; +/// JSON_Loader::JSON_Loader - Constructor for JSON_Loader base class. Simply inits to an unpopulated state. JSON_Loader::JSON_Loader() { this->populated = false; } -// loads json from a file into a deserializable type and sets to private member json_root +/// JSON_Loader::load_json_file - Loads JSON from a filepath into a serialized representation assigned as a local member +/// intended to be used as a buffer for further operations by base methods and derived class methods. +/// +/// \param filename - +/// \param verbose void JSON_Loader::load_json_file( std::string filename, bool verbose ) { // reads from a file into a Json::Value type. @@ -59,11 +61,15 @@ void JSON_Loader::load_json_file( std::string filename, bool verbose ) std::cout << "Parsed '" << filename << "' with " << this->json_root.size() << " element(s)." << std::endl; } } - // exit successfully and set flag that this can be used now. + // Flag as ready for consumption. this->populated = true; } -// loads json from std::string into a serialized type and sets to private member json_root +/// JSON_Loader::load_json_string - loads json from std::string into a json::value type and sets to protected member +/// 'json_root'. +/// +/// \param input - The JSON-formatted string to serialize +/// \param verbose - Whether or not to print verbose information to STDOUT. void JSON_Loader::load_json_string( std::string input, bool verbose ) { // reads from a string into a Json::Value type. @@ -91,20 +97,12 @@ void JSON_Loader::load_json_string( std::string input, bool verbose ) std::cout << input << std::endl << std::endl; } } - // exit successfully + // flag as ready for consumption this->populated = true; } -// returns the serialized representation of json_root -//Json::Value JSON_Loader::as_serialized() -//{ -// if ( ! this->populated ) { throw JSON_Loader_NotReady(); } -// -// return this->json_root; -//} - -// returns the string representation of json_root +/// JSON_Loader::as_string - returns the string representation of json_root std::string JSON_Loader::as_string() { if ( ! this->populated ) { throw JSON_Loader_NotReady(); } @@ -112,10 +110,12 @@ std::string JSON_Loader::as_string() return this->json_root.asString(); } -// returns the serialized representation of the value of a key -// the Jason::Value object to assign the fetched value to -// verbosity flag -// exit or not on failure +/// JSON_Loader::get_serialized - assigns the serialized representation of the value of a key (json::value) +/// +/// \param input - A reference to the json::value object to receive the new value. +/// \param key - The JSON key name to assign the value to (the root of the json::value object by name) +/// \param verbose - Whether or not to print verbose output to STDOUT. +/// \return - Boolean indicator of success or failure (0|1) int JSON_Loader::get_serialized(Json::Value &input, std::string key, bool verbose) { // throw if the class is not ready to be used. diff --git a/src/loaders/Suite.cpp b/src/loaders/Suite.cpp index 62401ba..e20694d 100644 --- a/src/loaders/Suite.cpp +++ b/src/loaders/Suite.cpp @@ -1,39 +1,51 @@ +#include #include "Suite.h" -Suite::Suite(): JSON_Loader() -{ - // empty -}; +/// Suite::Suite() - Constructor for Suite class. The Suite class is simply a managed container for a Unit vector. +/// Once instantiated, all methods will require either a JSON file or string to be loaded as deserialized Unit types +/// before being called or will simply throw an exception. +/// +/// From the high level, a Suite contains the full definitions of all potential Units to execute defined in the Unit +/// definition files that it is loading. It is meant to be used in such a way that as the application iterates through +/// the Task objects contained by the application Plan, it will iterate through the appplication's Suite, which contains +/// the definition of all available Tasks. In this manner, defining units and executing units are split into separate +/// human processes to allow modularly developed profiles of test suites. As inferred, Unit is expected to be one of +/// the two types that are only instantiated once per application run, though it is designed to be used more than once +/// if the implementor so desires. +Suite::Suite(): JSON_Loader() {}; +/// Suite::load_units_file - Uses the json_root buffer on each run to append intact Units as they're +/// deserialized from the provided file. +/// +/// \param filename - The file to pull the JSON-formatted units from. +/// \param verbose - Whether to print verbose output to STDOUT. void Suite::load_units_file( std::string filename, bool verbose ) { - // will use json_root staging buffer on each run to append to this->units vector as valid units are found. + // will use json_root buffer on each run to append to this->units vector as valid units are found. this->load_json_file( filename, verbose ); + // staging buffer Json::Value jbuff; - // refill the json_root buffer with a json object in the - if ( this->get_serialized( jbuff, "units", verbose ) != 0) + // fill the jbuff staging buffer with a json::value object in the supplied filename + if ( this->get_serialized( jbuff, "units", verbose ) == 0) { this->json_root = jbuff; } - // assemble the units - -} - -int Suite::load_file(std::string filename, true): JSON_Loader( filename ) -{ - Json::Value raw_units = this->get_serialized("") - for ( int index = 0; index < raw_units.size(); index++ ) + // iterate through the json::value members that have been loaded. append to this->units vector + // buffer for units to append: + Unit tmp_U; + for ( int index = 0; index < this->json_root.size(); index++ ) { - this->units.push_back( Unit( raw_units[ index ] ) ); + // assemble the unit from json_root using the built-in value operator + tmp_U.load_root( this->json_root[ index ] ); + // append to this->units + this->units.push_back( tmp_U ); } - std::cout << raw_units.size() << std::endl; - - return EXIT_SUCCESS; } +// TODO Implement /* Unit Suite::get_unit(std::string provided_name) * returns a unit from a unitholder object by name @@ -62,7 +74,3 @@ int Suite::load_file(std::string filename, true): JSON_Loader( filename ) return * returnable; } */ - - - -ca \ No newline at end of file diff --git a/src/loaders/Suite.h b/src/loaders/Suite.h index d6f1af6..d5432a2 100644 --- a/src/loaders/Suite.h +++ b/src/loaders/Suite.h @@ -6,6 +6,9 @@ #include "JSON_Loader.h" #include "Unit.h" + + + class Suite: public JSON_Loader { private: diff --git a/src/loaders/Unit.cpp b/src/loaders/Unit.cpp index 1e6872d..74b45a3 100644 --- a/src/loaders/Unit.cpp +++ b/src/loaders/Unit.cpp @@ -4,6 +4,8 @@ #include #include +/// Unit_NotPopulated - Meant to be thrown when a Unit type is not populated before being used. +/// Signaled by use of the 'populated' boolean member of the Unit class. class Unit_NotPopulated: public std::runtime_error { public: @@ -15,7 +17,7 @@ Unit::Unit() {} // where the serialized json is broken down into object members int Unit::load_root(Json::Value loader_root) { - +// this needs reworked to throw an Exception if any of the values aren't loadable. this->name = loader_root.get("name", "").asString(); this->target = loader_root.get("target", "").asString();