/*
   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.util;
   import xbn.XBNObject;
   import xbn.template.*;
   import xbn.AssertException;
   import xbn.array.VWObject;
   import xbn.array.VWString;
   import xbn.array.AOOValid;
   import xbn.array.AOOVCAll;
   import xbn.output.Outputter;
   import xbn.placeholder.i_i;
   import xbn.placeholder.s_s;
   import xbn.string.escape.EscapeString;
   import xbn.string.escape.ESConfig;
   import xbn.string.FLRString;
   import xbn.util.ForLineRetrieval;


/**
   <P>Random functions related to Templates.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../../CODE/xbn/template/util/UtilTemplate.java">UtilTemplate.java</A>.</I></CODE></P>

   @version  0.9b
   @author  Jeff Epstein, <A HREF="http://sourceforge.net/projects/xbnjava">http://sourceforge.net/projects/xbnjava</A>.
 **/
public class UtilTemplate extends XBNObject  {
   private AOOValid aoov = new AOOValid(new AOOVCAll());
   private TemplateFiller tf = new TemplateFiller(false);

   /**
      <P>Create a UtilTemplate.  This constructor does nothing.</P>
    **/
   public UtilTemplate()  {
   }

   /**
      <P>Get all the unique gap names that exist in the provided source text, or null if no gaps exist.</P>

      <P>See <A HREF="~JD~addUnqGapNamesToACS(vws,flr,gc,optr)~EJD~">addUnqGapNamesToACS</A></P>
    **/
   public final String[] getAOSUniqueGapNames(ForLineRetrieval flr_srcTxt, GapConfig gap_config, Outputter optr_dbg)  {
      VWString vws = new VWString();
      addUnqGapNamesToACS(vws, flr_srcTxt, gap_config, optr_dbg);

      if(vws.size() == 0)  {
         return null;
      }

      return vws.getAOString();
   }

   /**
      <P>Add all the unique gap names found in the source text to the VWString.</P>

      <P>This creates a new <A HREF="~JD~tdos~EJD~">TemplateDataOrString</A> with the following <A HREF="~JD~tdos#tdos(s,flr,tpc)~EJD~">constructor</A> parameters:</P>

      <P><CODE>(null, flr_srcTxt, (new <A HREF="~JD~tpc#tpc(gc,b,optr)~EJD~">TParseConfig</A>(gap_config, true, optr_dbg)))</CODE></P>

      @param  vws_uniqueGaps  The VWString to add to.  If null, a new VWString is created.  How convenient is that?  This parameter is manipulated by this function.  It...<UL>
         <LI>...is left unaltered, if there are no gaps in the source text, or if there are gaps in the source text, but every one already exists in vws_uniqueGaps.</LI>
         <LI>...has any unique gaps existing in the source text to the VWString.</LI>
      </UL>
      @return  An <B>i_i</B>  Where i1 equals the number of unique gap names added to vws_uniqueGaps, and i2 is the number of absolute gaps existing in flr_srcTxt.
    **/
   public final i_i addUnqGapNamesToACS(VWString vws_uniqueGaps, ForLineRetrieval flr_srcTxt, GapConfig gap_config, Outputter optr_dbg)  {
      throwAXIfNull(flr_srcTxt, "flr_srcTxt", "getAOSUniqueGapNames");
      throwAXIfNull(gap_config, "gap_config", "getAOSUniqueGapNames");
      throwAXIfNull(optr_dbg, "optr_dbg", "getAOSUniqueGapNames");

      TemplateDataOrString tdos = null;
      try  {
         tdos = new TemplateDataOrString(null, flr_srcTxt, (new TParseConfig(gap_config, true, optr_dbg)));
      }  catch(AssertException ax)  {
         throwAX("getAOSUniqueGapNames:  Attempting to create a TemplateDataOrString:  " + ax.toString());
      }  catch(TemplateFormatException tfx)  {
         throwAX("getAOSUniqueGapNames:  Attempting to create a TemplateDataOrString:  " + tfx.toString());
      }

      if(vws_uniqueGaps == null)  {
         vws_uniqueGaps = new VWString();
      }

      i_i ii = new i_i(0, 0);

      if(tdos.isString())  {
         return ii;
      }

      ii.i2 = tdos.getTemplateData().getAOSLookup().getUSAPAbsolute().getLength();

      boolean bExists = false;
      for(int i = 0; i < tdos.getTemplateData().getAOSLookup().getUSAPUnique().getLength(); i++, bExists = false)  {
         String sGapName = tdos.getTemplateData().getAOSLookup().getUSAPUnique().getUniqueString(i).getString();

         for(int j = 0; j < vws_uniqueGaps.size()  &&  !bExists; j++)  {
            if(vws_uniqueGaps.getString(0).equals(sGapName))  {
               bExists = true;
            }
         }

         if(!bExists)  {
            ii.i1++;
            vws_uniqueGaps.add(sGapName);
         }
      }


      return ii;
   }


