/*
   XBN Java:  Generically useful, non-GUI Java code.
   http://sourceforge.net/projects/xbnjava

   Copyright (C) 1997-2003, Jeff Epstein
   All rights reserved.

   Modifications: No

   Redistribution in binary form, with or without modifications, are permitted provided that the following conditions are met:

      * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
      * If modifications are made to source code then this license should indicate that fact in the "Modifications" section above.
      * Neither the author, nor the contributors may be used to endorse or promote products derived from this software without specific prior written permission.

   THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

   [NOTE:  This license contains NO advertising clause.]
 */
package xbn.template;
   import xbn.XBNObject;
   import xbn.array.AOSLHashtable;
   import xbn.array.UniqueStringAP;
   import xbn.array.primitive.ListPA;
   import xbn.named.Named;
   import xbn.util.ForLineRetrieval;

/**
   <P>A template is text that contains one or more \~G\~gaps\~EG\~, each representing a piece of information whose value is populated at runtime.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/template/Template.java">Template.java</A>. &nbsp;<B>Example code</B> &nbsp;See the example code for <A HREF="~JD~tf~EJD~">TemplateFiller</A></I></CODE></P>

   <h3>Rules for a template</h3>

   <UL>
      <LI>A template must contain one or more unique gaps.</LI>
      <LI>Each unique gap may exist one or more times.  Duplicates may be added or removed at any time, as long as at least one of each unique gap exists.</LI>
      <LI>Gaps may be re-ordered within a template without consequence.</LI>
   </UL>

   <h3>Rules for a gap</h3>

   <P><I>For the sake of this documentation, it is assumed that the gap tag delimiter is '<CODE>\~</CODE>', the text for the gap start and end tags is "<CODE>G</CODE>" and "<CODE>EG</CODE>", respectively, and the escape character is '<CODE>\\\\</CODE>'.  Use <A HREF="GapConfig.html">GapConfig</A> to configure different values.</I></P>

   <P><UL>
      <LI>A gap has the following format:  <B><CODE>\~G\~GAPNAME\~EG\~</CODE></B></LI>
      <LI>The name of a gap may be between one and <CODE><A HREF="~JD~tcd~EJD~">TConfigDefaults</A>.<A HREF="~JD~tcd~EJD~#getMaxGapNameLength()">getMaxGapNameLength</A></CODE> characters in length (inclusive).  It is recommended that all gap names be enforced to be only letters, digits and underscores, but you need to enforce this on your own.</LI>
      <LI>To literally display the gap tag delimiter, escape it with '<CODE>\\</CODE>'.  This is useful for recursive templates:  <CODE>\\\~G\\\~sub_gap\\\~EG\\\~</CODE></LI>
      <LI>'<CODE>\\</CODE>' must also be escaped (by itself) in order to be displayed literally.</LI>
   </UL></P>

   <h3>To learn more...</h3>

   <P>Read the documentation for the various functions in <A HREF="TemplateData.html">TemplateData</A>.</P>


   <H5>What's the difference between unique and absolute gaps?</H5>

   <P>Pretend this is your template:</P>

   <CODE><P> &nbsp; &nbsp; Hello there \~G\~name_first\~EG\~ \~G\~name_last\~EG\~</P>
   <P> &nbsp; &nbsp; I hope things are going well for you, \~G\~name_first\~EG\~.</P>
   <P> &nbsp; &nbsp; Love, Me.</P></CODE>

   <P>In order, the absolute gaps are:  <CODE>name_first, name_last, name_first</CODE></P>

   <P>And the unique gaps are:  <CODE>name_first, name_last</CODE></P>

   <P>Note that for every space <I>before and after</I> absolute gaps, there is a <A HREF="#getSurroundingText(int)">surrounding text</A> element.  In other words, the number of surrounding text elements is always exactly one more that the number of absolute gaps.</P>

   @version  0.9b
   @author  Jeff Epstein, <A HREF="http://sourceforge.net/projects/xbnjava">http://sourceforge.net/projects/xbnjava</A>.
 **/
public class Template extends XBNObject implements Named  {
   TemplateData tData = null;
   private TFilter tFilter = null;

