This section contains the reference to all the classes and functions in the tables handler.

FunctionConnector

class FunctionConnector

Class to encapsulate AMPL Exports functions.

Subclassed by amplp::FileHandler, amplp::TableConnector

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”:

  • splits the string by the “=” character into a key and a value;

  • checks if the key is verbose or in allowed_kargs. If the key is in allowed_kargs sets user_kargs[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 table 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.

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.