-.TH FMTTEST %manext1% "February 19, 2013" "%nmhversion%"
+.TH FMTTEST %manext1% "December 4, 2013" "%nmhversion%"
.\"
.\" %nmhwarning%
.\"
.RB [ \-format
.IR formatstring ]
.RB [ \-address " | " \-raw " | " \-date " | " \-message ]
+.RB [ \-file " | " \-nofile ]
.RB [ \-\|\-component
.IR component-text ]
.RB [ \-dupaddrs " | " \-nodupaddrs ]
.RB [ \-ccme " | " \-noccme ]
-.RB [ \-normalize " | " \-nonormalize ]
.RB [ \-outsize
.IR size-in-characters ]
.RB [ \-bufsize
.PP
In this mode
.B fmttest
-is equivant to
-.BR ap (8).
+is equivalent to
+.IR ap (8).
.PP
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
.RE
.PP
Date mode is equivalent to
-.BR dp (8).
+.IR dp (8).
.PP
In message mode the arguments to
.B fmttest
.RI %( unseen ),
and
.RI %( size )
-function escapes will be made available for each message.
+function escapes will be made available for each message. If the
+.B \-file
+switch is given, the arguments are interpreted as filenames instead of
+message numbers, but otherwise the behavior is the same (except that the
+.RI %( msg ),
+.RI %( cur ),
+and
+.RI %( unseen )
+function escapes will not provide any useful information).
.PP
The default format used in address mode is the default format used by
.BR scan .
.PP
.RS 5
.nf
-fmttest -nodupaddrs -form replcomps -outsize max [+folder] message
+fmttest \-nodupaddrs \-form replcomps \-outsize max [+folder] message
.fi
.RE
.PP
.PP
.RS 5
.nf
-fmttest --encrypted yes -message cur
+fmttest \-\|\-encrypted yes \-message cur
.fi
.RE
.PP
is in effect.
.PP
The
-.B \-normalize
-and
-.B \-nonormalize
-switches control whether or not email addresses are normalized by the
-address parsing routines. This is only functional when in address
-mode and is designed to replicate the switch of the same name to
-.BR ap (8).
-.PP
-The
.B \-outsize
switch controls the maximum number of printable characters that the format
engine will produce. Characters marked as non-printing by the format
.RI `%( 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: \*(lqmax\*(rq, which will set the value
-to the size of the output buffer, and \*(lqwidth\*(rq, which will set the
+Two special values are supported:
+.RI \*(lq max \*(rq,
+which will set the value
+to the size of the output buffer, and
+.RI \*(lq width \*(rq,
+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.
.PP
The
.B \-width
switch controls the column width which is used by the
-.RI %( width )
+.RI `%( width )'
function escape. By default is set to the terminal width.
.PP
The
.BR \-msgcur ,
.BR \-msgsize ,
and the
-.BR \-unseen
+.B \-unseen
switches all control the values used, respectively, by the following
function escapes:
-.RI %( num ),
-.RI %( cur ),
-.RI %( size ),
+.RI `%( num )',
+.RI `%( cur )',
+.RI `%( size )',
and
-.RI %( unseen ).
+.RI `%( unseen )'.
If none are supplied these values are taken from the message in message mode;
in all other modes the default values are 0.
-.SH FILES
+.SS COMPILING AND TRACING FORMAT PROGRAMS
+The
+.B \-dump
+switch outputs the complete set of format instructions for the specified
+format program. The
+.B \-trace
+switch will output each format instruction as it is being
+executed, and show the values of the
+.I num
+and
+.I str
+registers if they have changed from the previous instruction.
+The output buffer is also printed if it has changed from the previous
+instruction.
+.SS FORMAT INSTRUCTIONS
+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
+.RI \*(lq LV \*(rq
+generally return a integer into the
+.I num
+(value) register; instructions prefixed with a
+.RI \*(lq LS \*(rq
+return a string into the
+.I str
+register.
+.PP
+.nf
+.ta \w'LS_DECODECOMP 'u
+.I "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 \fInum\fR register
+NUMF Formatted output of the \fInum\fR register
+STR Output the \fIstr\fR register
+STRF Formatted output of the \fIstr\fR register
+STRFW Not used
+PUTADDR Output address list in \fIstr\fR register
+STRLIT Output \fIstr\fR, no space compression
+STRLITZ Like \fBSTRLIT\fR, but not counted against width
+LS_COMP Write component to \fIstr\fR register
+LS_LIT Write literal to \fIstr\fR register
+LS_GETENV Write environment var to \fIstr\fR register
+LS_DECODECOMP Decode RFC 2047 encoded component to \fIstr\fR register
+LS_DECODE Decode RFC 2047 encoded string to \fIstr\fR register
+LS_TRIM Trim trailing whitespace from \fIstr\fR register
+LV_COMP Convert component to integer, store in \fInum\fR register
+LV_COMPFLAG Set \fInum\fR to 1 if \fBTRUE\fR set in component
+LV_LIT Load literal value into \fInum\fR register
+LV_DAT Load value from \fIdat\fR array into \fInum\fR register (see note)
+LV_STRLEN Set \fInum\fR to the length of \fIstr\fR
+LV_PLUS_L Add value to \fInum\fR register
+LV_MINUS_L Substract value from \fInum\fR register
+LV_DIVIDE_L Divide \fInum\fR register by value
+LV_MODULO_L \fInum\fR modulo value
+LV_CHAR_LEFT Store remaining number of printable chars in \fInum\fR
+LS_MONTH Write short name of month to \fIstr\fR from date component
+LS_LMONTH Write long name of month to \fIstr\fR from date component
+LS_ZONE Write time zone offset to \fIstr\fR from date component
+LS_DAY Write short name of day of week to \fIstr\fR from date component
+LS_WEEKDAY Write long name of day of week to \fIstr\fR from date component
+LS_822DATE Write RFC 822 compatible date to \fIstr\fR from date component
+LS_PRETTY Write date with \*(lqpretty\*(rq timezone to \fIstr\fR
+LV_SEC Write date component seconds to \fInum\fR
+LV_MIN Write date component minutes to \fInum\fR
+LV_HOUR Write date component hour to \fInum\fR
+LV_MON Write date component numeric month to \fInum\fR (start at 1)
+LV_YEAR Write date component year to \fInum\fR
+LV_YDAY Write date component Julian day to \fInum\fR
+LV_WDAY Write date component day of week to \fInum\fR (0 == Sunday)
+LV_ZONE Write date component time zone offset to \fInum\fR
+LV_CLOCK Write date component in Unix epoch time to \fInum\fR
+LV_RCLOCK Write offset of date component from current time to \fInum\fR
+LV_DAYF Write 1 to \fInum\fR if day of week is explicit
+LV_DST Write 1 to \fInum\fR if DST is in effect for date component
+LV_ZONEF Write 1 to \fInum\fR if timezone is explicit
+LS_ADDR Write email address of addr component to \fIstr\fR
+LS_PERS Write personal name of addr component to \fIstr\fR
+LS_MBOX Write mailbox (username) of addr component to \fIstr\fR
+LS_HOST Write host of addr component to \fIstr\fR
+LS_PATH Write host route of addr component to \fIstr\fR
+LS_GNAME Write group name of addr component to \fIstr\fR
+LS_NOTE Write note portion of addr component to \fIstr\fR
+LS_822ADDR Write \*(lqproper\*(rq RFC 822 version of addr component to \fIstr\fR
+LS_FRIENDLY Write friendly (name or note) of address component to \fIstr\fR
+LS_UNQUOTE Remove RFC 2822 quotes from string
+LV_HOSTTYPE Set \fInum\fR to type of host (0=local, 1=network)
+LV_INGRPF Set \fInum\fR to 1 if address was inside of group
+LV_NOHOSTF Set \fInum\fR 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 \fIstr\fR
+CONCATADDR Like \fBFORMATADDR\fR, but will not suppress duplicates
+MYMBOX Set \fInum\fR if address component is a local address
+SAVESTR Save \fIstr\fR register temporarily
+DONE End program
+NOP No operation
+GOTO Jump to new instruction
+IF_S_NULL Branch if \fIstr\fR is \fBNULL\fR
+IF_S Branch if \fIstr\fR is not \fBNULL\fR
+IF_V_EQ Branch if \fInum\fR is equal to value
+IF_V_NE Branch if \fInum\fR is not equal to value
+IF_V_GT Branch if \fInum\fR is greater than value
+IF_MATCH Branch if \fIstr\fR contains string
+IF_AMATCH Branch if \fIstr\fR starts with string
+S_NULL Set \fInum\fR to 1 if \fIstr\fR is \fBNULL\fR
+S_NONNULL Set \fInum\fR to 1 if \fIstr\fR is not \fBNULL\fR
+V_EQ Set \fInum\fR to 1 if \fInum\fR equals value
+V_NE Set \fInum\fR to 1 if \fInum\fR does not equal value
+V_GT Set \fInum\fR to 1 if \fInum\fR is greater than value
+V_MATCH Set \fInum\fR to 1 if \fIstr\fR contains string
+V_AMATCH Set \fInum\fR to 1 if \fIstr\fR starts with string
+.fi
+.PP
+The
+.B 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:
+.PP
+.RS 5
+.nf
+.ta \w'dat[5]\0\0'u
+dat[0] %(\fInum\fR)
+dat[1] %(\fIcur\fR)
+dat[2] %(\fIsize\fR)
+dat[3] %(\fIwidth\fR)
+dat[4] %(\fIunseen\fR)
+.fi
+.RE
+.SH "SEE ALSO"
+.IR mh-format (5),
+.IR repl (1),
+.IR ap (8),
+.IR dp (8),
+.SH DEFAULTS
+.nf
+.RB ` \-message '
+.RB ` \-nofile '
+.RB ` \-dupaddrs '
+.fi
+.SH BUGS
+It shouldn't require as much code from other programs as it does.
projects / nmh / blobdiff