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    }