diplodocus.org Git - nmh/blob - man/fmttest.man

   1 .TH FMTTEST %manext1% 2014-08-31 "%nmhversion%"
   2 .
   3 .\" %nmhwarning%
   4 .
   5 .SH NAME
   6 fmttest \- test programs in nmh's \fImh-format\fP\^(5) language
   7 .SH SYNOPSIS
   8 .HP 5
   9 .na
  10 .B fmttest
  11 .RB [ \-help ]
  12 .RB [ \-version ]
  13 .RB [ \-form
  14 .IR formatfile ]
  15 .RB [ \-format
  16 .IR formatstring ]
  17 .RB [ \-address " | " \-raw " | " \-date " | " \-message ]
  18 .RB [ \-file " | " \-nofile ]
  19 .RB [ \-\|\-component
  20 .IR component-text ]
  21 .RB [ \-dupaddrs " | " \-nodupaddrs ]
  22 .RB [ \-ccme " | " \-noccme ]
  23 .RB [ \-outsize
  24 .IR size-in-characters ]
  25 .RB [ \-width
  26 .IR column-width ]
  27 .RB [ \-msgnum
  28 .IR number ]
  29 .RB [ \-msgcur
  30 .IR flag ]
  31 .RB [ \-msgsize
  32 .IR size ]
  33 .RB [ \-unseen
  34 .IR flag ]
  35 .RB [ \-dump " | " \-nodump ]
  36 .RB [ \-trace " | " \-notrace ]
  37 .RI [ +folder ]
  38 .RI [ msgs " | " strings ]
  39 .ad
  40 .SH DESCRIPTION
  41 .B fmttest
  42 is used to test programs written for the
  43 .B nmh
  44 format language as specified by
  45 .IR mh-format (5).
  46 It is also intended to replace the
  47 .BR ap ,
  48 .BR dp ,
  49 and
  50 .B fmtdump
  51 programs.
  52 .SS Format Program Selection
  53 The
  54 .B \-format
  55 .I string
  56 and
  57 .B \-form
  58 .I formatfile
  59 specify a format string or file to read.
  60 A format string, if given, must be a single argument to the
  61 .B \-format
  62 switch.  If a format file name is passed to the
  63 .BR \-form ,
  64 switch, the file is searched for using the normal
  65 .B nmh
  66 rules: absolute pathnames are accessed directly, tilde expansion is
  67 done on usernames, and files are searched for in the user's
  68 .I Mail
  69 directory as specified in their profile.  If not found there, the directory
  70 .RI \*(lq %nmhetcdir% \*(rq
  71 is checked.
  72 .SS Mode Selection and Component Specification
  73 .B fmttest
  74 has four operating modes - address, raw, date, and message -
  75 which are selected by the
  76 .BR \-address ,
  77 .BR \-raw ,
  78 .BR \-date ,
  79 and
  80 .B \-message
  81 switches, respectively.
  82 .PP
  83 Address mode treats every argument as an email address to be processed
  84 by nmh's email parser using the specified format program.
  85 The parsed address is made available as a special
  86 .RI %{ text }
  87 component escape, and the output from the program is printed on standard output.
  88 If there was an error parsing the email address the error message is
  89 stored in the
  90 .RI %{ error }
  91 component escape.  If no format program is given on the command line, the
  92 following default program is used:
  93 .PP
  94 .RS 5
  95 .nf
  96 %<{error}%{error}: %{text}%|%(putstr(proper{text}))%>
  97 .fi
  98 .RE
  99 .PP
 100 Address mode is equivalent to
 101 .IR ap (8).
 102 .PP
 103 In raw mode, no processing of the specified arguments is done.  Each argument
 104 is run against the specified format program with the argument text available
 105 in the
 106 .RI %{ text }
 107 component.  You must specify a format with
 108 .B \-form
 109 or
 110 .B \-format
 111 when using raw mode.
 112 .PP
 113 Date mode is identical to raw mode, with one exception: if no format is
 114 specified, the following format string is used:
 115 .PP
 116 .RS 5
 117 .nf
 118 %<(nodate{text})error: %{text}%|%(putstr(pretty{text}))%>
 119 .fi
 120 .RE
 121 .PP
 122 Date mode is equivalent to
 123 .IR dp (8).
 124 .PP
 125 In message mode the arguments to
 126 .B fmttest
 127 are interpreted as an optional folder and messages.
 128 .B fmttest
 129 will read each specified message and make all of the components in the
 130 message available to the format program.  Also, the appropriate information
 131 for the
 132 .RI %( msg ),
 133 .RI %( cur ),
 134 .RI %( unseen ),
 135 and
 136 .RI %( size )
 137 function escapes will be made available for each message.  If the
 138 .B \-file
 139 switch is given, the arguments are interpreted as filenames instead of
 140 message numbers, but otherwise the behavior is the same (except that the
 141 .RI %( msg ),
 142 .RI %( cur ),
 143 and
 144 .RI %( unseen )
 145 function escapes will not provide any useful information).
 146 .PP
 147 The default format used in address mode is the default format used by
 148 .BR scan .
 149 The following command can replicate the functionality of the
 150 .B repl
 151 command.
 152 .PP
 153 .RS 5
 154 .nf
 155 fmttest \-nodupaddrs \-form replcomps \-outsize max [+folder] message
 156 .fi
 157 .RE
 158 .PP
 159 Regardless of the mode, other components can be provided to the format
 160 program by the use of the
 161 .B \-\|\-component
 162 switch.  For example, the following program will test the use of the
 163 .RB \*(lq encrypted \*(rq
 164 component:
 165 .PP
 166 .RS 5
 167 .nf
 168 fmttest \-\|\-encrypted yes \-message cur
 169 .fi
 170 .RE
 171 .PP
 172 In message mode, components supplied on the command line will override
 173 components from messages.
 174 .SS Additional Switches
 175 The
 176 .B \-dupaddrs
 177 and
 178 .B \-nodupaddrs
 179 switches control whether duplicate addresses are allowed or suppressed by the
 180 .B FORMATADDR
 181 instruction, which is used by the
 182 .RI `%( formataddr )'
 183 function escape.  In normal operation duplicate addresses are only
 184 suppressed by
 185 .BR repl .
 186 .PP
 187 The
 188 .B \-ccme
 189 and
 190 .B \-noccme
 191 switches control whether or not to count the user's local mailbox as a
 192 duplicate address.  This replicates the behavior of the
 193 .B \-cc
 194 .I me
 195 switch to
 196 .BR repl ,
 197 and only applies if
 198 .B \-nodupaddrs
 199 is in effect.
 200 .PP
 201 The
 202 .B \-outsize
 203 switch controls the maximum number of printable characters that the format
 204 engine will produce.  Characters marked as non-printing by the format
 205 engine with
 206 .RI `%( zputlit )',
 207 characters with zero width, and extra bytes that are
 208 part of a multibyte character are not counted against this total.
 209 Two special values are supported:
 210 .RI \*(lq max \*(rq,
 211 which means as many characters as the format engine can produce
 212 (limited by internal buffers), and
 213 .RI \*(lq width \*(rq,
 214 which will set the
 215 value to the width of the terminal.  In message mode it defaults to
 216 .RI \*(lq width \*(rq,
 217 otherwise the default is
 218 .RI \*(lq max \*(rq.
 219 .PP
 220 The
 221 .B \-width
 222 switch controls the column width which is used by the
 223 .RI `%( width )'
 224 function escape.  It defaults to the terminal width.
 225 .PP
 226 The
 227 .BR \-msgnum ,
 228 .BR \-msgcur ,
 229 .BR \-msgsize ,
 230 and the
 231 .B \-unseen
 232 switches all control the values used, respectively, by the following
 233 function escapes:
 234 .RI `%( num )',
 235 .RI `%( cur )',
 236 .RI `%( size )',
 237 and
 238 .RI `%( unseen )'.
 239 If none are supplied, these values are taken from the message in
 240 message mode; in all other modes the default values are 0.
 241 .SS Compiling and Tracing Format Programs
 242 The
 243 .B \-dump
 244 switch outputs the complete set of format instructions for the specified
 245 format program.  The
 246 .B \-trace
 247 switch will output each format instruction as it is being
 248 executed, and show the values of the
 249 .I num
 250 and
 251 .I str
 252 registers if they have changed from the previous instruction.
 253 The output buffer is also printed if it has changed from the previous
 254 instruction.
 255 .SS Format Instructions
 256 It should be noted that there is not a one-to-one correspondence between
 257 format escapes and format instructions; many instructions have side
 258 effects.  Instructions prefixed with
 259 .RI \*(lq LV \*(rq
 260 generally return a integer into the
 261 .I num
 262 (value) register; instructions prefixed with a
 263 .RI \*(lq LS \*(rq
 264 return a string into the
 265 .I str
 266 register.
 267 .PP
 268 .nf
 269 .ta \w'LS_DECODECOMP 'u
 270 .I "Instruction Description"
 271 COMP    Output component
 272 COMPF   Formatted output component
 273 LIT     Output literal text
 274 LITF    Formatted literal text output
 275 CHAR    Output single character
 276 NUM     Output the \fInum\fR register
 277 NUMF    Formatted output of the \fInum\fR register
 278 STR     Output the \fIstr\fR register
 279 STRF    Formatted output of the \fIstr\fR register
 280 STRFW   Not used
 281 PUTADDR Output address list in \fIstr\fR register
 282 STRLIT  Output \fIstr\fR, no space compression
 283 STRLITZ Like \fBSTRLIT\fR, but not counted against width
 284 LS_COMP Write component to \fIstr\fR register
 285 LS_LIT  Write literal to \fIstr\fR register
 286 LS_GETENV       Write environment var to \fIstr\fR register
 287 LS_DECODECOMP   Decode RFC 2047 encoded component to \fIstr\fR register
 288 LS_DECODE       Decode RFC 2047 encoded string to \fIstr\fR register
 289 LS_TRIM         Trim trailing whitespace from \fIstr\fR register
 290 LV_COMP         Convert component to integer, store in \fInum\fR register
 291 LV_COMPFLAG     Set \fInum\fR to 1 if \fBTRUE\fR set in component
 292 LV_LIT  Load literal value into \fInum\fR register
 293 LV_DAT  Load value from \fIdat\fR array into \fInum\fR register (see note)
 294 LV_STRLEN       Set \fInum\fR to the length of \fIstr\fR
 295 LV_PLUS_L       Add value to \fInum\fR register
 296 LV_MINUS_L      Subtract value from \fInum\fR register
 297 LV_DIVIDE_L     Divide \fInum\fR register by value
 298 LV_MODULO_L     \fInum\fR modulo value
 299 LV_CHAR_LEFT    Store remaining number of printable chars in \fInum\fR
 300 LS_MONTH        Write short name of month to \fIstr\fR from date component
 301 LS_LMONTH       Write long name of month to \fIstr\fR from date component
 302 LS_ZONE         Write time zone offset to \fIstr\fR from date component
 303 LS_DAY          Write short name of day of week to \fIstr\fR from date component
 304 LS_WEEKDAY      Write long name of day of week to \fIstr\fR from date component
 305 LS_822DATE      Write RFC 822 compatible date to \fIstr\fR from date component
 306 LS_PRETTY       Write date with \*(lqpretty\*(rq timezone to \fIstr\fR
 307 LV_SEC  Write date component seconds to \fInum\fR
 308 LV_MIN  Write date component minutes to \fInum\fR
 309 LV_HOUR Write date component hour to \fInum\fR
 310 LV_MON  Write date component numeric month to \fInum\fR (start at 1)
 311 LV_YEAR Write date component year to \fInum\fR
 312 LV_YDAY Write date component Julian day to \fInum\fR
 313 LV_WDAY Write date component day of week to \fInum\fR (0 == Sunday)
 314 LV_ZONE Write date component time zone offset to \fInum\fR
 315 LV_CLOCK        Write date component in Unix epoch time to \fInum\fR
 316 LV_RCLOCK       Write offset of date component from current time to \fInum\fR
 317 LV_DAYF Write 1 to \fInum\fR if day of week is explicit
 318 LV_DST  Write 1 to \fInum\fR if DST is in effect for date component
 319 LV_ZONEF        Write 1 to \fInum\fR if timezone is explicit
 320 LS_ADDR Write email address of addr component to \fIstr\fR
 321 LS_PERS Write personal name of addr component to \fIstr\fR
 322 LS_MBOX Write mailbox (username) of addr component to \fIstr\fR
 323 LS_HOST Write host of addr component to \fIstr\fR
 324 LS_PATH Write host route of addr component to \fIstr\fR
 325 LS_GNAME        Write group name of addr component to \fIstr\fR
 326 LS_NOTE Write note portion of addr component to \fIstr\fR
 327 LS_822ADDR      Write \*(lqproper\*(rq RFC 822 version of addr component to \fIstr\fR
 328 LS_FRIENDLY     Write friendly (name or note) of address component to \fIstr\fR
 329 LS_UNQUOTE      Remove RFC 2822 quotes from string
 330 LV_HOSTTYPE     Set \fInum\fR to type of host (0=local, 1=network)
 331 LV_INGRPF       Set \fInum\fR to 1 if address was inside of group
 332 LV_NOHOSTF      Set \fInum\fR to 1 of no host was present in address component
 333 LOCALDATE       Convert date component to local timezone
 334 GMTDATE Convert date component to GMT
 335 PARSEDATE       Parse date component
 336 PARSEADDR       Parse address component
 337 FORMATADDR      Add address component to list in \fIstr\fR
 338 CONCATADDR      Like \fBFORMATADDR\fR, but will not suppress duplicates
 339 MYMBOX  Set \fInum\fR if address component is a local address
 340 SAVESTR         Save \fIstr\fR register temporarily
 341 DONE    End program
 342 NOP     No operation
 343 GOTO    Jump to new instruction
 344 IF_S_NULL       Branch if \fIstr\fR is \fBNULL\fR
 345 IF_S    Branch if \fIstr\fR is not \fBNULL\fR
 346 IF_V_EQ Branch if \fInum\fR is equal to value
 347 IF_V_NE Branch if \fInum\fR is not equal to value
 348 IF_V_GT Branch if \fInum\fR is greater than value
 349 IF_MATCH        Branch if \fIstr\fR contains string
 350 IF_AMATCH       Branch if \fIstr\fR starts with string
 351 S_NULL  Set \fInum\fR to 1 if \fIstr\fR is \fBNULL\fR
 352 S_NONNULL       Set \fInum\fR to 1 if \fIstr\fR is not \fBNULL\fR
 353 V_EQ    Set \fInum\fR to 1 if \fInum\fR equals value
 354 V_NE    Set \fInum\fR to 1 if \fInum\fR does not equal value
 355 V_GT    Set \fInum\fR to 1 if \fInum\fR is greater than value
 356 V_MATCH Set \fInum\fR to 1 if \fIstr\fR contains string
 357 V_AMATCH        Set \fInum\fR to 1 if \fIstr\fR starts with string
 358 .fi
 359 .PP
 360 The
 361 .B LV_DAT
 362 instruction is a bit special.  Callers of the format library pass in an
 363 array of integers that are used by certain format escapes.  The current
 364 list of format escapes and the indexes they use are:
 365 .PP
 366 .RS 5
 367 .nf
 368 .ta \w'dat[5]\0\0'u
 369 dat[0]  %(\fInum\fR)
 370 dat[1]  %(\fIcur\fR)
 371 dat[2]  %(\fIsize\fR)
 372 dat[3]  %(\fIwidth\fR)
 373 dat[4]  %(\fIunseen\fR)
 374 .fi
 375 .RE
 376 .SH "SEE ALSO"
 377 .IR mh-format (5),
 378 .IR repl (1),
 379 .IR ap (8),
 380 .IR dp (8),
 381 .IR fmtdump (8)
 382 .SH DEFAULTS
 383 .nf
 384 .RB ` \-message '
 385 .RB ` \-nofile '
 386 .RB ` \-dupaddrs '
 387 .fi
 388 .SH BUGS
 389 It shouldn't require as much code from other programs as it does.