NAME¶
fmttest - test tool for the
mh-format(5) language
SYNOPSIS¶
fmttest [-form formatfile] [-format
formatstring] [-address | -raw | -date |
-message] [-file | -nofile] [--component
component-text] [-dupaddrs | -nodupaddrs] [-ccme |
-noccme] [-outsize size-in-characters] [-bufsize
size-in-bytes] [-width column-width] [-msgnum
number] [-msgcur flag] [-msgsize size]
[-unseen flag] [-dump | -nodump] [-trace |
-notrace] [+folder] [msgs | strings]
DESCRIPTION¶
Fmttest is used to test programs written for the
nmh format
language as specified by
mh-format(5). It is also intended to replace
the
ap,
dp, and
fmtdump programs.
The
-format string and
-form formatfile switches may
be used to specify a format string or a format file to read. If given a format
string, it must be specified as a single argument to the
-format
switch. If given a format file name with
-form, the file is searched
for using the normal
nmh rules: absolute pathnames are accessed
directly, tilde expansion is done on usernames, and files are searched for in
the user's
Mail directory as specified in their profile. If not found
there, the directory “
/etc/nmh” is checked.
MODE SELECTION AND COMPONENT SPECIFICATION¶
Fmttest has four operating modes: address mode, raw mode, date mode, and
message mode. These modes are selected by the
-address,
-raw,
-date, and
-message switches respectively.
Address mode treats every argument as an email address and processes it with
nmh's email parser. Each argument is processed with the specified format
program with the parsed email address available as a special %{
text}
component escape, and the output from the program is printed on standard
output. If there was an error parsing the email address the error message is
stored in the %{
error} component escape. If no format program is given
on the command line, the following default program is used:
%<{error}%{error}: %{text}%|%(putstr(proper{text}))%>
In this mode
fmttest is equivalent to
ap(8).
In raw mode, no processing of the specified arguments is done. Each argument is
run against the specified format program with the argument text available in
the %{
text} component. You must specify a format with
-form or
-format when using raw mode.
Date mode is identical to raw mode, with one exception: if no format is
specified, the following format string is used:
%<(nodate{text})error: %{text}%|%(putstr(pretty{text}))%>
Date mode is equivalent to
dp(8).
In message mode the arguments to
fmttest are interpreted as an optional
folder and messages.
Fmttest will read each specified message and make
all of the components in the message available to the format program. Also,
the appropriate information for the %(
msg), %(
cur),
%(
unseen), and %(
size) function escapes will be made available
for each message. If the
-file switch is given, the arguments are
interpreted as filenames instead of message numbers, but otherwise the
behavior is the same (except that the %(
msg), %(
cur), and
%(
unseen) function escapes will not provide any useful information).
The default format used in address mode is the default format used by
scan. The following command can replicate the functionality of the
repl command.
fmttest -nodupaddrs -form replcomps -outsize max [+folder] message
Regardless of the mode, other components can be provided to the format program
by the use of the
--component switch. For example, the following
program will test out the use of the “
encrypted”
component:
fmttest --encrypted yes -message cur
In message mode components supplied on the command line will override components
from messages.
ADDITIONAL SWITCHES¶
The
-dupaddrs and
-nodupaddrs switches control whether duplicate
addresses are allowed or suppressed by the
FORMATADDR instruction,
which is used by the `%(
formataddr)' function escape. In normal
operation duplicate addresses are only suppressed by
repl.
The
-ccme and
-noccme switches control whether or not to count the
user's local mailbox as a duplicate address. This replicates the behavior of
the
-cc me switch to
repl, and only applies if
-nodupaddrs is in effect.
The
-outsize switch controls the maximum number of printable characters
that the format engine will produce. Characters marked as non-printing by the
format engine with `%(
zputlit)', characters with zero width, and extra
bytes that are part of a multibyte character are not counted against this
total. Two special values are supported: “
max”, which
will set the value to the size of the output buffer, and
“
width”, which will set the value to the width of the
terminal. In message mode it defaults to the terminal width, otherwise the
default is the output buffer size.
The
-bufsize switch controls the size of the output buffer. By default it
is set to the size of the
BUFSIZ C preprocessor symbol, which is
system-dependent.
The
-width switch controls the column width which is used by the
`%(
width)' function escape. By default is set to the terminal width.
The
-msgnum,
-msgcur,
-msgsize, and the
-unseen
switches all control the values used, respectively, by the following function
escapes: `%(
num)', `%(
cur)', `%(
size)', and
`%(
unseen)'. If none are supplied these values are taken from the
message in message mode; in all other modes the default values are 0.
The
-dump switch outputs the complete set of format instructions for the
specified format program. The
-trace switch will output each format
instruction as it is being executed, and show the values of the
num and
str registers if they have changed from the previous instruction. The
output buffer is also printed if it has changed from the previous instruction.
It should be noted that there is not a one-to-one correspondence between format
escapes and format instructions; many instructions have side effects.
Instructions prefixed with “
LV” generally return a
integer into the
num (value) register; instructions prefixed with a
“
LS” return a string into the
str register.
Instruction Description
COMP Output component
COMPF Formatted output component
LIT Output literal text
LITF Formatted literal text output
CHAR Output single character
NUM Output the num register
NUMF Formatted output of the num register
STR Output the str register
STRF Formatted output of the str register
STRFW Not used
PUTADDR Output address list in str register
STRLIT Output str, no space compression
STRLITZ Like STRLIT, but not counted against width
LS_COMP Write component to str register
LS_LIT Write literal to str register
LS_GETENV Write environment var to str register
LS_DECODECOMP Decode RFC 2047 encoded component to str register
LS_DECODE Decode RFC 2047 encoded string to str register
LS_TRIM Trim trailing whitespace from str register
LV_COMP Convert component to integer, store in num register
LV_COMPFLAG Set num to 1 if TRUE set in component
LV_LIT Load literal value into num register
LV_DAT Load value from dat array into num register (see note)
LV_STRLEN Set num to the length of str
LV_PLUS_L Add value to num register
LV_MINUS_L Substract value from num register
LV_DIVIDE_L Divide num register by value
LV_MODULO_L num modulo value
LV_CHAR_LEFT Store remaining number of printable chars in num
LS_MONTH Write short name of month to str from date component
LS_LMONTH Write long name of month to str from date component
LS_ZONE Write time zone offset to str from date component
LS_DAY Write short name of day of week to str from date component
LS_WEEKDAY Write long name of day of week to str from date component
LS_822DATE Write RFC 822 compatible date to str from date component
LS_PRETTY Write date with “pretty” timezone to str
LV_SEC Write date component seconds to num
LV_MIN Write date component minutes to num
LV_HOUR Write date component hour to num
LV_MON Write date component numeric month to num (start at 1)
LV_YEAR Write date component year to num
LV_YDAY Write date component Julian day to num
LV_WDAY Write date component day of week to num (0 == Sunday)
LV_ZONE Write date component time zone offset to num
LV_CLOCK Write date component in Unix epoch time to num
LV_RCLOCK Write offset of date component from current time to num
LV_DAYF Write 1 to num if day of week is explicit
LV_DST Write 1 to num if DST is in effect for date component
LV_ZONEF Write 1 to num if timezone is explicit
LS_ADDR Write email address of addr component to str
LS_PERS Write personal name of addr component to str
LS_MBOX Write mailbox (username) of addr component to str
LS_HOST Write host of addr component to str
LS_PATH Write host route of addr component to str
LS_GNAME Write group name of addr component to str
LS_NOTE Write note portion of addr component to str
LS_822ADDR Write “proper” RFC 822 version of addr component to str
LS_FRIENDLY Write friendly (name or note) of address component to str
LS_UNQUOTE Remove RFC 2822 quotes from string
LV_HOSTTYPE Set num to type of host (0=local, 1=network)
LV_INGRPF Set num to 1 if address was inside of group
LV_NOHOSTF Set num to 1 of no host was present in address component
LOCALDATE Convert date component to local timezone
GMTDATE Convert date component to GMT
PARSEDATE Parse date component
PARSEADDR Parse address component
FORMATADDR Add address component to list in str
CONCATADDR Like FORMATADDR, but will not suppress duplicates
MYMBOX Set num if address component is a local address
SAVESTR Save str register temporarily
DONE End program
NOP No operation
GOTO Jump to new instruction
IF_S_NULL Branch if str is NULL
IF_S Branch if str is not NULL
IF_V_EQ Branch if num is equal to value
IF_V_NE Branch if num is not equal to value
IF_V_GT Branch if num is greater than value
IF_MATCH Branch if str contains string
IF_AMATCH Branch if str starts with string
S_NULL Set num to 1 if str is NULL
S_NONNULL Set num to 1 if str is not NULL
V_EQ Set num to 1 if num equals value
V_NE Set num to 1 if num does not equal value
V_GT Set num to 1 if num is greater than value
V_MATCH Set num to 1 if str contains string
V_AMATCH Set num to 1 if str starts with string
The
LV_DAT instruction is a bit special. Callers of the format library
pass in an array of integers that are used by certain format escapes. The
current list of format escapes and the indexes they use are:
dat[0] %( num)
dat[1] %( cur)
dat[2] %( size)
dat[3] %( width)
dat[4] %( unseen)
SEE ALSO¶
mh-format(5),
repl(1),
ap(8),
dp(8),
DEFAULTS¶
`-message'
`-nofile'
`-dupaddrs'
BUGS¶
It shouldn't require as much code from other programs as it does.