import java.io.Writer;
import java.io.IOException;

/**
 * Interface for objects which support parsing from and output to a
 * character stream.  Although Java provides no way to specify it, all
 * objects implementing this interface must provide a method with one
 * or both of the following exact signatures:
 * <p>
 * <code>
 * public static Parseable loadYourself(TokenStream s) throws IOException;<br>
 * public static Parseable loadYourself(Reader r) throws IOException;
 * </code>
 * <p>
 * These methods support input from a <code>Reader</code> object or,
 * if the implementer prefers, a <code>TokenStream</code> object.
 * <code>TokenStream</code> is not specified here and must be provided
 * by the implementer, but the intention is that it should translate a
 * raw character input stream into a sequence of tokens, provide a
 * pushback facility, etc.
 * <p>
 * <strong>Note:</strong> This interface provides a {@link
 * #printLastMove} method that is specific to the
 * <code>PuzzleMuncher</code> project.  To use this code elsewhere,
 * please remove that method from this interface.  Its inclusion here
 * is something of a sub-optimal design choice...
 *
 * @author Terran Lane
 * @version 1.0
 */
public interface Parseable {

  /**
   * Print a formatted representation of the current object to an
   * output stream.  The output format should be a human-readable
   * form, ideally corresponding to the input format defined by the
   * <code>loadYourself()</code> method(s).
   *
   * @param w	Output stream onto which the object will be formatted.
   * @throws IOException	In case of an error while writing to
   * the output stream.
   */
  public void printYourself(Writer w) throws IOException;

  /**
   * Print a formatted representation of a move (action) to an output
   * stream.  The move printed is the move that generated the current
   * state; for the START state (or any other state posessing no
   * PREDECESSOR state), this should return without printing
   * anything.  The output should be a human-readable form.
   * <p>
   * <strong>Note:</strong>  This method is specific to the
   * <tt>PuzzleMuncher</tt> project and to <code>PuzState</code>
   * objects in particular.  If you wish to apply the
   * <code>Parseable</code> interface to other applications, please
   * remove this method from the interface.
   *
   * @param w	Output stream onto which the object will be formatted.
   * @exception IOException if an error occurs
   */
  public void printLastMove(Writer w) throws IOException;
}