-- 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 --
(635)\f1