3 * fmt_scan.h -- definitions for fmt_scan()
7 * This structure describes an "interesting" component. It holds
8 * the name & text from the component (if found) and one piece of
9 * auxilary info. The structure for a particular component is located
10 * by (open) hashing the name and using it as an index into the ptr array
11 * "wantcomp". All format entries that reference a particular component
12 * point to its comp struct (so we only have to do component specific
13 * processing once. e.g., parse an address.).
15 * In previous implementations "wantcomp" was made available to other
16 * functions, but now it's private and is accessed via functions.
19 char *c_name; /* component name (in lower case) */
20 char *c_text; /* component text (if found) */
21 struct comp *c_next; /* hash chain linkage */
22 short c_flags; /* misc. flags (from fmt_scan) */
23 short c_type; /* type info (from fmt_compile) */
26 struct mailname *c_u_mn;
28 int c_refcount; /* Reference count */
31 #define c_tws c_un.c_u_tws
32 #define c_mn c_un.c_u_mn
37 #define CT_ADDR (1<<0) /* referenced as address */
38 #define CT_DATE (1<<1) /* referenced as date */
43 #define CF_TRUE (1<<0) /* usually means component is present */
44 #define CF_PARSED (1<<1) /* address/date has been parsed */
45 #define CF_DATEFAB (1<<2) /* datefield fabricated */
46 #define CF_TRIMMED (1<<3) /* Component has been trimmed */
51 * This structure defines one formatting instruction.
56 short f_width; /* output field width */
58 struct comp *f_u_comp; /* associated component */
59 char *f_u_text; /* literal text */
60 char f_u_char; /* literal character */
61 int f_u_value; /* literal value */
63 short f_flags; /* misc. flags */
66 #define f_skip f_width /* instr to skip (false "if") */
68 #define f_comp f_un.f_u_comp
69 #define f_text f_un.f_u_text
70 #define f_char f_un.f_u_char
71 #define f_value f_un.f_u_value
77 #define FF_STRALLOC (1<<0) /* String has been allocated */
78 #define FF_COMPREF (1<<1) /* Component reference */
81 * prototypes used by the format engine
85 * Create a new format string. Arguments are:
87 * form - Name of format file. Will be searched by etcpath(), see that
88 * function for details.
89 * format - The format string to be used if no format file is given
90 * default_fs - The default format string to be used if neither form nor
93 * This function also takes care of processing \ escapes like \n, \t, etc.
95 * Returns an allocated format string.
98 char *new_fs (char *form, char *format, char *default_fs);
101 * Compile a format string into a set of format instructions. Arguments are:
103 * fstring - The format string (the "source code").
104 * fmt - Returns an allocated array of "struct fmt" elements. Each
105 * struct fmt is one format instruction interpreted by the
107 * reset - If set to true, the format compiler will reset the
108 * component hash table. The component hash table contains
109 * all of the references to message components refered to in
110 * the format instructions. If you have multiple format
111 * strings that you want to compile and operate on the
112 * same message, this should be set to false.
114 * Returns the total number of components referenced by all format instructions
115 * since the last reset of the hash table.
118 int fmt_compile (char *fstring, struct format **fmt, int reset);
121 * Interpret a sequence of compiled format instructions. Arguments are:
123 * format - Array of format instructions generated by fmt_compile()
124 * scanl - Passed-in character array that will contain the output
125 * of the format instructions. Is always terminated with
127 * max - Maximum number of bytes to be written to "scanl" (in other
128 * words, the buffer size). Includes the trailing NUL.
129 * width - Maximum number of displayed characters. Does not include
130 * characters marked as nonprinting or (depending on the
131 * encoding) bytes in a multibyte encoding that exceed the
132 * character's column width.
133 * dat - An integer array that contains data used by certain format
134 * functions. Currently the following instructions use
137 * dat[0] - %(msg), %(dat)
143 * The return value is a pointer to the next format instruction to
144 * execute, which is currently always NULL.
147 struct format *fmt_scan (struct format *format, char *scanl, size_t max,
148 int width, int *dat);
151 * Free a format structure and/or component hash table. Arguments are:
153 * format - An array of format structures allocated by fmt_compile,
155 * reset - If true, reset and remove all references in the component
159 void fmt_free (struct format *fmt, int reset);
162 * Search for a component structure in the component hash table. Arguments are:
164 * component - The name of the component to search for. By convention
165 * all component names used in format strings are lower case,
166 * but for backwards compatibility this search is done in
167 * a case-SENSITIVE manner.
169 * This function returns a "struct comp" corresponding to the named component,
170 * or NULL if the component is not found in the hash table.
173 struct comp *fmt_findcomp(char *component);
176 * Add a string to a component hash table entry. Arguments are:
178 * component - The name of the component to add text to. The component
179 * is searched for in a case-INSENSITIVE manner (note that
180 * this is different than fmt_findcomp()). If the component
181 * is not found in the hash table, this function will silently
183 * text - The text to add to a component hash table entry. Note that
184 * if the last character of the existing component
185 * text is a newline AND it is marked as an address
186 * component (the the CT_ADDR flag is set) existing
187 * component buffer is a newline, it will be separated
188 * from previous text by ",\n\t"; otherwise if the last
189 * character of the previous text is a newline it will
190 * simply be seperated by a "\t". This unusual processing
191 * is designed to handle the case where you have multiple
192 * headers with the same name (e.g.: multiple "cc:" headers,
193 * even though that isn't technically allowed in the RFCs).
195 * This function is designed to be called when you start processing a new
196 * component. The function returns the integer value of the hash table
197 * bucket corresponding to this component. If there was no entry found
198 * in the component hash table, this function will return -1.
201 int fmt_addcomp(char *component, char *text);
204 * Append to an existing component. Arguments are:
206 * bucket - The hash table bucket corresponding to this component,
207 * as returned by fmt_addcomp(). If -1, this function will
208 * return with no actions performed.
209 * component - The component to append text to. Like fmt_addcomp, the
210 * component is searched case-INSENSITIVELY.
211 * text - The text to append to the component. No special processing
214 * This function is designed to be called when you are processing continuation
215 * lines on the same header (state == FLDPLUS).
218 void fmt_appendcomp(int bucket, char *component, char *text);
221 * The implementation of the %(formataddr) function. This is available for
222 * programs to provide their own local implementation if they wish to do
223 * special processing (see uip/replsbr.c for an example). Arguments are:
225 * orig - Existing list of addresses
226 * str - New address(es) to append to list.
228 * This function returns an allocated string containing the new list of
232 char *formataddr(char *orig, char *str);
235 * The implementation of the %(concataddr) function. Arguments and behavior
236 * are the same as %(formataddr). Again, see uip/replsbr.c to see how you
237 * can override this behavior.
240 char *concataddr(char *orig, char *str);