   /**
      <P>Get the resulting string, after filling in the single gap, existing in the provided template string.</P>

      <P>Equal to <CODE><A HREF="~JD~getFilledXGapsTString(i,s,s[])~EJD~">getFilledXGapsTString</A>(1, s_templateWithOneGap, (new String[] {s_fillText}))</CODE></P>
    **/
   public final String getFilled1GapTString(String s_templateWithOneGap, String s_fillText)  {
      return getFilledXGapsTString(1, s_templateWithOneGap, (new String[] {s_fillText}));
   }


   /**
      <P>Get the resulting string, after filling in the gaps existing in the provided template string.</P>

      @param  i_rqdUniqueGaps  The number of gaps required to exist in s_templateWithXGaps.  Must be greater than zero.
      @param  s_templateWithXGaps  The template source text.  Must be non null, and contain exactly i_rqdUniqueGaps gaps.  All gap names are surrounded with tag delimiters which, by default, are TConfigDefaults.<A HREF="~JD~tcd~EJD~#getTagTxtStart()">getTagTxtStart</A> and TConfigDefaults.<A HREF="~JD~tcd~EJD~#getTagTxtEnd()">getTagTxtEnd</A>.
      @param  as_fillText  The array of strings containing the text to fill into the unique gaps in s_templateWithXGaps.  Must be valid according to <A HREF="~JD~aoov~EJD~">AOOValid</A>.<A HREF="~JD~aoov#crashIfBad(s,s,o[])~EJD~">crashIfBad</A>, and its length must equal i_rqdUniqueGaps.
      @exception  AssertException  If a <A HREF="~JD~tfx~EJD~">TemplateFormatException</A> is thrown when parsing s_templateWithXGaps, for any reason.
    **/
   public final String getFilledXGapsTString(int i_rqdUniqueGaps, String s_templateWithXGaps, String[] as_fillText)  {
      if(i_rqdUniqueGaps < 1)  {
         throwAX("getFilledXGapsTString:  i_rqdUniqueGaps must be greater than zero.  Currently " + i_rqdUniqueGaps + ".");
      }

      throwAXIfBadStr(s_templateWithXGaps, "s_templateWithXGaps", "getFilledXGapsTString");

      aoov.crashIfBad("xbn.template.util.UtilTemplate.getFilledXGapsTString", "as_fillText", as_fillText);

      if(as_fillText.length != i_rqdUniqueGaps)  {
         throwAX("getFilledXGapsTString:  as_fillText.length (" + as_fillText.length + ") must equal i_rqdUniqueGaps (" + i_rqdUniqueGaps + ").");
      }

      TemplateDataOrString tdos = null;
      try  {
         tdos = new TemplateDataOrString(new FLRString(s_templateWithXGaps));
      }  catch(TemplateFormatException tfx)  {
         throwAX("getFilledXGapsTString:  " + tfx.toString());
      }

      if(tdos.isString())  {
         throwAX("getFilledXGapsTString:  There are no gaps found in s_templateWithXGaps.");
      }

      Template t = new Template(tdos.getTemplateData());
      if(t.getUSAPUnique().getLength() != i_rqdUniqueGaps)  {
         throwAX("getFilledXGapsTString:  There are " + t.getUSAPUnique().getLength() + " unique gaps in s_templateWithOneGap.  It is required to have exactly " + i_rqdUniqueGaps + ".");
      }

      tf.setTemplate(t);
      for(int i = 0; i < t.getUSAPUnique().getLength(); i++)  {
         tf.fill(t.getUSAPUnique().getUniqueString(i).getString(), as_fillText[i]);
      }
      return tf.getResult();
   }

   /**
      <P>Want to see the original text, as it existed before it was parsed?</P>
    **/
   public final String getOriginalText(Template t_emplate)  {
      return getOriginalText(t_emplate.getTemplateData());
   }

   /**
      <P>Want to see the original text, as it existed before it was parsed?</P>
    **/
   public final String getOriginalText(TemplateData template_data)  {
      throwAXIfNull(template_data, "template_data", "getOriginalText");

      StringBuffer sb = new StringBuffer(sES);
      try  {
         EscapeString es = new EscapeString(new ESConfig(new char[] {template_data.getTagStart().charAt(0)}));
         for(int i = 0; i < template_data.getAPSSurrText().getLength(); i++)  {
            sb.append(es.get(template_data.getAPSSurrText().getString(i)));

            //There are always exactly 1 less items in the gap int
            //array than in the surrounding text array.
            if(i < (template_data.getAPSSurrText().getLength() - 1))  {
               int iUnqFromAbsolute = template_data.getAOSLookup().getUSAPAbsolute().getUniqueString(i).getUnqArrIdx();
               String s = template_data.getAOSLookup().getUSAPUnique().getUniqueString(iUnqFromAbsolute).getString();
               sb.append(template_data.getTagStart()).append(s).append(template_data.getTagEnd());
            }
         }
      }  catch(Exception x)  {
         throwAX("getOriginalText:  template_data is non-null, but must somehow be invalid.  This is only possible when it has been manually created or altered.  " + x.toString());
      }

      return sb.toString();
   }


