Coverage Report

Coverage Report - com.ccg.macros.At

Classes in this File
5.053
 /*----------------------------------------------------------------
  * $Id: At.java,v 1.1.1.1 2005/06/08 00:33:07 pkb Exp $
  * 
  * (c)2000 - Paul Blankenbaker
  *
  * Revision Log
  * 
  *  2000-11-16 13:10:56        Paul Blankenbaker 
  * 
  *         Created initial version
  */
 //----------------------------------------------------------------
 
 package com.ccg.macros;
 
 import com.ccg.util.*;
 import com.ccg.io.*;
 
 import java.io.*;                // needed for I/O operations
 import java.util.*;                // handy utility classes
 
 
 //----------------------------------------------------------------
 /** A command line implementation of "&#064;macros".
  * 
  * <p>This is a full working "filter" type of program which is capable
  * of processing macros. It comes with a built in set of macros (see
  * the method defintions for the built in macros.
  *
  * <p>This program works as a standard Unix filter. It reads in a
  * ASCII text file, interprets (processes) any contained macros and
  * outputs the resulting text file. As an example, try feeding in the
  * following contents to a invocation of "java com.ccg.macros.At":
  *
  * <pre>
 &#064;define(pkb_email,"&#064;quote(paul&#064;mekwin.com)")
 &#064;define(pkb,"Paul Blankenbaker (&#064;pkb_email)")
 
 Hello &#064;pkb, looks like your
 email is "&#064;pkb_email". Today is &#064;now.
 
 &#064;define(pkb_email,"&#064;quote(paul_blankenbaker&#064;yahoo.com)")
 Did the email address in the &#064;quote(&#064;pkb) macro change?
 &#064;quote(&#064;pkb)=&#064;pkb
 
 Currently, the &#064;quote(&#064;pkb) macro is defined as
 "&#064;definition(pkb)". The built-in &#064;quote(&#064;now) macro
 is defined as a Java method invocation which looks like:
 "&#064;definition(now)".
 
 Here is a list of ALL available definitions.
 
 &#064;dumpDefinitions
  * </pre>
  *
  * <p>You can use many of the standard command line options which the
  * {@link CommandLineUtility CommandLineUtility} class recognizes. In
  * addtion, the following command line options are recognized:
  *
  * <dl>
  *
  * <dt><b>-Dname=val</b></dt><dd>This allows one to define macros on
  * the command line. You may include zero or more definitions. For
  * example "-Dfirst=Paul -Dlast=Blankenbaker" on the command line is
  * equivalent to
  * '@define("first","Paul")@define("last","Blankenbaker")' in a source
  * file. This allows one to pass/define values outside of the source
  * files.</dd>
  *
  * <dt><b>-nodefaults [true|false]</b></dt><dd>Specify this option to
  * turn off the loading of the user's default macro definitions. By
  * default, this application first tries to load the file
  * "$HOME/.etc/atmacros/default.atmacros" (discarding all output) to
  * allow one to load a set of custom definitions (if this file isn't
  * found, it isn't loaded). Use the "-nodefaults" option to disable
  * this feature.</dd>
  *
  * </dl>
  * 
  * @version $Revision: 1.1.1.1 $
  * 
  * @since 1.0
  * 
  * @author $Author: pkb $
  * 
  * @see #run */
 //----------------------------------------------------------------
 
 public class At extends CommandLineUtility {
 
   //----------------------------------------------------------------
   /** Initializes object with an array of command line arguments.
    * 
    * <p>This constructor initializes the object with an array of
    * command line arguments. Once constructed one, can use the {@link
    * #run} method to cause the interpreter to run.
    *
    * @param        args
    *
    *        Array of command line arguments (typically the what the {@link
    *        #main} method would be passed at startup).
    * 
    * @since        1.0
    * 
    * @see #run */
   //----------------------------------------------------------------
 
   public At(String[] args) {
     super(args);
 
     setLineSeparator(null);
 
     AtMacros am = new AtMacros();
 
     //----------------------------------------------------------------  
     // See if any -Dmacro=val values on command line
     //----------------------------------------------------------------
 
     for (int i = 0; i < args.length; i++) {
       String a = args[i];
       if ((a.length() > 2) && a.startsWith("-D")) {
         int epos = a.indexOf('=');
         if (epos < 0) {
           am.addMacro(a.substring(2),"");
         }
         else {
           String mname = a.substring(2,epos);
           String mval = a.substring(epos+1);
           am.addMacro(mname,mval);
         }
       }
     }
 
     setAtMacros(am);
   }
 
 
   //----------------------------------------------------------------
   /** Holds the string used to separate lines on the current platform.
    * 
    * @serial        
    * 
    * @since        1.0  */
   //----------------------------------------------------------------
 
   private String _LineSeparator;
 
 
   //----------------------------------------------------------------
   /** Set the string used to separate lines on the current platform.
    * 
    * @param        val
    * 
    *         New String value to assign - note, if you pass null, we will
    *         attempt to reset it based on the "line.separator" system
    *         property.
    * 
    * @see #getLineSeparator  */
   //----------------------------------------------------------------
 
   public void setLineSeparator(String val) {
     if (val == null) {
       val = System.getProperty("line.separator");
       if (val == null) val = "\n";
     }
     _LineSeparator = val;
   }
 
 
   //----------------------------------------------------------------
   /** Get the string used to separate lines on the current platform.
    * 
    * @return
    * 
    *         Current String value assigned.
    * 
    * @see #setLineSeparator  */
   //----------------------------------------------------------------
 
   public String getLineSeparator() {
     return _LineSeparator;
   }
 
 
   //----------------------------------------------------------------
   /** Holds the "&#064;macro" interpreter to use.
    * 
    * @serial        
    * 
    * @since        1.0  */
   //----------------------------------------------------------------
 
   private AtMacros _AtMacros;
 
 
   //----------------------------------------------------------------
   /** Process a set of well known user files.
    * 
    * <p>This method will attempt to load definitions from file(s) in
    * some well known (or expected locations). All files are optional
    * (if not found nothing is done). Also, no output is produced while
    * interpretting these files (they are purely for the purpose of
    * adding standard definitions).
    *
    * <p>Refer to the {@link ConfigSource} class and in particular the
    * {@link ConfigSource#getFile} method to see how the path to the
    * default file is determined.
    * 
    * @since        1.0 */
   //----------------------------------------------------------------
 
   public void loadDefaultDefinitions() {
     File ifile = null;
     InputReader in = null;
 
     try {
       ConfigSource cs = new ConfigSource(At.class);
       ifile = cs.getFile();
 
       Interpreter amacs = getAtMacros();
 
       if (ifile.exists() && (amacs != null)) {
         in = new InputReader(ifile);
         amacs.interpret(new InputReader(ifile),new OutputNull());
         System.err.println("loaded file:"+ifile);
       }
       else System.err.println("didn't find file:"+ifile);
     } catch (Exception e) {
       Log.error("problem processing \""+in+"\"",e);
     }
 
     if (in != null) try { in.close(); } catch (IOException ioe) { }
 
   }
 
 
   //----------------------------------------------------------------
   /** Set the "&#064;macro" interpreter to use.
    * 
    * @param        val
    * 
    *         New AtMacros value to assign.
    * 
    * @see #getAtMacros  */
   //----------------------------------------------------------------
 
   public void setAtMacros(AtMacros val) {
     if (val != null) {
       _AtMacros = val;
       _AtMacros.addMacros(this);
     }
   }
 
 
   //----------------------------------------------------------------
   /** Get the "&#064;macro" interpreter to use.
    * 
    * @return
    * 
    *         Current AtMacros value assigned.
    * 
    * @see #setAtMacros  */
   //----------------------------------------------------------------
 
   public AtMacros getAtMacros() {
     return _AtMacros;
   }
 
 
   //----------------------------------------------------------------
   /** Runs the interpreter reading from the input source and writing
    * the output.
    * 
    * This method interprets the contents of the input file and
    * produces the resulting ASCII output file. By default, the
    * standard input will be used for input, and the standard output
    * will be used for output. However, one can adjust these via
    * command line arguments or the methods of the {@link
    * CommandLineUtility parent} class.
    * 
    * @since        1.0 */
   //----------------------------------------------------------------
 
   public void run() {
 
     OutputWriter o = null;
 
     try {
       AtMacros interpreter = getAtMacros();
       //      interpreter.addMacro("pkb_email","paul@mekwin.com");
       //      interpreter.addMacro("pkb","Paul Blankenbaker "+
       //                           "(@email(@pkb_email))");
 
       o = new OutputWriter(getOutputStream());
       //      Input isb = new Input("@define(paul,@pkb)Hello \"@paul\"!\n\n");
       //      interpreter.interpret(isb,o);
 
       if (!getBoolean("nodefaults",Boolean.FALSE).booleanValue()) {
         loadDefaultDefinitions();
       }
 
       interpreter.interpret(new InputReader(getInputStream()),o);
 
     } catch (Exception e) {
       e.printStackTrace();
     } finally {
       if (o != null) try { o.close(); } catch (Throwable t) { }
     }
   }
 
 
   //----------------------------------------------------------------
   /** &#064;param(N) macro - get parameter value.
    * 
    * This macro is typically used in the definition of run time macros
    * (in the VAL parameter of "&#064;define(NAME,VAL)". It allows a user
    * defined macro (run time defined) to reference the parameter
    * passed to its invocation. Take a look at the following:
    *
    * <pre>
    * &#064;define(email,"&lt;a href=\"mailto:&#064;param(0)\"&gt;&#064;param(0)&lt;/a&gt;")
    * &#064;email("&#064;("paul&#064;mekwin.com")")
    * </pre>
    *
    * <p>The above defines a new run time macro "&#064;email", the new
    * "&#064;email" macro allows the user to pass an argument which is
    * subsitutes in two places. This provides a means to make some
    * pretty powerful run time macros.
    * 
    * @param        out
    * 
    *         The {@link Output output device} to write the results of
    *         processing the argument to.
    * 
    * @param        args
    * 
    *         A {@link Vector vector} of arguments which were passed to the macro.
    * 
    * @throws        IOException
    * 
    *         If there is a problem writing to the {@link Output output device}
    * 
    * @throws        InterpretException
    * 
    *         If a problem is encountered interpretting the arguments passed.
    * 
    * @since        1.0 */
   //----------------------------------------------------------------
 
   public void param(Output out, Vector args)
     throws IOException, InterpretException {
 
     if ((args != null) && (args.size() >= 1)) {
       Object o = args.elementAt(0);
       int idx = -1;
       try {
         idx = Integer.parseInt(_AtMacros.interpretCheck(o.toString()));
       } catch (Throwable t) {
         throw new InterpretException("@param("+o+") - "+t.getMessage());
       }
       
       out.write(_AtMacros.getParameter(idx));
     }
   }
 
 
   //----------------------------------------------------------------
   /** &#064;quote(TEXT) macro - output text verbatim.
    * 
    * This macro is invoked in the form "&#064;quote(TEXT)". This macro only
    * looks at the first argument (additional arguments are
    * ignored). The text of the first argument is written verbatim to
    * the output device. This allows one to output macro names. For
    * example: <b>&#064;quote("&#064;quote(TEXT)")</b> would result in
    * <b>&#064;quote(TEXT)</b> in the output stream.
    * 
    * @param        out
    * 
    *         The {@link Output output device} to write the results of
    *         processing the argument to.
    * 
    * @param        args
    * 
    *         A {@link Vector vector} of arguments which were passed to the macro.
    * 
    * @throws        IOException
    * 
    *         If there is a problem writing to the {@link Output output device}
    * 
    * @throws        InterpretException
    * 
    *         If a problem is encountered interpretting the arguments passed.
    * 
    * @since        1.0 */
   //----------------------------------------------------------------
 
   public void quote(Output out, Vector args)
     throws IOException, InterpretException {
 
     if ((args != null) && (args.size() >= 1)) {
       Object o = args.elementAt(0);
       if (o != null) out.write(o.toString());
     }
   }
 
 
   //----------------------------------------------------------------
   /** &#064;now() macro - dumps current time.
    * 
    * This macro is invoked in the form "&#064;now()". This macro has no
    * arguments (currently) and simply dumps the current time in the
    * default date format of the JVM.
    * 
    * @param        out
    * 
    *         The {@link Output output device} to write the results of
    *         processing the argument to.
    * 
    * @param        args
    * 
    *         A {@link Vector vector} of arguments which were passed to the macro.
    * 
    * @throws        IOException
    * 
    *         If there is a problem writing to the {@link Output output device}
    * 
    * @throws        InterpretException
    * 
    *         If a problem is encountered interpretting the arguments passed.
    * 
    * @since        1.0 */
   //----------------------------------------------------------------
 
   public void now(Output out, Vector args) 
     throws IOException, InterpretException {
 
     out.write(getDateFormat().format(new Date()));
   }
 
 
   //----------------------------------------------------------------
   /** &#064;define(NAME,VAL[,OPT]) macro - define a new macro.
    * 
    * This macro is invoked in the form
    * "&#064;define(NAME,VAL[,OPT])". This macro is used to define new
    * text replacement macros. The first argument NAME is the name of
    * the new macro to define (do not include the leading "&#064;"
    * sign). The second argument VAL is the text which is to be
    * subsituted. The third arguments allows for some specialized
    * options during the definition. For example:
    *
    * <pre>
    * &#064;define(pkb_email,"&#064;quote("paul&#064;mekwin.com")")
    * </pre>
    *
    * <p>After interpretting the above, one could then use
    * "&#064;pkb_email()" in the document and have "paul&#064;mekwin.com"
    * appear. It should be noted, that the "VAL" area can contain
    * references to other macros. For example:
    *
    * <pre>
    * &#064;define(pkb,"Paul Blankenbaker (&#064;pkb_email)")
    * </pre>
    *
    * <p>There are two important concepts to understand with the
    * above. One is that the &#064;pkb macro just defined contains a
    * reference to another macro. This is handled properly and the
    * contained &#064;pkb_email reference will be expanded each time the
    * &#064;pkb macro is used. The second concept is that the expansion
    * occurs at the time the &#064;pkb macro is used, not at the time it is
    * defined. In other words, if someone changed the definition of the
    * &#064;pkb_email macro, then it would affect subsequent invocations of
    * the &#064;pkb macro.
    *
    * <p>The third parameter to this macro is optional, and can be
    * extremely useful in some circumstances. The third parameter can
    * be one of the following:
    *
    * <dl>
    *
    * <dt><b>ifnew</b></dt><dd>The "ifnew" option means that the
    * definition should only be accepted if a definition does not
    * already exist. This can be a very handy way to provide default
    * values.</dd>
    *
    * <dt><b>now</b></dt><dd>The "now" option means that the value
    * should be interpretted immediately (right now). This can be more
    * efficient and prevents future changes from having affects.</dd>
    *
    * </dl>
    *
    * <p>To get an idea of how these behave, try running the the
    * following through to see what comes out:
    *
    * <pre>
    * &#064;define("name","Joe Schmoe")
    * &#064;define("phone","333-333-3333")
    * &#064;define("pname","&#064;name &#064;phone")
    * &#064;define("nname","&#064;name &#064;phone","now")
    * &#064;define("phone","444-444-4444")
    * &#064;define("phone","555-555-5555","ifnew")
    * &#064;quote("&#064;pname=")&#064;pname
    * &#064;quote("&#064;nname=")&#064;nname
    * </pre>
    * 
    * @param        out
    * 
    *         The {@link Output output device} to write the results of
    *         processing the argument to.
    * 
    * @param        args
    * 
    *         A {@link Vector vector} of arguments which were passed to the macro.
    * 
    * @throws        IOException
    * 
    *         If there is a problem writing to the {@link Output output device}
    * 
    * @throws        InterpretException
    * 
    *         If a problem is encountered interpretting the arguments passed.
    * 
    * @since        1.0 */
   //----------------------------------------------------------------
 
   public void define(Output out, Vector args) 
     throws IOException, InterpretException {
 
     if ((args != null) && (args.size() >= 2)) {
       Object n = args.elementAt(0);
       Object v = args.elementAt(1);
       if ((n != null) && (v != null)) {
         String name = n.toString();
         String val = v.toString();
 
                                 // see if any special options specified
         if (args.size() > 2) {
           Object op = args.elementAt(2);
           String opStr = null;
           if (op != null) opStr = op.toString();
 
           if (opStr != null) {
                                 // "now" option requires us to evaluate now
             if (opStr.equals("now")) { val = _AtMacros.interpret(val); }
                                 // "ifnew" option means to skip
                                 // definition if already defined
             else if (opStr.equals("ifnew")) {
               if (_AtMacros.getMacro(name) != null) return;
             }
           }
         }
         _AtMacros.addMacro(name,val);
       }
     }
   }
 
 
   //----------------------------------------------------------------
   /** &#064;definition(NAME) macro - fetch definition of a macro.
    * 
    * This macro is mainly used for debugging purposes, it returns the
    * current definition of a macro. You pass the NAME of the macro
    * (without the leading "&#064;" symbol) which you want to retrieve the
    * definition for. The current definition of the macro is returned
    * as a text string. If the macro was created with the
    * "&#064;define(NAME,VAL)" macro, then the returned text will be
    * "VAL". If the macro is a built-in macro (such as
    * "&#064;definition(NAME)", then the returned value will be the name of
    * the Java class/method used to handle the macro.
    * 
    * @param        out
    * 
    *         The {@link Output output device} to write the results of
    *         processing the argument to.
    * 
    * @param        args
    * 
    *         A {@link Vector vector} of arguments which were passed to the macro.
    * 
    * @throws        IOException
    * 
    *         If there is a problem writing to the {@link Output output device}
    * 
    * @throws        InterpretException
    * 
    *         If a problem is encountered interpretting the arguments passed.
    * 
    * @since        1.0 */
   //----------------------------------------------------------------
 
   public void definition(Output out, Vector args) 
     throws IOException, InterpretException {
 
     if ((args != null) && (args.size() >= 1)) {
       Object n = args.elementAt(0);
       if (n != null) {
         Object o = _AtMacros.getMacro(n.toString());
         out.write(o);
       }
     }
   }
 
 
   //----------------------------------------------------------------
   /** &#064;htmlEscape(TEXT) - escape special HTML characters '<', '>' and '&'.
    * 
    * <p>This should probably be relocated to a special HTML version of
    * the {@link At At} class. However, I needed something that would
    * translate '<' into "&lt;", '>' into "&gt;" and '&' into "&amp;"
    * so that HTML examples would appear as the expected when viewed by
    * a browser.
    *
    * <p>This macro simply replaces HTML special characters, with the
    * HTML escape codes.
    * 
    * @param        out
    * 
    *         The {@link Output output device} to write the results of
    *         processing the argument to.
    * 
    * @param        args
    * 
    *         A {@link Vector vector} of arguments which were passed to the macro.
    * 
    * @throws        IOException
    * 
    *         If there is a problem writing to the {@link Output output device}
    * 
    * @throws        InterpretException
    * 
    *         If a problem is encountered interpretting the arguments passed.
    * 
    * @since        1.0 */
   //----------------------------------------------------------------
 
   public void htmlEscape(Output out, Vector args)
     throws IOException, InterpretException {
 
                                 // exit if nothing to do
     if ((args == null) || (args.size() != 1)) return;
 
                                 // see if there is anything to do
     Object f = args.elementAt(0);
     if (f == null) return;
 
     String text = _AtMacros.interpretCheck(f.toString());
 
     if ((text == null) || (text.length() == 0)) return;
 
     int tlen = text.length();
 
                                 // now, replace special HTML
                                 // characters with their escape codes
     StringBuffer sb = new StringBuffer(tlen*2);
 
     for (int i = 0; i < tlen; i++) {
       char c = text.charAt(i);
       if (c == '<') sb.append("&lt;");
       else if (c == '&') sb.append("&amp;");
       else sb.append(c);
     }
 
     out.write(sb);
 
   }
 
 
   //----------------------------------------------------------------
   /** &#064;dumpDefinitions() macro - dump definition of all macros.
    * 
    * <p>This macro is mainly used for debugging purposes. It dumps the
    * definition of ALL defined macros.
    *
    * <p>NOTE: You may optionally pass a single argument to this
    * method. If passed, the argument will be expanded for each
    * definition in our macro dictionary. The following macros will be
    * available:
    *
    * <dl> 
    *
    * <dt>&#064;dumpDefName()</dt><dd>The name of the macro the
    * definition refers to.
    *
    * <dt>&#064;dumpDefValue()</dt><dd>The string value of the macro
    * (this may be the name of the Java method used to evaluate
    * it.</dd>
    *
    * </dl>
    *
    * <p>Here is an example which produces the same results as the
    * default output:
    *
    * <pre>
    * &#064;dumpDefinitions("&#064;dumpDefName()=&#064;dumpDefValue()
    * ")
    * </pre>
    *
    * <p>Here's an example which provides a little fancier output in
    * HTML:
    *
    * <pre>
    * &#064;dumpDefinitions("&lt;h2&gt;&#064;quote(&#064;)&#064;dumpDefName()&lt;/h2&gt;
    * &lt;pre&gt;
    * &#064;htmlEscape("&#064;dumpDefValue()")
    * &lt;/pre&gt;
    * ")
    * </pre>
    * 
    * @param        out
    * 
    *         The {@link Output output device} to write the results of
    *         processing the argument to.
    * 
    * @param        args
    * 
    *         A {@link Vector vector} of arguments which were passed to the macro.
    * 
    * @throws        IOException
    * 
    *         If there is a problem writing to the {@link Output output device}
    * 
    * @throws        InterpretException
    * 
    *         If a problem is encountered interpretting the arguments passed.
    * 
    * @since        1.0 */
   //----------------------------------------------------------------
 
   public void dumpDefinitions(Output out, Vector args) 
     throws IOException, InterpretException {
 
                                 // default dump ouput
     String format = "@dumpDefName()=@dumpDefValue()"+_LineSeparator;
                                 // see if user overrode format
     if ((args != null) && (args.size() > 0)) {
       Object o = args.elementAt(0);
       if (o != null) format = o.toString();
     }
                                 // get and sort macro names that are defined
     Vector allNames = new Vector(500);
     Enumeration keys = _AtMacros.getMacroNames();
     while (keys.hasMoreElements()) {
       String name = keys.nextElement().toString();
       allNames.addElement(name);
     }
 
     String[] mnames = new String[allNames.size()];
     for (int i = 0; i < mnames.length; i++) {
       mnames[i] = (String) allNames.elementAt(i);
     }
     Arrays.sort(mnames,new com.ccg.util.CompareStrings());
 
     class Verbatim implements MacroHandler {
       String _Text;
       public void process(Output ov, Vector av)
         throws IOException, InterpretException {
         ov.write(_Text);
       }
     }
 
     Verbatim v = new Verbatim();
     _AtMacros.addMacro("dumpDefValue",v);
 
                                 // now, go process each macro definition
     for (int i = 0; i < mnames.length; i++) {
       _AtMacros.addMacro("dumpDefName",mnames[i]);
       v._Text = _AtMacros.getMacro(mnames[i]).toString();
       out.write(_AtMacros.interpretCheck(format));
     }
 
                                 // reset to blank definitions - not
                                 // sure if we need to do this
     //    _AtMacros.addMacro("dumpDefName",null);
     //    _AtMacros.addMacro("dumpDefValue",null);
     /*
     String beforeAll = null;
     //    String beforeEach = ""+_AtMacros.getStartMacroChar()+"define(\"";
     //    String betweenEach = "\",\"";
     //    String afterEach = "\")\n";
     String beforeEach = null;
     String betweenEach = "=";
     String afterEach = "\n";
     String afterAll = null;
 
     Enumeration keys = _AtMacros.getMacroNames();
     while (keys.hasMoreElements()) {
       String name = keys.nextElement().toString();
       Object o = _AtMacros.getMacro(name);
 
       if (beforeEach != null) out.write(beforeEach);
       out.write(name);
       out.write(betweenEach);
       out.write(o);
       out.write(afterEach);
     }
     */
   }
 
 
   //----------------------------------------------------------------
   /** &#064;loadTSV(NAME,SOURCE) load a tab separated table.
    * 
    * <p>This macro is used to load the definition of a tab separated
    * table. It doesn't actually read the contents of the database
    * immediately, instead it defines a new macro named "NAME" and
    * associates a SOURCE (typically a file or URL) where we should
    * fetch the data from.
    *
    * <p>When you want to insert the data of the table into your
    * output, you then use the "@NAME(FORMAT)" macro to read each line
    * from the table and FORMAT the output of the table.
    *
    * <p>For example, if one created a table named {@link
    * <a href=doc-files/phone.tsv>phone.tsv</a>} like the following:
    *
 <pre>
 Last        First        Phone
 Blankenbaker        Paul        555-555-5555
 Brown        Megan        555-555-5555
 </pre>
    *
    * <p>And you used the following macros:
    *
 <pre>
 &#064;loadTSV("phoneTable","{@link <a href=doc-files/phone.tsv>phone.tsv</a>}")
 &#064;phoneTable("@param(1),@param(0),@param(2)\n")
 </pre>
    *
    * <p>This will result in the output of one blank line followed by a
    * comma seaparated list of just the data fields. This is shown below:
    *
 <pre>
 
 Paul,Blankenbaker,555-555-5555
 Megan,Brown,555-555-5555
 </pre>
    *
    * <p>If you are producing HTML, you can use the table formatting
    * tags to nicely format your table data.
    * 
    * @param        out
    * 
    *         The {@link Output output device} to write the results of
    *         processing the argument to.
    * 
    * @param        args
    * 
    *         A {@link Vector vector} of arguments which were passed to the macro.
    * 
    * @throws        IOException
    * 
    *         If there is a problem writing to the {@link Output output device}
    * 
    * @throws        InterpretException
    * 
    *         If a problem is encountered interpretting the arguments passed.
    * 
    * @since        1.0 */
   //----------------------------------------------------------------
 
   public void loadTSV(Output out, Vector args) 
     throws IOException, InterpretException {
 
     if (args.size() < 2) {
       throw new InterpretException("@loadTSV(NAME,SOURCE) requires "+
                                    "two arguments.");
     }
 
     String name = args.elementAt(0).toString();
     String source = args.elementAt(1).toString();
 
     if ((name == null) || (source == null) ||
         (name.length() == 0) || (source.length() == 0)) {
       throw new InterpretException("null argument passed to "+
                                    "@loadTSV(NAME,SOURCE)");
     }
 
     _AtMacros.addMacro(name,new TableInsert(_AtMacros,name,source));
   }
 
 
   //----------------------------------------------------------------
   /** &#064;include(SOURCE,[IGNERR],[NOOUT]) insert and process other file(s).
    * 
    * <p>This macro is used to load and process the contents of another
    * file. Currently the full or relative path to the source must be
    * specified (in the future, path searching may be added).
    *
    * <p>For example, to include the file
    * "/opt/include/atmacros/companies.atmacros", one could use the
    * following command:
    *
 <pre>
 &#064;include("/etc/hosts")
 </pre>
    *
    * <p>The second parameter IGNERR is optional. It may be set to
    * either "true" or "false" (only first letter is checked). If
    * omitted, it defaults to a value of "false". When set to "true",
    * then no error will be thrown if the file is not found. If set to
    * "false" (or omitted), then an error will be thrown if the desired
    * SOURCE could not be found.
    *
    * <p>The third parameter DISOUT is optional. It may be set to
    * either "true" or "false" (only first letter is checked). If
    * omitted, it defaults to a value of "false". When set to "true",
    * then no output will be produced while interpretting the file
    * included (this allows one to load definition files). When set to
    * "false" (or omitted), any output produced as a result of
    * interpretting the file will be written to the current output
    * device.
    *
    * <p>When using this directive to include definition files, it is
    * often handy to set the DISOUT value to "true" to disable any
    * output as a result of interpretting the definition file (this
    * allows one to enter comments in their definition files).
    * 
    * @param        out
    * 
    *         The {@link Output output device} to write the results of
    *         processing the argument to.
    * 
    * @param        args
    * 
    *         A {@link Vector vector} of arguments which were passed to the macro.
    * 
    * @throws        IOException
    * 
    *         If there is a problem writing to the {@link Output output device}
    * 
    * @throws        InterpretException
    * 
    *         If a problem is encountered interpretting the arguments passed.
    * 
    * @since        1.0 */
   //----------------------------------------------------------------
 
   public void include(Output out, Vector args) 
     throws IOException, InterpretException {
 
     int argc = args.size();
     if (argc < 1) return;
 
     String source = _AtMacros.interpretCheck(args.elementAt(0).toString());
 
     try {
                                 // get source file to process
       Reader in = com.ccg.io.Utility.getReader(source);
 
       if (argc > 2) {                // turn off output if necessary
         String disout = _AtMacros.interpretCheck(args.elementAt(2).toString());
         if (disout.length() > 0 &&
             (Character.toLowerCase(disout.charAt(0)) == 't')) {
           out = new OutputNull();
         }
       }
 
                                 // go interpret the contents of the file
       _AtMacros.interpretCheck(new InputReader(in),out);
 
     } catch (IOException ioe) {
       if (argc > 1) {
         String cont = _AtMacros.interpretCheck(args.elementAt(1).toString());
         if (cont.length() > 0 && 
             Character.toLowerCase(cont.charAt(0)) == 't') {
           Log.warning("Warning: source \""+source+
                       "\" skipped:"+ioe.toString());
           ioe = null;                // OK to continue
         }
       }
       if (ioe != null) throw ioe;
     }
 
   }
 
 
   //----------------------------------------------------------------
   /** &#064;copyToDir(MATCH0,MATCH1,&02e;&02e;&02e;,DIR) copy one or
    * more files to directory.
    * 
    * <p>This macro is used to copy 0 or more existing files to a
    * output directory. If the directory doesn't exist, it will be
    * created. You may use the "*" as a wildcard in each of the file
    * name strings to match more than one file.
    *
    * <p>For example, to copy the ".at" and "*.properties" files from
    * the "/etc/macros" directory to the "/home/user/etc/macros"
    * directory, one could use the following:
    *
 <pre>
 &#064;defnow("sdir","/etc/macros")
 &#064;copyToDir("&#064;sdir()/*.at","&#064;sdir()/*.properties","/home/user/etc/macros")
 </pre>
    *
    * @param        out
    * 
    *         The {@link Output output device} to write the results of
    *         processing the argument to.
    * 
    * @param        args
    * 
    *         A {@link Vector vector} of arguments which were passed to the macro.
    * 
    * @throws        IOException
    * 
    *         If there is a problem writing to the {@link Output output device}
    * 
    * @throws        InterpretException
    * 
    *         If a problem is encountered interpretting the arguments passed.
    * 
    * @since        1.0 */
   //----------------------------------------------------------------
 
   public void copyToDir(Output out, Vector args) 
     throws IOException, InterpretException {
 
     int argc = args.size();
     if (argc < 2) return;        // must have at least two arguments
 
     argc--;                        // last argument is the output directory
     
                                 // get output directory
     String dstStr = _AtMacros.interpretCheck(args.elementAt(argc).toString());
 
     File dst = new File(FileName.fixSlashes(dstStr));
                                 // try to create directory - if it
                                 // doesn't exist
     if (!dst.isDirectory()) {
       dst.mkdirs();
       if (!dst.isDirectory()) {
         throw new IOException("unable to create directory \""+dst+"\"");
       }
     }
 
     PrintWriterString pws = PrintWriterString.create();
 
                                 // now, process each of the wild-card
                                 // file name strings
     for (int i = 0; i < argc; i++) {
       String match = _AtMacros.interpretCheck(args.elementAt(i).toString());
       String[] list = FilenameFilterWild.list(FileName.fixSlashes(match));
       if (list != null) for (int j = 0; j < list.length; j++) {
         File src = new File(list[j]);
                                 // only copy existing normal files
         if (src.exists() && src.isFile()) {
           File ofile = new File(dst,src.getName());
 
           pws.print("Copy:");
           pws.print(src);
           pws.print("  to:");
           pws.println(dst);
           Copy.fileToFile(src,ofile);
         }
         else if (Debug.ENABLED && Debug.isEnabledFor(3)) {
           pws.print("Skip:");
           pws.println(src);
         }
       }
     }
 
     out.write(pws);
   }
 
 
   //----------------------------------------------------------------
   /** &#064;atCopyToDir(MATCH0,MATCH1,&02e;&02e;&02e;,DIR) copy AND
    * interpret one or more files to directory.
    * 
    * <p>This macro is used to copy 0 or more existing files to a
    * output directory. If the directory doesn't exist, it will be
    * created. You may use the "*" as a wildcard in each of the file
    * name strings to match more than one file.
    *
    * <p>There is a HUGE difference between this command and the
    * "&#064;copyToDir". This command interprets each file that it
    * copies and evaluates any "&#064macros" which it contains. This
    * can be a VERY useful way to install HTML documents to their final
    * location and do some subsitutions during the installation process.
    *
    * <p>It should be noted that any definitions (or redefinitions)
    * made by the files processed WILL AFFECT all subsequent files
    * processed (I may add a version of this macro which saves/restores
    * the macros for each file processed).
    *
    * <p>To see the power of this function, take a look at the {@link
    * <a href=doc-files/atcopy.atmacros>atcopy.atmacros</a>}
    * "script". It does the following:
    *
    * <ul>
    *
    * <li>Makes some of its own definitions.</li>
    *
    * <li>Loads a set of definitions ({@link
    * <a href=doc-files/htmlmemo.atmacros>htmlmemo.atmacros</a>}).</li>
    *
    * <li>Then copies a set of HTML documents (both {@link
    * <a href=doc-files/memo1.html>memo1.html</a>} and  {@link
    * <a href=doc-files/memo2.html>memo2.html</a>}) using the defined macros.
    *
    * </ul>
    *
    * <p>If you have the source code installed such that the "ccg" top
    * level directory can be found under the "$COMHOME" environment
    * variable, you should be able to try this out via:
    *
    * <pre>
    * java {@link At com.ccg.macros.At} -Dcomhome=$COMHOME -Dhtmlroot=$HOME/public_html \
    *   -in {@link <a href=doc-files/atcopy.atmacros>$COMHOME/ccg/macros/doc-files/atcopy.atmacros</a>}
    * </pre>
    *
    * @param        out
    * 
    *         The {@link Output output device} to write the results of
    *         processing the argument to.
    * 
    * @param        args
    * 
    *         A {@link Vector vector} of arguments which were passed to the macro.
    * 
    * @throws        IOException
    * 
    *         If there is a problem writing to the {@link Output output device}
    * 
    * @throws        InterpretException
    * 
    *         If a problem is encountered interpretting the arguments passed.
    * 
    * @since        1.0 */
   //----------------------------------------------------------------
 
   public void atCopyToDir(Output out, Vector args) 
     throws IOException, InterpretException {
 
     int argc = args.size();
     if (argc < 2) return;        // must have at least two arguments
 
     argc--;                        // last argument is the output directory
     
                                 // get output directory
     String dstStr = _AtMacros.interpretCheck(args.elementAt(argc).toString());
 
     File dst = new File(FileName.fixSlashes(dstStr));
                                 // try to create directory - if it
                                 // doesn't exist
     if (!dst.isDirectory()) {
       dst.mkdirs();
       if (!dst.isDirectory()) {
         throw new IOException("unable to create directory \""+dst+"\"");
       }
     }
 
     PrintWriterString pws = PrintWriterString.create();
 
                                 // now, process each of the wild-card
                                 // file name strings
     for (int i = 0; i < argc; i++) {
       String match = _AtMacros.interpretCheck(args.elementAt(i).toString());
       String[] list = FilenameFilterWild.list(FileName.fixSlashes(match));
       if (list != null) for (int j = 0; j < list.length; j++) {
         File src = new File(list[j]);
                                 // only copy existing normal files
         if (src.exists() && src.isFile()) {
           File ofile = new File(dst,src.getName());
 
           pws.print("Interpret:");
           pws.print(src);
           pws.print("  to:");
           pws.println(dst);
 
           OutputWriter ow = new OutputWriter(ofile);
           InputReader ir = new InputReader(src);
 
                                 // and copy/interpret the files
           getAtMacros().interpret(ir,ow);
           ow.close();                // don't forget to close (to flush out data)
         }
         else if (Debug.ENABLED && Debug.isEnabledFor(3)) {
           pws.print("Skip:");
           pws.println(src);
         }
       }
     }
 
     out.write(pws);
   }
 
 }
 
 