1FMTTEST(1) General Commands Manual FMTTEST(1)
2
6 fmttest - test programs in nmh's mh-format(5) language
7
9 fmttest [-help] [-version] [-form formatfile] [-format formatstring]
10 [-address | -raw | -date | -message] [-file | -nofile] [--compo‐
11 nent component-text] [-dupaddrs | -nodupaddrs] [-ccme | -noccme]
12 [-outsize size-in-characters] [-width column-width] [-msgnum num‐
13 ber] [-msgcur flag] [-msgsize size] [-unseen flag] [-dump |
14 -nodump] [-trace | -notrace] [+folder] [msgs | strings]
15
17 fmttest is used to test programs written for the nmh format language as
18 specified by mh-format(5). It is also intended to replace the ap, dp,
19 and fmtdump programs.
20 Format Program Selection
22 The -format string and -form formatfile specify a format string or file
23 to read. A format string, if given, must be a single argument to the
24 -format switch. If a format file name is passed to the -form, switch,
25 the file is searched for using the normal nmh rules: absolute pathnames
26 are accessed directly, tilde expansion is done on usernames, and files
27 are searched for in the user's Mail directory as specified in their
28 profile. If not found there, the directory “/etc/nmh” is checked.
29 Mode Selection and Component Specification
31 fmttest has four operating modes - address, raw, date, and message -
32 which are selected by the -address, -raw, -date, and -message switches,
33 respectively.
34 Address mode treats every argument as an email address to be processed
36 by nmh's email parser using the specified format program. The parsed
37 address is made available as a special %{text} component escape, and
38 the output from the program is printed on standard output. If there
39 was an error parsing the email address the error message is stored in
40 the %{error} component escape. If no format program is given on the
41 command line, the following default program is used:
42 %<{error}%{error}: %{text}%|%(putstr(proper{text}))%>
44 Address mode is equivalent to ap(8).
46 In raw mode, no processing of the specified arguments is done. Each
48 argument is run against the specified format program with the argument
49 text available in the %{text} component. You must specify a format
50 with -form or -format when using raw mode.
51 Date mode is identical to raw mode, with one exception: if no format is
53 specified, the following format string is used:
54 %<(nodate{text})error: %{text}%|%(putstr(pretty{text}))%>
56 Date mode is equivalent to dp(8).
58 In message mode the arguments to fmttest are interpreted as an optional
60 folder and messages. fmttest will read each specified message and make
61 all of the components in the message available to the format program.
62 Also, the appropriate information for the %(msg), %(cur), %(unseen),
63 and %(size) function escapes will be made available for each message.
64 If the -file switch is given, the arguments are interpreted as file‐
65 names instead of message numbers, but otherwise the behavior is the
66 same (except that the %(msg), %(cur), and %(unseen) function escapes
67 will not provide any useful information).
68 The default format used in address mode is the default format used by
70 scan. The following command can replicate the functionality of the
71 repl command.
72 fmttest -nodupaddrs -form replcomps -outsize max [+folder] message
74 Regardless of the mode, other components can be provided to the format
76 program by the use of the --component switch. For example, the follow‐
77 ing program will test the use of the “encrypted” component:
78 fmttest --encrypted yes -message cur
80 In message mode, components supplied on the command line will override
82 components from messages.
83 Additional Switches
85 The -dupaddrs and -nodupaddrs switches control whether duplicate ad‐
86 dresses are allowed or suppressed by the FORMATADDR instruction, which
87 is used by the `%(formataddr)' function escape. In normal operation
88 duplicate addresses are only suppressed by repl.
89 The -ccme and -noccme switches control whether or not to count the
91 user's local mailbox as a duplicate address. This replicates the be‐
92 havior of the -cc me switch to repl, and only applies if -nodupaddrs is
93 in effect.
94 The -outsize switch controls the maximum number of printable characters
96 that the format engine will produce. Characters marked as non-printing
97 by the format engine with `%(zputlit)', characters with zero width, and
98 extra bytes that are part of a multibyte character are not counted
99 against this total. Two special values are supported: “max”, which
100 means as many characters as the format engine can produce (limited by
101 internal buffers), and “width”, which will set the value to the width
102 of the terminal. In message mode it defaults to “width”, otherwise the
103 default is “max”.
104 The -width switch controls the column width which is used by the
106 `%(width)' function escape. It defaults to the terminal width.
107 The -msgnum, -msgcur, -msgsize, and the -unseen switches all control
109 the values used, respectively, by the following function escapes:
110 `%(num)', `%(cur)', `%(size)', and `%(unseen)'. If none are supplied,
111 these values are taken from the message in message mode; in all other
112 modes the default values are 0.
113 Compiling and Tracing Format Programs
115 The -dump switch outputs the complete set of format instructions for
116 the specified format program. The -trace switch will output each for‐
117 mat instruction as it is being executed, and show the values of the num
118 and str registers if they have changed from the previous instruction.
119 The output buffer is also printed if it has changed from the previous
120 instruction.
121 Format Instructions
123 It should be noted that there is not a one-to-one correspondence be‐
124 tween format escapes and format instructions; many instructions have
125 side effects. Instructions prefixed with “LV” generally return a inte‐
126 ger into the num (value) register; instructions prefixed with a “LS”
127 return a string into the str register.
128 Instruction Description
130 COMP Output component
131 COMPF Formatted output component
132 LIT Output literal text
133 CHAR Output single character
134 NUM Output the num register
135 NUMF Formatted output of the num register
136 STR Output the str register
137 STRF Formatted output of the str register
138 STRFW Not used
139 PUTADDR Output address list in str register
140 STRLIT Output str, no space compression
141 STRLITZ Like STRLIT, but not counted against width
142 LS_COMP Write component to str register
143 LS_LIT Write literal to str register
144 LS_GETENV Write environment var to str register
145 LS_DECODECOMP Decode RFC 2047 encoded component to str register
146 LS_DECODE Decode RFC 2047 encoded string to str register
147 LS_TRIM Trim trailing whitespace from str register
148 LV_COMP Convert component to integer, store in num register
149 LV_COMPFLAG Set num to 1 if TRUE set in component
150 LV_LIT Load literal value into num register
151 LV_DAT Load value from dat array into num register (see note)
152 LV_STRLEN Set num to the length of str
153 LV_PLUS_L Add value to num register
154 LV_MINUS_L Subtract value from num register
155 LV_DIVIDE_L Divide num register by value
156 LV_MODULO_L num modulo value
157 LV_CHAR_LEFT Store remaining number of printable chars in num
158 LS_MONTH Write short name of month to str from date component
159 LS_LMONTH Write long name of month to str from date component
160 LS_ZONE Write time zone offset to str from date component
161 LS_DAY Write short name of day of week to str from date component
162 LS_WEEKDAY Write long name of day of week to str from date component
163 LS_822DATE Write RFC 822 compatible date to str from date component
164 LS_PRETTY Write date with “pretty” timezone to str
165 LV_SEC Write date component seconds to num
166 LV_MIN Write date component minutes to num
167 LV_HOUR Write date component hour to num
168 LV_MON Write date component numeric month to num (start at 1)
169 LV_YEAR Write date component year to num
170 LV_YDAY Write date component Julian day to num
171 LV_WDAY Write date component day of week to num (0 == Sunday)
172 LV_ZONE Write date component time zone offset to num
173 LV_CLOCK Write date component in Unix epoch time to num
174 LV_RCLOCK Write offset of date component from current time to num
175 LV_DAYF Write 1 to num if day of week is explicit
176 LV_DST Write 1 to num if DST is in effect for date component
177 LV_ZONEF Write 1 to num if timezone is explicit
178 LS_ADDR Write email address of addr component to str
179 LS_PERS Write personal name of addr component to str
180 LS_MBOX Write mailbox (username) of addr component to str
181 LS_HOST Write host of addr component to str
182 LS_PATH Write host route of addr component to str
183 LS_GNAME Write group name of addr component to str
184 LS_NOTE Write note portion of addr component to str
185 LS_822ADDR Write “proper” RFC 822 version of addr component to str
186 LS_FRIENDLY Write friendly (name or note) of address component to str
187 LS_UNQUOTE Remove RFC 2822 quotes from string
188 LV_HOSTTYPE Set num to type of host (0=local, 1=network)
189 LV_INGRPF Set num to 1 if address was inside of group
190 LV_NOHOSTF Set num to 1 of no host was present in address component
191 LOCALDATE Convert date component to local timezone
192 GMTDATE Convert date component to GMT
193 PARSEDATE Parse date component
194 PARSEADDR Parse address component
195 FORMATADDR Add address component to list in str
196 CONCATADDR Like FORMATADDR, but will not suppress duplicates
197 MYMBOX Set num if address component is a local address
198 SAVESTR Save str register temporarily
199 DONE End program
200 NOP No operation
201 GOTO Jump to new instruction
202 IF_S_NULL Branch if str is NULL
203 IF_S Branch if str is not NULL
204 IF_V_EQ Branch if num is equal to value
205 IF_V_NE Branch if num is not equal to value
206 IF_V_GT Branch if num is greater than value
207 IF_MATCH Branch if str contains string
208 IF_AMATCH Branch if str starts with string
209 S_NULL Set num to 1 if str is NULL
210 S_NONNULL Set num to 1 if str is not NULL
211 V_EQ Set num to 1 if num equals value
212 V_NE Set num to 1 if num does not equal value
213 V_GT Set num to 1 if num is greater than value
214 V_MATCH Set num to 1 if str contains string
215 V_AMATCH Set num to 1 if str starts with string
216 The LV_DAT instruction is a bit special. Callers of the format library
218 pass in an array of integers that are used by certain format escapes.
219 The current list of format escapes and the indexes they use are:
220 dat[0] %(num)
222 dat[1] %(cur)
223 dat[2] %(size)
224 dat[3] %(width)
225 dat[4] %(unseen)
226
228 mh-format(5), repl(1), ap(8), dp(8), fmtdump(8)
229
231 `-message'
232 `-nofile'
233 `-dupaddrs'
234
236 If a folder is given, it will become the current folder.
237
239 It shouldn't require as much code from other programs as it does.
240nmh-1.8 2014-08-31 FMTTEST(1)