   /**
      <P>Create a Template.</P>

      <P>Equal to <CODE><A HREF="~JD~t(s,flr)~EJD~">Template</A>(null, flr_srcTxt)</CODE></P>
    **/
   public Template(ForLineRetrieval flr_srcTxt) throws TemplateFormatException  {
      this(null, flr_srcTxt);
   }

   /**
      <P>Create a Template.</P>

      <P>Equal to <CODE><A HREF="~JD~t(s,flr,tpc)~EJD~">Template</A>(s_name, flr_srcTxt, (new <A HREF="~JD~tpc#tpc()~EJD~">TParseConfig</A>()))</CODE></P>
    **/
   public Template(String s_name, ForLineRetrieval flr_srcTxt) throws TemplateFormatException  {
      this(s_name, flr_srcTxt, (new TParseConfig()));
   }

   /**
      <P>Create a Template.</P>

      <P>Equal to <CODE><A HREF="~JD~t(s,flr,tpc,tfltr)~EJD~">Template</A>(null, flr_srcTxt, tp_config, null)</CODE></P>
    **/
   public Template(ForLineRetrieval flr_srcTxt, TParseConfig tp_config) throws TemplateFormatException  {
      this(null, flr_srcTxt, tp_config, null);
   }

   /**
      <P>Create a Template.</P>

      <P>Equal to <CODE><A HREF="~JD~t(s,flr,tpc,tfltr)~EJD~">Template</A>(s_name, flr_srcTxt, tp_config, null)</CODE></P>
    **/
   public Template(String s_name, ForLineRetrieval flr_srcTxt, TParseConfig tp_config) throws TemplateFormatException  {
      this(s_name, flr_srcTxt, tp_config, null);
   }

   /**
      <P>Create a Template.</P>

      <P>Equal to <CODE><A HREF="~JD~t(s,flr,tpc,tfltr)~EJD~">Template</A>(null, flr_srcTxt, tp_config, template_filter)</CODE></P>
    **/
   public Template(ForLineRetrieval flr_srcTxt, TParseConfig tp_config, TFilter template_filter) throws TemplateFormatException  {
      this(null, flr_srcTxt, tp_config, template_filter);
   }


   /**
      <P>Create a Template.</P>

      @param  s_templateName  The name of the template.  See <A HREF="#getName()">getName</A>
      @param  flr_srcTxt  The source text for this Template.  May not be null.
      @param  tp_config  The configuration defining a gap.  May not be null.
      @param  template_filter  The TFilter used to enforce the integrity of the about-to-be-retrieved template text.  If null, no restrictions are imposed.  See <A HREF="#getTFilter()">getTFilter</A>.
    **/
   public Template(String s_name, ForLineRetrieval flr_srcTxt, TParseConfig tp_config, TFilter template_filter) throws TemplateFormatException  {
      TemplateDataOrString tdos = new TemplateDataOrString(s_name, flr_srcTxt, tp_config);

      //Using getName() will throw a NullPointerException...START
         if(!tdos.isTemplate())  {
            throw new TemplateFormatException("constructor:  There are no gaps in the provided template text.  TemplateDataOrString.isTemplate() equals false.");
         }

         tData = tdos.getTemplateData();
      //Using getName() will throw a NullPointerException...END

      if(template_filter != null  &&  !template_filter.isTemplateValid(this))  {
         throwTFX(sCNSTR, "This template is invalid according to template_filter.isTemplateValid().  Check that all required gaps (in template_filter) actually exist in 'this' Template, and that there are no extras.\ntemplate_filter.toString()=\n[" + template_filter.toString() + "]\nthis.toString()\n[" + toString() + "].");
      }

      tFilter = template_filter;
   }


   /**
      <P>Create a copy of the provided Template.</P>

      @param  t_emplate  The Tempate to copy.  May not be null.
    **/
   public Template(Template t_emplate)  {
      try  {
         tData = t_emplate.tData.getTDClone();
      }  catch(NullPointerException npx)  {
         throwAX("constructor:  t_emplate is null.");
      }

      tFilter = t_emplate.tFilter;
   }

