mh-format.man

早期freebsd实现

MH-FORMAT(5)         BSD Programmer's Manual         MH-FORMAT(5)


NNAAMMEE
       mh-format - format file for MH message system

SSYYNNOOPPSSIISS
       some _M_H commands

DDEESSCCRRIIPPTTIIOONN
       Several  _M_H  commands  utilize either a _f_o_r_m_a_t string or a
       _f_o_r_m_a_t file during their execution.  For example, _s_c_a_n (1)
       uses  a format string which directs it how to generate the
       scan listing for each message; _r_e_p_l (1) uses a format file
       which  directs  it how to generate the reply to a message,
       and so on.

       Format strings are designed to be efficiently parsed by _M_H
       which  means  they are not necessarily simple to write and
       understand.  This  means  that  novice,  casual,  or  even
       advanced  users  of  _M_H should not have to deal with them.
       Some    canned    scan    listing    formats    are     in
       /usr/contrib/mh-6.8/lib/scan.time,
       /usr/contrib/mh-6.8/lib/scan.size,                     and
       /usr/contrib/mh-6.8/lib/scan.timely.         Look       in
       /usr/contrib/mh-6.8/lib for other  _s_c_a_n  and  _r_e_p_l  format
       files which may have been written at your site.

       It  suffices  to  have your local _M_H expert actually write
       new format commands or modify existing ones.  This  manual
       section  explains  how to do that.  Note: familiarity with
       the C _p_r_i_n_t_f routine is assumed.

       A format string consists of  ordinary  text,  and  special
       multi-character  _e_s_c_a_p_e  sequences  which  begin with `%'.
       When specifying a format string,  the  usual  C  backslash
       characters  are honored: `\b', `\f', `\n', `\r', and `\t'.
       Continuation lines in format files end with  `\'  followed
       by the newline character.  There are three types of _e_s_c_a_p_e
       sequences: header _c_o_m_p_o_n_e_n_t_s, built-in _f_u_n_c_t_i_o_n_s, and flow
       _c_o_n_t_r_o_l.

       A  _c_o_m_p_o_n_e_n_t  escape  is  specified as `%{_c_o_m_p_o_n_e_n_t}', and
       exists for each header found in  the  message  being  pro-
       cessed.  For example `%{date}' refers to the "Date:" field
       of the appropriate message.  All component escapes have  a
       string  value.   Normally, component values are compressed
       by converting any  control  characters  (tab  and  newline
       included)  to spaces, then eliding any leading or multiple
       spaces.  However, commands may give different  interpreta-
       tions  to some component escapes; be sure to refer to each
       command's manual entry for complete details.

       A _f_u_n_c_t_i_o_n escape  is  specified  as  `%(_f_u_n_c_t_i_o_n)'.   All



[mh.6]                        MH.6.8                            1








