/*----------------------------------------------------------------

  * $Id: Interpreter.java,v 1.1.1.1 2004/01/26 20:46:18 pkb Exp $

  * 

  * (c)2000 - Paul Blankenbaker

  *

  * Revision Log

  * 

  *  2000-11-14 13:08:22        Paul Blankenbaker 

  * 

  *         Created initial version

  */

 //----------------------------------------------------------------

 package com.ccg.macros;

 import java.io.*;                // needed for I/O operations

 //----------------------------------------------------------------

 /** This interface should be implemented by all macro processors.

  * 

  * <p>All interpreters from this package are expected to read text

  * from a {@link Input Input} source and write the results of the text

  * processing to a {@link Output Output}.

  *

  * <p>To see a example of how this works in a final "macro processor",

  * take a look at the {@link AtMacros AtMacros} and {@link At At}

  * classes.

  * 

  * @version $Revision: 1.1.1.1 $

  * 

  * @since 1.0

  * 

  * @author $Author: pkb $

  * 

  * @see At */

 //----------------------------------------------------------------

 public interface Interpreter {

   //----------------------------------------------------------------

   /** The fundamental method which ALL {@link Interpreter interpreters} must implement.

    * 

    * This is the fundamental method which ALL implementations of a

    * {@link Interpreter} object must implement. This method is

    * designed to read information from a generic {@link Input input

    * source}, interpret any macros or special values from the input

    * and write the resulting output to the {@link Output output

    * destination}.

    *

    * <p>You can refer to the {@link AtMacros} class as a fully working

    * interpreter which does this. However, a quick example of how one

    * might use a interpreter to evaluate a simple string has been

    * included below. It assumes a macro "@name()" has been defined

    * which will insert the user's name during interpretation. If a

    * error results during interpretation, a simple string of "Hello:"

    * is returned.

    *

    * <pre><code>

    * {@link String String} getGreeting({@link Interpreter Interpreter} i) {

    *   try {

    *     {@link OutputStringBuffer OutputStringBuffer} osb = new OutputStringBuffer(200);

    *     i.interpret(new {@link Input Input}("Hello @name():"),osb);

    *     return osb.toString();

    *   } 

    *   catch ({@link IOException IOException} ioEx) { 

    *   }

    *   catch ({@link InterpretException InterpretException} inEx) {

    *   }

    *   return "Hello:";

    * }

    * </code></pre>

    * 

    * @param        in

    * 

    *         The {@link Input input} source to read the text information

    *         from. See the {@link Input} class to pass a {@link String} or

    *         set of characters. See the {@link InputReader} class to pass a

    *         file.

    * 

    * @param        out

    * 

    *         The {@link Output output} destination to write the results of

    *         the interpretation to. See the {@link OutputStringBuffer}

    *         class to get your results as a string, and the {@link

    *         OutputWriter} class to get your results to a file.

    * 

    * @throws        IOException

    * 

    *         If a I/O error is encountered when reading from a input

    *         source, or writing to a output destination.

    * 

    * @throws        InterpretException

    * 

    *         If the contents of the source being interpretted violates the

    *         rules of the interpreter. Note, each interpretter is able to

    *         define its own set of rules as to what is allowed or not.

    * 

    * @since        1.0

    * 

    * @see AtMacros */

   //----------------------------------------------------------------

   public void interpret(Input in, Output out)

     throws IOException, InterpretException;

 }