cpar - Variable function parameters for C

The C language requires that you predefine the types and positions of all the parameters to every function. There is also the C variable parameters handling mechanism, although this is risky for several reasons. There are many cases when this is inconvenient:

All these problems are solved by this package.

The cpar library provides the following features:

cpar depends on glib version 2.0 or newer.

Send bug reports to software@danielwebb.us.

The following C program should make the basic principles clear:

void subroutine(int k, cpar_table *vp)
{
real *k2;
int i;
char *string;

string = CPAR_GET_STRING(vp, "key can be any string");
i = CPAR_GET_INT(vp, "key 1");
k2 = CPAR_GET_REAL_POINTER(vp, "key 0");
*k2 = 1.2345 * i * k;
}

void main(void)
{
real value = 0.0;
cpar_table *vp;

subroutine(
    10,
    vp = CPAR_CREATE_PARAMETERS(
        CPAR_ADD_REAL_POINTER, "key 0", &value),
        CPAR_ADD_INT("key 1", 15000),
        CPAR_ADD_STRING("key can be any string", "contents");
        )
    );
// value now == 1.2345 * 15000 * 10
CPAR_FREE_PARAMETERS(vp);
}
    

CPAR_CREATE_PARAMETERS() creates a parameter table, and three parameters are inserted. This table is passed to the subroutine, which can access the values of the parameters. The parameter table is freed by the main program using CPAR_FREE_PARAMETERS().

Types are checked each time a parameter is retrieved from the table. Type mismatch is a fatal error (this can be changed by setting CPAR_TYPE_MISMATCH_IS_FATAL to false in cpar_internal.h).

cpar_table *vp;
vp = CPAR_CREATE_PARAMETERS(<parameters>)
    

where <parameters> is a list of the following functions:

char *key;

CPAR_ADD_BOOL(key, value)
CPAR_ADD_INT(key, value) 
CPAR_ADD_DOUBLE(key, value) 
CPAR_ADD_REAL(key, value)
CPAR_ADD_STRING(key, value)
CPAR_ADD_BOOL_POINTER(key, value)
CPAR_ADD_CHAR_POINTER(key, value) 
CPAR_ADD_INT_POINTER(key, value) 
CPAR_ADD_DOUBLE_POINTER(key, value) 
CPAR_ADD_REAL_POINTER(key, value) 
CPAR_ADD_CPAR_POINTER(key, value) 
CPAR_ADD_GENERIC(key, cpar_type, value)

CPAR_ADD_GPOINTER(key, gpointer_type, value)
CPAR_ADD_SV_GPOINTER(key, gpointer_type, value, size)
CPAR_ADD_CV_GPOINTER(key, gpointer_type, value, allocate_func, 
                     copy_func, free_func)

CPAR_ADD_MERGE(vp)
CPAR_ADD_MERGE_OVERWRITE(vp)
CPAR_ADD_MERGE_NEW(vp)
CPAR_ADD_MERGE_UPDATE(vp)

CPAR_ADD_TRANSFER(new_key, old_vp, old_key)
CPAR_ADD_TRANSFER_OVERWRITE(new_key, old_vp, old_key)
CPAR_ADD_TRANSFER_NEW(new_key, old_vp, old_key)
CPAR_ADD_TRANSFER_UPDATE(new_key, old_vp, old_key)
    

Most of the basic types are self explanitory. Note that one of the basic types is a pointer to a cpar table. This means you cast nest cpar tables inside each other.

CPAR_ADD_GENERIC() is a little different than the other basic types, because the type is a variable. The advantage of this is more flexibility, but disadvantage is that type checking can't be performed on the value of this function. Use the type-specific versions unless you need to change the type at runtime.

The gpointer type is described in detail in section the section called “Custom pointer types”

Merging cpar tables is described in detail in section the section called “Modifying parameter tables”

Transfering parameters is described in detail in section the section called “Transfer”

There are two families of macro functions for retrieving parameter values.

The "assign" family takes a pointer and assigns the value of the parameter there. They return true if the parameter key was found and assigned to your pointer, false if not.

cpar_table *vp;
char *key;

