Arguments parsing

Collaboration diagram for Arguments parsing:

Read lists
These functions try to read N values of the desired type into the given structure (either a STL vector of any numerical type by adding the read values at the end or a Matrix1D of any numerical type and then the values are written at PHYSICAL positions 0 ... N-1, the Matrix1D must be big enough to hold all the data since it is not resized internally. If it is not possible to read all parameters an exception is thrown. You can provide the exception in the function call but there are default values. These functions are based in those for reading single values, so it might be possible that these other functions throw other exceptions. The different elements of the list are selected using the tokenizing functions (different elements in the string are separated by spaces), so after the application of this function to the input string, this is modified and NULL characters are introduced as delimiters of the elements. The following code is an example of doing so: getline(in_stream, line); readFloatList(line, 10, v1); // Read 10 values from line in v1 readFloatList(NULL, 10, v2); // Read NEXT!! 10 values in v2
template<typename T >
void	readFloatList (const char *str, int N, std::vector< T > &v)
template<typename T >
void	readFloatList (const std::string &str, size_t &i, int N, std::vector< T > &v)
template<typename T >
void	readFloatList (const char *str, int N, Matrix1D< T > &v, ErrorType _errno=ERR_VALUE_INCORRECT, std::string errmsg="Error reading floating list", int exit=0)

Functions for parsing the command line
These functions help you to manage the command line parameters
const char *	getParameter (int argc, const char **argv, const char *param, const char *option=NULL)
bool	getTwoDoubleParams (int argc, const char **argv, const char *param, double &v1, double &v2, double v1_def, double v2_def)
bool	getThreeDoubleParams (int argc, const char **argv, const char *param, double &v1, double &v2, double &v3, double v1_def, double v2_def, double v3_def)
bool	checkParameter (int argc, const char **argv, const char *param)
int	paremeterPosition (int argc, const char **argv, const char *param)
int	numComponents (const std::string &str)
Matrix1D< double >	getVectorParameter (int argc, const char **argv, const char *param, int dim=2)
Matrix1D< double >	getVectorParameter (FILE *fh, const char *param, int dim=2)
void	generateCommandLine (const std::string &command_line, int &argcp, char **&argvp, char *&copy)
bool	generateCommandLine (FILE *fh, const char *param, int &argcp, char **&argvp, char *&copy)
std::string	getParameter (FILE *fh, const char *param, int skip=0, const char *option=NULL)
bool	checkParameter (FILE *fh, const char *param)

Detailed Description

This set of functions are designed for make easier checking and reading parameters from a string. The single value readings don't modify the value of the input string, while the multiple value readings do. In general, the reading is oriented to be done with a chain of strtok (a general C function), for this reason the string itself is modified by the successive calls to strtok.

The second group (list reading) uses tokens internally, while in the single read functions the token must be given by hand. Anyway, it is not so difficult to read a set of fields from a line with all the normal checks we would like (existence of a parameter, checking for numerical correctness...)

The following is an example of its use. This code tries to read a number, a character and a list of numbers from a line. In the example you can also see how to write code for the different error handling methods.

std::string line;
int key, param_no;
std::vector< float > data;

try
{
key = textToFloat(firstToken(line), 1602, "Error reading key");
param_no = textToInt(nextToken(), 1602, "Error reading number parameters");
readFloatList(NULL, param_no, data, 1602, "Error reading doc file line");
}
catch (XmippError XE)
{
    std::cout << XE;
    DL.line_type = 0;
    REPORT_ERROR(1602, "Line is discarded");
}

Function Documentation

checkParameter() [1/2]

bool checkParameter	(	int	argc,
		const char **	argv,
		const char *	param
	)

Get boolean parameters from the command line.

This function assumes that the command line is structured in such a way that for each parameter a block like "-param" is defined. The label "param" can be substituted by any other one you like. It might be used to look for a boolean parameter, for instance:

-verbose means that verbose functionality is set (TRUE)

verbose = checkParameter(argc, argv, "-verbose"));

// checks if "-verbose" was supplied in the command line. If -verbose was
// supplied the function returns TRUE (1), otherwise returns FALSE (0)

Definition at line 97 of file args.cpp.

{
    int i = 0;

    while ((i < argc) && (strcmp(param, argv[i]) != 0))
        i++;

    if (i < argc)
        return(true);
    else
        return(false);
}

checkParameter() [2/2]

bool checkParameter	(	FILE *	fh,
		const char *	param
	)

