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

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