MH-FORMAT(5)         BSD Programmer's Manual         MH-FORMAT(5)NNAAMMEE       mh-format - format file for MH message systemSSYYNNOOPPSSIISS       some _M_H commandsDDEESSCCRRIIPPTTIIOONN       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                            1MH-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                            2MH-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                            3MH-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                            4MH-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