Check if a parameter is present in a file.

The same as the previous function, but this function only reports if a parameter is present or not in a file. Notice that boolean parameters must be defined as "parameter=". If after the parameter, "no" comes then this function returns FALSE

Definition at line 434 of file args.cpp.

{
    long actual_pos = ftell(fh);
    fseek(fh, 0, SEEK_SET);

    char    line[201];
    bool found = false;
    std::string retval;

    // Read lines
    while (fgets(line, 200, fh) != NULL)
    {
        if (line[0] == 0)
            continue;
        if (line[0] == '#')
            continue;
        if (line[0] == '\n')
            continue;

        int i = 0;
        while (line[i] != 0 && line[i] != '=')
            i++;
        if (line[i] == '=')
        {
            line[i] = 0;
            if (strcmp(line, param) == 0)
            {
                retval = line + i + 1;
                found = true;
                break;
            }
        }
    }
    fseek(fh, actual_pos, SEEK_SET);
    return found && retval != "No" && retval != "NO" && retval != "no";
}

generateCommandLine() [1/2]

void generateCommandLine	(	const std::string &	command_line,
		int &	argcp,
		char **&	argvp,
		char *&	copy
	)

Generate argc and argv for a string.

Given a string this function makes a copy of the string and divides it into tokens such that they can be used as argc and argv, as if it were a command line.

The string copy remains in "copy" and it can be freed by disposing this variable.

argvp[0] (normally the program name) is set to any value, in this case to "autom", standing for "automatically generated".

argcp==0 if now valid command line is provided, ie, the line is empty or only with blanks.

Next time the function is called it checks that argv and copy are empty (pointing to NULL), if they aren't then firstly the associated memory is freed.

int argcp;
char** argvp;
char* copy;

copy = NULL;
argvp = NULL;

string command_line = "-i input_file -o output_file";

generateCommandLine(command_line, argcp, &argvp, &copy);

if (argcp != 0)
read_parameters(argcp, argvp);

Definition at line 238 of file args.cpp.

{
    int L = command_line.length();

    // Some initialization
    if (L == 0)
    {
        argcp = 0;
        return;
    }
    if (command_line[0] == '\n')
    {
        argcp = 0;
        return;
    }

    // Check that argvp and copy are empty
    if (argvp != NULL)
        delete argvp;
    if (copy != NULL)
        delete[] copy;

    // Copy command line
    copy = new char[L+1];
    int i = 0;
    while (i < L && command_line[i] != '\n')
    {
        copy[i] = command_line[i];
        i++;
    }
    L = i;
    copy[L] = '\0';

    // Now count how many different words are there
    int words;
    int state;
    if (copy[0] == ' ')
    {
        state = OUTSIDE_WORD;
        words = 0;
    }
    else
    {
        state = INSIDE_WORD;
        words = 1;
    }
    i = 1;
    while (i < L)
    {
        if (state == OUTSIDE_WORD && copy[i] != ' ')
        {
            state = INSIDE_WORD;
            words++;
        }
        if (state == INSIDE_WORD && copy[i] == ' ')
            state = OUTSIDE_WORD;
        i++;
    }

    // Resize argv and cut words
    argvp = new char *[words+1];
    argvp[0] = new char[6];
    strcpy(argvp[0], "autom");
    if (copy[0] == ' ')
    {
        state = OUTSIDE_WORD;
        argcp = 1;
    }
    else
    {
        state = INSIDE_WORD;
        argvp[1] = &(copy[0]);
        argcp = 2;
    }
    i = 1;
    while (i < L)
    {
        if (state == OUTSIDE_WORD && copy[i] != ' ')
        {
            state = INSIDE_WORD;
            argvp[argcp] = &(copy[i]);
            argcp++;
        }
        if (state == INSIDE_WORD && copy[i] == ' ')
        {
            state = OUTSIDE_WORD;
            copy[i] = '\0';
        }
        i++;
    }
}

generateCommandLine() [2/2]

bool generateCommandLine	(	FILE *	fh,
		const char *	param,
		int &	argcp,
		char **&	argvp,
		char *&	copy
	)

Generate articial command line from a file.

The copy variable must be destroyed outside by "delete copy". This function takes "input_file=<input_file>" and turns it into "-input_file <input_file>" The appropriate argc, argv are also returned.

Returns TRUE if the parameter is found in the file, and FALSE if it is not

Definition at line 332 of file args.cpp.

