//==============================================================================
// tribble/io/LineInputStreamI.java
//------------------------------------------------------------------------------

package tribble.io;


// System imports

import java.io.IOException;
import java.io.Reader;

import java.lang.String;


// Local imports

import tribble.io.TextLineI;


/*******************************************************************************
* Generic text line input stream interface.
*
* <p>
* This interface is used to implement any kind of input stream that is capable
* of reading a single line of text at a time.  Such a stream can be used to
* read the underlying source text for a lexical analyzer (lexer), such as the
* {@link LexerI} interface; or such a stream could be used as the underlying
* input stream for a character-based input stream, such as the
* {@link CharInputStreamI} interface.
*
* @version	$Revision: 1.2 $ $Date: 2001/04/22 18:21:50 $
* @since	2001-04-22
* @author
*	David R. Tribble,
*	<a href="mailto:david@tribble.com">david@tribble.com</a>.
*	<br>
*	<a href="../Copyright.html">Copyright</a> ©2001 by David R. Tribble,
*	all rights reserved.
*	<br>
*	Permission is granted to freely use and distribute this source code
*	provided that the original copyright and authorship notices remain
*	intact.
*
* @see	CharInputStreamI
* @see	LexerI
*/

public interface LineInputStreamI
{
// Identification

    /** Revision information. */
    static final String		REV =
        "@(#)tribble/io/LineInputStreamI.java $Revision: 1.2 $ $Date: 2001/04/22 18:21:50 $\n";


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public methods

    /***************************************************************************
    * Establishes the input stream from which to read text lines.
    *
    * @param	in
    * The input stream from which to read text lines.
    *
    * @since	1.1, 2001-04-22
    */

    public void setInput(Reader in);


    /***************************************************************************
    * Closes the input stream.
    *
    * @since	1.1, 2001-04-22
    */

    public void close();


    /***************************************************************************
    * Reads the next text line from the input stream.
    *
    * @return
    * The next text line read from the input stream, or null if there are no
    * more lines to read (i.e., the end of file was reached).
    *
    * @throws	IOException
    * Thrown if an I/O (read) error occurs.
    *
    * @since	1.1, 2001-04-22
    */

    public TextLineI readLine()
        throws IOException;


    /***************************************************************************
    * Reads the next text line from the input stream.
    *
    * @param	ln
    * The text line object to read the next line into.
    *
    * @return
    * True if a text line was successfully read from the input stream, or false
    * if there are no more lines to read (i.e., the end of file was reached).
    *
    * @throws	IOException
    * Thrown if an I/O (read) error occurs.
    *
    * @since	1.1, 2001-04-22
    */

    public boolean readLine(TextLineI ln)
        throws IOException;
}

// End LineInputStreamI.java