mh−format − format file for MH message system some MH commands
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 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 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. A component escape is specified as ‘%{name}’, and is created for each header found in the message being processed. 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 interpreting again.
A function escape is specified as ‘%(name)’, and is statically defined. Here is the list:
escapeargumentreturnsinterpretation
nonzerointegerintegernum is non−zero
zerointegerintegernum is zero
eqintegerintegernum == width
neintegerintegernum != width
gtintegerintegerwidth > num
nullstringintegerstr is empty
nonnullstringintegerstr is non−empty
putstrstringprint str
putstrfstringprint str in the specified width
(e.g., %20(putstrf{subject})
putnumintegerprint num
putnumfintegerprint num in the specified width
(e.g., %4(putnumf(msg))
msgintegermessage number
curintegermessage is current
sizeintegersize of message
strlenstringintegerlength of str
mestringthe user’s mailbox
plusintegeradd width to num
minusintegersubtract num from width
charleftintegerspace left in output buffer
timenowintegerseconds since the UNIX epoch
When str is a date, these escapes are useful:
escapeargumentreturnsinterpretation
secstringintegerseconds of the minute
minstringintegerminutes of the day
hourstringintegerhours of the day (24 hour clock)
mdaystringintegerday of the month
monstringintegermonth of the year
wdaystringintegerday of the week (Sunday=0)
yearstringintegeryear of the century
ydaystringintegerday of the year
dststringintegerdaylight savings in effect
zonestringintegertimezone
sdaystringintegerday 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)
clockstringintegerseconds since the UNIX epoch
rclockstringintegerseconds prior to current time
monthstringstringmonth of the year
lmonthstringstringmonth of the year (long form)
tzonestringstringtimezone
daystringstringday of the week
weekdaystringstringday of the week (long)
twsstringstringofficial 822 rendering of the date
prettystringstringa more user−friendly rendering
nodatestringdate wasn’t parseable
When str is an address, these escapes are useful:
escapeargumentreturnsinterpretation
persstringstringthe personal name of the address
mboxstringstringthe local part of the address
hoststringstringthe domain part of the address
pathstringstringthe route part of the address
typestringintegerthe type of host
−1 for uucp
0 for local
1 for network
2 for unknown
nohoststringintegerno host was present in the address
ingrpstringintegerthe address appeared inside a group
gnamestringstringname of the group (present for first
address only)
notestringstringcommentary text
properstringstringofficial 822 rendering of the address
friendlystringstringa more user−friendly rendering
mymboxstringthe address refers to the user’s mailbox
formataddrstringprint 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 readability. 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, otherwise 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}%>
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. None None ap(8), dp(8) None None On hosts where MH was configured with the BERK option, address parsing is not enabled.
NEWS-OSRelease 3.3