{
    long actual_pos = ftell(fh);
    fseek(fh, 0, SEEK_SET);

    char line[201];
    char *retval;
    bool found = false;

    // Read lines
    while (fgets(line, 200, fh) != NULL && !found)
    {
        if (line[0] == 0)
            continue;
        if (line[0] == '#')
            continue;
        if (line[0] == ';')
            continue;
        if (line[0] == '\n')
            continue;

        int i = 0;
        while (line[i] != 0 && line[i] != '=')
            i++;
        if (line[i] == '=')
        {
            line[i] = 0;
            if (strcmp(line, param) == 0)
            {
                retval = line + i + 1;
                found = true;
                break;
            }
        }
    }
    fseek(fh, actual_pos, SEEK_SET);
    if (!found)
        return false;

    std::string artificial_line;
    artificial_line = (std::string)"-" + param + " " + retval;
    generateCommandLine(artificial_line, argcp, argvp, copy);
    return true;
}

getParameter() [1/2]

const char* getParameter	(	int	argc,
		const char **	argv,
		const char *	param,
		const char *	option = NULL
	)

Get parameters from the command line.

This function assumes that the command line is structured in such a way that for each parameter a block like "-param <param_value>" is defined. The label "param" can be substituted by any other one you like. If the parameter is optional then this function allows you to define a default value. If no default value is supplied and the parameter is not specified in the command line, then an exception is thrown. You may change the default exception.

You may also indicate that in case of error no exception is raised and force the program to abort (use the exit variable).

m_param = textToFloat(getParameter(argc, argv, "-m"));

// Get compulsory parameter "-m"
m_param = textToFloat(getParameter(argc, argv, "-m","2.65"));

