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

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

  * 

  * (c)2000 - Paul Blankenbaker

  *

  * Revision Log

  * 

  *  2000-11-14 13:43:20        Paul Blankenbaker 

  * 

  *         Created initial version

  */

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

 package com.ccg.macros;

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

 import java.util.*;                // handy utility classes

 import java.lang.reflect.*;

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

 /** Implementation of a "@macro" {@link Interpreter Interpreter}.

  * 

  * <p>This class provides all of the building blocks for a full macro

  * {@link Interpreter interpreter}. It has all of the tools necessary

  * to scan ASCII text files looking for "@macros" which it will

  * then attempt to process.

  *

  * <p>A "&#064;macro" entered in the following form will always be

  * recognized:

  *

  * <pre>

  * @NAME(["ARG0"][,"ARG1"][,"ARG2"]...)

  * </pre>

  *

  * <p>By default, the NAME of the macro must contain only lower case

  * characters ('a'-'z'), upper case characters ('A'-'Z'), digits

  * ('0'-'9') and the underscore character ('_').

  *

  * <p>For example:

  *

  * <pre>

  * @define("pkb","Paul Blankenbaker")

  * </pre>

  *

  * <p>The following alternative forms can be used as well:

  *

  * <dl>

  *

  * <dt>&#064;NAME</dt><dd>If the macro takes no arguments, and is

  * followed by white space, you can use this "short form" notation. It

  * is a recognized "short form" of @NAME(). For example,

  * "<b>&#064;pkb - programmer</b>" is equivalent to "<b>&#064;pkb() -

  * programmer</b>".</dd>

  *

  * <dt>&#064;NAME(ARG0[,ARG1])</dt>If your arguments do not contain

  * any special characters (like spaces, quotes, commas, parenthesis),

  * you can optionally omit the double quotes. For example,

  * <b>&#064;define(pkb,Paul)</b> is interpretted the same as

  * <b>&#064;define("pkb","Paul")</b>.</dd>

  *

  * </dl>

  *

  * <p>Your best bet is to use the full form (include the parenthesis

  * and argument quoting) as that form will always be processed as you

  * expect.

  *

  * <p>At times, you may find that you need to escape characters in the

  * arguments you pass to the macros (in particular the double quote

  * character). The standard Java escape characters can be used in a

  * quoted argument. For example, to pass the argument <b>A "very" wet

  * day!</b> as a argument, one would construct the macro in the

  * following form:

  *

  * <pre>

  * @define("dayType","A \"very\" wet day!")

  * <pre>

  *

  * <p><b>NOTE:</b>The escape characters are only recognized within

  * quoted parameters. The following escape sequences are supported:

  *

  * <table border=1>

  *

  * <tr>

  * <th align="center"><strong>Escape Seq</strong></th>

  * <th align="center"><strong>Unicode Value</strong></th>

  * <th align="center"><strong>Description</strong></th>

  * </tr>

  *

  * <tr>

  * <td>\b</td><td>&#092;u0008</td><td>Backspace</td>

  * </tr>

  *

  * <tr>

  * <td>\f</td><td>&#092;u000c</td><td>Form feed</td>

  * </tr>

  *

  * <tr>

  * <td>\n</td><td>&#092;u000a</td><td>Line feed (new line)</td>

  * </tr>

  *

  * <tr>

  * <td>\r</td><td>&#092;u000d</td><td>Carriage return</td>

  * </tr>

  *

  * <tr>

  * <td>\t</td><td>&#092;u0009</td><td>Tab</td>

  * </tr>

  *

  * <tr>

  * <td>\'</td><td>&#092;u0027</td><td>Single Quote</td>

  * </tr>

  *

  * <tr>

  * <td>\"</td><td>&#092;u0022</td><td>Double Quote</td>

  * </tr>

  *

  * <tr>

  * <td>\\</td><td>&#092;u005c</td><td>Backslash</td>

  * </tr>

  *

  * <tr>

  * <td>\(</td><td>&#092;u0040</td><td>Begin Parenthesis</td>

  * </tr>

  *

  * <tr>

  * <td>\)</td><td>&#092;u0041</td><td>End Parenthesis</td>

  * </tr>

  *

  * <tr><td>&#092;uXXXX</td><td>&#092;uXXXX</td><td>Any unicode

  * character - must use 4 hex digits</td></tr>

  *

  * </table>

  *

  * <p>Using an unrecognized escape sequence in a string will have

  * unpredictable results. Most likely, the escape character will

  * simply be ignored (and not appear in the output). You may find

  * yourself hit with this when quoting DOS style file names. For

  * example, "c:\t.txt" should be written as "c:\\t.txt" to prevent the

  * "\t" from coming out as a tab character.

  *

  * <p>Also, the escaping of a double quote is only required (it never

  * hurts to do it), if:</p>

  *

  * <ul>

  * <li>The double quote is outside of parathesis.

  * <li>AND, the double quote is followed by a comma or end parenthesis.

  * </ul>

  *

  * <p>For example, the following parameters are equal <b>"Hello

  * \"Paul\"."</b> and <b>"Hello "Paul"."</b>, however the first form

  * is preferred (support of the latter form was added later as it

  * seemed reasonable). However, <b>"\"Paul\", B."</b> works where as

  * <b>""Paul", B."</b> does not (due to the comma following the double

  * quote).

  *

  * <p>There is one issue in regards to including paranthesis in quoted

  * strings. For example, consider the following:

  *

  * <pre>

  * @define("FullName","@param(0) @param(1)")

  * @define("PlusPhone","@FullName("@param(0)","@param(1)") (@param(2))")

  * @define("UnmatchedParen","((--->")

  * </pre>

  *

  * <p>The definition of "PlusPhone" above wants to pass two parameters

  * to the "@define" macro. The first parameter is not a problem,

  * but the second parameter contains nested quoted arguments. The

  * interpreter is "smart" in that it detects the parenthesis following

  * "@FullName" and ignores all quotes until the last parenthesis

  * is found. This allows the interpreter to correctly extract the two

  * arguments in the complex example. However, because of this rule,

  * the "UnmatchedParen" will not be interpretted properly. When the

  * two mismatched parathesis in "((--->" string are encountered the

  * interpreter will ignore the ending quote until it finds two

  * matching ending parenthesis. If you find yourself in this

  * situation, you will need to "escape" your parenthesis and write

  * your macro as follows:

  *

  * <pre>

 @define("FullName","@param(0) @param(1)")

 @define("PlusPhone","@FullName("@param(0)","@param(1)") (@param(2))")

 @define("UnmatchedParen","\(\(--->")

 @define(pkb,"@PlusPhone(Paul,"Blankenbaker","555-7676")")

 @UnmatchedParen() @pkb

  * </pre>

  *

  * <p>It should be noted, that this class doesn't actually provide any

  * built in macros itself. This class just provides the parsing

  * building blocks and methods to make the construction of custom

  * macro sets possible. Typically other classes make use of the {@link

  * #addMacro(String,String)} method to define simple text replacement,

  * the {@link #addMacro(String,MacroHandler)} method to install more

  * sophisticated macro handlers, and the {@link #addMacros(Object)} to

  * automatically add methods with a certain signature to the set of

  * recognized macro handlers.

  *

  * <p>The {@link At At} class is a full implementation of an

  * interpreter which defines several built in macros and provides a

  * means for additional macros to be defined based on the contents of

  * the processed file.

  * 

  * 

  * @version $Revision: 1.1.1.1 $

  * 

  * @since 1.0

  * 

  * @author $Author: pkb $

  * 

  * @see At */

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

 public class AtMacros implements Interpreter {

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

   /** Initializes object to the default parsing rules.

    * 

    * <p>This constructor prepares the macro interpreter with the

    * default parsing rules, but <b>without</b> any definitions.

    *

    * <p>After construction, one will typically use the the "add macro"

    * methods to define macros (see {@link #addMacro(String,String)},

    * {@link #addMacro(String,MacroHandler)}, and {@link

    * #addMacros(Object)}).

    *

    * <p>Typically one will probably not want to change the parsing

    * characters, HOWEVER you can with methods like {@link

    * #setStartMacroChar(char)}, {@link #setEndMacroChars(String)},

    * etc.

    * 

    * @since        1.0 */

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

   public AtMacros() {

     _Macros = new Hashtable();

     _RecursionDepth = 128;

     _StartMacroChar = '@';

     _StartQuoteChar = '\"';

     _EndQuoteChar = '\"';

     _EscapeChar = '\\';

     _StartParamChar = '(';

     _EndParamChar = ')';

     _SepParamChar = ',';

                                 // array of parameters for invocation

     _Params = new Vector[_RecursionDepth];

                                 // characters which indicate end of a macro

     setEndMacroChars("()~!#$%^&*-+=@{}[]\"|\\\';:<>,./?` \t\n\r");

   }

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

   /** A copy constructor of another {@link AtMacros AtMacros} object.

    * 

    * <p>This constructor makes a duplicate of another {@link AtMacros

    * AtMacros} object. Initially after construction, both objects will

    * have the same set of definitions - however any new definitions

    * added to either the new copy or the original will only affect the

    * object they are added to (each object will have its own

    * definition rules after the intial construction).

    * 

    * @param        from

    * 

    *         The {@link AtMacros AtMacros}

    * 

    * @since        1.0

    * 

    * @see #AtMacros() */

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

   public AtMacros(AtMacros from) {

     _Macros = (Hashtable) from._Macros.clone();

     _RecursionDepth = from._RecursionDepth;

     _StartMacroChar = from._StartMacroChar;

     _StartQuoteChar = from._StartQuoteChar;

     _EndQuoteChar = from._EndQuoteChar;

     _EscapeChar = from._EscapeChar;

     _StartParamChar = from._StartParamChar;

     _EndParamChar = from._EndParamChar;

     _SepParamChar = from._SepParamChar;

     _RecursionDepth = from._RecursionDepth;

     _Depth = 0;

                                 // array of parameters for invocation

     _Params = new Vector[_RecursionDepth];

     _ParamIdx = 0;

     _EndMacroChars = (boolean[]) from._EndMacroChars.clone();

   }

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

   /** Fetch one of the parameters (arguments) passed to a macro.

    * 

    * <p>This method is used by macro handlers to retrieve arguments

    * which are passed to the macro. For example, if one were to write

    * a macro handler for the "@define(NAME,TEXT)" macro, the

    * handler would use this method to retrieve the information (see

    * {@link At#define} for the definition of this handler).

    *

    * <p>For example, if the following text were being processed by the

    * "define" macro handler:

    *

    * <pre>

    * @define("pkb","Paul Blankenbaker")

    * </pre>

    *

    * <p>The "define" macro handler would get the value <b>pkb</b> if

    * it invoked {@link #getParameter getParameter(0)}, and the value

    * <b>Paul Blankenbaker</b> if it invoked {@link #getParameter

    * getParameter(1)}.

    * 

    * <p>Requesting a parameter that was not passed returns a zero

    * length string (not null).

    *

    * <p>It should be noted that each parameter returned is also run

    * through the interpreter if you set the second parameter to

    * true. This means that if one of the arguments contains macros

    * itself, they will be expanded in the returned result. Pass false

    * as the second parameter to get the "raw" string value of the

    * original parameter.

    * 

    * @param        index

    * 

    *         The index of the argument you want to request (0 correpsonds

    *         to the first argument, 1 to the second, and so on).

    * 

    * @param        eval

    * 

    *         Whether the raw value of the parameter should be evaluated or

    *         not.

    * 

    * @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.

    * 

    * @return

    * 

    *         The interpretted results of the parameter passed - never

    *         returns null, but may return a zero length string (if the

    *         index specify is out of range or no argument was passed).

    * 

    * @since        1.0 */

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

   public String getParameter(int i, boolean eval) 

     throws InterpretException, IOException {

                                 // if no parameter vector to search,

                                 // or negative index passed, return

                                 // empty string

     int pi = _ParamIdx - 1;

     if ((i < 0) || (pi < 0) || (pi >= _Params.length)) return "";

                                 // if parameter vector is null or

                                 // doesn't contain a value for the

                                 // index specified, return null

     Vector params = _Params[pi];

     if ((params == null) || (i >= params.size())) return "";

                                 // if no entry for specified parameter

                                 // return empty string

     Object entry = params.elementAt(i);

     if (entry == null) return "";

                                 // otherwise return interpretted parameter

     if (eval) {

                                 // back off parameter index incase

                                 // parameter contains references to

                                 // other parameters

       _ParamIdx--;                

       String val = interpretCheck(entry.toString());

       _Params[pi] = params;        // incase parameters clobbered, restore now

       _ParamIdx++;

       return val;

     }

     return entry.toString();

   }

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

   /** Fetch one of the parameters (arguments) passed to a macro.

    * 

    * <p>This method is used by macro handlers to retrieve arguments

    * which are passed to the macro. For example, if one were to write

    * a macro handler for the "@define(NAME,TEXT)" macro, the

    * handler would use this method to retrieve the information (see

    * {@link At#define} for the definition of this handler).

    *

    * <p>For example, if the following text were being processed by the

    * "define" macro handler:

    *

    * <pre>

    * @define("pkb","Paul Blankenbaker")

    * </pre>

    *

    * <p>The "define" macro handler would get the value <b>pkb</b> if

    * it invoked {@link #getParameter getParameter(0)}, and the value

    * <b>Paul Blankenbaker</b> if it invoked {@link #getParameter

    * getParameter(1)}.

    * 

    * <p>Requesting a parameter that was not passed returns a zero

    * length string (not null).

    *

    * <p>It should be noted that each parameter returned is also run

    * through the interpreter. This means that if one of the arguments

    * contains macros itself, they will be expanded in the returned

    * result.

    * 

    * @param        index

    * 

    *         The index of the argument you want to request (0 correpsonds

    *         to the first argument, 1 to the second, and so on).

    * 

    * @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.

    * 

    * @return

    * 

    *         The interpretted results of the parameter passed - never

    *         returns null, but may return a zero length string (if the

    *         index specify is out of range or no argument was passed).

    * 

    * @since        1.0 */

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

   public String getParameter(int i) throws InterpretException, IOException {

     return getParameter(i,true);

   }

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

   /** Add a simple string subsitution macro.

    * 

    * <p>This command defines (or replaces an existing definition) a

    * macro which evaluates to a simple text replacement. Hence, when

    * the macro is encountered during processing it will be replaced

    * with the <em>interpretted</em> value assigned. For example:

    *

    * <code><pre>

    * public static void foo(AtMacros am) {

    *   am.addMacro("first","Paul");

    *   am.addMacro("last","Blankenbaker");

    *   am.addMacro("name","@first() @last()");

    * }

    * </pre></code>

    *

    * <p>After the following is run, when the macro "&#064;first" is

    * encountered in the text being processed, it will be replaced with

    * "Paul". The key thing to notice here is that the replaced text is

    * also interpretted. This means that when the "@name" macro is

    * encountered in the text being processed, its contained text will

    * be interpretted as well. This would result in "Paul Blankenbaker"

    * appearing in the output in this example.

    * 

    * @param        mname

    * 

    *         The name of the macro to define (if you pass null or a zero

    *         length string we ignore your request).

    * 

    * @param        val

    * 

    *         The value to associate with the macro (null is treated like "")

    * 

    * @since        1.0

    * 

    * @see #addMacros */

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

   public void addMacro(String name, String val) {

     if ((name != null) && (name.length() > 0)) {

       if (val == null) val = "";

       _Macros.put(name,val);

     }

   }

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

   /** Fetch the object definition for a particular macro.

    * 

    * @param        mname

    * 

    *         The name of the macro you want to lookup the associated value

    *         for. You can pass null - and get null back.

    * 

    * @return

    * 

    *         The {@link java.lang.Object object} associated with the macro

    *         name, or null if there isn't one associated.

    * 

    * @since        1.0 */

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

   public Object getMacro(String name) {

     return (name != null) ? _Macros.get(name) : null;

   }

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

   /** Fetch the list of all macro names which are currently defined.

    * 

    * @return

    * 

    *         The {@link Enumeration list} of all macro names which are

    *         currently defined.

    * 

    * @since        1.0 */

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

   public Enumeration getMacroNames() {

     return _Macros.keys();

   }

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

   /** Associate a {@link MacroHandler MacroHandler} with a macro name.

    *

    * <p>This installs any object which implements the {@link

    * MacroHandler MacroHandler} interface into the defined set of

    * macros.

    * 

    * @param        mname

    * 

    *         The name of the macro to define (this must NOT be null!).

    * 

    * @param        val

    * 

    *         The value to associate with the macro (null is treated like "")

    * 

    * @since        1.0 */

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

   public void addMacro(String name, MacroHandler mh) {

     Object o = mh;

     if (o == null) o = "";

     _Macros.put(name,o);

   }

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

   /** Add all "macro handling methods" from a class to our defined set.

    * 

    * <p>This method can be used to install a LOT of macro handlers

    * based upon the method signatures within the object passed. It

    * uses Java's reflection mechanisms to inspect the methods in the

    * object passed. For every method which matches the following

    * signature:

    *

    * <pre>

    * public void mName({@link Output Output} out, {@link Vector Vector} args)

    *   throws {@link IOException IOException}, {@link InterpretException InterpretException}

    * </pre>

    *

    * <p>A new macro is added such that if the method name in its macro

    * form ("@mName") is encountered, the associated method in the

    * object passed will be invoked to carry out the processing.

    *

    * <p>This is the easy way to add your own specialized macro

    * handlers, and what the {@link At} utility relies upon to add all

    * of its "built-in" functions (like: "@define",

    * "@include", "@param", etc).

    * 

    * @param        o

    * 

    *         The object to inspect and look for methods matching the rules

    *         specified above (must not be null).

    * 

    * @since        1.0

    * 

    * @see At */

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

   public void addMacros(Object macroHandler) {

     Method[] methods = macroHandler.getClass().getMethods();

     for (int i = 0; i < methods.length; i++) {

       Class[] ptypes = methods[i].getParameterTypes();

       if ((ptypes.length == 2) &&

           (ptypes[0] == Output.class) &&

           (ptypes[1] == Vector.class)) {

         String mname = methods[i].getName();

         _Macros.put(mname,new MacroHandlerMethod(macroHandler,methods[i]));

       }

     }

   }

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

   /** Process a {@link Input input source} and write the results to a {@link Output output destination}.

    * 

    * <p>This is one of the methods used to actually do the processing

    * of data. It reads information from the input, processes any

    * contained macros and writes the results to the output.

    *

    * <p>This is how one typically starts to process macros. This

    * method simply resets our current recursion depth and then invokes

    * the {@link #interpretCheck(Input,Output) recursion safe}

    * implementation to do the actual processing.

    * 

    * @param        in

    * 

    *         A {@link Input input source} to read and interpret

    * 

    * @param        out

    * 

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

    *         the interpretation.

    * 

    * @throws        InterpretException

    * 

    *         If a internal (or macro error) is encountered while processing.

    * 

    * @throws        IOException

    * 

    *         If a problem reading input or writing output is encountered.

    * 

    * @since        1.0

    * 

    * @see #interpret(String)

    * @see #interpretCheck(Input,Output) */

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

   public void interpret(Input in, Output out)

     throws IOException, InterpretException {

     _Depth = 0;

     _ParamIdx = 0;

     interpretCheck(in,out);

   }

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

   /** Process a source string and return the resulting string.

    * 

    * <p>This method evaluates a simple string for any contained

    * macros. Any contained macros are expanded and the resulting

    * string is returned.

    * 

    * @param        in

    * 

    *         A string to interpret - if you pass null you get null back.

    * 

    * @return

    * 

    *         The results of processing the input string (any contained

    *         macros are evaluated)

    * 

    * @throws        InterpretException

    * 

    *         If a internal (or macro error) is encountered while processing.

    * 

    * @throws        IOException

    * 

    *         If a problem reading input or writing output is encountered.

    * 

    * @since        1.0

    * 

    * @see #interpret(Input,Output) */

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

   public String interpret(String in)

     throws IOException, InterpretException {

                                 // if null or no macro start character, just

                                 // return the string

     if ((in == null) || (in.indexOf(getStartMacroChar()) < 0)) return in;

                                 // otherwise do interpretation

     OutputStringBuffer osb = new OutputStringBuffer(in.length()*2);

     _Depth = 0;

     _ParamIdx = 0;

     interpretCheck(new Input(in),osb);

     return osb.toString();

   }

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

   /** Process a source string and return the resulting string.

    * 

    * <p>This method evaluates a simple string for any contained

    * macros. Any contained macros are expanded and the resulting

    * string is returned.

    *

    * <p>Since macros often require recursive evaulation, this method

    * makes sure that the recursion {@link #setDepth depth} is not

    * exceeded. If the recursion depth is exceeded, a {@link

    * InterpretException Interpret exception} is thrown indicating as

    * much.

    * 

    * @param        in

    * 

    *         A string to interpret - if you pass null you get null back.

    * 

    * @return

    * 

    *         The results of processing the input string (any contained

    *         macros are evaluated)

    * 

    * @throws        InterpretException

    * 

    *         If a internal (or macro error) is encountered while processing.

    * 

    * @throws        IOException

    * 

    *         If a problem reading input or writing output is encountered.

    * 

    * @since        1.0

    * 

    * @see #interpretCheck(Input,Output) */

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

   public String interpretCheck(String in)

     throws IOException, InterpretException {

                                 // if null or no macro start character, just

                                 // return the string

     if ((in == null) || (in.indexOf(getStartMacroChar()) < 0)) return in;

                                 // otherwise do interpretation

     OutputStringBuffer osb = new OutputStringBuffer(in.length()*2);

     interpretCheck(new Input(in),osb);

     return osb.toString();

   }

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

   /** Process a {@link Input input source} and write the results to a {@link Output output destination}.

    * 

    * <p>This is one of the methods used to actually do the processing

    * of data. It reads information from the input, processes any

    * contained macros and writes the results to the output.

    *

    * <p>Since macros often require recursive evaulation, this method

    * makes sure that the recursion {@link #setDepth depth} is not

    * exceeded. If the recursion depth is exceeded, a {@link

    * InterpretException Interpret exception} is thrown indicating as

    * much.

    * 

    * @param        in

    * 

    *         A {@link Input input source} to read and interpret

    * 

    * @param        out

    * 

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

    *         the interpretation.

    * 

    * @throws        InterpretException

    * 

    *         If a internal (or macro error) is encountered while processing.

    * 

    * @throws        IOException

    * 

    *         If a problem reading input or writing output is encountered.

    * 

    * @since        1.0

    * 

    * @see #interpret(String)

    * @see #interpret(Input,Output) */

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

   public void interpretCheck(Input in, Output out)

     throws IOException, InterpretException {

     if (_Depth >= _RecursionDepth) {

       throw new InterpretException("recursion depth of "+_Depth+

                                    " exceeded - giving up");

     }

     _Depth++;

     char atSymbol = getStartMacroChar();

     char startParamChar = getStartParamChar();

     boolean[] endMacro = _EndMacroChars;

     int endMacroLen = endMacro.length;

                                 // get info about current buffer

     char[] shiftBuf = in.getBuffer();

     int ofs = in.getOffset();

     int len = in.getLength();

                                 // while data to process

     for (;;) {

       if (ofs >= len) {                // if we are out of data in buffer

                                 // try to get more

         len = in.shiftAndFill(ofs);

         ofs = in.getOffset();        // reset offset after shift/fill

         if (ofs >= len) {        // if no more, then we are done

           _Depth--;                // back off recursion depth count

           return;

         }

       }

       int i = ofs;                // look for next "@" symbol

       for (;(i < len) && (shiftBuf[i] != atSymbol); i++);

                                 // if characters prior to "@" symbol,

                                 // write them out

       if (i > ofs) {

         out.write(shiftBuf,ofs,i-ofs);

         ofs = i;

                                 // if no "@" symbol found, then go get

                                 // more data

         if (ofs >= len) continue;

       }

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

       // Found the "@" symbol (start of macro)

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

       ofs++;                        // move past the "@" symbol

       int j = ofs;                // look for character which ends macro

       for (;j < len;j++) { 

         char ch = shiftBuf[j];

         if ((ch < endMacroLen) && endMacro[ch]) break;

       }

                                 // if we found a name of a macro

       if ((j < len) || (i == 0)) {

         String mname = new String(shiftBuf,ofs,j-ofs);

         Object macro = _Macros.get(mname);

         if (macro == null) {        // if macro doesn't exist

           out.write(shiftBuf,i,j-i);

         }

         else {

           Vector params = null;

           if ((j < len) && (shiftBuf[j] == startParamChar)) {

             j++;

             in.setOffset(j);

             params = parseParams(in);

             j = in.getOffset();

             len = in.getLength();

           }

           if (macro instanceof MacroHandler) {

             ((MacroHandler)macro).process(out,params);

           }

           else {

                                 // evaluate defined parameters prior

                                 // to processing simple text subsitutions

             /*

             if (params != null) {

               for (int k = 0; k < params.size(); k++) {

                 StringBuffer pval = (StringBuffer) params.elementAt(k);

                 if ((pval != null) && (pval.length() > 0)) {

                   oparam.clear();

                   interpretCheck(new Input(pval.toString()),oparam);

                   params.setElementAt(oparam.toString(),k);

                 }

               }

             }

             */

             _Params[_ParamIdx++] = params;

             interpretCheck(new Input(macro.toString()),out);

             if (_ParamIdx <= 0) {

               String pmsg = "Internal error - _ParamIdx invalid ("+

                 (_ParamIdx-1)+") after evaluating \""+mname+"\".";

               throw new InterpretException(pmsg);

             }

             _ParamIdx--;

             _Params[_ParamIdx] = null;

           }

         }

         ofs = j;                // advance offset

       }

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

       // if we didn't find end of macro, see if we can shift buffer

       // over (maybe we need to fetch more data)

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

       else {                        // we didn't find end of macro name

         if (i > 0) {                // see if we can shift buffer to left

           len = in.shiftAndFill(i);

           ofs = in.getOffset();

         }

         else {                        // otherwise, simply write out the character

                                 // and process as normal

           out.write(shiftBuf,i,1);

         }

       }

     }

   }

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

   /** Holds the current depth of the recursion as we are processing

    * 

    * @serial        

    * 

    * @since        1.0  */

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

   private int _Depth;

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

   /** Set the current depth of the recursion as we are processing

    * 

    * @param        val

    * 

    *         New int value to assign.

    * 

    * @see #getDepth  */

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

   public void setDepth(int val) {

     _Depth = val;

   }

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

   /** Get the current depth of the recursion as we are processing

    * 

    * @return

    * 

    *         Current int value assigned.

    * 

    * @see #setDepth  */

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

   public int getDepth() {

     return _Depth;

   }

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

   /** Holds the number of recursive calls allowed while evalutating

    * 

    * @serial        

    * 

    * @since        1.0  */

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

   private int _RecursionDepth;

                                 // array of vectors for parameters

   private Vector[] _Params;

   private int _ParamIdx;

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

   /** Set the number of recursive calls allowed while evalutating

    *

    * Typically one doesn't need to worry about setting a recursion

    * depth limit (the default value should be sufficient in most

    * cases). However, if one anticipates that they will need to

    * evalute heavily recursive definitions, you can call this method

    * to increase how deep we allow the evaluations to proceed before

    * giving up.

    *

    * <p>This value sets the maximum recursive call limit. If the

    * interpretation of the source input requires a recursion level

    * greater than this value, the interpreter will give up and throw

    * an exception. This provides a "safety" from entering a infinite

    * recursion loop that doesn't terminate until memory is exhausted.

    * 

    * @param        val

    * 

    *         New int value to assign.

    * 

    * @see #getRecursionDepth  */

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

   public void setRecursionDepth(int val) {

     if (val != _RecursionDepth) {

                                 // make copy of parameter stack - but

                                 // with new size limit

       Vector[] nparams = new Vector[val];

       int n = (val > _RecursionDepth) ? _RecursionDepth : val;

       for (int i = 0; i < n; i++) nparams[i] = _Params[i];

       _RecursionDepth = val;

       _Params = nparams;

     }

   }

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

   /** Get the number of recursive calls allowed while evalutating

    * 

    * @return

    * 

    *         Current int value assigned.

    * 

    * @see #setRecursionDepth  */

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

   public int getRecursionDepth() {

     return _RecursionDepth;

   }

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

   /** Holds the symbol which indicates the start of a macro

    * 

    * @serial        

    * 

    * @since        1.0  */

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

   private char _StartMacroChar;

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

   /** Set the symbol which indicates the start of a macro

    * 

    * @param        val

    * 

    *         New char value to assign.

    * 

    * @see #getStartMacroChar  */

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

   public void setStartMacroChar(char val) {

     _StartMacroChar = val;

   }

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

   /** Get the symbol which indicates the start of a macro

    * 

    * @return

    * 

    *         Current char value assigned.

    * 

    * @see #setStartMacroChar  */

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

   public char getStartMacroChar() {

     return _StartMacroChar;

   }

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

   /** Set the symbol(s) which indicate the end of a macro name

    * 

    * @param        val

    * 

    *         String containing characters which mark the end of a token. */

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

   public boolean setEndMacroChars(String val) {

     boolean rc = (val != null) && (val.length() > 0);

     if (rc) {

       if (_EndMacroChars == null) _EndMacroChars = new boolean[128];

       for (int i = 0; i < _EndMacroChars.length; i++ ) {

         _EndMacroChars[i] = false;

       }

       int vlen = val.length();

       for (int i = 0; i < vlen; i++) {

         int pos = val.charAt(i);

         if ((pos >= 0) && (pos < _EndMacroChars.length)) {

           _EndMacroChars[pos] = true;

         }

         else rc = false;

       }

     }

     return rc;                        // true if ALL values specified accepted

   }

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

   /** Set/clear individual character which indicates end of macro name.

    * 

    * <p>This method can be used to individually add/remove characters

    * which indicate the end of a macro name.

    * 

    * @param        c

    * 

    *         The character which we are trying to match against

    * 

    * @param        indicates_end

    * 

    *         Set to true if you want the character to indicate the end of a

    *         macro, or false if you don't want it to indicate the end.

    * 

    * @return

    * 

    *         true if we allowed the addition, false if not

    * 

    * @since        1.0

    * 

    * @see #setEndMacroChars */

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

   public boolean setEndMacroChar(char match, boolean indicates_end) {

     if ((match >= 0) && (match < _EndMacroChars.length)) {

       _EndMacroChars[match] = indicates_end;

       return true;

     }

     return false;

   }

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

   /** Holds the symbol which starts a "quoted" string

    * 

    * @serial        

    * 

    * @since        1.0  */

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

   private char _StartQuoteChar;

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

   /** Set the symbol which starts a "quoted" string

    * 

    * @param        val

    * 

    *         New char value to assign.

    * 

    * @see #getStartQuoteChar  */

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

   public void setStartQuoteChar(char val) {

     _StartQuoteChar = val;

   }

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

   /** Get the symbol which starts a "quoted" string

    * 

    * @return

    * 

    *         Current char value assigned.

    * 

    * @see #setStartQuoteChar  */

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

   public char getStartQuoteChar() {

     return _StartQuoteChar;

   }

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

   /** Holds the symbol which ends a "quoted" string

    * 

    * @serial        

    * 

    * @since        1.0  */

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

   private char _EndQuoteChar;

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

   /** Set the symbol which ends a "quoted" string

    * 

    * @param        val

    * 

    *         New char value to assign.

    * 

    * @see #getEndQuoteChar  */

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

   public void setEndQuoteChar(char val) {

     _EndQuoteChar = val;

   }

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

   /** Get the symbol which ends a "quoted" string

    * 

    * @return

    * 

    *         Current char value assigned.

    * 

    * @see #setEndQuoteChar  */

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

   public char getEndQuoteChar() {

     return _EndQuoteChar;

   }

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

   /** Holds the "escape" character which can appear in quoted strings

    * 

    * @serial        

    * 

    * @since        1.0  */

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

   private char _EscapeChar;

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

   /** Set the "escape" character which can appear in quoted strings

    * 

    * @param        val

    * 

    *         New char value to assign.

    * 

    * @see #getEscapeChar  */

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

   public void setEscapeChar(char val) {

     _EscapeChar = val;

   }

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

   /** Get the "escape" character which can appear in quoted strings

    * 

    * @return

    * 

    *         Current char value assigned.

    * 

    * @see #setEscapeChar  */

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

   public char getEscapeChar() {

     return _EscapeChar;

   }

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

   /** Holds the symbol which indicates the start of the parameter list

    * 

    * @serial        

    * 

    * @since        1.0  */

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

   private char _StartParamChar;

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

   /** Set the symbol which indicates the start of the parameter list

    * 

    * @param        val

    * 

    *         New char value to assign.

    * 

    * @see #getStartParamChar  */

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

   public void setStartParamChar(char val) {

     if (val != _StartParamChar) {

       setEndMacroChar(_StartParamChar,false);

       setEndMacroChar(val,true);

       _StartParamChar = val;

     }

   }

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

   /** Get the symbol which indicates the start of the parameter list

    * 

    * @return

    * 

    *         Current char value assigned.

    * 

    * @see #setStartParamChar  */

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

   public char getStartParamChar() {

     return _StartParamChar;

   }

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

   /** Holds the symbol which indicates the end of the parameter list

    * 

    * @serial        

    * 

    * @since        1.0  */

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

   private char _EndParamChar;

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

   /** Set the symbol which indicates the end of the parameter list

    * 

    * @param        val

    * 

    *         New char value to assign.

    * 

    * @see #getEndParamChar  */

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

   public void setEndParamChar(char val) {

     _EndParamChar = val;

   }

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

   /** Get the symbol which indicates the end of the parameter list

    * 

    * @return

    * 

    *         Current char value assigned.

    * 

    * @see #setEndParamChar  */

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

   public char getEndParamChar() {

     return _EndParamChar;

   }

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

   /** Holds the character used to separate parameters in a parameter list

    * 

    * @serial        

    * 

    * @since        1.0  */

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

   private char _SepParamChar;