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 }