// Optional parameter, if no parameter is given it takes 2.65 by default
m_param = textToFloat(getParameter(argc, argv, "-m", NULL, 6001, "-m parameter not \
    found. I'm going out", TRUE);

// Compulsory parameter, if not found give an special error message and exit
// the program

Definition at line 30 of file args.cpp.

{
    int i = 0;

    while ((i < argc) && (strcmp(param, argv[i])))
        i++;
    if (i < argc - 1)
        return(argv[i+1]);
    else
        if (option == NULL)
            REPORT_ERROR(ERR_ARG_MISSING, param);

    return((char *) option);
}

getParameter() [2/2]

std::string getParameter	(	FILE *	fh,
		const char *	param,
		int	skip = 0,
		const char *	option = NULL
	)

Get parameter from file.

Parameters are supposed to be identified with an =, so any line which doesn't contain an = character cannot contain a parameter. The left part of the "=" is the identifier, and the right part the value. The value is returned without any extra space, if it is compound of several words, then the spaces in between are simplified to a single blank space.

The file position inside the file is not moved and comments are allowed starting with "#" and ";".

Parameter skip controls the number of these parameters to skip before returning the value, ie, if there are several "parameter=" tags in a file and you want the first one then you should skip 0, if you want the second the skip=1, ...

The meaning and use of the exit, errors and optional value is the same as in the command line getParameter

Definition at line 379 of file args.cpp.

{
    long actual_pos = ftell(fh);
    fseek(fh, 0, SEEK_SET);

    char    line[201];
    std::string  retval;
    bool found = false;
    int skipped = 0;

    // Read lines
    while (fgets(line, 200, fh) != NULL && !found)
    {
        if (line[0] == 0)
            continue;
        if (line[0] == '#')
            continue;
        if (line[0] == ';')
            continue;
        if (line[0] == '\n')
            continue;

        int i = 0;
        char *line_wo_spaces = line;
        while (*line_wo_spaces == ' ' || *line_wo_spaces == '\t')
            line_wo_spaces++;
        while (line_wo_spaces[i] != 0 && line_wo_spaces[i] != '=')
            i++;
        if (line_wo_spaces[i] == '=')
        {
            line_wo_spaces[i] = 0;
            if (strcmp(line_wo_spaces, param) == 0)
            {
                if (skipped == skip)
                {
                    retval = line_wo_spaces + i + 1;
                    found = true;
                    break;
                }
                else
                    skipped++;
            }
        }
    }
    fseek(fh, actual_pos, SEEK_SET);
    if (!found)
        if (option == NULL)
            REPORT_ERROR(ERR_ARG_INCORRECT, param);
        else
            return option;
    else
        return removeSpaces(retval);
}

getThreeDoubleParams()

bool getThreeDoubleParams	(	int	argc,
		const char **	argv,
		const char *	param,
		double &	v1,
		double &	v2,
		double &	v3,
		double	v1_def,
		double	v2_def,
		double	v3_def
	)

Get 3 float parameters after a flag from the command line.

An exception is thrown if there are not enough parameters after the flag, if the message is empty then "Not enough parameters after <param>" is shown. The default values must be provided. TRUE is returned if the two values have been found

Definition at line 70 of file args.cpp.

{
    bool retval;
    int i = paremeterPosition(argc, argv, param);
    if (i != -1)
    {
        if (i + 3 >= argc)
            REPORT_ERROR(ERR_ARG_MISSING,
                         (std::string)"Not enough arguments after " + *param);
        v1 = textToFloat(argv[i+1]);
        v2 = textToFloat(argv[i+2]);
        v3 = textToFloat(argv[i+3]);
        retval = true;
    }
    else
    {
        v1 = v1_def;
        v2 = v2_def;
        v3 = v3_def;
        retval = false;
    }
    return retval;
}

getTwoDoubleParams()

bool getTwoDoubleParams	(	int	argc,
		const char **	argv,
		const char *	param,
		double &	v1,
		double &	v2,
		double	v1_def,
		double	v2_def
	)

Get two float parameters after a flag from the command line.

An exception is thrown if there are not enough parameters after the flag, if the message is empty then "Not enough parameters after <param>" is shown. The default values must be provided. TRUE is returned if the two values have been found

Definition at line 46 of file args.cpp.

{
    bool retval;
    int i = paremeterPosition(argc, argv, param);
    if (i != -1)
    {
        if (i + 2 >= argc)
            REPORT_ERROR(ERR_ARG_MISSING,
                         (std::string)"Not enough arguments after " + *param);
        v1 = textToFloat(argv[i+1]);
        v2 = textToFloat(argv[i+2]);
        retval = true;
    }
    else
    {
        v1 = v1_def;
        v2 = v2_def;
        retval = false;
    }
    return retval;
}

getVectorParameter() [1/2]

Matrix1D< double > getVectorParameter	(	int	argc,
		const char **	argv,
		const char *	param,
		int	dim = 2
	)

Get float vector.

A vector is defined as a "[x,y,z, ...]" of any dimension (by default 2D vectors are read). The vector must not contain blank spaces.

a = getVectorParameter(argc, argv, "-a", 3); // a 3D vector called "-a".

The vector is internally resized properly. If the dimension is -1 then all the vector components are read disregarding their dimensionality, ie,-1 is used to read vectors of an unknown dimension. If the parameter is not found when no dimensionality is given an empty vector is returned but no exception is thrown. If there is no dimensionality and a single parameter is behind the flag then no brackets are needed

Definition at line 138 of file args.cpp.

{
    Matrix1D<double> aux;
    bool count_dimensionality = (dim == -1);

    // Find and form vector
    int pos = paremeterPosition(argc, argv, param);
    if (pos == -1 || (pos + 1 == argc))
    {
        if (count_dimensionality)
            return aux;
        else
            REPORT_ERROR(ERR_ARG_MISSING, param);
    }
    pos++;
    if (*(argv[pos]) != '[')
    {
        double d = textToFloat(argv[pos]);
        aux.resize(1);
        aux(0) = d;
        return aux;
    }

    std::string vector;
    bool finished = false;
    while (!finished)
    {
        vector += argv[pos];
        if (vector[vector.length()-1] == ']')
            finished = true;
        if (++pos == argc && !finished)
            REPORT_ERROR(ERR_ARG_INCORRECT, param);
    }

    // Remove brackets
    vector = vector.substr(1, vector.length() - 2);

    // Count dimensionality
    int start_copy = 0, end_copy;
    if (count_dimensionality)
    {
        dim = 0;
        start_copy = 0;
        do
        {
            end_copy = vector.find(',', start_copy);
            if (end_copy == -1)
                break;
            start_copy = end_copy + 1;
            dim++;
        }
        while (1);
        dim++;
    }

    // Read different vector elements
    int i = 0;
    start_copy = 0;
    aux.resize(dim);
    while (i < dim - 1)
    {
        // Find colon
        end_copy = vector.find(',', start_copy);
        // Store number
        aux(i) = textToFloat(vector.substr(start_copy, end_copy));

        // Prepare for next iteration
        i++;
        start_copy = end_copy + 1;
    }

    // Copy last element
    aux(i) = textToFloat(vector.substr(start_copy, vector.length()));

    return aux;
}

getVectorParameter() [2/2]

Matrix1D<double> getVectorParameter	(	FILE *	fh,
		const char *	param,
		int	dim = 2
	)

Get float vector.

Same as the previous function but from a file.

Definition at line 216 of file args.cpp.

{
    int argcp;
    char **argvp = NULL;
    char *copy = NULL;
    Matrix1D<double> retval;
    if (!generateCommandLine(fh, param, argcp, argvp, copy))
    {
        if (dim != -1)
            REPORT_ERROR(ERR_ARG_MISSING, param);
    }
    else
    {
        retval = getVectorParameter(argcp, (const char **)argvp, ((std::string)"-" + param).c_str(), dim);
        delete[] copy;
    }
    return retval;
}

numComponents()

int numComponents

(

const std::string &

str

)

Return the number of components of a vector argument.

A vector argument is defined as [x,y,z,...]. It returns 0 if the string does not contain a vector

Definition at line 125 of file args.cpp.

{
    int imax = str.length();
    int retval = 0;
    if (str[0] != '[' && str[imax-1] != ']')
        return retval;
    for (int i = 0; i < imax; i++)
        if (str[i] == ',')
            retval++;
    return retval + 1;
}

paremeterPosition()

int paremeterPosition	(	int	argc,
		const char **	argv,
		const char *	param
	)

Returns the position where the given parameter is in the command line.

This function assumes that the command line is structured in such a way that for each parameter a block like "-param" is defined. The label "param" can be substituted by any other one you like. It returns -1 if the parameter is not found. It is used to look for parameters having a list of values behind, for instance:

-ang rot tilt psi

i = paremeterPosition(argc, argv, "-ang"));