   /**
      <P>Create a Template.</P>

      @param  template_data  The TempateData.  May not be null.
    **/
   public Template(TemplateData template_data)  {
      throwAXIfNull(template_data, "template_data", sCNSTR);
      tData = template_data;

   }

   /**
      <P>Get the TFilter for direct manipulation.</P>

      <P>This is only used in the constructor, but is referenced here for giggles.</P>
    **/
   public final TFilter getTFilter()  {
      return tFilter;
   }

   /**
      <P>Get the TemplateData for direct manipulation.</P>
    **/
   public final TemplateData getTemplateData()  {
      return tData;
   }

   /**
      <P>Get the AOSLHashtable for direct manipulation.</P>

      @return <CODE>getTemplateData().getAOSLookup().getAOSLHashtable()</CODE>
    **/
   public final AOSLHashtable getAOSLHashtable()  {
      return getTemplateData().getAOSLookup().getAOSLHashtable();
   }

   /**
      <P>Get the UniqueStringAP, which contains all unique gaps.</P>

      @return <CODE>getTemplateData().getAOSLookup().getUSAPUnique()</CODE>
    **/
   public final UniqueStringAP getUSAPUnique()  {
      return getTemplateData().getAOSLookup().getUSAPUnique();
   }


   /**
      <P>Get the UniqueStringAP, which contains all absolute gaps.</P>

      @return <CODE>getTemplateData().getAOSLookup().getUSAPAbsolute()</CODE>
    **/
   public final UniqueStringAP getUSAPAbsolute()  {
      return getTemplateData().getAOSLookup().getUSAPAbsolute();
   }


   /**
      <P>Get a listing of the unique gap names.</P>

      @return <CODE>(new <A HREF="~JD~lpa#lpa()~EJD~">ListPA</A>()).<A HREF="~JD~lpa#get(pa)~EJD~">get</A>(<A HREF="~JD~aosl~EJD~#getUSAPUnique()">getUSAPUnique</A>().<A HREF="~JD~usap~EJD~#getUniqueStringPAS()">getUniqueStringPAS</A>())</CODE>
    **/
   public String getListUnq()  {
      return (new ListPA()).get(getUSAPUnique().getUniqueStringPAS());
   }

   /**
      <P>Get a listing of the unique gap names.</P>

      @return <CODE>(new <A HREF="~JD~lpa#lpa(lpac)~EJD~">ListPA</A>(s_divider)).<A HREF="~JD~lpa#get(pa)~EJD~">get</A>(<A HREF="~JD~aosl~EJD~#getUSAPUnique()">getUSAPUnique</A>().<A HREF="~JD~usap~EJD~#getUniqueStringPAS()">getUniqueStringPAS</A>())</CODE>
    **/
   public String getListUnq(String s_divider)  {
      return (new ListPA(s_divider)).get(getUSAPUnique().getUniqueStringPAS());
   }

   /**
      <P>Get a listing of the unique gap names.</P>

      @return <CODE>(new <A HREF="~JD~lpa#lpa(lpac)~EJD~">ListPA</A>(s_prefix, s_postfix)).<A HREF="~JD~lpa#get(pa)~EJD~">get</A>(<A HREF="~JD~aosl~EJD~#getUSAPUnique()">getUSAPUnique</A>().<A HREF="~JD~usap~EJD~#getUniqueStringPAS()">getUniqueStringPAS</A>())</CODE>
    **/
   public String getListUnq(String s_prefix, String s_postfix)  {
      return (new ListPA(s_prefix, s_postfix)).get(getUSAPUnique().getUniqueStringPAS());
   }

   /**
      <P>Get a listing of the unique gap names.</P>

      @return <CODE>(new <A HREF="~JD~lpa#lpa(lpac)~EJD~">ListPA</A>(s_prefix, s_divider, s_postfix)).<A HREF="~JD~lpa#get(pa)~EJD~">get</A>(<A HREF="~JD~aosl~EJD~#getUSAPUnique()">getUSAPUnique</A>().<A HREF="~JD~usap~EJD~#getUniqueStringPAS()">getUniqueStringPAS</A>())</CODE>
    **/
   public String getListUnq(String s_prefix, String s_divider, String s_postfix)  {
      return (new ListPA(s_prefix, s_divider, s_postfix)).get(getUSAPUnique().getUniqueStringPAS());
   }


