format.h

   1 /** \file format.h Exported symbols from \p format.c. */
   2
   3 /** The possible types of format string directives (aka atoms). */
   4 enum atom_type {
   5         /** String, supports alignment and width. */
   6         AT_STRING,
   7         /** Used for user IDs, supports alignment and width. */
   8         AT_ID,
   9         /**
  10          *  Used for number of files/directories, supports alignment,
  11          *  width, unit.
  12          */
  13         AT_COUNT,
  14         /**
  15          * Used for number of bytes. Like \p AT_COUNT, but the unit is
  16          * treated differently: By default, 1024 is used as the base,
  17          * and low numbers get a "b" (bytes) appended which does not make
  18          * sense for counters.
  19          */
  20         AT_SIZE
  21 };
  22
  23 /**
  24  * One format string directive.
  25  *
  26  * Each application must define its own set of valid atoms as an array
  27  * of struct atom. The \ref parse_format_string() function takes a format
  28  * string and the array of valid atoms and returns an opaque pointer to
  29  * a struct \a format_info.
  30  *
  31  * At a later time the application may pass the \a format_info pointer
  32  * together with the current value for each atom to \a format_items() which
  33  * returns these values, formated according to the format string which has
  34  * been passed to parse_format_string() previously.
  35  *
  36  * Usually, the application will call parse_format_string() only once, but
  37  * format_items() many times.
  38  */
  39 struct atom {
  40         /** The name of the directive. */
  41         const char const *name;
  42         /** Its type. */
  43         enum atom_type type;
  44 };
  45
  46 /**
  47  * The current value of one atom.
  48  *
  49  * An array of this type, whose entries must match the array of valid atoms,
  50  * may be passed to format_items() to obtain a formated string.
  51  */
  52 union atom_value {
  53         /** Used for atoms of type string. */
  54         char *string_value;
  55         /** Used for atoms not of type string. */
  56         long long unsigned num_value;
  57 };
  58
  59 /**
  60  * The details of this structure are only relevant to the functions in \p
  61  * format.c.
  62  */
  63 struct format_info;
  64
  65 int parse_format_string(char *fmt, struct atom *atoms,
  66                 struct format_info **result);
  67 char *format_items(struct format_info *info, union atom_value *values);
  68 void free_format_info(struct format_info *info);