    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    }