X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/0b0d96e4d473ab8706d0a7246aee28bf31f5edb2..07661005b9a36338ab158bcbe7762788a1df4030:/man/fmttest.man?ds=inline diff --git a/man/fmttest.man b/man/fmttest.man index b63bac56..31de59d3 100644 --- a/man/fmttest.man +++ b/man/fmttest.man @@ -1,4 +1,4 @@ -.TH FMTTEST %manext1% "February 19, 2013" "%nmhversion%" +.TH FMTTEST %manext1% "December 4, 2013" "%nmhversion%" .\" .\" %nmhwarning% .\" @@ -15,11 +15,11 @@ language .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 @@ -103,8 +103,8 @@ following default program is used: .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 @@ -126,7 +126,7 @@ specified, the following format string is used: .RE .PP Date mode is equivalent to -.BR dp (8). +.IR dp (8). .PP In message mode the arguments to .B fmttest @@ -140,7 +140,15 @@ for the .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 . @@ -150,7 +158,7 @@ command. .PP .RS 5 .nf -fmttest -nodupaddrs -form replcomps -outsize max [+folder] message +fmttest \-nodupaddrs \-form replcomps \-outsize max [+folder] message .fi .RE .PP @@ -164,7 +172,7 @@ component: .PP .RS 5 .nf -fmttest --encrypted yes -message cur +fmttest \-\|\-encrypted yes \-message cur .fi .RE .PP @@ -198,15 +206,6 @@ and only applies if 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 @@ -214,8 +213,12 @@ engine with .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 @@ -229,7 +232,7 @@ C preprocessor symbol, which is system-dependent. 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 @@ -237,14 +240,161 @@ 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.