format.h

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