// This condition checks if 3 arguments where introduced after -ang parameter
// (assuming that the -ang argument is the last one in the string)
if (i+3 >= argc)
    EXIT_ERROR(1, "Not enough parameters behind -ang");

ang1 = argv[i+1];
ang2 = argv[i+2];
ang3 = argv[i+3];

Definition at line 111 of file args.cpp.

{
    int i = 0;

    while ((i < argc) && (strcmp(param, argv[i])))
        i++;

    if (i < argc - 1)
        return  i;
    else
        return -1;
}

readFloatList() [1/3]

template<typename T >

void readFloatList	(	const char *	str,
		int	N,
		std::vector< T > &	v
	)

List to STL vector.

Definition at line 104 of file args.h.

{
    T valueF;
    char* token;

    token = firstToken(str);
    for (int i = 0; i < N; i++)
    {
        if (token == NULL)
            REPORT_ERROR(ERR_VALUE_INCORRECT, "Cannot convert string into a list of numbers");

        valueF = (T) textToFloat(token);
        v.push_back(valueF);

        if (i != N - 1)
            token = nextToken();
    }
}

readFloatList() [2/3]

template<typename T >

void readFloatList	(	const std::string &	str,
		size_t &	i,
		int	N,
		std::vector< T > &	v
	)

List to STL vector.

Definition at line 127 of file args.h.

{
    T valueF;
    std::string token;

    token = nextToken(str, i);
    for (int j = 0; j < N; j++)
    {
        if (token == "")
            REPORT_ERROR(ERR_VALUE_INCORRECT, "Cannot convert string into list of floats");
        valueF = (T) textToFloat(token.c_str());
        v.push_back(valueF);

        if (j != N - 1)
            token = nextToken(str, i);
    }
}

readFloatList() [3/3]

template<typename T >

void readFloatList	(	const char *	str,
		int	N,
		Matrix1D< T > &	v,
		ErrorType	_errno = ERR_VALUE_INCORRECT,
		std::string	errmsg = "Error reading floating list",
		int	exit = 0
	)

Read list into a Matrix1D.

Definition at line 151 of file args.h.

{
    T valueF;
    char* token;

    token = firstToken(str);
    for (int i = 0; i < N; i++)
    {
        if (token == NULL)
        {
            // CO: Should not report other error than the required one
            // std::cout << "Read float list: Number of true parameters doesn't coincide\n";
            REPORT_ERROR(_errno, errmsg);
        }

        try
        {
            valueF = (T) textToFloat(token);
        }
        catch (XmippError)
        {
            REPORT_ERROR(_errno, errmsg);
        }

        v(i) = valueF;
        if (i != N - 1)
            token = nextToken();
    }
}