mh-format man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

mh-format(4)							  mh-format(4)

NAME
       mh-format - Format file for the MH message system

DESCRIPTION
       Several	MH  commands  utilize  either a format string or a format file
       during their execution.	For example,  scan(1)  uses  a	format	string
       which specifies how scan should generate the scan listing for each mes‐
       sage; repl(1) uses a format file which directs it how to	 generate  the
       reply to a message, and so on.

       This  reference page describes how to write new format commands or mod‐
       ify existing ones.  You should not attempt this unless you are an expe‐
       rienced MH user.

       A  format  string  is similar to a printf string, but uses multi-letter
       escapes.	 The rest of this reference page assumes a  knowledge  of  the
       printf  routine.	 When specifying a string, the usual C backslash char‐
       acters are honored: \b, \f, \n, \r and \t.  Continuation lines in  for‐
       mat files end with \ followed by the newline character.

       When  an	 escape	 is interpreted and the result is immediately printed,
       you can specify an optional field width to print the field in exactly a
       given number of characters.  A numeric escape, such as "%4(size)", will
       print at most 4 digits of the value.  Any overflow is marked by a ?  in
       the  first  position,  for  example  ?123.  A  string  escape,  such as
       "%4(me)", will print the first four characters of the string.  In  both
       cases,  short fields are padded at the right, usually with a blank.  If
       the field width argument begins with a zero, for	 example  "%04(size)",
       the fill character is a zero.

       The  interpretation  model is based on a simple machine with two regis‐
       ters, num and str.  The former contains an integer value, the latter  a
       string value.  When an escape is processed, if it requires an argument,
       it reads the current value of either num or str; and, if it  returns  a
       value, it writes either num or str.

       Escapes are of three types: components, functions, and control.

   Component Escapes
       A  component escape represents a header field in the message being pro‐
       cessed.	It is written {name}, where the name is the name of the header
       field.  For example, {date} refers to the Date: field of the message.

       The  value  of  a  component  escape is the content of the named field.
       This is always a string.	 For example, the header of an unsent  message
       might  look  as	follows: To: smith@local cc: davis Subject: tomorrow's
       meeting In this example, the value of the component escape {subject} is
       the string "tomorrow's meeting".

   Control Escapes
       A  control  escape  is  one of: %<, %| and %>.  These correspond to if-
       then-else constructs.

       There are two syntaxes allowed by these control escapes.	 The first is:
       %<(function)Command-string%> %<{component}Command-String%> If the func‐
       tion or component is non-zero (for integer-valued escapes) or non-empty
       (for  string-valued  escapes), everything up to the corresponding %> is
       interpreted.  Otherwise, skip to the next  %>  and  begin  interpreting
       again.

       The  second  form  of  syntax  is as follows: %<(function)Then-Command-
       String%|Else-Command-String%>   %<{component}Then-Command-String%|Else-
       Command-String%>	 If the function or component is non-zero or non-null,
       the Then-Command-String is interpreted.	 Otherwise,  skip  to  %|  and
       interpret  the  Else-Command-String.   Only  one	 string is ever inter‐
       preted; if the first string is interpreted, the system skips  from  the
       %| control escape to the %> character.

   Function Escapes
       A function escape is specified as %(name), and is statically defined.

       Most  functions expect an argument of a particular type.	 In the tables
       of functions that follow, these types are referred to:

       literal	 A literal number or string; for example, %(func  1234)	 takes
		 the number 1234 as its argument.

       comp	 Any  header  component;  for example, %(func{from}) takes the
		 contents of the From: header field as an argument.

       expr	 An optional component, function or  string,  perhaps  nested.
		 For  example, %(func (func2{comp})) takes the return value of
		 the function (func2{comp}) as its argument.  If  no  argument
		 is provided, the function will read either the num or the str
		 register, as appropriate.

       Functions return three types of values: string, integer, and, for those
       functions  which return a true or false status, boolean.	 In the tables
       that follow, str and num represent the values stored  in	 these	regis‐
       ters.  arg  represents  the value of the argument supplied to the func‐
       tion.

       The following table lists the function escapes:

       ───────────────────────────────────────────────────────────────────
       Escape	  Argument   Returns   Interpretation
       ───────────────────────────────────────────────────────────────────
       msg		     integer   message number
       cur		     integer   message is current
       size		     integer   size of message
       strlen		     integer   length of str
       width		     integer   output buffer size in bytes
       charleft	  integer    integer   space left in output buffer
       timenow		     integer   seconds since the epoch
       me		     string    the user's mailbox
       eq	  literal    integer   num == arg
       ne	  literal    integer   num != arg
       gt	  literal    integer   num > arg
       match	  literal    boolean   str contains arg
       amatch	  literal    boolean   str starts with arg
       plus		     integer   arg plus num
       minus		     integer   arg minus num
       divide	  literal    integer   num divided by arg
       num	  literal    integer   Set num to arg
       lit	  literal    integer   Set str to arg
       nonzero	  expr	     integer   num is non-zero
       zero	  expr	     integer   num is zero
       null	  expr	     integer   str is empty
       nonnull	  expr	     integer   str is non-empty
       void	  expr		       Set str or num
       comp	  comp	     string    Set str to component text
       compval	  comp	     integer   num set to atoi(str)
       trim	  expr		       trim trailing white space from str
       putstr	  expr		       print str
       putstrf	  expr		       print str in a fixed width
       putnum	  expr		       print num

       putnum	  expr		       print num in a fixed width
       ───────────────────────────────────────────────────────────────────

       The following functions require a date component as an argument:

       ─────────────────────────────────────────────────────────────────────────
       Escape	    Argument   Returns	 Interpretation
       ─────────────────────────────────────────────────────────────────────────
       sec	    date       integer	 seconds of the minute
       min	    date       integer	 minutes of the day
       hour	    date       integer	 hours of the day (24 hour clock)
       wday	    date       integer	 day of the week (Sunday=0)
       day	    date       string	 day of the week
       weekday	    date       string	 day of the week (long)
       sday	    date       integer	 day of the week known
					 1 for explicit in date
					 0 for implicit
					 -1 for unknown
       mday	    date       integer	 day of the month
       yday	    date       integer	 day of the year
       mon	    date       integer	 month of the year
       month	    date       string	 month of the year (abbreviated)
       lmonth	    date       string	 month of the year (long form)
       year	    date       integer	 year of the century
       zone	    date       integer	 timezone in hours
       tzone	    date       string	 timezone as a string
       szone	    date       integer	 timezone explicit?
					 1 for explicit
					 0 for implicit
					 -1 for unknown
       date2local   date		 coerce date to local timezone
       date2gmt	    date		 coerce date to GMT
       dst	    date       integer	 daylight savings in effect?
       clock	    date       integer	 seconds since the epoch
       rclock	    date       integer	 seconds prior to current time
       tws	    date       string	 official RFC 822 rendering of the date
       pretty	    date       string	 a more user-friendly rendering
       nodate	    date		 str could not be parsed as a date
       ─────────────────────────────────────────────────────────────────────────

       The following functions require an address component  as	 an  argument.
       Some  functions	return a value based on the first address in the field
       only.  These are indicated by the note (first only).

       ───────────────────────────────────────────────────────────────────────
       Escape	    Argument   Returns	 Interpretation
       ───────────────────────────────────────────────────────────────────────
       proper	    addr       string	 official RFC 822 rendering
					 of the address
       friendly	    string     string	 a more user-friendly
					 rendering
       pers	    addr       string	 the personal name (first only)
       note	    addr       string	 commentary text (first only)
       mbox	    addr       string	 the local part of the address
					 (first only)
       mymbox	    addr		 does the address refer to
					 the user's mailbox?
					 (0=no, 1=yes)
       host	    addr       string	 the domain part of the address
					 (first only)
       nohost	    addr       integer	 no host was present in the address
					 (first only)
       type	    addr       integer	 the type of host
					 -1 for uucp
					 0 for local

					 1 for network
					 2 for unknown
       path	    addr       string	 the route part of the address
					 (first only)
       ingrp	    addr       integer	 the address appeared inside a group
					 (first only)
       gname	    addr       string	 name of the group (first only)
       formataddr   expr		 append arg to str as
					 an address list
       putaddr	    literal		 print str address list with arg
					 as an optional label; get line width
					 from num
       ───────────────────────────────────────────────────────────────────────

       Some functions that print their arguments can be controlled  by	giving
       field  width  arguments.	  The  functions (putnumf) and (putstrf) print
       their arguments as specified by the field width arguments.  So %06(put‐
       numf(size))  will  print	 the  message  size in six digits, filled with
       leading zeros; %14(putsrtf{from}) will print the From: header field  in
       14  characters, with trailing spaces as required.  With (putstrf), sup‐
       plying a negative field width will cause the string to be  right-justi‐
       fied  within the field.	The functions (putnum) and (putstr) ignore any
       field width arguments, and print their arguments in the minimum	number
       of characters required.

