Functions for using customized formatting specifiers. More...
Functions | |
| trio_pointer_t | trio_register (trio_callback_t callback, const char *name) |
| Register new user-defined specifier. | |
| void | trio_unregister (trio_pointer_t handle) |
| Unregister an existing user-defined specifier. | |
Functions for using customized formatting specifiers.
SYNOPSIS
cc ... -ltrio -lm #include <trio.h> #include <triop.h>
DESCRIPTION
This documentation is incomplete.
User-defined Specifier
The user-defined specifier consists of a start character (\074 = '<'), an optional namespace string followed by a namespace separator (\072 = ':'), a format string, an optional skipping separator (\174 = '|'), and an end character (\076 = '>').
The namespace string can consist of alphanumeric characters, and is used to define a named reference (see below). The namespace is case-sensitive. If no namespace is specified, then we use an unnamed reference (see below).
The format can consist of any character except the end character ('>'), the namespace separator (':'), the skipping separator ('|'), and the nil character (\000).
Any modifier can be used together with the user-defined specifier.
There are two formats for invoking a user-defined specifier. The first format is an extension of the normal printf/scanf formatting. It uses the percent character (\045 = '') followed by optional qualifiers and a specifier. For example:
trio_printf("%<format>\n", my_handle, my_data);
Some C compilers can issue a warning if there is a mismatch between specifiers and arguments. Unfortunately, these warnings does not work with the first format for user-defined specifiers. Therefore the second format has been introduced. The second format can only be applied to user-defined specifiers.
The second format starts with a dollar character (\044 = '$') instead of the percent character, and is followed by optional qualifiers and the user-defined specifier. If the specifier contains a pipe character (\174 = '|'), then everything between the pipe character and the end character ('>') is ignored. The ignored part can be used to list the normal specifiers that the C compiler uses to determine mismatches. For example:
trio_printf("$<format|%p%p>\n", my_handle, my_data);
Registering
A user-defined specifier must be registered before it can be used. Unregistered user-defined specifiers are ignored. The trio_register function is used to register a user-defined specifier. It takes two argument, a callback function and a namespace, and it returns a handle. The handle must be used to unregister the specifier later.
The following example registers a user-define specifier with the "my_namespace" namespace:
my_handle = trio_register(my_callback, "my_namespace");
There can only be one user-defined specifier with a given namespace. There can be an unlimited number (subject to maximum length of the namespace) of different user-defined specifiers.
Passing NULL as the namespace argument results in an anonymous reference. There can be an unlimited number of anonymous references.
REFERENCES
There are two ways that a registered callback can be called. Either the user-defined specifier must contain the registered namespace in the format string, or the handle is passed as an argument to the formatted printing function.
If the namespace is used, then a user-defined pointer must be passed as an argument:
trio_printf("%<my_namespace:format>\n", my_data);
If the handle is used, then the user-defined specifier must not contain a namespace. Instead the handle must be passed as an argument, followed by a user-defined pointer:
trio_printf("%<format>\n", my_handle, my_data);
The two examples above are equivalent.
There must be exactly one user-defined pointer per user-defined specifier. This pointer can be used within the callback function with the trio_get_argument getter function (see below).
The format string is optional. It can be used within the callback function with the trio_get_format getter function.
Anonymous References Anonymous references are specified by passing NULL as the namespace.
The handle must be passed as an argument followed by a user-defined pointer. No namespace can be specified.
anon_handle = trio_register(callback, NULL);
trio_printf("%<format>\n", anon_handle, my_data);
Restrictions
CALLBACK FUNCTION
The callback function will be called if a matching user-defined specifier is found within the formatting string. The callback function takes one input parameter, an opaque reference which is needed by the private functions. It returns an int, which is currently ignored. The prototype is
int (*trio_callback_t)(void *ref);
See the Example section for full examples.
PRINTING FUNCTIONS
The following printing functions must only be used inside a callback function. These functions will print to the same output medium as the printf function which invoked the callback function. For example, if the user-defined specifier is used in an sprintf function, then these print functions will output their result to the same string.
Elementary Printing
There are a number of function to print elementary data types.
trio_print_int(42);
trio_print_string("Hello World");
trio_print_string(trio_get_format());
Formatted Printing
The functions trio_print_ref, trio_vprint_ref, and trio_printv_ref outputs a formatted string just like its printf equivalents.
trio_print_ref(ref, "There are %d towels\n", 42); trio_print_ref(ref, "%<recursive>\n", recursive_writer, trio_get_argument(ref));
GETTER AND SETTER FUNCTIONS
The following getter and setter functions must only be used inside a callback function. They can either operate on the modifiers or on special data.
Modifiers
The value of a modifier, or a boolean indication of its presence or absence, can be found or set with the getter and setter functions. The generic prototypes of the these getter and setter functions are
int trio_get_???(void *ref); void trio_set_???(void *ref, int);
where ??? refers to a modifier. For example, to get the width of the user-defined specifier use
int width = trio_get_width(ref);
Special Data
Consider the following user-defined specifier, in its two possible referencing presentations.
trio_printf("%<format>\n", namespace_writer, argument);
trio_printf("%<namespace:format>\n", argument);
trio_get_format will get the format string, and trio_get_argument} will get the argument parameter. There are no associated setter functions.
EXAMPLES
The following examples show various types of user-defined specifiers. Although each specifier is demonstrated in isolation, they can all co-exist within the same application.
Time Example
Print the time in the format "HOUR:MINUTE:SECOND" if "time" is specified inside the user-defined specifier.
static int time_print(void *ref)
{
const char *format;
time_t *data;
char buffer[256];
format = trio_get_format(ref);
if ((format) && (strcmp(format, "time") == 0)) {
data = trio_get_argument(ref);
if (data == NULL)
return -1;
strftime(buffer, sizeof(buffer), "%H:%M:%S", localtime(data));
trio_print_string(ref, buffer);
}
return 0;
}
int main(void)
{
void *handle;
time_t now = time(NULL);
handle = trio_register(time_print, "my_time");
trio_printf("%<time>\n", handle, &now);
trio_printf("%<my_time:time>\n", &now);
trio_unregister(handle);
return 0;
}
Complex Numbers Example
Consider a complex number consisting of a real part, re, and an imaginary part, im.
struct Complex {
double re;
double im;
};
This example can print such a complex number in one of two formats. The default format is "re + i im". If the alternative modifier is used, then the format is "r exp(i theta)", where r is the length of the complex vector (re, im) and theta is its angle.
static int complex_print(void *ref)
{
struct Complex *data;
const char *format;
data = (struct Complex *)trio_get_argument(ref);
if (data) {
format = trio_get_format(ref);
if (trio_get_alternative(ref)) {
double r, theta;
r = sqrt(pow(data->re, 2) + pow(data->im, 2));
theta = acos(data->re / r);
trio_print_ref(ref, "%#f exp(i %#f)", r, theta);
} else {
trio_print_ref(ref, "%#f + i %#f", data->re, data->im);
}
}
return 0;
}
int main(void)
{
void *handle;
handle = trio_register(complex_print, "complex");
/* Normal format. With handle and the with namespace */
trio_printf("%<>\n", handle, &complex);
trio_printf("%<complex:>\n", &complex);
/* In exponential notation */
trio_printf("%#<>\n", handle, &complex);
trio_printf("%#<complex:unused data>\n", &complex);
trio_unregister(handle);
return 0;
}
RETURN VALUES
trio_register returns a handle, or NULL if an error occured.
SEE ALSO
NOTES
User-defined specifiers, trio_register, and trio_unregister are not thread-safe. In multi-threaded applications they must be guarded by mutexes. Trio provides two special callback functions, called ":enter" and ":leave", which are invoked every time a thread-unsafe operation is attempted. As the thread model is determined by the application, these callback functions must be implemented by the application.
The following callback functions are for demonstration-purposes only. Replace their bodies with locking and unlocking of a mutex to achieve thread-safety.
static int enter_region(void *ref)
{
fprintf(stderr, "Enter Region\n");
return 1;
}
static int leave_region(void *ref)
{
fprintf(stderr, "Leave Region\n");
return 1;
}
These two callbacks must be registered before other callbacks are registered.
trio_register(enter_region, ":enter"); trio_register(leave_region, ":leave"); another_handle = trio_register(another_callback, NULL);
| trio_pointer_t trio_register | ( | trio_callback_t | callback, |
| const char * | name | ||
| ) |
Register new user-defined specifier.
| callback | |
| name |
| void trio_unregister | ( | trio_pointer_t | handle | ) |
Unregister an existing user-defined specifier.
| handle |