001    /* Copyright 2000, 2001, Compaq Computer Corporation */
002    
003    package javafe.reader;
004    
005    import javafe.ast.CompilationUnit;
006    import javafe.genericfile.*;
007    
008    /**
009     * A Reader is an object that reads then parses a {@link GenericFile},
010     * returning a {@link CompilationUnit}.  Iff problems arise, errors
011     * will be reported via {@link javafe.util.ErrorSet} and then
012     * <code>null</code> will be returned.
013     *
014     * <p> Readers may or may not cache the results of their reading.
015     *
016     * <p> The class {@link CachedReader} can be used to turn a noncaching
017     * Reader into a caching Reader.
018     */
019    
020    abstract public class Reader {
021      /***************************************************
022       *                                                 *
023       * Reading:                                          *
024       *                                                 *
025       **************************************************/
026      
027      /**
028       * Attempt to read and parse a CompilationUnit from target.
029       * Any errors encountered are reported via javafe.util.ErrorSet.
030       * Null is returned iff an error was encountered.<p>
031       *
032       *
033       * By default, we attempt to read only a spec (e.g., specOnly is set
034       * in the resulting CompilationUnit) to save time.  If avoidSpec is
035       * true, we attempt to return a non-spec, although this may not
036       * always be possible.<p>
037       *
038       *
039       * The result of this function may or may not be cached.<p>
040       * If it is cached, then only the value of avoidSpec used the first
041       * time a given file is read is used.  This may result in a spec
042       * being returned unnecessarily when avoidSpec is true.<p>
043       *
044       * Target must be non-null.<p>
045       * 
046       * @param target    The source to be read
047       * @param avoidSpec If true, then bodies are parsed as well, if possible;
048       *                  if false, no method bodies are parsed.
049       * @return          The resulting compilation unit, or null if an error
050       *                  occurred during parsing
051       */
052      abstract public CompilationUnit read(
053          /*@ non_null */ GenericFile target, 
054          boolean avoidSpec);
055    }