001 /* Copyright 2000, 2001, Compaq Computer Corporation */ 002 003 package javafe.parser; 004 005 import javafe.util.CorrelatedReader; 006 007 /** 008 * <code>PragmaParser</code> objects are called by <code>Lex</code> 009 * objects to parse pragmas out of pragma-containing comments. They 010 * are also called to see if a comment contains pragmas in the first 011 * place. See <code>Lex</code> for more details. 012 * 013 * <p> Pragmas are described using <code>Token</code> objects. The 014 * <code>ttype</code> field of a pragma token must be one of 015 * <code>TagConstants.LEXICALPRAGMA</code>, 016 * <code>TagConstants.MODIFIERPRAGMA</code>, 017 * <code>TagConstants.STMTPRAGMA</code>, or 018 * <code>TagConstants.TYPEDECLELEMPRAGMA</code>; the 019 * <code>auxVal</code> field must be filled have a type according to 020 * the table in <code>Token</code>. 021 * 022 * @todo These methods need JML specifications. 023 * 024 * @see javafe.parser.Token 025 * @see javafe.parser.Lex 026 */ 027 028 public interface PragmaParser 029 { 030 /** 031 * Decide whether a comment contains pragmas. When it encounters a 032 * comment, a <code>Lex</code> object passes the first character of 033 * the comment to the <code>checkTag</code> method of its 034 * <code>PragmaParser</code>. If this call returns false, the 035 * comment is assumed to contain no pragmas and thus is discarded. 036 * If this call returns true, the comment may contain pragmas, so it 037 * is converted into a <code>CorrelatedReader</code> and passed to 038 * <code>restart</code>. (The <code>tag</code> argument is either a 039 * <code>char</code> or <code>-1</code>; <code>-1</code> indicates 040 * the empty comment.) 041 */ 042 //@ requires -1 <= tag && tag <= 127; 043 boolean checkTag(int tag); 044 045 /** 046 * @todo Need to write documentation for this method. 047 */ 048 javafe.ast.FieldDecl isPragmaDecl(/*@ non_null @*/ Token l); 049 050 /** 051 * Restart a pragma parser on a new input stream. If 052 * <code>this</code> already opened on another 053 * <code>CorrelatedReader</code>, closes the old reader. 054 055 * <p> <code>eolComment</code> is true to indicate that the 056 * correlated reader stream is reading from a Java comment that 057 * begins with "//" as opposed to a Java comment that begins with 058 * "/*". </p> 059 */ 060 void restart(/*@ non_null @*/ CorrelatedReader in, boolean eolComment); 061 062 /** 063 * Parse the next pragma. If none are left, returns 064 * <code>false</code>; otherwise, returns <code>true</code> and 065 * updates fields of <code>destination</code> to describe the 066 * pragma. When <code>false</code> is returned, the pragma parser 067 * is expected to close the underlying <code>CorrelatedReader</code> 068 * and in other ways clean up resources. 069 * 070 * <p> This method requires that the <code>PragmaParser</code> is 071 * "open;" that is, <code>restart</code> has been called and, since 072 * the last call to <code>restart</code>, <code>getNextPragma</code> 073 * has not returned false and <code>close</code> has not been 074 * called. 075 */ 076 boolean getNextPragma(/*@ non_null @*/ Token destination); 077 078 /** 079 * Stop parsing the current reader. Sometimes a <code>Lex</code> 080 * object will be stopped before its associated 081 * <code>PragmaParser</code> has finished reading all pragmas out of 082 * a comment (for example, when <code>Lex.restart</code> is called). 083 * In this case, the <code>Lex</code> object calls 084 * <code>PragmaParser.close</code>. This method should close the 085 * underlying <code>CorrelatedReader</code> and in other ways clean 086 * up resources. 087 */ 088 void close(); 089 }