mh-format
Purpose
Defines message formats for the Message Handling (MH)
Package.
Description
Several MH commands use either a format string (similar
to a printf string) or a format file to format their
output. For example, the scan command uses a format
string to format the scan listing for each message, while
the repl command uses a format file to format a message
reply.
A MH format string is similar to a printf string, but
uses multi-letter escape sequences beginning with the "%"
(percent) character. In addition, the usual C language
backslash characters (\b, \f, \n, \r, and \t) are recog-
nized. To continue a format line to the next line,
precede the newline character with a \ (backslash).
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 the escape requires an argument, the
system reads the current value of either num or str, and
if the escape returns a value, the system writes either
num or str.
Escapes
Escapes are of three types: components, functions, or
control. A component escape, specified as "%{"name"}",
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
%|
%>
which corresponds to an if-then-else construct. If
escape has a non-zero value (for integer-valued escapes)
or is not empty (for string-valued escapes), then every-
thing up to "%|" or "%>" (whichever comes first) is
interpreted; otherwise, processing skips to "%|" or "%>"
(whichever comes first) and starts interpreting again.
A function escape is specified as "%("name")" and is
statically defined. Here is the list:
+------------+----------------------+-------------------+
| Escape | Argument | Returns Interpreta|ion
+------------+----------------------+-------------------+
| nonzero | integer integer | num has a non- |
| | | zero value |
+------------+----------------------+-------------------+
| 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 not empty |
+------------+----------------------+-------------------+
| putstr | string | Display str |
+------------+----------------------+-------------------+
| putstrf | string | Display str in |
| | | the specified |
| | | width, for |
| | | example: |
| | | |
| | | %20(putstrf{subj|ct})
+------------+----------------------+-------------------+
| putnum | integer | Display num |
+------------+----------------------+-------------------+
| putnumf | integer | Display num in |
| | | the specified |
| | | width, for |
| | | example: |
| | | |
| | | %4(putnum(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 |
+------------+----------------------+-------------------+
+------------+----------------------+-------------------+
| Escape | Argument | Returns Interpreta|ion
+------------+----------------------+-------------------+
| timenow | integer | Seconds from |
| | | 00:00:00 GMT |
| | | January 1, 1970 |
+------------+----------------------+-------------------+
When str is a date, these escapes are useful:
+------------+----------------------+-------------------+
| Escape | Argument | Returns Interpreta|ion
+------------+----------------------+-------------------+
| 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 | Time zone |
+------------+----------------------+-------------------+
| sday | string integer | Day of the week |
| | | known. Values |
| | | are: |
| | | |
| | | 1 Explicit day |
| | | 0 Implicit (the |
| | | MH package |
| | | figured it |
| | | out) |
| | | -1 Unknown (the |
| | | MH package |
| | | could not |
| | | figure it out) |
+------------+----------------------+-------------------+
| clock | string integer | Seconds from |
| | | 00:00:00 GMT |
| | | January 1, 1970 |
+------------+----------------------+-------------------+
| rclock | string integer | Seconds prior to |
| | | current time |
+------------+----------------------+-------------------+
| month | string string | Month of the year |
+------------+----------------------+-------------------+
| lmonth | string string | Month of the year |
| | | (long form) |
+------------+----------------------+-------------------+
+------------+----------------------+-------------------+
| Escape | Argument | Returns Interpreta|ion
+------------+----------------------+-------------------+
| tzone | string string | Time zone |
+------------+----------------------+-------------------+
| day | string string | Day of the week |
+------------+----------------------+-------------------+
| weekday | string string | Day of the week |
| | | (long) |
+------------+----------------------+-------------------+
| tws | string string | RFC 822 rendering |
| | | of the date |
+------------+----------------------+-------------------+
| pretty | string string | A more user- |
| | | friendly ren- |
| | | dering |
+------------+----------------------+-------------------+
| nodate | string | Date was not |
| | | parseable |
+------------+----------------------+-------------------+
When str is an address, these escapes are useful:
+------------+----------------------+-------------------+
| Escape | Argument | Returns Interpreta|ion
+------------+----------------------+-------------------+
| 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. |
| | | Values are: |
| | | |
| | | -1 uucp |
| | | 0 Local |
| | | 1 Network |
| | | 2 Unknown |
+------------+----------------------+-------------------+
| nohost | string integer | No host was |
| | | present in the |
| | | address |
+------------+----------------------+-------------------+
| ingrp | string integer | The address |
| | | appeared inside a |
| | | group |
+------------+----------------------+-------------------+
| gname | string string | The name of the |
| | | group (present |
| | | for first address |
| | | only) |
+------------+----------------------+-------------------+
| note | string string | Commentary text |
+------------+----------------------+-------------------+
| proper | string string | RFC 822 rendering |
| | | of the address |
+------------+----------------------+-------------------+
| friendly | string string | A more user- |
| | | friendly ren- |
| | | dering |
+------------+----------------------+-------------------+
| mymbox | string | The address |
| | | refers to the |
| | | user's mailbox |
+------------+----------------------+-------------------+
| formataddr | string | Display str in an |
| | | address list |
+------------+----------------------+-------------------+
mhl.format
The mhl.format file is similar to other MH format files,
but controls the format of output when mhl is the message
listing program. Each line of the mhl.format file must
have one of the following forms:
;comment
:cleartext
variable"[",variable"...]"
component:"["variable"...]"
A line beginning with the ; character contains comments
that are ignored. A line beginning with the : character
contains text for output. A line that contains the :
character only produces a blank output line. A line
beginning with component defines the format of the speci-
fied component. If a variable follows a component, the
variable applies only to that component. Lines having
other formats define the global environment.
Variables that have integer or string values as arguments
must be followed by an "=" (equal) character and the
integer or string value (for example,
"overflowoffset=5"). String values must also be enclosed
in double quotation characters (for example,
"overflowtext="***""). An argument specified with the
suffix /G has global scope. An argument specified with
the suffix /L has local scope.
The entire mhl.format file is parsed before output proc-
essing begins. Thus, if a variable's global setting is
defined in multiple places, the last global definition
for that variable describes the real global setting.
The following table lists the mhl.format variables and
their arguments:
+-------------------+--------------+--------------------+
| Variable | Argument | Description |
+-------------------+--------------+--------------------+
| width | integer | Set the screen |
| | | width or component |
| | | width |
+-------------------+--------------+--------------------+
| length | integer | Set the screen |
| | | length or compo- |
| | | nent length |
+-------------------+--------------+--------------------+
| offset | integer | Indent component |
| | | the specified |
| | | number of columns |
+-------------------+--------------+--------------------+
| overflowtext | string | Output string at |
| | | the beginning of |
| | | each overflow line |
+-------------------+--------------+--------------------+
+-------------------+--------------+--------------------+
| Variable | Argument | Description |
+-------------------+--------------+--------------------+
| overflowoffset | integer | Indent overflow |
| | | lines the speci- |
| | | fied number of |
| | | columns |
+-------------------+--------------+--------------------+
| compwidth | integer | Indent component |
| | | text the specified |
| | | number of columns |
| | | after the first |
| | | line of output |
+-------------------+--------------+--------------------+
| uppercase | flag | Output text of |
| | | component in all |
| | | upper case charac- |
| | | ters |
+-------------------+--------------+--------------------+
| nouppercase | flag | Output text of |
| | | component in the |
| | | case entered |
+-------------------+--------------+--------------------+
| clearscreen | flag/G | Clear the screen |
| | | before each page |
+-------------------+--------------+--------------------+
| noclearscreen | flag/G | Do not clear the |
| | | screen before each |
| | | page |
+-------------------+--------------+--------------------+
| bell | flag/G | Produce an audible |
| | | indicator at the |
| | | end of each page |
+-------------------+--------------+--------------------+
| nobell | flag/G | Do not produce an |
| | | audible indicator |
| | | at the end of each |
| | | page |
+-------------------+--------------+--------------------+
| component | string/L | Use string as the |
| | | name for the spec- |
| | | ified component |
| | | instead of the |
| | | string component |
+-------------------+--------------+--------------------+
| nocomponent | flag | Do not output the |
| | | string component |
| | | for the specified |
| | | component |
+-------------------+--------------+--------------------+
| center | flag | Center component |
| | | on line. This |
| | | variable works for |
| | | one-line compo- |
| | | nents only. |
+-------------------+--------------+--------------------+
| nocenter | flag | Do not center com- |
| | | ponent |
+-------------------+--------------+--------------------+
+-------------------+--------------+--------------------+
| Variable | Argument | Description |
+-------------------+--------------+--------------------+
| leftadjust | flag | Strip off the |
| | | leading whitespace |
| | | characters from |
| | | each line of text |
+-------------------+--------------+--------------------+
| noleftadjust | flag | Do not strip off |
| | | the leading |
| | | whitespace charac- |
| | | ters from each |
| | | line of text |
+-------------------+--------------+--------------------+
| compress | flag | Change newline |
| | | characters in text |
| | | to space charac- |
| | | ters |
+-------------------+--------------+--------------------+
| nocompress | flag | Do not change |
| | | newline characters |
| | | in text to space |
| | | characters |
+-------------------+--------------+--------------------+
| formatfield | string | Use string as the |
| | | format string for |
| | | the specified com- |
| | | ponent |
+-------------------+--------------+--------------------+
| addrfield | flag | The specified com- |
| | | ponent contains |
| | | addresses |
+-------------------+--------------+--------------------+
| datefield | flag | The specified com- |
| | | ponent contains |
| | | dates. |
+-------------------+--------------+--------------------+
| ignore | unquoted | Do not ouptut com- |
| | string | ponent specified |
| | | by string |
+-------------------+--------------+--------------------+
Example
The following format string is the default for the scan
command. It has been divided into several pieces for
readability. The first part is:
%4(putnum(msg))%<(cur)+%| %>%<{replied}-%| %>
This says that the message number should be displayed in
four digits. If the message is the current message, a +
character is displayed next; otherwise, a space character
is displayed. If a "Replied:" field is present, then a -
(minus) is displayed; otherwise, a space is displayed.
Next:
%02(putnumf(mon{date}))%02(putnumf(mday{date}))
The month and day are displayed in two digits (zero
filled). Next:
%<{date} %|*>
If no "Date:" field is present, then an "*" (asterisk)
character is displayed; otherwise, a space character is
displayed. Next:
%<(mymbox{from})To:%14(putstr(friendly{to}))
If the message is from me, display "To:" followed by a
friendly rendering of the first address in the "To:"
field. Continuing:
%|%17(putstrf(friendly{from}))%
If the message is not from me, display "From:" followed
by the "From:" address. And finally:
%{subject}<<%{body}>>
Display the subject and initial body of the message.
This method of formatting messages allows you to extract
individual fields and display them in the format you
desire.
If you use the -form file argument when you run scan, it
treats each line in file as a format string and acts
accordingly. The following files contain scan listing
formats that you can look at: /usr/lib/mh/scan.time,
/usr/lib/mh/scan.size, and /usr/lib/mh/scan.timely.
The following line is an example of a line that could
appear in the mhl.format file:
width=80,length=40,clearscreen,overflowtext="***",overflowoffset=5
This format line defines the screen size to be "80"
columns by "40" rows and specifies that the screen should
be cleared before each page, that the overflow text
should be flagged with the string "***", and that the
overflow indentation should be "5" columns.
Related Information
The ap, dp, mhl, and scan commands in AIX Operating
System Commands Reference.
The "Overview of the Message Handling Package" in Man-
aging the AIX Operating System.