Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
FMTTEST(1)		    General Commands Manual		    FMTTEST(1)

       fmttest - test programs in nmh's	mh-format(5) language

       fmttest [-help] [-version] [-form formatfile] [-format formatstring]
	    [-address |	-raw | -date | -message] [-file	| -nofile] [--compo-
	    nent component-text] [-dupaddrs | -nodupaddrs] [-ccme | -noccme]
	    [-outsize size-in-characters] [-width column-width]	[-msgnum num-
	    ber] [-msgcur flag]	[-msgsize size]	[-unseen flag] [-dump |
	    -nodump] [-trace | -notrace] [+folder] [msgs | strings]

       fmttest is used to test programs	written	for the	nmh format language as
       specified  by mh-format(5).  It is also intended	to replace the ap, dp,
       and fmtdump programs.

   Format Program Selection
       The -format string and -form formatfile specify a format	string or file
       to  read.   A format string, if given, must be a	single argument	to the
       -format switch.	If a format file name is passed	to the -form,  switch,
       the file	is searched for	using the normal nmh rules: absolute pathnames
       are accessed directly, tilde expansion is done on usernames, and	 files
       are  searched  for  in  the user's Mail directory as specified in their
       profile.	 If not	found there,  the  directory  "/usr/local/etc/nmh"  is

   Mode	Selection and Component	Specification
       fmttest	has  four  operating modes - address, raw, date, and message -
       which are selected by the -address, -raw, -date,	and -message switches,

       Address	mode treats every argument as an email address to be processed
       by nmh's	email parser using the specified format	program.   The	parsed
       address	is  made  available as a special %{text} component escape, and
       the output from the program is printed on standard  output.   If	 there
       was  an	error parsing the email	address	the error message is stored in
       the %{error} component escape.  If no format program is	given  on  the
       command line, the following default program is used:

	    %<{error}%{error}: %{text}%|%(putstr(proper{text}))%>

       Address mode is equivalent to ap(8).

       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	in  the	 %{text} component.  You must specify a	format
       with -form or -format when using	raw mode.

       Date mode is identical to raw mode, with	one exception: if no format is
       specified, the following	format string is used:

	    %<(nodate{text})error: %{text}%|%(putstr(pretty{text}))%>

       Date mode is equivalent to dp(8).

       In message mode the arguments to	fmttest	are interpreted	as an optional
       folder and messages.  fmttest will read each specified message and make
       all  of	the components in the message available	to the format program.
       Also, the appropriate information for the  %(msg),  %(cur),  %(unseen),
       and  %(size)  function escapes will be made available for each message.
       If the -file switch is given, the arguments are	interpreted  as	 file-
       names  instead  of  message  numbers, but otherwise the behavior	is the
       same (except that the %(msg), %(cur), and  %(unseen)  function  escapes
       will not	provide	any useful information).

       The  default  format used in address mode is the	default	format used by
       scan.  The following command can	replicate  the	functionality  of  the
       repl command.

	    fmttest -nodupaddrs	-form replcomps	-outsize max [+folder] message

       Regardless  of the mode,	other components can be	provided to the	format
       program by the use of the --component switch.  For example, the follow-
       ing program will	test the use of	the "encrypted"	component:

	    fmttest --encrypted	yes -message cur

       In  message mode, components supplied on	the command line will override
       components from messages.

   Additional Switches
       The -dupaddrs and -nodupaddrs switches control  whether	duplicate  ad-
       dresses	are allowed or suppressed by the FORMATADDR instruction, which
       is used by the `%(formataddr)' function escape.	 In  normal  operation
       duplicate addresses are only suppressed by repl.

       The  -ccme  and	-noccme	 switches  control whether or not to count the
       user's local mailbox as a duplicate address.  This replicates  the  be-
       havior of the -cc me switch to repl, and	only applies if	-nodupaddrs is
       in effect.

       The -outsize switch controls the	maximum	number of printable characters
       that the	format engine will produce.  Characters	marked as non-printing
       by the format engine with `%(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:	 "max",	 which
       means  as  many characters as the format	engine can produce (limited by
       internal	buffers), and "width", which will set the value	to  the	 width
       of the terminal.	 In message mode it defaults to	"width", otherwise the
       default is "max".

       The -width switch controls the  column  width  which  is	 used  by  the
       `%(width)' function escape.  It defaults	to the terminal	width.

       The  -msgnum,  -msgcur,	-msgsize, and the -unseen switches all control
       the values used,	 respectively,	by  the	 following  function  escapes:
       `%(num)',  `%(cur)', `%(size)', and `%(unseen)'.	 If none are supplied,
       these values are	taken from the message in message mode;	in  all	 other
       modes the default values	are 0.

   Compiling and Tracing Format	Programs
       The  -dump  switch  outputs the complete	set of format instructions for
       the specified format program.  The -trace switch	will output each  for-
       mat instruction as it is	being executed,	and show the values of the num
       and str registers if they have changed from the	previous  instruction.
       The  output  buffer is also printed if it has changed from the previous

   Format Instructions
       It should be noted that there is	not a  one-to-one  correspondence  be-
       tween  format  escapes  and format instructions;	many instructions have
       side effects.  Instructions prefixed with "LV" generally	return a inte-
       ger  into  the  num (value) register; instructions prefixed with	a "LS"
       return a	string into the	str register.

       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	num register
       NUMF	     Formatted output of the num register
       STR	     Output the	str register
       STRF	     Formatted output of the str register
       STRFW	     Not used
       PUTADDR	     Output address list in str	register
       STRLIT	     Output str, no space compression
       STRLITZ	     Like STRLIT, but not counted against width
       LS_COMP	     Write component to	str register
       LS_LIT	     Write literal to str register
       LS_GETENV     Write environment var to str register
       LS_DECODECOMP Decode RFC	2047 encoded component to str register
       LS_DECODE     Decode RFC	2047 encoded string to str register
       LS_TRIM	     Trim trailing whitespace from str register
       LV_COMP	     Convert component to integer, store in num	register
       LV_COMPFLAG   Set num to	1 if TRUE set in component
       LV_LIT	     Load literal value	into num register
       LV_DAT	     Load value	from dat array into num	register (see note)
       LV_STRLEN     Set num to	the length of str
       LV_PLUS_L     Add value to num register
       LV_MINUS_L    Subtract value from num register
       LV_DIVIDE_L   Divide num	register by value
       LV_MODULO_L   num modulo	value
       LV_CHAR_LEFT  Store remaining number of printable chars in num
       LS_MONTH	     Write short name of month to str from date	component
       LS_LMONTH     Write long	name of	month to str from date component
       LS_ZONE	     Write time	zone offset to str from	date component
       LS_DAY	     Write short name of day of	week to	str from date component
       LS_WEEKDAY    Write long	name of	day of week to str from	date component
       LS_822DATE    Write RFC 822 compatible date to str from date component
       LS_PRETTY     Write date	with "pretty" timezone to str
       LV_SEC	     Write date	component seconds to num
       LV_MIN	     Write date	component minutes to num
       LV_HOUR	     Write date	component hour to num
       LV_MON	     Write date	component numeric month	to num (start at 1)
       LV_YEAR	     Write date	component year to num
       LV_YDAY	     Write date	component Julian day to	num
       LV_WDAY	     Write date	component day of week to num (0	== Sunday)
       LV_ZONE	     Write date	component time zone offset to num
       LV_CLOCK	     Write date	component in Unix epoch	time to	num
       LV_RCLOCK     Write offset of date component from current time to num
       LV_DAYF	     Write 1 to	num if day of week is explicit
       LV_DST	     Write 1 to	num if DST is in effect	for date component
       LV_ZONEF	     Write 1 to	num if timezone	is explicit
       LS_ADDR	     Write email address of addr component to str
       LS_PERS	     Write personal name of addr component to str
       LS_MBOX	     Write mailbox (username) of addr component	to str
       LS_HOST	     Write host	of addr	component to str
       LS_PATH	     Write host	route of addr component	to str
       LS_GNAME	     Write group name of addr component	to str
       LS_NOTE	     Write note	portion	of addr	component to str
       LS_822ADDR    Write "proper" RFC	822 version of addr component to str
       LS_FRIENDLY   Write friendly (name or note) of address component	to str
       LS_UNQUOTE    Remove RFC	2822 quotes from string
       LV_HOSTTYPE   Set num to	type of	host (0=local, 1=network)
       LV_INGRPF     Set num to	1 if address was inside	of group
       LV_NOHOSTF    Set num 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 str
       CONCATADDR    Like FORMATADDR, but will not suppress duplicates
       MYMBOX	     Set num if	address	component is a local address
       SAVESTR	     Save str register temporarily
       DONE	     End program
       NOP	     No	operation
       GOTO	     Jump to new instruction
       IF_S_NULL     Branch if str is NULL
       IF_S	     Branch if str is not NULL
       IF_V_EQ	     Branch if num is equal to value
       IF_V_NE	     Branch if num is not equal	to value
       IF_V_GT	     Branch if num is greater than value
       IF_MATCH	     Branch if str contains string
       IF_AMATCH     Branch if str starts with string
       S_NULL	     Set num to	1 if str is NULL
       S_NONNULL     Set num to	1 if str is not	NULL
       V_EQ	     Set num to	1 if num equals	value
       V_NE	     Set num to	1 if num does not equal	value
       V_GT	     Set num to	1 if num is greater than value
       V_MATCH	     Set num to	1 if str contains string
       V_AMATCH	     Set num to	1 if str starts	with string

       The 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:

	    dat[0]  %(num)
	    dat[1]  %(cur)
	    dat[2]  %(size)
	    dat[3]  %(width)
	    dat[4]  %(unseen)

       mh-format(5), repl(1), ap(8), dp(8), fmtdump(8)


       It shouldn't require as much code from other programs as	it does.

nmh-1.7.1			  2014-08-31			    FMTTEST(1)


Want to link to this manual page? Use this URL:

home | help