1 /************************************************************************* 2 * 3 * $Id$ 4 * 5 * Copyright (C) 2001 Bjorn Reese and Daniel Stenberg. 6 * 7 * Permission to use, copy, modify, and distribute this software for any 8 * purpose with or without fee is hereby granted, provided that the above 9 * copyright notice and this permission notice appear in all copies. 10 * 11 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED 12 * WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF 13 * MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE AUTHORS AND 14 * CONTRIBUTORS ACCEPT NO RESPONSIBILITY IN ANY CONCEIVABLE MANNER. 15 * 16 ************************************************************************/ 17 18 /** @addtogroup UserDefined User-defined Formatted Printing Functions. 19 Functions for using customized formatting specifiers. 20 21 @b SYNOPSIS 22 23 @verbatim 24 cc ... -ltrio -lm 25 26 #include <trio.h> 27 #include <triop.h> 28 @endverbatim 29 30 @b DESCRIPTION 31 32 This documentation is incomplete. 33 34 @b User-defined @b Specifier 35 36 The user-defined specifier consists of a start character (\\074 = '<'), an 37 optional namespace string followed by a namespace separator (\\072 = ':'), 38 a format string, an optional skipping separator (\\174 = '|'), and an end 39 character (\\076 = '>'). 40 41 The namespace string can consist of alphanumeric characters, and is used to 42 define a named reference (see below). The namespace is case-sensitive. If no 43 namespace is specified, then we use an unnamed reference (see below). 44 45 The format can consist of any character except the end character ('>'), the 46 namespace separator (':'), the skipping separator ('|'), and the nil character 47 (\\000). 48 49 Any modifier can be used together with the user-defined specifier. 50 51 There are two formats for invoking a user-defined specifier. The first format 52 is an extension of the normal printf/scanf formatting. It uses the percent 53 character (\\045 = '%') followed by optional qualifiers and a specifier. For 54 example: 55 56 @verbatim 57 trio_printf("%<format>\n", my_handle, my_data); 58 @endverbatim 59 60 Some C compilers can issue a warning if there is a mismatch between specifiers 61 and arguments. Unfortunately, these warnings does not work with the first 62 format for user-defined specifiers. Therefore the second format has been 63 introduced. The second format can only be applied to user-defined specifiers. 64 65 The second format starts with a dollar character (\\044 = '$') instead of the 66 percent character, and is followed by optional qualifiers and the user-defined 67 specifier. If the specifier contains a pipe character (\\174 = '|'), then 68 everything between the pipe character and the end character ('>') is ignored. 69 The ignored part can be used to list the normal specifiers that the C compiler 70 uses to determine mismatches. For example: 71 72 @verbatim 73 trio_printf("$<format|%p%p>\n", my_handle, my_data); 74 @endverbatim 75 76 @b Registering 77 78 A user-defined specifier must be registered before it can be used. 79 Unregistered user-defined specifiers are ignored. The @ref trio_register 80 function is used to register a user-defined specifier. It takes two argument, 81 a callback function and a namespace, and it returns a handle. The handle must 82 be used to unregister the specifier later. 83 84 The following example registers a user-define specifier with the "my_namespace" 85 namespace: 86 87 @verbatim 88 my_handle = trio_register(my_callback, "my_namespace"); 89 @endverbatim 90 91 There can only be one user-defined specifier with a given namespace. There 92 can be an unlimited number (subject to maximum length of the namespace) of 93 different user-defined specifiers. 94 95 Passing NULL as the namespace argument results in an anonymous reference. 96 There can be an unlimited number of anonymous references. 97 98 @b REFERENCES 99 100 There are two ways that a registered callback can be called. Either the 101 user-defined specifier must contain the registered namespace in the format 102 string, or the handle is passed as an argument to the formatted printing 103 function. 104 105 If the namespace is used, then a user-defined pointer must be passed as an 106 argument: 107 108 @verbatim 109 trio_printf("%<my_namespace:format>\n", my_data); 110 @endverbatim 111 112 If the handle is used, then the user-defined specifier must not contain a 113 namespace. Instead the handle must be passed as an argument, followed by a 114 user-defined pointer: 115 116 @verbatim 117 trio_printf("%<format>\n", my_handle, my_data); 118 @endverbatim 119 120 The two examples above are equivalent. 121 122 There must be exactly one user-defined pointer per user-defined specifier. 123 This pointer can be used within the callback function with the 124 @ref trio_get_argument getter function (see below). 125 126 The format string is optional. It can be used within the callback function 127 with the @ref trio_get_format getter function. 128 129 @b Anonymous @b References 130 Anonymous references are specified by passing NULL as the namespace. 131 132 The handle must be passed as an argument followed by a user-defined pointer. 133 No namespace can be specified. 134 135 @verbatim 136 anon_handle = trio_register(callback, NULL); 137 trio_printf("%<format>\n", anon_handle, my_data); 138 @endverbatim 139 140 @b Restrictions 141 142 @li The length of the namespace string cannot exceed 63 characters. 143 @li The length of the user-defined format string cannot exceed 255 characters. 144 @li User-defined formatting cannot re-define existing specifiers. 145 This restriction was imposed because the existing formatting specifiers have 146 a well-defined behaviour, and any re-definition would apply globally to an 147 application (imagine a third-party library changing the behaviour of a 148 specifier that is crusial to your application). 149 150 @b CALLBACK @b FUNCTION 151 152 The callback function will be called if a matching user-defined specifier 153 is found within the formatting string. The callback function takes one input 154 parameter, an opaque reference which is needed by the private functions. It 155 returns an @c int, which is currently ignored. The prototype is 156 157 @verbatim 158 int (*trio_callback_t)(void *ref); 159 @endverbatim 160 161 See the Example section for full examples. 162 163 @b PRINTING @b FUNCTIONS 164 165 The following printing functions must only be used inside a callback function. 166 These functions will print to the same output medium as the printf function 167 which invoked the callback function. For example, if the user-defined 168 specifier is used in an sprintf function, then these print functions will 169 output their result to the same string. 170 171 @b Elementary @b Printing 172 173 There are a number of function to print elementary data types. 174 175 @li @ref trio_print_int Print a signed integer. For example: 176 @verbatim 177 trio_print_int(42); 178 @endverbatim 179 @li @ref trio_print_uint Print an unsigned integer. 180 @li @ref trio_print_double Print a floating-point number. 181 @li @ref trio_print_string Print a string. For example: 182 @verbatim 183 trio_print_string("Hello World"); 184 trio_print_string(trio_get_format()); 185 @endverbatim 186 @li @ref trio_print_pointer Print a pointer. 187 188 @b Formatted @b Printing 189 190 The functions @ref trio_print_ref, @ref trio_vprint_ref, and 191 @ref trio_printv_ref outputs a formatted string just like its printf 192 equivalents. 193 194 @verbatim 195 trio_print_ref(ref, "There are %d towels\n", 42); 196 trio_print_ref(ref, "%<recursive>\n", recursive_writer, trio_get_argument(ref)); 197 @endverbatim 198 199 @b GETTER @b AND @b SETTER @b FUNCTIONS 200 201 The following getter and setter functions must only be used inside a callback 202 function. They can either operate on the modifiers or on special data. 203 204 @b Modifiers 205 206 The value of a modifier, or a boolean indication of its presence or absence, 207 can be found or set with the getter and setter functions. 208 The generic prototypes of the these getter and setter functions are 209 210 @verbatim 211 int trio_get_???(void *ref); 212 void trio_set_???(void *ref, int); 213 @endverbatim 214 215 where @c ??? refers to a modifier. For example, to get the width of the 216 user-defined specifier use 217 218 @verbatim 219 int width = trio_get_width(ref); 220 @endverbatim 221 222 @b Special @b Data 223 224 Consider the following user-defined specifier, in its two possible referencing 225 presentations. 226 227 @verbatim 228 trio_printf("%<format>\n", namespace_writer, argument); 229 trio_printf("%<namespace:format>\n", argument); 230 @endverbatim 231 232 @ref trio_get_format will get the @p format string, and 233 @ref trio_get_argument} will get the @p argument parameter. 234 There are no associated setter functions. 235 236 @b EXAMPLES 237 238 The following examples show various types of user-defined specifiers. Although 239 each specifier is demonstrated in isolation, they can all co-exist within the 240 same application. 241 242 @b Time @b Example 243 244 Print the time in the format "HOUR:MINUTE:SECOND" if "time" is specified inside 245 the user-defined specifier. 246 247 @verbatim 248 static int time_print(void *ref) 249 { 250 const char *format; 251 time_t *data; 252 char buffer[256]; 253 254 format = trio_get_format(ref); 255 if ((format) && (strcmp(format, "time") == 0)) { 256 data = trio_get_argument(ref); 257 if (data == NULL) 258 return -1; 259 strftime(buffer, sizeof(buffer), "%H:%M:%S", localtime(data)); 260 trio_print_string(ref, buffer); 261 } 262 return 0; 263 } 264 @endverbatim 265 266 @verbatim 267 int main(void) 268 { 269 void *handle; 270 time_t now = time(NULL); 271 272 handle = trio_register(time_print, "my_time"); 273 274 trio_printf("%<time>\n", handle, &now); 275 trio_printf("%<my_time:time>\n", &now); 276 277 trio_unregister(handle); 278 return 0; 279 } 280 @endverbatim 281 282 @b Complex @b Numbers @b Example 283 284 Consider a complex number consisting of a real part, re, and an imaginary part, 285 im. 286 287 @verbatim 288 struct Complex { 289 double re; 290 double im; 291 }; 292 @endverbatim 293 294 This example can print such a complex number in one of two formats. 295 The default format is "re + i im". If the alternative modifier is used, then 296 the format is "r exp(i theta)", where r is the length of the complex vector 297 (re, im) and theta is its angle. 298 299 @verbatim 300 static int complex_print(void *ref) 301 { 302 struct Complex *data; 303 const char *format; 304 305 data = (struct Complex *)trio_get_argument(ref); 306 if (data) { 307 format = trio_get_format(ref); 308 309 if (trio_get_alternative(ref)) { 310 double r, theta; 311 312 r = sqrt(pow(data->re, 2) + pow(data->im, 2)); 313 theta = acos(data->re / r); 314 trio_print_ref(ref, "%#f exp(i %#f)", r, theta); 315 316 } else { 317 trio_print_ref(ref, "%#f + i %#f", data->re, data->im); 318 } 319 } 320 return 0; 321 } 322 @endverbatim 323 324 @verbatim 325 int main(void) 326 { 327 void *handle; 328 329 handle = trio_register(complex_print, "complex"); 330 331 /* Normal format. With handle and the with namespace */ 332 trio_printf("%<>\n", handle, &complex); 333 trio_printf("%<complex:>\n", &complex); 334 /* In exponential notation */ 335 trio_printf("%#<>\n", handle, &complex); 336 trio_printf("%#<complex:unused data>\n", &complex); 337 338 trio_unregister(handle); 339 return 0; 340 } 341 @endverbatim 342 343 @b RETURN @b VALUES 344 345 @ref trio_register returns a handle, or NULL if an error occured. 346 347 @b SEE @b ALSO 348 349 @ref trio_printf 350 351 @b NOTES 352 353 User-defined specifiers, @ref trio_register, and @ref trio_unregister are 354 not thread-safe. In multi-threaded applications they must be guarded by 355 mutexes. Trio provides two special callback functions, called ":enter" and 356 ":leave", which are invoked every time a thread-unsafe operation is attempted. 357 As the thread model is determined by the application, these callback functions 358 must be implemented by the application. 359 360 The following callback functions are for demonstration-purposes only. 361 Replace their bodies with locking and unlocking of a mutex to achieve 362 thread-safety. 363 @verbatim 364 static int enter_region(void *ref) 365 { 366 fprintf(stderr, "Enter Region\n"); 367 return 1; 368 } 369 370 static int leave_region(void *ref) 371 { 372 fprintf(stderr, "Leave Region\n"); 373 return 1; 374 } 375 @endverbatim 376 These two callbacks must be registered before other callbacks are registered. 377 @verbatim 378 trio_register(enter_region, ":enter"); 379 trio_register(leave_region, ":leave"); 380 381 another_handle = trio_register(another_callback, NULL); 382 @endverbatim 383 384 */ 385