CPAR_ASSIGN_BOOL(vp, key, pointer)
CPAR_ASSIGN_INT(vp, key, pointer)
CPAR_ASSIGN_UINT(vp, key, pointer)
CPAR_ASSIGN_DOUBLE(vp, key, pointer)
CPAR_ASSIGN_REAL(vp, key, pointer)
CPAR_ASSIGN_STRING(vp, key, pointer)
CPAR_ASSIGN_BOOL_POINTER(vp, key, pointer)
CPAR_ASSIGN_CHAR_POINTER(vp, key, pointer)
CPAR_ASSIGN_INT_POINTER(vp, key, pointer)
CPAR_ASSIGN_UINT_POINTER(vp, key, pointer)
CPAR_ASSIGN_DOUBLE_POINTER(vp, key, pointer)
CPAR_ASSIGN_REAL_POINTER(vp, key, pointer)
CPAR_ASSIGN_CPAR_POINTER(vp, key, pointer)
CPAR_ASSIGN_GPOINTER(vp, key, gpointer_type, pointer)
    

The "get" family return the value of the parameter. The program aborts with failure if vp doesn't exist, or if key doesn't exist in vp.

cpar_table *vp;
char *key;

bool         CPAR_GET_BOOL(vp, key)
int          CPAR_GET_INT(vp, key)
double       CPAR_GET_DOUBLE(vp, key)
real         CPAR_GET_REAL(vp, key)
char *       CPAR_GET_STRING(vp, key)
bool *       CPAR_GET_BOOL_POINTER(vp, key)
char *       CPAR_GET_CHAR_POINTER(vp, key)
int *        CPAR_GET_INT_POINTER(vp, key)
double *     CPAR_GET_DOUBLE_POINTER(vp, key)
real *       CPAR_GET_REAL_POINTER(vp, key)
cpar_table * CPAR_GET_CPAR_POINTER(vp, key)
gpointer     CPAR_GET_GPOINTER(vp, key, gpointer_type)
gpointer     CPAR_GET_RAW(vp, key)
int          CPAR_GET_TYPE(vp, key)
    

CPAR_GET_RAW() returns a gpointer to whatever is in the hash table for the key given. It is different from CPAR_GET_GPOINTER() because it doesn't check that the type of the pointer matches the type given when the parameter was inserted.

CPAR_GET_TYPE() returns the type number used by cpar for the key given.

There are many cases where you will want to change a parameter table before passing it on to to a deeper subroutine. These are the macro functions to modify parameter tables.

CPAR_UPDATE(vp, <parameters>)
CPAR_UPDATE_OVERWRITE(vp, <parameters>)
CPAR_UPDATE_NEW(vp, <parameters>)
CPAR_UPDATE_UPDATE(vp, <parameters>)
    

cpar_table *vp_to, *vp_from;

CPAR_MERGE(vp_to, vp_from)
CPAR_MERGE_OVERWRITE(vp_to, vp_from)
CPAR_MERGE_NEW(vp_to, vp_from)
CPAR_MERGE_UPDATE(vp_to, vp_from)
    

cpar_table *vp;

CPAR_ADD_MERGE(vp)
CPAR_ADD_MERGE_OVERWRITE(vp)
CPAR_ADD_MERGE_NEW(vp)
CPAR_ADD_MERGE_UPDATE(vp)
    

CPAR_UPDATE_OVERWRITE(vp1,
    CPAR_ADD_INT("new parameter", 22),
    CPAR_ADD_MERGE(vp2));
    

CPAR_ADD_TRANSFER(to_key, from_vp, from_key)
CPAR_ADD_TRANSFER_OVERWRITE(to_key, from_vp, from_key)
CPAR_ADD_TRANSFER_NEW(to_key, from_vp, from_key)
CPAR_ADD_TRANSFER_UPDATE(to_key, from_vp, from_key)
    

cpar_table *vp1, *vp2;

CPAR_UPDATE(vp1,
    CPAR_ADD_TRANSFER_OVERWRITE("vp1 parameter", vp2, "vp2 parameter"));
    

cpar can be used as a very easy command-line processor. How to do it is probably best illustrated with code:

int main(int argc, char *argv[])
{
cpar_table *command_line_options = CPAR_CREATE_EMPTY_PARAMETERS();
CPAR_PROCESS_COMMAND_LINE(command_line_options, argc, argv,
    "-n",              CPAR_BOOL,
    "--long-n-option", CPAR_BOOL,
    "-s",              CPAR_STRING,
    "-k",              CPAR_DOUBLE);

printf("This program was called with name %s \n", 
    CPAR_GET_STRING(command_line_options, "program_name"));
if (CPAR_GET_BOOL(command_line_options, "-n") 
    || CPAR_GET_BOOL(command_line_options, "--long-n-option")) 
  {
    printf("-n or --long-n-option was used \n");
  }
if (CPAR_EXISTS(command_line_options, "-s"))
  {
    char *s = CPAR_GET_STRING(command_line_options, "-s");
  }
if (CPAR_EXISTS(command_line_options, "-k"))
  {
    double *k = CPAR_GET_DOUBLE(command_line_options, "-k");
  }
if (CPAR_EXISTS(command_line_options, "commands"))
  {
    printf("commands after options = %s \n", 
        CPAR_GET_STRING(command_line_options, "commands"));
    printf("first command is argv[%d] \n", 
        CPAR_GET_INT(command_line_options, "commands_first_index"));
  }
CPAR_FREE(command_line_options);
}
    

If the above program was called with:

./example -n -s test_string -k 23.5 command1 -a
    

Then `example' is the program name, `-n', `-s', and `-k' are options, `test_string' and `23.5' are option arguments, and `command1' and `-a' are commands.

The cpar macro function CPAR_PROCESS_COMMAND_LINE() takes as many pairs of string,type as you want. For all types except CPAR_BOOL, if the command-line option is missing, the corresponding parameter in the cpar table will not exist. That is why the CPAR_EXISTS() calls are needed in the code above. For type CPAR_BOOL, the parameter will always exist: it is true if the option was given on the command-line, and false if it wasn't. The special parameter "program_name" is set with the name used to call the program.

Options are identified by starting with a `-'. The first command-line argument that doesn't start with `-' is the first command. Also, you will get a warning if the first character of the argument after a non-boolean option is a `-'. For example, if the program above was run as "./example -s -test_string", you will get a warning. This is to catch the case of accidentally forgetting the argument after the option. The first option on the command-line that doesn't begin with a `-' is assumed to be the first command. If there are commands, then the parameter "commands" contains a string consisting of all the commands concatenated with a space between each one. The int parameter "commands_first_index" contains the index of argv[] for the first command.

The seen flag is cleared for all options parameters after the call to CPAR_PROCESS_COMMAND_LINE(). The built-in parameters "program_name", "commands", and "commands_first_index" have the seen flag set. This allows a simple check using CPAR_IS_ALL_SEEN() at the end of command-line processing to make sure you did something with all the command-line options.

Most cpar functions silently return if passed a parameter table with value NULL. This is to allow a calling function to use no extra parameters by just passing the NULL value instead of a CPAR_CREATE_EMPTY_PARAMETERS(). The exceptions are the functions that expect a parameter table:

These functions will abort with an error message if passed a NULL parameter table.

CPAR lets you use a type called "real" for your floating point parameters. This allows you to change your real type to float, double, or long double with just a recompile. This type is defined at compile-time by setting one of the following the preprocessor variables:

CPAR_REAL_TYPE_IS_FLOAT
CPAR_REAL_TYPE_IS_DOUBLE
CPAR_REAL_TYPE_IS_LONG_DOUBLE
    

The default type for real if none of these are defined is double. There are things to watch out for though. Because of the weird way ISO C "promotes" arguments in a variable parameter list, all floats are converted to double when passed using CPAR_ADD_GENERIC(). They are stored in the correct type by the CPAR library, however. Also, if the "real" type is long double and you pass a number using

CPAR_ADD_GENERIC("some key", CPAR_REAL, 1.2E5)
    

The number will be passed on the function argument list as a double, but then read by cpar as a long double. Can you say "segmentation fault"? So be sure to typecast the number:

CPAR_ADD_GENERIC("some key", CPAR_REAL, 1.2E5L)
    

or

CPAR_ADD_GENERIC("some key", CPAR_REAL, (real)(1.2E5))
    

or use the CPAR_ADD_REAL() function which promotes the type correctly.

The CPAR "string" type is similar to the "char pointer" type, except that a copy of the string is made when the parameter is added. It is freed when the cpar_table is freed. Use "char pointer" when you want to be in control of the string memory management, use "string" if you want CPAR to be in charge of it.

For example, in the following code:

void f(cpar_table *vp)
{
char local_string[20] = "a string";
CPAR_UPDATE(vp,
    CPAR_ADD_CHAR_POINTER("test1", local_string));
}

