(* Copyright (C) 1990, Digital Equipment Corporation.         *)
(* All rights reserved.                                       *)
(* See the file COPYRIGHT for a full description.             *)

(* Last modified on Wed Mar 21 00:10:24 1990 by muller        *)


INTERFACE M3NoisyAST;

(* This interface defines conventions for associating comments, pragmas 
   and formatting information with an abstract syntax tree.  There 
   is a flag that directs the parser to save this information.  The 
   information is in the form of indexes into the reader from which 
   the AST was parsed, so you need access to the source if you want 
   to make use of the information. *)

IMPORT M3AST;

TYPE 
  Location = BRANDED "ASTLocation" REF LocRec; 
  LocRec = RECORD start, len: CARDINAL END;
  (* The interval [start .. start+len) of character indexes 
     in the reader that was parsed to produce the AST. 

     An entry of type Location on the property set of a node represents 
     the interval of source input that was parsed to produce the node. 
     Thus
  
        Property.Get(nd, TYPECODE(Location))
  
     returns the source location of nd. *)

TYPE Formatting = BRANDED "ASTFormatting" REF ARRAY OF LocRec;
  (* A sequence of intervals. *)

  (* A "formatting element" is a comment, pragma, blank line, formfeed, 
     or syntactically redundant occurrence of ";", "|" or VALUE.
     The formatting that "follows" a source token is the interval of source 
     characters that contain all formatting elements that directly 
     follow that source token; the interval is empty if there are no 
     such formatting elements.

     An AST node nd "owns" a token t if t is part of the source for 
     nd and is not part of the source for any child of nd. 

     An entry of type Formatting on the property set of a node 
     is an array whose ith entry is the formatting that follows the 
     ith token owned by the node.  The entry can be NIL if all of these 
     are empty intervals.
       
     For example, consider a ForStmt node, which represents the syntax
    
        FOR Id := Expr TO Expr [BY Expr] DO {Stmt ;...} END

     It owns the tokens FOR, :=, TO, DO, and END, also the token BY 
     if it is present.  In addition, if there are n statements in the 
     body, then the ForStmt node owns then n-1 semicolons between them.

     Single newlines before or after a comment or prama (with possible 
     intervening whitespace) are considered part of the formatting 
     sequence containing the comment or pragma. 

     GetLocation on an entire CompilationUnit will reveal what part 
     of the source was parsed, excluding the leading comment and any 
     text following the final ".".  This is the way to get at the 
     leading and final comments --- the last "." token in the 
     CompilationUnit never has any formatting.  *)

END M3NoisyAST.