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

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