Content-type: text/html Man page of mh-format


Section: Devices and Network Interfaces (4)
Index Return to Main Contents


mh-format - Format file for the MH message system  


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 message; 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 modify existing ones. You should not attempt this unless you are an experienced 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 characters are honored: \b, \f, \n, \r and \t. Continuation lines in format 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 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.  

Component Escapes

A component escape represents a header field in the message being processed. 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 function 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 interpreted; 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:

A literal number or string; for example, %(func 1234) takes the number 1234 as its argument.
Any header component; for example, %(func{from}) takes the contents of the From: header field as an argument.
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 registers. arg represents the value of the argument supplied to the function.

The following table lists the function escapes:


msg integermessage number
cur integermessage is current
size integersize of message
strlen integerlength of str
width integeroutput buffer size in bytes
charleftintegerintegerspace left in output buffer
timenow integerseconds since the epoch
me stringthe user's mailbox
eqliteralintegernum == arg
neliteralintegernum != arg
gtliteralintegernum > arg
matchliteralbooleanstr contains arg
amatchliteralbooleanstr starts with arg
plus integerarg plus num
minus integerarg minus num
divideliteralintegernum divided by arg
numliteralintegerSet num to arg
litliteralintegerSet str to arg
nonzeroexprintegernum is non-zero
zeroexprintegernum is zero
nullexprintegerstr is empty
nonnullexprintegerstr is non-empty
voidexpr Set str or num
compcompstringSet str to component text
compvalcompintegernum set to atoi(str)
trimexpr trim trailing white space from str
putstrexpr print str
putstrfexpr print str in a fixed width
putnumexpr print num
putnumexpr print num in a fixed width

The following functions require a date component as an argument:


secdateintegerseconds of the minute
mindateintegerminutes of the day
hourdateintegerhours of the day (24 hour clock)
wdaydateintegerday of the week (Sunday=0)
daydatestringday of the week
weekdaydatestringday of the week (long)
sdaydateintegerday of the week known
1 for explicit in date
0 for implicit
-1 for unknown
mdaydateintegerday of the month
ydaydateintegerday of the year
mondateintegermonth of the year
monthdatestringmonth of the year (abbreviated)
lmonthdatestringmonth of the year (long form)
yeardateintegeryear of the century
zonedateintegertimezone in hours
tzonedatestringtimezone as a string
szonedateintegertimezone explicit?
1 for explicit
0 for implicit
-1 for unknown
date2localdatecoerce date to local timezone
date2gmtdatecoerce date to GMT
dstdateintegerdaylight savings in effect?
clockdateintegerseconds since the epoch
rclockdateintegerseconds prior to current time
twsdatestringofficial RFC 822 rendering of the date
prettydatestringa more user-friendly rendering
nodatedatestr 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).


properaddrstringofficial RFC 822 rendering
of the address
friendlystringstringa more user-friendly
persaddrstringthe personal name (first only)
noteaddrstringcommentary text (first only)
mboxaddrstringthe local part of the address
(first only)
mymboxaddrdoes the address refer to
the user's mailbox?
(0=no, 1=yes)
hostaddrstringthe domain part of the address
(first only)
nohostaddrintegerno host was present in the address
(first only)
typeaddrintegerthe type of host
-1 for uucp
0 for local
1 for network
2 for unknown
pathaddrstringthe route part of the address
(first only)
ingrpaddrintegerthe address appeared inside a group
(first only)
gnameaddrstringname of the group (first only)
formataddrexprappend arg to str as
an address list
putaddrliteralprint 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(putnumf(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), supplying a negative field width will cause the string to be right-justified within the field. The functions (putnum) and (putstr) ignore any field width arguments, and print their arguments in the minimum number of characters required.  


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.  


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: %<(mymbox{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 accordingly. 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.  


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



Component Escapes
Control Escapes
Function Escapes

This document was created by man2html, using the manual pages.
Time: 02:40:09 GMT, October 02, 2010