RESTRICTIONS
       When  the  friendly format for addresses is used, addresses longer than
       about 180 characters are truncated to an empty string.  This means that
       such addresses will not appear in the scan display.

       The  function  (mymbox{comp}) checks each of the addresses in the named
       header component {comp} against the user's mailbox  name,  and  against
       any  other  mailboxes  listed  in  the Alternate-Mailboxes entry in the
       user's .mh_profile.  It returns true if any  of	the  address  matches.
       However,	 it  also returns true if the named {comp} header field is not
       present. If necessary, you can use the (null) or (nonnull) functions to
       test explicitly for the presence of the field.

EXAMPLES
       The default format string for scan follows.  This has been divided into
       several pieces for readability.	The first part	is:  %4(msg)%<(cur)+%|
       %>%<{replied}-%|	 %>  This  means  that	the  message  number should be
       printed in four digits; if the message is the current message then a  +
       is printed.  If the message is not the current message, then a space is
       printed.	 If a Replied: field is	 present,  a  -	 is  printed.	If  no
       Replied:	  field	  is   present,	  then	a  space  is  printed.	 Next:
       %02(mon{date})/%02(mday{date}) The month and date are  printed  in  two
       digits  (zero  filled).	 Next:	%<{date}  %|*>	If  no	Date: field is
       present, then a	*  is  printed,	 otherwise  a  space.	Next:  %<(mym‐
       box{from})To:%14(friendly{to})  If  the	message	 is from me, print To:
       followed by a user-friendly rendering of the first address in  the  To:
       field.  %|%17(friendly{from})%> If the message is not from me, then the
       From: address is printed.  And  finally:	 %{subject}%<{body}<<%{body}%>
       The subject and initial body are printed preceded by the string <<.

       Although	 this  seems  complicated,  this  method is flexible enough to
       extract individual fields  and  print  them  in	any  format  the  user
       desires.

       If  the -form formatfile switch is given with the scan command, it will
       treat each line in the named file as a format string, and  act  accord‐
       ingly.  This lets the user develop template scan listing formats.  Some
       examples can be found in /usr/lib/mh/scan.time,	/usr/lib/mh/scan.size,
       and /usr/lib/mh/scan.timely.

RELATED INFORMATION
       scan(1), ap(8), dp(8) delim off

								  mh-format(4)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net