1 .TH FMTTEST %manext1% "February 19, 2013" "%nmhversion%"
6 fmttest \- test tool for the
17 .RB [ \-address " | " \-raw " | " \-date " | " \-message ]
18 .RB [ \-file " | " \-nofile ]
21 .RB [ \-dupaddrs " | " \-nodupaddrs ]
22 .RB [ \-ccme " | " \-noccme ]
23 .RB [ \-normalize " | " \-nonormalize ]
25 .IR size-in-characters ]
38 .RB [ \-dump " | " \-nodump ]
39 .RB [ \-trace " | " \-notrace ]
41 .RI [ msgs " | " strings ]
45 is used to test programs written for the
47 format language as specified by
49 It is also intended to replace the
56 .SS FORMAT PROGRAM SELECTION
63 switches may be used to specify a format string or a format file to read.
64 If given a format string, it must be specified as a single argument to
67 switch. If given a format file name with
69 the file is searched for using the normal
71 rules: absolute pathnames are accessed directly, tilde expansion is
72 done on usernames, and files are searched for in the user's
74 directory as specified in their profile. If not found there, the directory
75 .RI \*(lq %etcdir% \*(rq
77 .SS MODE SELECTION AND COMPONENT SPECIFICATION
79 has four operating modes: address mode, raw mode, date mode, and message
80 mode. These modes are selected by the
86 switches respectively.
88 Address mode treats every argument as an email address and processes it
89 with nmh's email parser. Each argument is processed with the specified
90 format program with the parsed email address available as a special
92 component escape, and the output from the program is printed on standard output.
93 If there was an error parsing the email address the error message is
96 component escape. If no format program is given on the command line, the
97 following default program is used:
101 %<{error}%{error}: %{text}%|%(putstr(proper{text}))%>
110 In raw mode, no processing of the specified arguments is done. Each argument
111 is run against the specified format program with the argument text available
114 component. You must specify a format with
120 Date mode is identical to raw mode, with one exception: if no format is
121 specified, the following format string is used:
125 %<(nodate{text})error: %{text}%|%(putstr(pretty{text}))%>
129 Date mode is equivalent to
132 In message mode the arguments to
134 are interpreted as an optional folder and messages.
136 will read each specified message and make all of the components in the
137 message available to the format program. Also, the appropriate information
144 function escapes will be made available for each message. If the
146 switch is given, the arguments are interpreted as filenames instead of
147 message numbers, but otherwise the behavior is the same (except that the
152 function escapes will not provide any useful information).
154 The default format used in address mode is the default format used by
156 The following command can replicate the functionality of the
162 fmttest \-nodupaddrs \-form replcomps \-outsize max [+folder] message
166 Regardless of the mode, other components can be provided to the format
167 program by the use of the
169 switch. For example, the following program will test out the use of
171 .RB \*(lq encrypted \*(rq
176 fmttest \-\|\-encrypted yes \-message cur
180 In message mode components supplied on the command line will override
181 components from messages.
182 .SS ADDITIONAL SWITCHES
187 switches control whether duplicate addresses are allowed or suppressed by the
189 instruction, which is used by the
190 .RI `%( formataddr )'
191 function escape. In normal operation duplicate addresses are only
199 switches control whether or not to count the user's local mailbox as a
200 duplicate address. This replicates the behavior of the
213 switches control whether or not email addresses are normalized by the
214 address parsing routines. This is only functional when in address
215 mode and is designed to replicate the switch of the same name to
220 switch controls the maximum number of printable characters that the format
221 engine will produce. Characters marked as non-printing by the format
224 characters with zero width, and extra bytes that are
225 part of a multibyte character are not counted against this total.
226 Two special values are supported:
228 which will set the value
229 to the size of the output buffer, and
230 .RI \*(lq width \*(rq,
232 value to the width of the terminal. In message mode it defaults to the
233 terminal width, otherwise the default is the output buffer size.
237 switch controls the size of the output buffer. By default it is set
240 C preprocessor symbol, which is system-dependent.
244 switch controls the column width which is used by the
246 function escape. By default is set to the terminal width.
254 switches all control the values used, respectively, by the following
261 If none are supplied these values are taken from the message in message mode;
262 in all other modes the default values are 0.
263 .SS COMPILING AND TRACING FORMAT PROGRAMS
266 switch outputs the complete set of format instructions for the specified
269 switch will output each format instruction as it is being
270 executed, and show the values of the
274 registers if they have changed from the previous instruction.
275 The output buffer is also printed if it has changed from the previous
277 .SS FORMAT INSTRUCTIONS
278 It should be noted that there is not a one-to-one correspondence between
279 format escapes and format instructions; many instructions have side
280 effects. Instructions prefixed with
282 generally return a integer into the
284 (value) register; instructions prefixed with a
286 return a string into the
291 .ta \w'LS_DECODECOMP 'u
292 .I "Instruction Description"
293 COMP Output component
294 COMPF Formatted output component
295 LIT Output literal text
296 LITF Formatted literal text output
297 CHAR Output single character
298 NUM Output the \fInum\fR register
299 NUMF Formatted output of the \fInum\fR register
300 STR Output the \fIstr\fR register
301 STRF Formatted output of the \fIstr\fR register
303 PUTADDR Output address list in \fIstr\fR register
304 STRLIT Output \fIstr\fR, no space compression
305 STRLITZ Like \fBSTRLIT\fR, but not counted against width
306 LS_COMP Write component to \fIstr\fR register
307 LS_LIT Write literal to \fIstr\fR register
308 LS_GETENV Write environment var to \fIstr\fR register
309 LS_DECODECOMP Decode RFC 2047 encoded component to \fIstr\fR register
310 LS_DECODE Decode RFC 2047 encoded string to \fIstr\fR register
311 LS_TRIM Trim trailing whitespace from \fIstr\fR register
312 LV_COMP Convert component to integer, store in \fInum\fR register
313 LV_COMPFLAG Set \fInum\fR to 1 if \fBTRUE\fR set in component
314 LV_LIT Load literal value into \fInum\fR register
315 LV_DAT Load value from \fIdat\fR array into \fInum\fR register (see note)
316 LV_STRLEN Set \fInum\fR to the length of \fIstr\fR
317 LV_PLUS_L Add value to \fInum\fR register
318 LV_MINUS_L Substract value from \fInum\fR register
319 LV_DIVIDE_L Divide \fInum\fR register by value
320 LV_MODULO_L \fInum\fR modulo value
321 LV_CHAR_LEFT Store remaining number of printable chars in \fInum\fR
322 LS_MONTH Write short name of month to \fIstr\fR from date component
323 LS_LMONTH Write long name of month to \fIstr\fR from date component
324 LS_ZONE Write time zone offset to \fIstr\fR from date component
325 LS_DAY Write short name of day of week to \fIstr\fR from date component
326 LS_WEEKDAY Write long name of day of week to \fIstr\fR from date component
327 LS_822DATE Write RFC 822 compatible date to \fIstr\fR from date component
328 LS_PRETTY Write date with \*(lqpretty\*(rq timezone to \fIstr\fR
329 LV_SEC Write date component seconds to \fInum\fR
330 LV_MIN Write date component minutes to \fInum\fR
331 LV_HOUR Write date component hour to \fInum\fR
332 LV_MON Write date component numeric month to \fInum\fR (start at 1)
333 LV_YEAR Write date component year to \fInum\fR
334 LV_YDAY Write date component Julian day to \fInum\fR
335 LV_WDAY Write date component day of week to \fInum\fR (0 == Sunday)
336 LV_ZONE Write date component time zone offset to \fInum\fR
337 LV_CLOCK Write date component in Unix epoch time to \fInum\fR
338 LV_RCLOCK Write offset of date component from current time to \fInum\fR
339 LV_DAYF Write 1 to \fInum\fR if day of week is explicit
340 LV_DST Write 1 to \fInum\fR if DST is in effect for date component
341 LV_ZONEF Write 1 to \fInum\fR if timezone is explicit
342 LS_ADDR Write email address of addr component to \fIstr\fR
343 LS_PERS Write personal name of addr component to \fIstr\fR
344 LS_MBOX Write mailbox (username) of addr component to \fIstr\fR
345 LS_HOST Write host of addr component to \fIstr\fR
346 LS_PATH Write host route of addr component to \fIstr\fR
347 LS_GNAME Write group name of addr component to \fIstr\fR
348 LS_NOTE Write note portion of addr component to \fIstr\fR
349 LS_822ADDR Write \*(lqproper\*(rq RFC 822 version of addr component to \fIstr\fR
350 LS_FRIENDLY Write friendly (name or note) of address component to \fIstr\fR
351 LS_UNQUOTE Remove RFC 2822 quotes from string
352 LV_HOSTTYPE Set \fInum\fR to type of host (0=local, 1=network)
353 LV_INGRPF Set \fInum\fR to 1 if address was inside of group
354 LV_NOHOSTF Set \fInum\fR to 1 of no host was present in address component
355 LOCALDATE Convert date component to local timezone
356 GMTDATE Convert date component to GMT
357 PARSEDATE Parse date component
358 PARSEADDR Parse address component
359 FORMATADDR Add address component to list in \fIstr\fR
360 CONCATADDR Like \fBFORMATADDR\fR, but will not suppress duplicates
361 MYMBOX Set \fInum\fR if address component is a local address
362 SAVESTR Save \fIstr\fR register temporarily
365 GOTO Jump to new instruction
366 IF_S_NULL Branch if \fIstr\fR is \fBNULL\fR
367 IF_S Branch if \fIstr\fR is not \fBNULL\fR
368 IF_V_EQ Branch if \fInum\fR is equal to value
369 IF_V_NE Branch if \fInum\fR is not equal to value
370 IF_V_GT Branch if \fInum\fR is greater than value
371 IF_MATCH Branch if \fIstr\fR contains string
372 IF_AMATCH Branch if \fIstr\fR starts with string
373 S_NULL Set \fInum\fR to 1 if \fIstr\fR is \fBNULL\fR
374 S_NONNULL Set \fInum\fR to 1 if \fIstr\fR is not \fBNULL\fR
375 V_EQ Set \fInum\fR to 1 if \fInum\fR equals value
376 V_NE Set \fInum\fR to 1 if \fInum\fR does not equal value
377 V_GT Set \fInum\fR to 1 if \fInum\fR is greater than value
378 V_MATCH Set \fInum\fR to 1 if \fIstr\fR contains string
379 V_AMATCH Set \fInum\fR to 1 if \fIstr\fR starts with string
384 instruction is a bit special. Callers of the format library pass in an
385 array of integers that are used by certain format escapes. The current
386 list of format escapes and the indexes they use are:
394 dat[3] %(\fIwidth\fR)
395 dat[4] %(\fIunseen\fR)
410 It shouldn't require as much code from other programs as it does.