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

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