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
86       addresses are allowed or  suppressed  by  the  FORMATADDR  instruction,
87       which is used by the `%(formataddr)' function escape.  In normal opera‐
88       tion 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
92       behavior of the -cc me switch to repl, and only applies if  -nodupaddrs
93       is 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
124       between 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       LITF          Formatted literal text output
134       CHAR          Output single character
135       NUM           Output the num register
136       NUMF          Formatted output of the num register
137       STR           Output the str register
138       STRF          Formatted output of the str register
139       STRFW         Not used
140       PUTADDR       Output address list in str register
141       STRLIT        Output str, no space compression
142       STRLITZ       Like STRLIT, but not counted against width
143       LS_COMP       Write component to str register
144       LS_LIT        Write literal to str register
145       LS_GETENV     Write environment var to str register
146       LS_DECODECOMP Decode RFC 2047 encoded component to str register
147       LS_DECODE     Decode RFC 2047 encoded string to str register
148       LS_TRIM       Trim trailing whitespace from str register
149       LV_COMP       Convert component to integer, store in num register
150       LV_COMPFLAG   Set num to 1 if TRUE set in component
151       LV_LIT        Load literal value into num register
152       LV_DAT        Load value from dat array into num register (see note)
153       LV_STRLEN     Set num to the length of str
154       LV_PLUS_L     Add value to num register
155       LV_MINUS_L    Subtract value from num register
156       LV_DIVIDE_L   Divide num register by value
157       LV_MODULO_L   num modulo value
158       LV_CHAR_LEFT  Store remaining number of printable chars in num
159       LS_MONTH      Write short name of month to str from date component
160       LS_LMONTH     Write long name of month to str from date component
161       LS_ZONE       Write time zone offset to str from date component
162       LS_DAY        Write short name of day of week to str from date component
163       LS_WEEKDAY    Write long name of day of week to str from date component
164       LS_822DATE    Write RFC 822 compatible date to str from date component
165       LS_PRETTY     Write date with “pretty” timezone to str
166       LV_SEC        Write date component seconds to num
167       LV_MIN        Write date component minutes to num
168       LV_HOUR       Write date component hour to num
169       LV_MON        Write date component numeric month to num (start at 1)
170       LV_YEAR       Write date component year to num
171       LV_YDAY       Write date component Julian day to num
172       LV_WDAY       Write date component day of week to num (0 == Sunday)
173       LV_ZONE       Write date component time zone offset to num
174       LV_CLOCK      Write date component in Unix epoch time to num
175       LV_RCLOCK     Write offset of date component from current time to num
176       LV_DAYF       Write 1 to num if day of week is explicit
177       LV_DST        Write 1 to num if DST is in effect for date component
178       LV_ZONEF      Write 1 to num if timezone is explicit
179       LS_ADDR       Write email address of addr component to str
180       LS_PERS       Write personal name of addr component to str
181       LS_MBOX       Write mailbox (username) of addr component to str
182       LS_HOST       Write host of addr component to str
183       LS_PATH       Write host route of addr component to str
184       LS_GNAME      Write group name of addr component to str
185       LS_NOTE       Write note portion of addr component to str
186       LS_822ADDR    Write “proper” RFC 822 version of addr component to str
187       LS_FRIENDLY   Write friendly (name or note) of address component to str
188       LS_UNQUOTE    Remove RFC 2822 quotes from string
189       LV_HOSTTYPE   Set num to type of host (0=local, 1=network)
190       LV_INGRPF     Set num to 1 if address was inside of group
191       LV_NOHOSTF    Set num to 1 of no host was present in address component
192       LOCALDATE     Convert date component to local timezone
193       GMTDATE       Convert date component to GMT
194       PARSEDATE     Parse date component
195       PARSEADDR     Parse address component
196       FORMATADDR    Add address component to list in str
197       CONCATADDR    Like FORMATADDR, but will not suppress duplicates
198       MYMBOX        Set num if address component is a local address
199       SAVESTR       Save str register temporarily
200       DONE          End program
201       NOP           No operation
202       GOTO          Jump to new instruction
203       IF_S_NULL     Branch if str is NULL
204       IF_S          Branch if str is not NULL
205       IF_V_EQ       Branch if num is equal to value
206       IF_V_NE       Branch if num is not equal to value
207       IF_V_GT       Branch if num is greater than value
208       IF_MATCH      Branch if str contains string
209       IF_AMATCH     Branch if str starts with string
210       S_NULL        Set num to 1 if str is NULL
211       S_NONNULL     Set num to 1 if str is not NULL
212       V_EQ          Set num to 1 if num equals value
213       V_NE          Set num to 1 if num does not equal value
214       V_GT          Set num to 1 if num is greater than value
215       V_MATCH       Set num to 1 if str contains string
216       V_AMATCH      Set num to 1 if str starts with string
217
218       The LV_DAT instruction is a bit special.  Callers of the format library
219       pass in an array of integers that are used by certain  format  escapes.
220       The current list of format escapes and the indexes they use are:
221
222            dat[0]  %(num)
223            dat[1]  %(cur)
224            dat[2]  %(size)
225            dat[3]  %(width)
226            dat[4]  %(unseen)
227

SEE ALSO

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

DEFAULTS

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

BUGS

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