-- 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 --