]> diplodocus.org Git - nmh/blob - man/fmttest.man
Temporarily added a few hacks to diagnose problems found by buildbot.
[nmh] / man / fmttest.man
1 .TH FMTTEST %manext1% "February 19, 2013" "%nmhversion%"
2 .\"
3 .\" %nmhwarning%
4 .\"
5 .SH FMTTEST
6 fmttest \- test tool for the
7 .IR mh-format (5)
8 language
9 .SH SYNOPSIS
10 .HP 5
11 .na
12 .B fmttest
13 .RB [ \-form
14 .IR formatfile ]
15 .RB [ \-format
16 .IR formatstring ]
17 .RB [ \-address " | " \-raw " | " \-date " | " \-message ]
18 .RB [ \-file " | " \-nofile ]
19 .RB [ \-\|\-component
20 .IR component-text ]
21 .RB [ \-dupaddrs " | " \-nodupaddrs ]
22 .RB [ \-ccme " | " \-noccme ]
23 .RB [ \-normalize " | " \-nonormalize ]
24 .RB [ \-outsize
25 .IR size-in-characters ]
26 .RB [ \-bufsize
27 .IR size-in-bytes ]
28 .RB [ \-width
29 .IR column-width ]
30 .RB [ \-msgnum
31 .IR number ]
32 .RB [ \-msgcur
33 .IR flag ]
34 .RB [ \-msgsize
35 .IR size ]
36 .RB [ \-unseen
37 .IR flag ]
38 .RB [ \-dump " | " \-nodump ]
39 .RB [ \-trace " | " \-notrace ]
40 .RI [ +folder ]
41 .RI [ msgs " | " strings ]
42 .ad
43 .SH DESCRIPTION
44 .B Fmttest
45 is used to test programs written for the
46 .B nmh
47 format language as specified by
48 .IR mh-format (5).
49 It is also intended to replace the
50 .BR ap ,
51 .BR dp ,
52 and
53 .B fmtdump
54 programs.
55 .PP
56 .SS FORMAT PROGRAM SELECTION
57 The
58 .B \-format
59 .I string
60 and
61 .B \-form
62 .I formatfile
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
65 the
66 .B \-format
67 switch. If given a format file name with
68 .BR \-form ,
69 the file is searched for using the normal
70 .B nmh
71 rules: absolute pathnames are accessed directly, tilde expansion is
72 done on usernames, and files are searched for in the user's
73 .I Mail
74 directory as specified in their profile. If not found there, the directory
75 .RI \*(lq %etcdir% \*(rq
76 is checked.
77 .SS MODE SELECTION AND COMPONENT SPECIFICATION
78 .B Fmttest
79 has four operating modes: address mode, raw mode, date mode, and message
80 mode. These modes are selected by the
81 .BR \-address ,
82 .BR \-raw ,
83 .BR \-date ,
84 and
85 .B \-message
86 switches respectively.
87 .PP
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
91 .RI %{ text }
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
94 stored in the
95 .RI %{ error }
96 component escape. If no format program is given on the command line, the
97 following default program is used:
98 .PP
99 .RS 5
100 .nf
101 %<{error}%{error}: %{text}%|%(putstr(proper{text}))%>
102 .fi
103 .RE
104 .PP
105 In this mode
106 .B fmttest
107 is equivalent to
108 .IR ap (8).
109 .PP
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
112 in the
113 .RI %{ text }
114 component. You must specify a format with
115 .B \-form
116 or
117 .B \-format
118 when using raw mode.
119 .PP
120 Date mode is identical to raw mode, with one exception: if no format is
121 specified, the following format string is used:
122 .PP
123 .RS 5
124 .nf
125 %<(nodate{text})error: %{text}%|%(putstr(pretty{text}))%>
126 .fi
127 .RE
128 .PP
129 Date mode is equivalent to
130 .IR dp (8).
131 .PP
132 In message mode the arguments to
133 .B fmttest
134 are interpreted as an optional folder and messages.
135 .B Fmttest
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
138 for the
139 .RI %( msg ),
140 .RI %( cur ),
141 .RI %( unseen ),
142 and
143 .RI %( size )
144 function escapes will be made available for each message. If the
145 .B \-file
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
148 .RI %( msg ),
149 .RI %( cur ),
150 and
151 .RI %( unseen )
152 function escapes will not provide any useful information).
153 .PP
154 The default format used in address mode is the default format used by
155 .BR scan .
156 The following command can replicate the functionality of the
157 .B repl
158 command.
159 .PP
160 .RS 5
161 .nf
162 fmttest \-nodupaddrs \-form replcomps \-outsize max [+folder] message
163 .fi
164 .RE
165 .PP
166 Regardless of the mode, other components can be provided to the format
167 program by the use of the
168 .B \-\|\-component
169 switch. For example, the following program will test out the use of
170 the
171 .RB \*(lq encrypted \*(rq
172 component:
173 .PP
174 .RS 5
175 .nf
176 fmttest \-\|\-encrypted yes \-message cur
177 .fi
178 .RE
179 .PP
180 In message mode components supplied on the command line will override
181 components from messages.
182 .SS ADDITIONAL SWITCHES
183 The
184 .B \-dupaddrs
185 and
186 .B \-nodupaddrs
187 switches control whether duplicate addresses are allowed or suppressed by the
188 .B FORMATADDR
189 instruction, which is used by the
190 .RI `%( formataddr )'
191 function escape. In normal operation duplicate addresses are only
192 suppressed by
193 .BR repl .
194 .PP
195 The
196 .B \-ccme
197 and
198 .B \-noccme
199 switches control whether or not to count the user's local mailbox as a
200 duplicate address. This replicates the behavior of the
201 .B \-cc
202 .I me
203 switch to
204 .BR repl ,
205 and only applies if
206 .B \-nodupaddrs
207 is in effect.
208 .PP
209 The
210 .B \-normalize
211 and
212 .B \-nonormalize
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
216 .IR ap (8).
217 .PP
218 The
219 .B \-outsize
220 switch controls the maximum number of printable characters that the format
221 engine will produce. Characters marked as non-printing by the format
222 engine with
223 .RI `%( zputlit )',
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:
227 .RI \*(lq max \*(rq,
228 which will set the value
229 to the size of the output buffer, and
230 .RI \*(lq width \*(rq,
231 which will set the
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.
234 .PP
235 The
236 .B \-bufsize
237 switch controls the size of the output buffer. By default it is set
238 to the size of the
239 .B BUFSIZ
240 C preprocessor symbol, which is system-dependent.
241 .PP
242 The
243 .B \-width
244 switch controls the column width which is used by the
245 .RI `%( width )'
246 function escape. By default is set to the terminal width.
247 .PP
248 The
249 .BR \-msgnum ,
250 .BR \-msgcur ,
251 .BR \-msgsize ,
252 and the
253 .B \-unseen
254 switches all control the values used, respectively, by the following
255 function escapes:
256 .RI `%( num )',
257 .RI `%( cur )',
258 .RI `%( size )',
259 and
260 .RI `%( unseen )'.
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
264 The
265 .B \-dump
266 switch outputs the complete set of format instructions for the specified
267 format program. The
268 .B \-trace
269 switch will output each format instruction as it is being
270 executed, and show the values of the
271 .I num
272 and
273 .I str
274 registers if they have changed from the previous instruction.
275 The output buffer is also printed if it has changed from the previous
276 instruction.
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
281 .RI \*(lq LV \*(rq
282 generally return a integer into the
283 .I num
284 (value) register; instructions prefixed with a
285 .RI \*(lq LS \*(rq
286 return a string into the
287 .I str
288 register.
289 .PP
290 .nf
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
302 STRFW Not used
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
363 DONE End program
364 NOP No operation
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
380 .fi
381 .PP
382 The
383 .B LV_DAT
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:
387 .PP
388 .RS 5
389 .nf
390 .ta \w'dat[5]\0\0'u
391 dat[0] %(\fInum\fR)
392 dat[1] %(\fIcur\fR)
393 dat[2] %(\fIsize\fR)
394 dat[3] %(\fIwidth\fR)
395 dat[4] %(\fIunseen\fR)
396 .fi
397 .RE
398 .SH "SEE ALSO"
399 .IR mh-format (5),
400 .IR repl (1),
401 .IR ap (8),
402 .IR dp (8),
403 .SH DEFAULTS
404 .nf
405 .RB ` \-message '
406 .RB ` \-nofile '
407 .RB ` \-dupaddrs '
408 .fi
409 .SH BUGS
410 It shouldn't require as much code from other programs as it does.