-- File: GVMailParse.mesa
-- based on MailParseDefs.mesa of Brotz, March 3, 1983  8:32 PM
--
-- Last Edited by: Willie-sue, April 19, 1983 10:13 am

DIRECTORY
   Rope USING [ROPE];

GVMailParse: CEDAR DEFINITIONS =

BEGIN

ROPE: TYPE = Rope.ROPE;


-- 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 = REF ParseInfo;
-- 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.

ParseInfo: TYPE;

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: PROC 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".  

FinalizeParse: PROC [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: PROC [ph: ParseHandle, next: PROC RETURNS [CHAR]]
        RETURNS [fieldName: ROPE, found: BOOL];
-- 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,
--   as "fieldName".  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). 
--  Upon return, "found" is FALSE if no field names remain in the header.
--  If the header field ends prematurely or illegal header charactersare encountered,
--   ParseError[badFieldName] is raised.


GetFieldBody: PROC
  [ph: ParseHandle, next: PROC RETURNS [CHAR],
   suppressBody: BOOL_ FALSE, suppressWhiteSpace: BOOL_ FALSE]
      RETURNS [fieldBody: ROPE];
-- The (remainder of the) current field body is read using "next" (see InitializeParse)
--  and is returned as "fieldBody".  If the field body terminates before a CR is seen,
--  ParseError[badFieldBody] is raised.  Upon return, "fieldBody" 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.
--  IF suppressBody is TRUE, then no fieldBody is generated


ParseNameList: PROC
  [ph: ParseHandle,
   next: PROC RETURNS[CHAR],
   process: PROC [ROPE, ROPE, BOOL, BOOL] RETURNS [ROPE, BOOL],
  -- process PROC [simpleName, registry, isFile, isNested] RETURNS [reg, write] --
  write: PROC [CHAR]_ 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 rope parameters are free from leading, trailing
--   and excess internal white space 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 GVMailParse --