This section contains the reference to all the classes and functions in the tables handler.
TableConnector
-
class amplp::TableConnector : public amplp::FunctionConnector
Main class used to read, write and update tables.
Public Functions
-
inline TableConnector(AmplExports *ae, TableInfo *TI)
Add pointers to comunicate with AMPL.
-
inline void run()
Helper function that encapsulates the necessary steps to read/write/update a table.
-
inline bool is_handler_extensions(const std::string &arg)
Check if any of the string args provide by the user end with any of the previously defined file extensions.
-
inline void parse_arguments()
Parses all the arguments passed by ampl’s table declaration into the structures user_args and user_kargs according to the definitions in allowed_args and allowed_kargs.
Filters the verbose flag and updates the level in the logger. Launches warnings for redundant/unused arguments. The parser will automatically separate the strings provided by the user by the semicolon “;” and equal “=” symbols so they shoul not be used in allowed_args and allowed_kargs.
-
inline bool is_karg(std::string &str)
Check if a given string is a potential karg, i.e.
has the form “key=val”.
-
inline void process_string(std::string &str)
Check if a given string represents an arg or karg and dispatch it acordingly.
-
inline void process_arg(std::string &arg_string)
Given a string that represents an arg checks if the string:
is “verbose”;
has a file extension provided in register_handler_extensions;
is in allowed_args;
represents an alias. If the string is in allowed_args it will be included in used_args. Only the first string with a file extension will be accepted, posterior ones will be discarded with a warning. If the string is not “verbose”, is not in allowed_args and does not represent a file extension it will be interpreted as an alias. Only the first alias will be accepted, posterior ones will be discarded with a warning.
-
inline void process_karg(std::string &karg_string)
Given a string that represents a karg “key=val”:
-
inline void validate_filepath()
Check if a path to an external file was defined, otherwise construct a path based on the table name and the provided extensions.
-
inline size_t nkeycols()
Returns the number of arity (key) columns in AMPL’s table.
-
inline size_t ndatacols()
Returns the number of non arity (data) columns in AMPL’s table.
-
inline size_t ncols()
Returns the total number of columns in AMPL’s table.
-
inline size_t nrows()
Returns the number of rows in AMPL’s table.
-
inline void set_col_val(double val, int col)
Sets the value of column in position “col” in AMPL’s table to the double “val”.
-
inline void set_col_val(const std::string &val, int col)
Sets the value of column in position “col” in AMPL’s table to the string “val”.
-
inline void set_col_missing_val(int col)
Sets the value of column in position “col” in AMPL’s table to missing.
-
inline bool is_numeric_val(int row, int col)
Check if value of a given row at a given column in AMPL’s table is numeric.
-
inline bool is_missing(int row, int col)
Check if value of a given row at a given column in AMPL’s table is missing.
-
inline double get_numeric_val(int row, int col)
Get the numerical value of a given row at a given column in AMPL’s table.
-
inline char *get_char_val(int row, int col)
Gets a pointer to the char value of a given row at a given column in AMPL’s table.
-
inline bool is_char_val(int row, int col)
Check if value of a given row at a given column in AMPL’s table is a char.
-
inline char *get_col_name(int col)
Gets a pointer the the first char of the name of column in position col in AMPL’s table.
-
inline double *get_col_double(int col)
Get a pointer to the numerical values of a given column.
The number of elements in the column is nrows()
-
inline char **get_col_char(int col)
Get a pointer to the char values of a given column.
The number of elements in the column is nrows()
-
inline void add_row()
After we fill all the values of a row with the set_col_value functions we pass the values to AMPL with this function.
-
inline void prepare()
Parse and validate arguments, ensure the external file is found.
-
inline void process_table()
Decide if we will read, write or update the data.
We also allocate the size of row in case of a read.
-
inline virtual void check_table()
After we check the file exists we might need to check if the table exists.
-
virtual void read_in() = 0
Read data from an external an table.
-
virtual void write_out() = 0
Write data into an external table.
-
virtual void write_inout() = 0
Update external table.
-
virtual void generate_table() = 0
If the external table does not exist we need a function to create one.
If it’s not possible to create the table from scratch we should log an appropriate message and throw DBE_Error.
-
virtual void register_handler_names() = 0
In order to tell AMPL how to invoke this handler fill the vector handler_names with something like:
handler_names = {“somename”};
The parser will automatically detect if the table handler was invoked correctly in a table declaration such as:
table mytable IN “somename”
Note that the search for the table handler name is not case sensitive.
-
virtual void register_handler_extensions() = 0
Define what type of file extensions will be accepted.
For example, if you set
handler_extensions = {“txt”};
the parser will search for strings with that extension and assign it to the variable filepath.
-
virtual void register_handler_args() = 0
Tell the parser wich keywords to search for in the table declaration.
-
virtual void register_handler_kargs() = 0
Tell the parser which key/value pairs (of the form key=type) in the table declaration.
-
virtual void validate_arguments() = 0
Validates the structures derived from the parsing.
You should look at user_args and user_kargs to see the input from the user and procedd acordingly.
-
inline bool get_bool_karg(const std::string &key)
Given a string key checks if it is a key of user_kargs and returns bolean true or false if the value of the map of the key is string “true” or “false”.
Throws DBE_Error if the value of the key is not “true” or “false” and sets the appropriate message in the logger.
-
inline int get_int_karg(const std::string &key)
Given a string key checks if it is a key of user_kargs and returns the convertion of the corresponding value to integer.
-
inline double get_double_karg(const std::string &key)
Given a string key checks if it is a key of user_kargs and returns the corresponding double value associated.
Throws DBE_Error if it’s not possible to convert the value to double and sets the appropriate message in the logger.
-
inline std::string get_map_karg(const std::string &key, std::vector<std::string> &orig, std::vector<std::string> &dest)
Given a string key, a vector of strings orig and a vector of strings dest gets the value val of key in user_kargs, searches.for val in the orig vector and if val is found returns the element in the same position at the dest vector.
Throws DBE_Error if the value of the key is not found in the vector orig and sets the appropriate message in the logger.
-
inline FileHandler get_file_handler(const std::string &filename, const std::string &mode)
Provide a FileHandler object to be used with the TableConnector class.
Public Members
-
std::string handler_version
Current version of the handler.
-
std::string table_name
Name of the table.
-
std::string filepath
Path for the file (or something else) to read/write/update.
-
std::string inout
Inout keyword of the table, can be IN, OUT or INOUT.
-
std::vector<std::string> handler_names
Names that will identify this table handler in the table declaration.
-
std::vector<std::string> handler_extensions
File extensions accepted by the handler.
-
std::unordered_set<std::string> user_args
Vector with the args parsed from the table handler declaration.
-
std::unordered_map<std::string, std::string> user_kargs
Vector with the kargs parsed from the table handler declaration.
For every provided string of the type “key=val” we will set user_kargs[key] = val.
-
std::unordered_set<std::string> allowed_args
Set with the args that the user is allowed to provide in the table handler declaration.
This structure should be filled in the table handler constructor.
-
std::unordered_set<std::string> allowed_kargs
Set with the kargs keys that the user is allowed to provide in the table handler declaration.
This structure should be filled in the table handler constructor.
-
std::vector<std::string> ampl_args
Vector with all the args provided by the user in the table handler declaration.
-
bool is_writer
In order to have a single parser for the reader/writer we need to be able to tell one from the other.
-
int requested_verbose
Verbosed level specified by the user.
Logger
-
class amplp::Logger
A simple logger class.
Level specifies the level from wich to print the messages. Successive messages are stored in the messages vector. The corresponding code of the error is stored in the code vector and should follow the LOG_LEVELS enum. Messages with error code LOG_ERROR should be issued before throwing an exception without sending further information to AMPL. Other LOG_LEVELS should be used as apropriate.
Public Functions
-
inline void log(const std::string &msg, int code)
Pass a message to the logger.
Error messages are printed immendiatly as they should result from an exception. Other messages are printed acording to their code and the level requested by the user.
-
inline void print_log()
Initially the level of the logger is 0.
When we get the requested logger level from the user we print the already existing messages accordingly.
FileHandler
-
class FileHandler : public amplp::FunctionConnector
Auxiliary class to handle text files.
The created object will use AMPL’s fprintf in order to read/write numbers from/to text files and close automaticaly if an exception is raised.