MH-FORMAT(5) RISC/os Reference Manual MH-FORMAT(5)
NAME
mh-format - format file for MH message system
SYNOPSIS
some MH commands
DESCRIPTION
Several MH commands utilize either a format string or a for-
mat file during their execution. For example, scan (1) uses
a format string which directs it how to generate the scan
listing for each message; repl (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 MH
since they represent an integral part of MH. This means
that novice, casual, or even advanced users of MH should
deal with them. It suffices to have your local MH expert
actually write new format commands or modify existing ones.
This manual section explains how to do just that.
A format string is similar to a printf (3) string, but uses
multi-letter `%'-escapes. When specifying a 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.
The interpretation model is based on a simple machine with
two registers, num and str. The former contains an integer
value, the latter a string value. When an escape is pro-
cessed, 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. A component escape is specified as `%{name}', and
is created for each header found in the message being pro-
cessed. For example `%{date} refers to the "Date:" field of
the appropriate message. A component escape is always
string valued.
A control escape is one of: `%<escape', `%|', and `%>',
which correspond to if-then-else constructs: if `escape' is
non-zero (for integer-valued escapes), or non-empty (for
string-valued escapes), then everything up to `%|' or `%>'
(whichever comes first) is interpreted; otherwise, then skip
to `%|' or `%>' (whichever comes first) and start interpret-
ing again.
A function escape is specified as `%(name)', and is stati-
cally defined. Here is the list:
escape argument returns interpretation
Printed 1/15/91 MH Page 1
MH-FORMAT(5) RISC/os Reference Manual MH-FORMAT(5)
nonzero integer integer num is non-zero
zero integer integer num is zero
eq integer integer num == width
ne integer integer num != width
gt integer integer width > num
null string integer str is empty
nonnull string integer str is non-empty
putstr string print str
putstrf string print str in the specified width
(e.g., %20(putstrf{subject})
putnum integer print num
putnumf integer print num in the specified width
(e.g., %4(putnumf(msg))
msg integer message number
cur integer message is current
size integer size of message
strlen string integer length of str
me string the user's mailbox
plus integer add width to num
minus integer subtract num from width
charleft integer space left in output buffer
timenow integer seconds since the UNIX epoch
When str is a date, these escapes are useful:
escape argument returns interpretation
sec string integer seconds of the minute
min string integer minutes of the day
hour string integer hours of the day (24 hour clock)
mday string integer day of the month
mon string integer month of the year
wday string integer day of the week (Sunday=0)
year string integer year of the century
yday string integer day of the year
dst string integer daylight savings in effect
zone string integer timezone
sday string integer day of the week known
1 for explicit in date
0 for implicit (MH figured it out)
-1 for unknown (MH couldn't figure it out)
clock string integer seconds since the UNIX epoch
rclock string integer seconds prior to current time
month string string month of the year
lmonth string string month of the year (long form)
tzone string string timezone
day string string day of the week
weekday string string day of the week (long)
tws string string official 822 rendering of the date
pretty string string a more user-friendly rendering
nodate string date wasn't parseable
When str is an address, these escapes are useful:
escape argument returns interpretation
MH Page 2 Printed 1/15/91
MH-FORMAT(5) RISC/os Reference Manual MH-FORMAT(5)
pers string string the personal name of the address
mbox string string the local part of the address
host string string the domain part of the address
path string string the route part of the address
type string integer the type of host
-1 for uucp
0 for local
1 for network
2 for unknown
nohost string integer no host was present in the address
ingrp string integer the address appeared inside a group
gname string string name of the group (present for first
address only)
note string string commentary text
proper string string official 822 rendering of the address
friendly string string a more user-friendly rendering
mymbox string the address refers to the user's mailbox
formataddr string print str in an address list
With all this in mind, here's the default format string for
scan. It's been divided into several pieces for readabil-
ity. The first part is:
%4(putnumf(msg))%<(cur)+%| %>%<{replied}-%| %>
which says that the message number should be printed in four
digits, if the message is the current message then a `+'
else a space should be printed, and if a "Replied:" field is
present then a `-' else a space should be printed. Next:
%02(putnumf(mon{date}))/%02(putnumf(mday{date}))
the hours and minutes are printed in two digits (zero
filled). Next,
%<{date} %|*>
If no "Date:" field was present, then a `*' is printed, oth-
erwise a space. Next,
%<(mymbox{from})To:%14(putstrf(friendly{to}))
if the message is from me, print `To:' followed by a
"user-friendly" rendering of the first address in the "To:"
field. Continuing,
%|%17(putstrf(friendly{from}))%>
if the message isn't from me, then the print the "From:"
address is printed. And finally,
%{subject}%<{body}<<%{body}%>
Printed 1/15/91 MH Page 3
MH-FORMAT(5) RISC/os Reference Manual MH-FORMAT(5)
the subject and initial body are printed.
Although this seems complicated, in point of fact, 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, scan will treat
each line in the named file as a format string and act
accordingly. This lets the user employ canned scan listing
formats. Take a look at the three files
/usr/new/lib/mh/scan.time, /usr/new/lib/mh/scan.size, and
/usr/new/lib/mh/scan.timely.
FILES
None
PROFILE COMPONENTS
None
SEE ALSO
ap(8), dp(8)
DEFAULTS
None
CONTEXT
None
BUGS
On hosts where MH was configured with the BERK option,
address parsing is not enabled.
MH Page 4 Printed 1/15/91