   /**
      <P>Recursively fill a set of templates, and get the resulting name/value in a placeholder.s_s object (name=s1, value=s2).</P>

      <P>At least one element must be a string, which is the "seed" to prevent circular fills.  Every gap must be the name of an existing template/string (except itself).  There must be at least one gap in at least one Template.</P>

      <P><CODE><I><B>Example code</B> &nbsp;<A HREF="../../../xbn_examples/template/util/XmplRecursiveFill.html">XmplRecursiveFill.java</A></CODE></I></P>
    **/
   public final s_s[] getRecursivelyFilled(TDOSArray tdosa_recursive)  {
      throwAXIfNull(tdosa_recursive, "tdosa_recursive", "getRecursiveFills");

      int iCount = tdosa_recursive.getLength();

      /*
         TO START...

            [atf] is an array that mirrors the one in tdosa_recursive (at least, with concern to ordering), with each Template set into a TemplateFiller.  Those tdosa_recursive elements that are strings are represented with a null element here.

            [ass] is the opposite of atf.  It holds the strings from tdosa_recursive, and the elements that are Templates are null.

            [acoTAndIdx] is a compressed version of atf (with the array index, anvs the same Template exists in atf).  Both this and atf point to the same TemplateFiller objects, but acoTAndIdx has no null elements.

         AS SOON AS A TEMPLATE IS COMPLETELY FILLED, the result is put into anvs
       */
      TemplateFiller[] atf = new TemplateFiller[iCount];
      s_s[] ass = new s_s[iCount];
      VWObject acoTAndIdx = new VWObject();

      for(int i = 0; i < iCount; i++)  {
         if(tdosa_recursive.isTemplate(i))  {
            atf[i] = new TemplateFiller();
            atf[i].setTemplate(new Template(tdosa_recursive.getTemplateData(i)));
            acoTAndIdx.add(new TFAndArrIdx(i, atf[i]));

         }  else  {
            //It is a string
            ass[i] = new s_s(tdosa_recursive.getName(i), tdosa_recursive.getString(i));
         }
      }

      if(acoTAndIdx.size() == 0)  {
         throwAX("getRecursivelyFilled:  There are no Templates in tdosa_recursive (there are a total of " + iCount + " elements in tdosa_recursive, all of which are strings).");
      }

      StringBuffer sbPath = new StringBuffer(sES);
      for(int i = 0; i < acoTAndIdx.size(); i++)  {
         TFAndArrIdx tfaai = (TFAndArrIdx)acoTAndIdx.getObject(i);
         TemplateFiller tf = tfaai.tf;
         int iArrIdxInATF = tfaai.iArrIdxInATF;

         if(ass[iArrIdxInATF] == null)  {
            //sbPath is used only for circular path error messages.
            if(sbPath.length() > 0)  {
               sbPath.setLength(0);
            }
            sbPath.append(tf.getTemplate().getName());

            //Fill this template, and it's sub-templates as necessary.
            ass[iArrIdxInATF] = getRecursiveTmplResult(tf, ass, tdosa_recursive, iArrIdxInATF, sbPath, atf);
         }
      }

      return ass;
   }

   private final s_s getRecursiveTmplResult(TemplateFiller tf_beingFilled, s_s[] ass_filled, TDOSArray tdosa_all, int i_idxTop, StringBuffer sb_path, TemplateFiller[] atf_all)  {
      Template t = tf_beingFilled.getTemplate();

      for(int i = 0; i < t.getUSAPUnique().getLength(); i++)  {
         String sUnqGap = t.getUSAPUnique().getUniqueString(i).getString();

         if(!tdosa_all.doesExist(sUnqGap))  {
            throwAX("getRecursivelyFilled:  Gap named '" + sUnqGap + "' exists in Template named '" + t.getName() + "', but this name does not exist in tdosa_recursive.");
         }

         int iArrIdxOfGapInTDOSA = tdosa_all.getArrIdx(sUnqGap);
         if(iArrIdxOfGapInTDOSA == i_idxTop)  {
            sb_path.append(" ... ").append(sUnqGap);
            throwAX("getRecursivelyFilled:  Circular sub variable path [ " + sb_path.toString() + " ]");
         }

         if(ass_filled[iArrIdxOfGapInTDOSA] == null)  {
            //There are some sub-gaps in the contents.  Fill them.
            sb_path.append(" ... ").append(sUnqGap);

            TemplateFiller tfSubTemplate = atf_all[iArrIdxOfGapInTDOSA];
            ass_filled[iArrIdxOfGapInTDOSA] = getRecursiveTmplResult(tfSubTemplate, ass_filled, tdosa_all, i_idxTop, sb_path, atf_all);
         }
         //The contents for this gap have been filled.  Completely.
         tf_beingFilled.fill(sUnqGap, ass_filled[iArrIdxOfGapInTDOSA].s2);
      }

      //This template is now completely filled.
      return (new s_s(tf_beingFilled.getTemplate().getName(), tf_beingFilled.getResult()));
   }
}

class TFAndArrIdx  {
   int iArrIdxInATF = -1;
   TemplateFiller tf = null;
   public TFAndArrIdx(int i_idxInATF, TemplateFiller template_filler)  {
      iArrIdxInATF = i_idxInATF;
      tf = template_filler;
   }
}