   /**
      <P>Get a listing of the absolute gap names.</P>

      @return <CODE>(new <A HREF="~JD~lpa#lpa()~EJD~">ListPA</A>()).<A HREF="~JD~lpa#get(pa)~EJD~">get</A>(<A HREF="~JD~aosl~EJD~#getUSAPAbsolute()">getUSAPAbsolute</A>().<A HREF="~JD~usap~EJD~#getUniqueStringPAS()">getUniqueStringPAS</A>())</CODE>
    **/
   public String getListAbs()  {
      return (new ListPA()).get(getUSAPAbsolute().getUniqueStringPAS());
   }

   /**
      <P>Get a listing of the absolute gap names.</P>

      @return <CODE>(new <A HREF="~JD~lpa#lpa(lpac)~EJD~">ListPA</A>(s_divider)).<A HREF="~JD~lpa#get(pa)~EJD~">get</A>(<A HREF="~JD~aosl~EJD~#getUSAPAbsolute()">getUSAPAbsolute</A>().<A HREF="~JD~usap~EJD~#getUniqueStringPAS()">getUniqueStringPAS</A>())</CODE>
    **/
   public String getListAbs(String s_divider)  {
      return (new ListPA(s_divider)).get(getUSAPAbsolute().getUniqueStringPAS());
   }

   /**
      <P>Get a listing of the absolute gap names.</P>

      @return <CODE>(new <A HREF="~JD~lpa#lpa(lpac)~EJD~">ListPA</A>(s_prefix, s_postfix)).<A HREF="~JD~lpa#get(pa)~EJD~">get</A>(<A HREF="~JD~aosl~EJD~#getUSAPAbsolute()">getUSAPAbsolute</A>().<A HREF="~JD~usap~EJD~#getUniqueStringPAS()">getUniqueStringPAS</A>())</CODE>
    **/
   public String getListAbs(String s_prefix, String s_postfix)  {
      return (new ListPA(s_prefix, s_postfix)).get(getUSAPAbsolute().getUniqueStringPAS());
   }

   /**
      <P>Get a listing of the absolute gap names.</P>

      @return <CODE>(new <A HREF="~JD~lpa#lpa(lpac)~EJD~">ListPA</A>(s_prefix, s_divider, s_postfix)).<A HREF="~JD~lpa#get(pa)~EJD~">get</A>(<A HREF="~JD~aosl~EJD~#getUSAPAbsolute()">getUSAPAbsolute</A>().<A HREF="~JD~usap~EJD~#getUniqueStringPAS()">getUniqueStringPAS</A>())</CODE>
    **/
   public String getListAbs(String s_prefix, String s_divider, String s_postfix)  {
      return (new ListPA(s_prefix, s_divider, s_postfix)).get(getUSAPAbsolute().getUniqueStringPAS());
   }

   /**
      <P>Given the provided absolute gap's array index, what is the array index for the corresponding <I>unique</I> gap?</P>

      @return  <CODE>getUSAPAbsolute().getUniqueString(i_absArrIdx).getUnqArrIdx()</CODE>
    **/
   public final int getUnqArrIdxFromAbs(int i_absArrIdx)  {
      return getUSAPAbsolute().getUniqueString(i_absArrIdx).getUnqArrIdx();
   }

   /**
      <P>From the absolute-to-unique-gap-map array, get the unique gap array index for the requested absolute gap.</P>

      <P>Pretend this is your template:</P>

      <CODE><P> &nbsp; &nbsp; Hello there \~G\~name_first\~EG\~ \~G\~name_last\~EG\~</P>
      <P> &nbsp; &nbsp; I hope things are going well for you, \~G\~name_first\~EG\~.</P>
      <P> &nbsp; &nbsp; Love, Me.</P></CODE>

      <P>Here is a complete listing of all the surrounding text elements:<UL>
         <LI><CODE>"Hello there "</CODE></LI>
         <LI><CODE>" "</CODE></LI>
         <LI><CODE>"[NEWLINE]I hope things are going well for you, "</CODE></LI>
         <LI><CODE>".[NEWLINE]Love, Me."</CODE></LI>
      </UL></P>

      <P>Note that for every space <I>between</I> surrounding text elements, there is an <a href="#getUSAPAbsolute()">absolute gap</a>.  In other words, the number of absolute gaps is always exactly one less that the number of surrounding text elements.</P>

      <P>For an in-depth description of all the internal Template objects, see <A HREF="TemplateData.html">TemplateData</A>.</P>

      @return  <CODE>[internal TemplateData].<A HREF="TemplateData.html#getAPSSurrText()">getAOSSurroundingText</A>().<A HREF="~JD~aps#getString(i)~EJD~">getString</A>(i_dx)</CODE>
    **/
   public String getSurroundingText(int i_dx)  {
      return getTemplateData().getAPSSurrText().getString(i_dx);
   }

