User handling improvments.
[adu.git] / 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);