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

  * $Id: Base.java,v 1.1.1.1 2002/08/27 15:48:37 pkb Exp $

  * 

  * (c)2001 - Paul Blankenbaker

  *

  * Revision Log

  *

  * $Log: Base.java,v $

  * Revision 1.1.1.1  2002/08/27 15:48:37  pkb

  * initial import of very old @macro() code

  *

  * Revision 1.4  2002/08/27 15:48:37  pkb

  * javadoc updates: It took about 53 million periods, but I went through

  * the com.ccg packages and got the javadoc (under JVM 1.4) to build

  * without all of the new warning messages.

  *

  * Revision 1.3  2001/11/02 15:58:37  pkb

  *

  * Added macros for formatting times and extracting information from the

  * CVS Id values in source files.

  *

  * Revision 1.2  2001/10/19 19:35:01  pkb

  *

  * Starting playing with the "@macros" again. Cleaned up a few more

  * issues with netsted parameters and added a lot more "supporting

  * macros". If you've been playing with them, you should prefer

  * "com.ccg.macros.at.All" over "com.ccg.macros.At" as your interpretter.

  *

  * Still needs documentation and javadoc (sigh - where does the time go).

  *

  * Revision 1.1  2001/09/10 16:14:03  pkb

  *

  * Added updates to @macro processing (starting the separation of

  * standard at macros into their own sub-package).

  *

  *

  */

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

 package com.ccg.macros.at;

 import com.ccg.macros.*;

 import com.ccg.util.Debug;

 import java.util.Vector;

 import java.io.InputStream;

 import java.io.IOException;

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

 /** Base class for specialized @macro handlers.

  * 

  * <p>This class is used to build specialized macro handlers. It

  * provides common methods which derived classes will find useful

  * (allowing them to concentrate on their specific macro

  * definitions).</p>

  * 

  * @version $Revision: 1.1.1.1 $

  * 

  * @since 1.0

  * 

  * @author $Author: pkb $ */

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

 public class Base {

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

   /** Construct the object and optionally interpret a initialization file.

    * 

    * @param        hasFile

    * 

    *         Set to true if there is a associated initialization file. The

    *         initialization file must be found in the same manner as the

    *         class file - except that it will end with ".At" instead of

    *         ".class". For example, the "/com/ccg/macros/at/Html" class has

    *         a "/com/ccg/macros/at/Html.At" file associated with it.

    * 

    * @since        1.0 */

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

   protected Base(boolean hasFile) {

     _NeedPFile = hasFile;

   }

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

   /** Register's all of the method macros AND loads the predefined

    * property macros for the class.

    * 

    * <p>First, this method installs all of the "macro handler" methods

    * (see {@link AtMacros#addMacros AtMacros.addMacros(Object)} for

    * information on macro handler methods) of the class.

    *

    * <p>If the class also has a associated macro resource file, the

    * resource file will then be interpretted by the macro processor

    * (to load simple text style macros). During this "loading" phase,

    * no output will be generated (unless the associated property file

    * tries really hard to generate some).

    *

    * @param        am

    * 

    *         The {@link AtMacros AtMacros} object to register all of the

    *         macros with. Must not be null.

    * 

    * @since        1.0 */

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

   public void install(AtMacros at) {

     _AtMacros = at;                // save reference to associated processor

                                 // first register any macro handler's

                                 // which the class handles directly

     at.addMacros(this);

     String fname = null;

     InputStream is = null;

     if (_NeedPFile) try {

                                 // get full name of class, like:

                                 // "com.ccg.macros.at.File.At"

       Class cl = getClass();

       String clname = cl.getName();

       if (clname.indexOf('.') > 0) {

         java.util.StringTokenizer tokens = 

           new java.util.StringTokenizer(clname,".");

         StringBuffer buf = new StringBuffer(clname.length()+6);

         while (tokens.hasMoreTokens()) {

           buf.append('/');

           buf.append(tokens.nextToken());

         }

         buf.append(".At");

         fname = buf.toString();

       }

       else fname = clname+".At";

       if (at.getMacro("include") == null) {

                                 // open up the resource file

         is = cl.getResourceAsStream(fname);

                                 // and then interpret

         at.interpret(new InputReader(is), OutputNull.getInstance());

         is.close();

       }

       else {                        // use include method

         at.interpret(new Input("@include(\""+fname+"\",f,d)"),

                      OutputNull.getInstance());

       }

     } catch (Exception e) {

       if (Debug.ENABLED && Debug.isEnabledFor(1)) {

         Debug.out("problem loading file:"+fname,e);

       }

     } finally {

       if (is != null) try { is.close(); } catch (Throwable t) { }

     }

   }

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

   /** Safely retrieve and interpret a parameter.

    * 

    * <p>Many times a macro isn't picky about the string value of a

    * parameter passed to the macro - it just wants to make sure it

    * isn't passed a null. This method will fetch the desired parameter

    * which was passed to your macro, interpret it and return the

    * string representation.

    *

    * <p>It never returns null, but it may return a zero length string.

    *

    * <p>It will throw an exception if interpretation of the parameter

    * was required but failed.

    * 

    * @param        args

    * 

    *         A {@link Vector vector} of arguments which were passed to the macro.

    * 

    * @param        i

    * 

    *         Index of the argument you want (0 corresponds to first entry).

    * 

    * @throws        InterpretException

    * 

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

    * 

    * @throws        IOException

    * 

    *         If interpretation of parameter involved output that triggered

    *         a I/O error.

    * 

    * @return

    * 

    *         String representation of the parameter to the macro (after

    *         interpretation). Returns "" if parameter omitted or index out

    *         of range (never returns null).

    * 

    * @since        1.0 */

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

   public final String getStringParameter(Vector args, int i) 

     throws IOException, InterpretException {

     if (i >= args.size()) return "";

     Object o = args.elementAt(i);

     if (o == null) return "";

                                 // need to interpret

     String text = getAtMacros().interpretCheck(o.toString());

     if (text == null) text = "";

     return text;

   }

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

   /** Safely retrieve and interpret a parameter and get the integer value. 

    * 

    * <p>Many times a macro isn't picky about the string value of a

    * parameter passed to the macro - it just wants to make sure it

    * isn't passed a null. This method will fetch the desired parameter

    * which was passed to your macro, interpret it and return the

    * string representation.

    *

    * <p>It will throw an exception if interpretation of the parameter

    * was required but failed.

    * 

    * @param        args

    * 

    *         A {@link Vector vector} of arguments which were passed to the

    *         macro.

    * 

    * @param        i

    * 

    *         Index of the argument you want (0 corresponds to first entry).

    * 

    * @param        def

    * 

    *         Default value to return if argument omitted or doesn't

    *         evaluate properly.

    * 

    * @throws        InterpretException

    * 

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

    * 

    * @throws        IOException

    * 

    *         If interpretation of parameter involved output that triggered

    *         a I/O error.

    * 

    * @return

    * 

    *         Integer value of the specified parameter (or your default

    *         value if we could not convert it).

    * 

    * @since        1.0 */

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

   public final int getIntParameter(Vector args, int i, int def) 

     throws IOException, InterpretException {

     String istr = getStringParameter(args,i);

     if (istr.length() == 0) return def;

     try {

       def = Integer.parseInt(istr);

     } catch (Throwable t) { 

       throw new InterpretException("required integer value, passed \""+

                                    istr+"\"");

     }

     return def;

   }

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

   /** Safely retrieve and interpret a parameter and get the integer value. 

    * 

    * <p>Many times a macro isn't picky about the string value of a

    * parameter passed to the macro - it just wants to make sure it

    * isn't passed a null. This method will fetch the desired parameter

    * which was passed to your macro, interpret it and return the

    * string representation.

    *

    * <p>It will throw an exception if interpretation of the parameter

    * was required but failed.

    * 

    * @param        args

    * 

    *         A {@link Vector vector} of arguments which were passed to the

    *         macro.

    * 

    * @param        i

    * 

    *         Index of the argument you want (0 corresponds to first entry).

    * 

    * @param        def

    * 

    *         Default value to return if argument omitted or doesn't

    *         evaluate properly.

    * 

    * @throws        InterpretException

    * 

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

    * 

    * @throws        IOException

    * 

    *         If interpretation of parameter involved output that triggered

    *         a I/O error.

    * 

    * @return

    * 

    *         Integer value of the specified parameter (or your default

    *         value if we could not convert it).

    * 

    * @since        1.0 */

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

   public final long getLongParameter(Vector args, int i, long def) 

     throws IOException, InterpretException {

     String istr = getStringParameter(args,i);

     if (istr.length() == 0) return def;

     try {

       def = Long.parseLong(istr);

     } catch (Throwable t) { 

       throw new InterpretException("required long integer value, passed \""+

                                    istr+"\"");

     }

     return def;

   }

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

   /** Safely retrieve and interpret a parameter and get the double value. 

    * 

    * <p>Many times a macro isn't picky about the string value of a

    * parameter passed to the macro - it just wants to make sure it

    * isn't passed a null. This method will fetch the desired parameter

    * which was passed to your macro, interpret it and return the

    * string representation.

    *

    * <p>It will throw an exception if interpretation of the parameter

    * was required but failed.

    * 

    * @param        args

    * 

    *         A {@link Vector vector} of arguments which were passed to the

    *         macro.

    * 

    * @param        i

    * 

    *         Index of the argument you want (0 corresponds to first entry).

    * 

    * @param        def

    * 

    *         Default value to return if argument omitted or doesn't

    *         evaluate properly.

    * 

    * @throws        InterpretException

    * 

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

    * 

    * @throws        IOException

    * 

    *         If interpretation of parameter involved output that triggered

    *         a I/O error.

    * 

    * @return

    * 

    *         Double value of the specified parameter (or your default

    *         value if we could not convert it).

    * 

    * @since        1.0 */

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

   public final double getDoubleParameter(Vector args, int i, double def) 

     throws IOException, InterpretException {

     String istr = getStringParameter(args,i);

     if (istr.length() == 0) return def;

     try {

       def = Double.parseDouble(istr);

     } catch (Throwable t) { 

       throw new InterpretException("required double value, passed \""+

                                    istr+"\"");

     }

     return def;

   }

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

   /** Holds the associated {@link AtMacros AtMacros} processor.

    * 

    * @serial        

    * 

    * @since        1.0  */

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

   private AtMacros _AtMacros;

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

   /** Get the associated {@link AtMacros AtMacros} processor.

    * 

    * <p>This method allows derived classes to get access to the {@link

    * AtMacros macro processor} which they are working for. It

    * corresponds to the last registered {@link AtMacros AtMacros}

    * which was {@link #install installed}.

    *

    * @return

    * 

    *         Current AtMacros value assigned during last {@link #install

    *         install}.  */

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

   protected AtMacros getAtMacros() {

     return _AtMacros;

   }

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

   // private data

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

   private transient boolean _NeedPFile;

 }