Pileus Git - ~andy/fetchmail/blob - trio/doc/doc_register.h

   1 /*************************************************************************
   2  *
   3  * $Id: doc_register.h,v 1.2 2002/04/20 13:28:09 breese Exp $
   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, and an end character (\076 = '>').
  39
  40 The namespace string can consist of alphanumeric characters, and is used to
  41 define a named reference (see below). The namespace is case-sensitive. If no
  42 namespace is specified, then we use an unnamed reference (see below).
  43
  44 The format can consist of any character except the end character ('>'), the
  45 namespace separator (':'), and the nil character (\000).
  46
  47 Any modifier can be used together with the user-defined specifier.
  48
  49 @b Registering
  50
  51 A user-defined specifier must be registered before it can be used.
  52 Unregistered user-defined specifiers are ignored. The @ref trio_register
  53 function is used to register a user-defined specifier. It takes two argument,
  54 a callback function and a namespace, and it returns a handle. The handle must
  55 be used to unregister the specifier later.
  56
  57 The following example registers a user-define specifier with the "my_namespace"
  58 namespace:
  59
  60 @verbatim
  61   my_handle = trio_register(my_callback, "my_namespace");
  62 @endverbatim
  63
  64 There can only be one user-defined specifier with a given namespace. There
  65 can be an unlimited number (subject to maximum length of the namespace) of
  66 different user-defined specifiers.
  67
  68 Passing NULL as the namespace argument results in an anonymous reference.
  69 There can be an unlimited number of anonymous references.
  70
  71 @b REFERENCES
  72
  73 There are two ways that a registered callback can be called. Either the
  74 user-defined specifier must contain the registered namespace in the format
  75 string, or the handle is passed as an argument to the formatted printing
  76 function.
  77
  78 If the namespace is used, then a user-defined pointer must be passed as an
  79 argument:
  80
  81 @verbatim
  82   trio_printf("<my_namespace:format>\n", my_data);
  83 @endverbatim
  84
  85 If the handle is used, then the user-defined specifier must not contain a
  86 namespace. Instead the handle must be passed as an argument, followed by a
  87 user-defined pointer:
  88
  89 @verbatim
  90   trio_printf("<format>\n", my_handle, my_data);
  91 @endverbatim
  92
  93 The two examples above are equivalent.
  94
  95 There must be exactly one user-defined pointer per user-defined specifier.
  96 This pointer can be used within the callback function with the
  97 @ref trio_get_argument getter function (see below).
  98
  99 The format string is optional. It can be used within the callback function
 100 with the @ref trio_get_format getter function.
 101
 102 @b Anonymous @b References
 103 Anonymous references are specified by passing NULL as the namespace.
 104
 105 The handle must be passed as an argument followed by a user-defined pointer.
 106 No namespace can be specified.
 107
 108 @verbatim
 109   anon_handle = trio_register(callback, NULL);
 110   trio_printf("<format>\n", anon_handle, my_data);
 111 @endverbatim
 112
 113 @b Restrictions
 114
 115 @li The length of the namespace string cannot exceed 63 characters.
 116 @li The length of the user-defined format string cannot exceed 255 characters.
 117 @li User-defined formatting cannot re-define existing specifiers.
 118 This restriction was imposed because the existing formatting specifiers have
 119 a well-defined behaviour, and any re-definition would apply globally to an
 120 application (imagine a third-party library changing the behaviour of a
 121 specifier that is crusial to your application).
 122
 123 @b CALLBACK @b FUNCTION
 124
 125 The callback function will be called if a matching user-defined specifier
 126 is found within the formatting string. The callback function takes one input
 127 parameter, an opaque reference which is needed by the private functions. It
 128 returns an @c int, which is currently ignored. The prototype is
 129
 130 @verbatim
 131   int (*trio_callback_t)(void *ref);
 132 @endverbatim
 133
 134 See the Example section for full examples.
 135
 136 @b PRINTING @b FUNCTIONS
 137
 138 The following printing functions must only be used inside a callback function.
 139 These functions will print to the same output medium as the printf function
 140 which invoked the callback function. For example, if the user-defined
 141 specifier is used in an sprintf function, then these print functions will
 142 output their result to the same string.
 143
 144 @b Elementary @b Printing
 145
 146 There are a number of function to print elementary data types.
 147
 148 @li @ref trio_print_int Print a signed integer. For example:
 149 @verbatim
 150   trio_print_int(42);
 151 @endverbatim
 152 @li @ref trio_print_uint Print an unsigned integer.
 153 @li @ref trio_print_double Print a floating-point number.
 154 @li @ref trio_print_string Print a string. For example:
 155 @verbatim
 156   trio_print_string("Hello World");
 157   trio_print_string(trio_get_format());
 158 @endverbatim
 159 @li @ref trio_print_pointer Print a pointer.
 160
 161 @b Formatted @b Printing
 162
 163 The functions @ref trio_print_ref, @ref trio_vprint_ref, and
 164 @ref trio_printv_ref outputs a formatted string just like its printf
 165 equivalents.
 166
 167 @verbatim
 168   trio_print_ref(ref, "There are %d towels\n", 42);
 169   trio_print_ref(ref, "%<recursive>\n", recursive_writer, trio_get_argument());
 170 @endverbatim
 171
 172 @b GETTER @b AND @b SETTER @b FUNCTIONS
 173
 174 The following getter and setter functions must only be used inside a callback
 175 function. They can either operate on the modifiers or on special data.
 176
 177 @b Modifiers
 178
 179 The value of a modifier, or a boolean indication of its presence or absence,
 180 can be found or set with the getter and setter functions.
 181 The generic prototypes of the these getter and setter functions are
 182
 183 @verbatim
 184   int  trio_get_???(void *ref);
 185   void trio_set_???(void *ref, int);
 186 @endverbatim
 187
 188 where @c ??? refers to a modifier. For example, to get the width of the
 189 user-defined specifier use
 190
 191 @verbatim
 192   int width = trio_get_width(ref);
 193 @endverbatim
 194
 195 @b Special @b Data
 196
 197 Consider the following user-defined specifier, in its two possible referencing
 198 presentations.
 199
 200 @verbatim
 201   trio_printf("%<format>\n", namespace_writer, argument);
 202   trio_printf("%<namespace:format>\n", argument);
 203 @endverbatim
 204
 205 @ref trio_get_format will get the @p format string, and
 206 @ref trio_get_argument} will get the @p argument parameter.
 207 There are no associated setter functions.
 208
 209 @b EXAMPLES
 210
 211 The following examples show various types of user-defined specifiers. Although
 212 each specifier is demonstrated in isolation, they can all co-exist within the
 213 same application.
 214
 215 @b Time @b Example
 216
 217 Print the time in the format "HOUR:MINUTE:SECOND" if "time" is specified inside
 218 the user-defined specifier.
 219
 220 @verbatim
 221   static int time_writer(void *ref)
 222   {
 223     const char *format;
 224     time_t *data;
 225     char buffer[256];
 226
 227     format = trio_get_format(ref);
 228     if ((format) && (strcmp(format, "time") == 0)) {
 229       data = trio_get_argument(ref);
 230       if (data == NULL)
 231         return -1;
 232       strftime(buffer, sizeof(buffer), "%H:%M:%S", localtime(data));
 233       trio_print_string(ref, buffer);
 234     }
 235     return 0;
 236   }
 237 @endverbatim
 238
 239 @verbatim
 240   int main(void)
 241   {
 242     void *handle;
 243     time_t now = time(NULL);
 244
 245     handle = trio_register(time_print, "my_time");
 246
 247     trio_printf("%<time>\n", handle, &now);
 248     trio_printf("%<my_time:time>\n", &now);
 249
 250     trio_unregister(handle);
 251     return 0;
 252   }
 253 @endverbatim
 254
 255 @b Complex @b Numbers @b Example
 256
 257 Consider a complex number consisting of a real part, re, and an imaginary part,
 258 im.
 259
 260 @verbatim
 261   struct Complex {
 262     double re;
 263     double im;
 264   };
 265 @endverbatim
 266
 267 This example can print such a complex number in one of two formats.
 268 The default format is "re + i im". If the alternative modifier is used, then
 269 the format is "r exp(i theta)", where r is the length of the complex vector
 270 (re, im) and theta is its angle.
 271
 272 @verbatim
 273   static int complex_print(void *ref)
 274   {
 275     struct Complex *data;
 276     const char *format;
 277
 278     data = (struct Complex *)trio_get_argument(ref);
 279     if (data) {
 280       format = trio_get_format(ref);
 281
 282       if (trio_get_alternative(ref)) {
 283         double r, theta;
 284
 285         r = sqrt(pow(data->re, 2) + pow(data->im, 2));
 286         theta = acos(data->re / r);
 287         trio_print_ref(ref, "%#f exp(i %#f)", r, theta);
 288
 289       } else {
 290         trio_print_ref(ref, "%#f + i %#f", data->re, data->im);
 291       }
 292     }
 293     return 0;
 294   }
 295 @endverbatim
 296
 297 @verbatim
 298   int main(void)
 299   {
 300     void *handle;
 301
 302     handle = trio_register(complex_print, "complex");
 303
 304     /* Normal format. With handle and the with namespace */
 305     trio_printf("%<>\n", handle, &complex);
 306     trio_printf("%<complex:>\n", &complex);
 307     /* In exponential notation */
 308     trio_printf("%#<>\n", handle, &complex);
 309     trio_printf("%#<complex:unused data>\n", &complex);
 310
 311     trio_unregister(handle);
 312     return 0;
 313   }
 314 @endverbatim
 315
 316 @b RETURN @b VALUES
 317
 318 @ref trio_register returns a handle, or NULL if an error occured.
 319
 320 @b SEE @b ALSO
 321
 322 @ref trio_printf
 323
 324 @b NOTES
 325
 326 User-defined specifiers, @ref trio_register, and @ref trio_unregister are
 327 not thread-safe. In multi-threaded applications they must be guarded by
 328 mutexes. Trio provides two special callback functions, called ":enter" and
 329 ":leave", which are invoked every time a thread-unsafe operation is attempted.
 330 As the thread model is determined by the application, these callback functions
 331 must be implemented by the application.
 332
 333 The following callback functions are for demonstration-purposes only.
 334 Replace their bodies with locking and unlocking of a mutex to achieve
 335 thread-safety.
 336 @verbatim
 337   static int enter_region(void *ref)
 338   {
 339     fprintf(stderr, "Enter Region\n");
 340     return 1;
 341   }
 342
 343   static int leave_region(void *ref)
 344   {
 345     fprintf(stderr, "Leave Region\n");
 346     return 1;
 347   }
 348 @endverbatim
 349 These two callbacks must be registered before other callbacks are registered.
 350 @verbatim
 351   trio_register(enter_region, ":enter");
 352   trio_register(leave_region, ":leave");
 353
 354   another_handle = trio_register(another_callback, NULL);
 355 @endverbatim
 356
 357 */