1FMTTEST(1)                  General Commands Manual                 FMTTEST(1)
2
3
4

NAME

6       fmttest - test programs in nmh's mh-format(5) language
7

SYNOPSIS

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

DESCRIPTION

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
21   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
30   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
35       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
43            %<{error}%{error}: %{text}%|%(putstr(proper{text}))%>
44
45       Address mode is equivalent to ap(8).
46
47       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
52       Date mode is identical to raw mode, with one exception: if no format is
53       specified, the following format string is used:
54
55            %<(nodate{text})error: %{text}%|%(putstr(pretty{text}))%>
56
57       Date mode is equivalent to dp(8).
58
59       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
69       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
73            fmttest -nodupaddrs -form replcomps -outsize max [+folder] message
74
75       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
79            fmttest --encrypted yes -message cur
80
81       In message mode, components supplied on the command line will  override
82       components from messages.
83
84   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
90       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
95       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
105       The  -width  switch  controls  the  column  width  which is used by the
106       `%(width)' function escape.  It defaults to the terminal width.
107
108       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
114   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
122   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
129       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
217       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
221            dat[0]  %(num)
222            dat[1]  %(cur)
223            dat[2]  %(size)
224            dat[3]  %(width)
225            dat[4]  %(unseen)
226

SEE ALSO

228       mh-format(5), repl(1), ap(8), dp(8), fmtdump(8)
229

DEFAULTS

231       `-message'
232       `-nofile'
233       `-dupaddrs'
234

CONTEXT

236       If a folder is given, it will become the current folder.
237

BUGS

239       It shouldn't require as much code from other programs as it does.
240
241
242
243nmh-1.8                           2014-08-31                        FMTTEST(1)
Impressum