mh-format.rf

<B>Digital的Unix操作系统VAX 4.2源码</B>

putaddr	literal		print \fIstr\fR address list with
			\fIarg\fR as optional label;
			get line width from \fInum\fR
.re	
.fi

When escapes are nested, evaluation is done from inner-most to outer-most.
The outer-most escape must begin with `%'; the inner escapes must not.
For example,

.ti +.5i
%<(mymbox{from} To: %{to}%>

writes the value of the header component \*(lqFrom:\*(rq to \fIstr\fR;
then (\fImymbox\fR\^) reads \fIstr\fR 
and writes its result to \fInum\fR;
then the control escape evaluates \fInum\fR.  If \fInum\fR is
non-zero, the string \*(lqTo: \*(rq is printed followed by
the value of the header component \*(lqTo:\*(rq.

A minor explanation of (\fImymbox\fR\^{\fIcomp\fR\^}) is in order.
In general, it checks each of the addresses in the header component
\*(lq\fIcomp\fR\*(rq
against the user's mailbox name and any \fIAlternate-Mailboxes\fR.
It returns true if any address matches, however, it
also returns true if the \*(lq\fIcomp\fR\*(rq header is not present
in the message.  If needed, the (\fInull\fR\^) function can be
used to explicitly test for this condition.

When a function or component escape is interpreted and the result
will be immediately printed,
an optional field width can be
specified to print the field in exactly a given number of characters.
For example, a numeric escape like %4(\fIsize\fR\^) will print at most 4
digits of the message size; overflow will be indicated by a `?' in the
first position (like `?234').
A string escape like %4(\fIme\fR\^) will print the first 4 characters and
truncate at the end.  
Short fields are padded at the right with the fill character (normally,
a blank).  If the field width argument begins with a leading zero,
then the fill character is set to a zero.

As above,
the functions (\fIputnumf\fR\^) and (\fIputstrf\fR\^) print their result in
exactly the number of characters specified by their leading field width
argument.  
For example,
%06(\fIputnumf\fR\^(\fIsize\fR\^)) will print the message size 
in a field six characters wide filled with leading zeros;
%14(\fIputstrf\^\fR{\fIfrom\^\fR}) will print
the \*(lqFrom:\*(rq header component in fourteen characters with
trailing spaces added as needed.
For \fIputstrf\fR,
using a negative value for the field width causes right-justification
of the string within the field,
with padding on the left up to the field width.
The functions (\fIputnum\fR\^) and (\fIputstr\fR\^) print their result in
the minimum number of characters required, and ignore any leading 
field width argument.

The available output width is kept in an internal register; any output past
this width will be truncated.

With all this in mind,
here's the default format string for \fIscan\fR.
It's been divided into several pieces for readability.
The first part is:

.ti +.5i
%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 \*(lqReplied:\*(rq field is present then a `\-' else a space should
be printed.
Next:

.ti +.5i
%02(putnumf(mon{date}))/%02(putnumf(mday{date}))

the month and date are printed in two digits (zero filled) separated by
a slash.
Next,

.ti +.5i
%<{date} %|*>

If a \*(lqDate:\*(rq field was present,
then a space is printed, otherwise a `*'.
Next,

.ti +.5i
%<(mymbox{from})To:%14(putstrf(friendly{to}))

if the message is from me,
print `To:' followed by a \*(lquser\-friendly\*(rq rendering of the 
first address in the \*(lqTo:\*(rq field.
Continuing,

.ti +.5i
%|%17(putstrf(friendly{from}))%>

if the message isn't from me,
then the print the \*(lqFrom:\*(rq address is printed.
And finally,

.ti +.5i
%{subject}%<{body}<<%{body}%>

the subject and initial body (if any) are printed.

For a more complicated example, next consider
the default \fIreplcomps\fR format file.

.ti +.5i
%(lit)%(formataddr %<{reply-to}%|

This clears \fIstr\fR and formats the \*(lqReply-To:\*(rq header 
if present.  If not present, the else clause is executed:

.ti +.5i
%<{from}%|%<{sender}%|%<{return-path}%>%>%>%>)\\

This formats the 
\*(lqFrom:\*(rq, \*(lqSender:\*(rq and \*(lqReturn-Path:\*(rq
headers, stopping as soon as one of them is present.  Next:

.ti +.5i
%<(nonnull)%(void(width))%(putaddr To: )\\n%>\\

If the \fIformataddr\fR result is non\-null, it is printed as
an address (with line folding if needed) in a field \fIwidth\fR
wide with a leading label of \*(lqTo: \*(rq.

.ti +.5i
%(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\\

\fIstr\fR is cleared, and the 
\*(lqTo:\*(rq and \*(lqCc:\*(rq headers, along with the user's
address 
(depending on what was specified with
the \*(lq\-cc\*(rq switch to \fIrepl\fR\^) are formatted.

.ti +.5i
%<(nonnull)%(void(width))%(putaddr cc: )\\n%>\\

If the result is non\-null, it is printed as above with a
leading label of \*(lqcc: \*(rq.

.ti +.5i
%<{fcc}Fcc: %{fcc}\\n%>\\

If a \*(lq\-fcc\ folder\*(rq switch was given to \fIrepl\fR
(see \fIrepl\fR\0(1) for more details about %{\fIfcc\fR\^}),
an \*(lqFcc:\*(rq header is output.

.ti +.5i
%<{subject}Subject: Re: %{subject}\\n%>\\

If a subject component was present,
a suitable reply subject is output.

.nf
.ti +.5i
%<{date}In-reply-to: Your message of "\\
.ti +.5i
%<(nodate{date})%{date}%|%(tws{date})%>."%<{message-id}
.ti +.5i
             %{message-id}%>\\n%>\\
.ti +.5i
--------
.fi

If a date component was present,
an \*(lqIn-Reply-To:\*(rq header is output with the preface
\*(lqYour message of \*(rq.  If the date was parseable, it is
output in official format, otherwise it is output as\-is.
The message-id is included if present.
As with all plain\-text,
the row of dashes are output as\-is.

This last part is a good example for a little more elaboration.
Here's that part again in pseudo\-code:
.sp 1
.nf
.in +.5i
.ta .5i 1i 1.5i 2i
if (comp_exists(date))  then
	print (\*(lqIn-reply-to: Your message of \\\*(lq\*(rq)
	if (not_date_string(date.value) then
		print (date.value)
	else
		print (rfc822(date.value))
	endif
	print (\*(lq\\\*(rq\*(rq)
	if (comp_exists(message-id)) then
		print (\*(lq\\n\\t\*(rq)
		print (message-id.value)
	endif
	print (\*(lq\\n\*(rq)
endif
.re
.in -.5i
.fi
.sp 1
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.
.Fi
None
.Pr
None
.Sa
scan(1), repl(1), ap(8), dp(8)
.De
None
.Co
None
.Hi
This software was contributed for MH 6.3.  Prior to this, output
format specifications were much easier to write, but considerably
less flexible.
.Bu
On hosts where \fIMH\fR was configured with the BERK option,
address parsing is not enabled.
.En