void main(void)
{
cpar_table *vp = CPAR_CREATE_EMPTY_PARAMETERS();
f(vp);
printf("test1 = %s\n", CPAR_GET_CHAR_POINTER(vp, "test1"));
CPAR_FREE(vp);
}
    

vp will hold a pointer to a string that no longer exists after the function returns, so the printf statement will return garbage or segfault. If the string type was used, the code would work as expected.

cpar_table *vp;
CPAR_EXISTS(vp, <keys>)
    

Return true if all the keys in <keys> are in parameter table vp, false otherwise.

See the file example.c in the source directory for an example of all cpar features. This code is mainly intended to be a compile-time test of the library, so it is not very easy to read. For simple example of cpar code, see the section called “Simple example” and the section called “Custom pointer types”.

cpar has a limited number of variable types built in. To extend cpar you can create your own pointer types. To create your own pointer types:

An example:

-------------------------------------------------
/* example.h */
struct test_struct {
  int a;
  double b;
};
extern unsigned int custom_long_double;
extern unsigned int custom_struct;
extern unsigned int custom_function;
#define custom_long_double_TYPECAST(var)  long double *var
#define custom_struct_TYPECAST(var)  struct test_struct *var
#define custom_function_TYPECAST(var)  int (*var)(cpar_table *vp)

-------------------------------------------------
/* example.c */
unsigned int custom_long_double = CPAR_TYPE_UNINITIALIZED;
unsigned int custom_struct = CPAR_TYPE_UNINITIALIZED;
unsigned int custom_function = CPAR_TYPE_UNINITIALIZED;

void subroutine(cpar_table *vp)
{
custom_struct_TYPECAST(t);
custom_long_double_TYPECAST(u); 

u = CPAR_GET_GPOINTER(vp, "key 0", custom_long_double);
t = CPAR_GET_GPOINTER(vp, "key 1", custom_struct);
*u = t->b * t->a;
}

void main(void)
{
cpar_table *vp;
long double ld = 0.0L;
struct test_struct s;
custom_function_TYPECAST(a_function);
CPAR_ASSIGN_POINTER_TYPE(custom_long_double);
CPAR_ASSIGN_POINTER_TYPE(custom_struct);
CPAR_ASSIGN_POINTER_TYPE(custom_function);

s.a = 2;
s.b = 3.4;
a_function = subroutine;
subroutine(
    vp = CPAR_CREATE_PARAMETERS(
        CPAR_ADD_GPOINTER("key 0", custom_long_double, &ld),
        CPAR_ADD_GPOINTER("key 1", custom_struct, &s)
        CPAR_ADD_GPOINTER("key 2", custom_function, a_function)
        )
    );
}
CPAR_FREE(vp);
    

Because the cpar library appends "_TYPECAST" to the global variable holding your custom type, the literal string of your global variable is important, and you must always use the same name.

For gpointer types, there are two ways to store a parameter in cpar: by value and by reference. By value is when the parameter contains the pointer along with the value pointed to, and by reference is when the parameter just contains the pointer to the value. Once you decide to store the value pointed to by a pointer, you have to know more about what you're pointing to. For a simple pointer, like a char pointer to a string, you only need to know the size. This would also be true of a struct like:

struct example {
  char s[50];
  int t;
};
    

because there are no pointers inside the example struct. So for simple cases like this, you only need to specify the size of the value stored, and use this function instead of CPAR_ADD_GPOINTER:

CPAR_ADD_SV_GPOINTER(key, gpointer_type, pointer, size)
    

If the struct you're pointing to has pointers itself, though, it is obviously more complicated to store all the values pointed to by those pointers, because cpar doesn't know anything about your structure. For these cases, you need to write three functions and pass them to cpar so it will know what to do with your structure:

Once you write these functions, you use

CPAR_ADD_CV_GPOINTER(key, gpointer_type, pointer, 
                     allocate_func, copy_func, free_func)
    

within a CPAR_CREATE_PARAMETERS() or CPAR_UPDATE() call to add your structure to the parameter table.

There are a few options when debugging a problem related to the cpar library:

Add the line:

#define CPAR_DEBUG
    

to cpar.h to turn on internal debugging

Use CPAR_LIST(vp) to print a human-readable version of vp to CPAR_ERROR_STREAM (defined in cpar_internal.h as stderr by default)