-- File: MailParseDefs.mesa
-- Last edited by Brotz, March 3, 1983 8:32 PM

MailParseDefs: DEFINITIONS =

BEGIN

-- General Note: The organization of this interface is motivated by RFC 822,
-- "Standard for the Format of Arpa Network Text Messages", August 13, 1982.


-- Types and Constants --


ParseErrorCode: TYPE = {none, badFieldName, badFieldBody, truncated};


ParseHandle: TYPE[1];
-- Instances of this type represent independent instances of the parser. This
-- permits multiple clients of this interface to be using the parser implementation
-- at the same time.


maxFieldNameSize: CARDINAL = 30;
-- This is a plausible maximum size for field names, but there is no guarantee
-- that it will not be exceeded. See the description of InitializeParse for a
-- discussion of field name truncation.


maxRecipientLength: CARDINAL = 64;
-- This is a reasonable bound on the total number of significant characters in a recipient
-- name (excluding excess white space, comments, and the like). However, the length of
-- the strings passed to ParseNameList’s "process" procedure may exceed this bound.


endOfInput: CHARACTER = 203C;
-- This character should be returned by the client’s "next" procedure (see InitializeParse)
-- when the end of the input is reached.


endOfList: CHARACTER = 204C;
-- This character may be used as an "invisible delimiter" terminating a list of names.
-- It has no other effect.


-- Signals --


ParseError: ERROR [code: ParseErrorCode];


-- Procedures --


InitializeParse: PROCEDURE [next: PROCEDURE RETURNS [CHARACTER],
notifyTruncation: BOOLEAN ← FALSE] RETURNS [ParseHandle];
-- Initializes the header parser, and returns a ParseHandle which is to be passed to all other
-- procedures of this interface. Subsequent invocations of GetFieldName, GetFieldBody,
-- and ParseNameList will obtain their input using "next". If "notifyTruncation" is TRUE,
-- GetFieldName and GetFieldBody will raise ParseError[truncated] if the string they are
-- collecting overflows the string provided. (The signal is not raised until the entire field
-- name or body has been scanned.) If "notifyTruncation" is FALSE, this signal is
-- suppressed.


FinalizeParse: PROCEDURE [ph: ParseHandle];
-- Finalizes the parser instance specified by "pH". This procedure must be called when the
-- client has finished parsing, either because of normal completion or because some error
-- has occurred. After calling this procedure, "pH" is no longer meaningful and must not
-- be reused. Note: FinalizeParse may not be called while a call to ParseNameList is
-- pending (for the same ParseHandle).


GetFieldName: PROCEDURE [ph: ParseHandle, fieldNameOut: STRING]
RETURNS [found: BOOLEAN];
-- GetFieldName presumes that "next" (see InitializeParse) is positioned to read the first
-- character of a field name and returns the field name, without the terminating colon,
-- in "fieldNameOut". GetFieldName leaves "next" ready to return the first character
-- following the colon (or, if the end of the message header has been reached, the
-- character (if any) after the two CRs that normally terminate the header). If the field
-- name is too long, the behavior of GetFieldName depends upon the "notifyTruncation"
-- parameter passed to InitializeParse. Upon return, "found" is FALSE if no field names
-- remain in the header. If the header field ends prematurely or illegal header characters
-- are encountered, ParseError[badFieldName] is raised.


GetFieldBody: PROCEDURE
[ph: ParseHandle, fieldBodyOut: STRING, suppressWhiteSpace: BOOLEAN ← FALSE];
-- The (remainder of the) current field body is read using "next" (see InitializeParse) and is
-- returned in "fieldBodyOut". If the field body is too long, the behavior GetFieldBody
-- depends upon the "notifyTruncation" parameter passed to InitializeParse. If the field
-- body terminates before a CR is seen, ParseError[badFieldBody] is raised. Upon return,
-- "fieldBodyOut" has no initial or terminal white space (blanks and tabs) and, if
-- "suppressWhiteSpace" is TRUE, each internal run of white space has been replaced by
-- a single blank. ArpaNet folding conventions are also observed.


ParseNameList: PROCEDURE
[ph: ParseHandle,
process: PROCEDURE [STRING, STRING, BOOLEAN, BOOLEAN] RETURNS [BOOLEAN],
-- process PROC [name, registry, isFile, isNested] RETURNS [write] --
write: PROCEDURE [CHARACTER] ← NIL ];
-- ParseNameList expects to read characters using "next" (see InitializeParse) for a structured
-- field body consisting of a list of recipient names. For each such name encountered, it
-- will call "process", passing it two string arguments that designate the simple name and
-- registry. The simple name is always non-empty. If the registry is absent, a string of
-- length zero (not NIL) is passed. If the simple name contains an Arpanet host name,
-- the registry passed is "Arpa". The string parameters are free from leading, trailing
-- and excess internal white space and are guaranteed to be at least "maxRecipientLength"
-- characters in length. The "process" routine has a third parameter that indicates, if
-- TRUE, that the simple name is a file name, if FALSE, that the simple name and
-- registry combine to form a normal name. The fourth parameter supplied to "process"
-- indicates, if TRUE, that the name was "nested", i.e., it occurred within brackets or
-- within a group. This is useful to the Answer client who may wish to suppress
-- duplicate elimination in such cases.
-- If any syntax errors are detected during parsing, ParseError[badFieldBody] is raised. It is
-- legitimate for the "process" routine to raise a signal that causes ParseNameList to be
-- unwound.


END. -- of MailParseDefs --