MH-FORMAT(5)         BSD Programmer's Manual         MH-FORMAT(5)


       functions  are built-in, and most have a string or numeric
       value.


   CCoonnttrrooll--ffllooww eessccaappeess
       A _c_o_n_t_r_o_l escape is one of: `%<',  `%?',  `%|',  or  `%>'.
       These  are  combined  into  the conditional execution con-
       struct:

            %<condition
                 _f_o_r_m_a_t _t_e_x_t _1
            %?condition2
                 _f_o_r_m_a_t _t_e_x_t _2
            %?condition3
                 _f_o_r_m_a_t _t_e_x_t _3
            ...
            %|
                 _f_o_r_m_a_t _t_e_x_t _N
            %>

       Extra white space is shown here only for  clarity.   These
       constructs  may  be nested without ambiguity.  They form a
       general iiff--eellsseeiiff--eellssee--eennddiiff block where only one  of  the
       _f_o_r_m_a_t _t_e_x_t segments is interpreted.

       The `%<' and `%?' control escapes causes a condition to be
       evaluated.  This condition may be either a _c_o_m_p_o_n_e_n_t or  a
       _f_u_n_c_t_i_o_n.  The four constructs have the following syntax:

            %<{component}
            %<(function)
            %?{component}
            %?(function)

       These  control escapes test whether the function or compo-
       nent value is non-zero (for  integer-valued  escapes),  or
       non-empty (for string-valued escapes).

       If  this  test  evaulates true, then the format text up to
       the next corresponding control escape (one of `%|',  `%?',
       or  `%>')  is interpreted normally.  Next, all format text
       (if any) up to the corresponding `%>'  control  escape  is
       skipped.  The `%>' control escape is not interpreted; nor-
       mal interpretation resumes after the `%>' escape.

       If the test evaluates false, however, then the format text
       up to the next corresponding control escape (again, one of
       `%|', `%?', or `%>') is skipped, instead of  being  inter-
       preted.   If the control escape encountered was `%?', then
       the condition associated with that control escape is eval-
       uated,  and  interpretation  proceeds  after  that test as



[mh.6]                        MH.6.8                            2








MH-FORMAT(5)         BSD Programmer's Manual         MH-FORMAT(5)


       described in  the  previous  paragraph.   If  the  control
       escape  encountered  was  `%|', then the format text up to
       the corresponding `%>' escape is interpreted normally.  As
       above,  the  `%>'  escape  is  not  interpreted and normal
       interpretation resumes after the `%>' escape.

       The `%?' control escape and its following format  text  is
       optional,  and  may  be  included zero or more times.  The
       `%|' control escape and its following format text is  also
       optional, and may be included zero or one times.


   FFuunnccttiioonn eessccaappeess
       Most functions expect an argument of a particular type:

       _A_r_g_u_m_e_n_t _D_e_s_c_r_i_p_t_i_o_n            _E_x_a_m_p_l_e _S_y_n_t_a_x
       literal  A literal number,      %(_f_u_n_c 1234)
                or string              %(_f_u_n_c text string)
       comp     Any header component   %(_f_u_n_c{_i_n_-_r_e_p_l_y_-_t_o})
       date     A date component       %(_f_u_n_c{_d_a_t_e})
       addr     An address component   %(_f_u_n_c{_f_r_o_m})
       expr     An optional component, %(_f_u_n_c(_f_u_n_c_2))
                function or control,   %(_f_u_n_c %<{_r_e_p_l_y_-_t_o}%|%{_f_r_o_m}%>)
                perhaps nested         %(_f_u_n_c(_f_u_n_c_2{_c_o_m_p}))

       The  types _d_a_t_e and _a_d_d_r have the same syntax as _c_o_m_p, but
       require that the header component be  a  date  string,  or
       address string, respectively.

       All arguments except those of type _e_x_p_r are required.  For
       the _e_x_p_r argument type, the leading `%'  must  be  omitted
       for  component  and function escape arguments, and must be
       present (with a leading space) for  control  escape  argu-
       ments.

       The  evaluation  of  format  strings  is based on a simple
       machine with an integer register _n_u_m, and  a  text  string
       register  _s_t_r.  When a function escape is processed, if it
       accepts an optional _e_x_p_r argument which is not present, it
       reads  the current value of either _n_u_m or _s_t_r as appropri-
       ate.


   RReettuurrnn vvaalluueess
       Component escapes write the value of their message  header
       in  _s_t_r.  Function escapes write their return value in _n_u_m
       for functions returning _i_n_t_e_g_e_r or _b_o_o_l_e_a_n values, and  in
       _s_t_r  for  functions returning string values.  (The _b_o_o_l_e_a_n
       type is a subset of integers with usual values 0=false and
       1=true.)   Control escapes return a _b_o_o_l_e_a_n value, and set
       _n_u_m.



[mh.6]                        MH.6.8                            3








MH-FORMAT(5)         BSD Programmer's Manual         MH-FORMAT(5)


       All component escapes, and those  function  escapes  which
       return an _i_n_t_e_g_e_r or _s_t_r_i_n_g value, pass this value back to
       their caller in addition to setting  _s_t_r  or  _n_u_m.   These
       escapes will print out this value unless called as part of
       an argument to another  escape  sequence.   Escapes  which
       return  a  _b_o_o_l_e_a_n  value do pass this value back to their
       caller in _n_u_m, but will never print out the value.

       _F_u_n_c_t_i_o_n   _A_r_g_u_m_e_n_t _R_e_t_u_r_n   _D_e_s_c_r_i_p_t_i_o_n
       msg                 integer  message number
       cur                 integer  message is current
       size                integer  size of message
       strlen              integer  length of _s_t_r
       width               integer  output buffer size in bytes
       charleft            integer  bytes left in output buffer
       timenow             integer  seconds since the UNIX epoch
       me                  string   the user's mailbox
       eq         literal  boolean  _n_u_m == _a_r_g
       ne         literal  boolean  _n_u_m != _a_r_g
       gt         literal  boolean  _n_u_m > _a_r_g
       match      literal  boolean  _s_t_r contains _a_r_g
       amatch     literal  boolean  _s_t_r starts with _a_r_g
       plus       literal  integer  _a_r_g plus _n_u_m
       minus      literal  integer  _a_r_g minus _n_u_m
       divide     literal  integer  _n_u_m divided by _a_r_g
       modulo     literal  integer  _n_u_m modulo _a_r_g
       num        literal  integer  Set _n_u_m to _a_r_g
       lit        literal  string   Set _s_t_r to _a_r_g
       getenv     literal  string   Set _s_t_r to environment value of _a_r_g
       profile    literal  string   Set _s_t_r to profile component _a_r_g value
       nonzero    expr     boolean  _n_u_m is non-zero
       zero       expr     boolean  _n_u_m is zero
       null       expr     boolean  _s_t_r is empty
       nonnull    expr     boolean  _s_t_r is non-empty
       void       expr              Set _s_t_r or _n_u_m
       comp       comp     string   Set _s_t_r to component text
       compval    comp     integer  _n_u_m set to "aattooii(_c_o_m_p)"
       trim       expr              trim trailing white-space from _s_t_r
       putstr     expr              print _s_t_r
       putstrf    expr              print _s_t_r in a fixed width
       putnum     expr              print _n_u_m
       putnumf    expr              print _n_u_m in a fixed width

       These functions require a date component as an argument:

       _F_u_n_c_t_i_o_n   _A_r_g_u_m_e_n_t _R_e_t_u_r_n   _D_e_s_c_r_i_p_t_i_o_n
       sec        date     integer  seconds of the minute
       min        date     integer  minutes of the hour
       hour       date     integer  hours of the day (0-23)
       wday       date     integer  day of the week (Sun=0)
       day        date     string   day of the week (abbrev.)



[mh.6]                        MH.6.8                            4








MH-FORMAT(5)         BSD Programmer's Manual         MH-FORMAT(5)


       weekday    date     string   day of the week
       sday       date     integer  day of the week known?
                                    (0=implicit,-1=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 (abbrev.)
       lmonth     date     string   month of the year
       year       date     integer  year (may be > 100)
       zone       date     integer  timezone in hours
       tzone      date     string   timezone string
       szone      date     integer  timezone explicit?
                                    (0=implicit,-1=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 UNIX epoch
       rclock     date     integer  seconds prior to current time
       tws        date     string   official 822 rendering
       pretty     date     string   user-friendly rendering
       nodate     date     integer  _s_t_r not a date string

       These functions require an address component as  an  argu-
       ment.   The  return value of functions noted with `*' per-
       tain only to the first address present in the header  com-
       ponent.

       _F_u_n_c_t_i_o_n   _A_r_g_u_m_e_n_t _R_e_t_u_r_n   _D_e_s_c_r_i_p_t_i_o_n