   /**
      <P>How many surrounding text elements exist in this template?.  This will always return a number exactly one greater than the number of <a href="#getUSAPAbsolute()">absolute gaps</a>.</P>

      <P>For an in-depth description of all the internal Template objects, see <A HREF="TemplateData.html">TemplateData</A>.</P>

      @return  <CODE>[internal TemplateData].<A HREF="TemplateData.html#getAPSSurrText()">getAOSSurroundingText</A>().<A HREF="~JD~aps~EJD~#getLength()">getLength</A>()</CODE>
    **/
   public int getSurroundingTextCount()  {

      //SANITY CHECK...start
      //	if(getTemplateData().getAPSSurrText().getLength() != (getUSAPUnique().getLength() + 1))  {
      //		throwAX("getSurroundingTextCount SANITY CHECK:  getTemplateData().getAPSSurrText().getLength() (" + getTemplateData().getAPSSurrText().getLength() + ") must equal [getUSAPUnique().getLength() + 1] (" + (getUSAPUnique().getLength() + 1) + ")!");
      //	}
      //SANITY CHECK...end

      return getTemplateData().getAPSSurrText().getLength();
   }

   //REQUIRED BY xbn.named.Named...START
      public String getName()  {
         return getTemplateData().getName();
      }
   //REQUIRED BY xbn.named.Named...END


   /**
      <P>Get some information about this Template.</P>
    **/
   public String toString()  {
      return this.getClass().getName() + ":  getName()=" + getName() + ", unique gaps:  ['" + getListUnq("', '") + "'], absolute gap array indexes:  ['" + getListAbs("', '") + "'], surrounding text:  [NOT DISPLAYED.  MUST MANUALLY GET VIA getSurroundingText()]";
   }


   /**
      <P>Throw a TemplateFormatException with a standardized message.</P>

      <P>Equal to <CODE>throw new <A HREF="~JD~tfx~EJD~">TemplateFormatException</A>(s_callingFunc, <A HREF="#getName()">getName</A>(), s_message)</CODE></P>
    **/
   protected final void throwTFX(String s_callingFunc, String s_message) throws TemplateFormatException  {
      throw new TemplateFormatException(s_callingFunc + (getName()==null?sES:" [getName()=" + getName() + "]") + s_message);
   }

   /**
      <P>Throw a TemplateFormatException with a standardized message.</P>

      <P>Equal to <CODE>throw new <A HREF="~JD~tfx~EJD~">TemplateFormatException</A>(s_callingFunc + (<A HREF="#getName()">getName</A>()==null?"":" [getName()=" + getName() + "]") + s_message)</CODE></P>
    **/
   protected final void throwTFX(String s_callingFunc, String s_name, String s_message) throws TemplateFormatException  {
      throw new TemplateFormatException(s_callingFunc + (getName()==null?sES:" [getName()=" + getName() + "]") + s_message);
   }

   /**
      <P>Throw an AssertException.</P>

      <P>Equal to <CODE><A HREF="~JD~xbno#throwAX(s)~EJD~">throwAX</A>(s_callingFunc + (<A HREF="#getName()">getName</A>()==null?"":" [getName()=" + getName() + "]") + s_message)</CODE></P>
    **/
   protected final void throwAX(String s_callingFunc, String s_message)  {
      throwAX(s_callingFunc + (getName()==null?sES:" [getName()=" + getName() + "]") + s_message);
   }
}