/*
   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.string.escape;
   import xbn.XBNObject;
   import xbn.array.APChar;
   import xbn.array.primitive.PACChar;
   import xbn.array.primitive.PARChar;
   import xbn.array.primitive.PARDupNullLen;
   import xbn.array.primitive.PAROrderDir;

   import java.util.Arrays;

/**
   <P>Configuration for EscapeString.  See <A HREF="~JD~es~EJD~">EscapeString</A>.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../../CODE/xbn/string/escape/ESConfig.java">ESConfig.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 ESConfig extends XBNObject  {
   private char cEsc = ' ';
   private String sEsc = null;
   private char[] acToEscape = null;
   private APChar apcToEscape = null;


   /**
      <P>Create an ESConfig with default values.</P>

      <P>Equal to <CODE><A HREF="~JD~esc(c)~EJD~">ESConfig</A>(<A HREF="#getEscapeCharDefault()">getEscapeCharDefault</A>())</CODE></P>
    **/
   public ESConfig()  {
      this(getEscapeCharDefault());
   }

   /**
      <P>Create an ESConfig.</P>

      <P>Equal to <CODE><A HREF="~JD~esc(c,c[])~EJD~">ESConfig</A>(c_escape, (new char[] {}))</CODE></P>
    **/
   public ESConfig(char c_escape)  {
      this(c_escape, (new char[] {}));
   }

   /**
      <P>Create an ESConfig.</P>

      <P>Equal to <CODE><A HREF="~JD~esc(c,c[])~EJD~">ESConfig</A>(<A HREF="#getEscapeCharDefault()">getEscapeCharDefault</A>(), ac_toEscape)</CODE></P>
    **/
   public ESConfig(char[] ac_toEscape)  {
      this(getEscapeCharDefault(), ac_toEscape);
   }


   /**
      <P>Create an ESConfig.</P>

      @param  c_escape  The escape character.
      @param  ac_toEscape  The array of charcters that can be escaped by c_escape (in addition to c_escape).  Must be non-null.  If at least one element in length, it must be ordered ascending, and its elements must be unique and not equal to c_escape.  If zero elements in length, then c_escape may only escape itself.
    **/
   public ESConfig(char c_escape, char[] ac_toEscape)  {
      PACChar pacc = new PACChar(ac_toEscape,
         new PARChar(
            new PARDupNullLen(false),
            new PAROrderDir(true),
            new char[] {c_escape}));
      pacc.crashIfBad("xbn.string.escape.UnescapeString.constructor", "ac_toEscape");

      cEsc = c_escape;
      sEsc = (new Character(cEsc)).toString();
      acToEscape = ac_toEscape;
      apcToEscape = new APChar(ac_toEscape);
   }

   /**
      <P>Create a full (deep) copy of the provided ESConfig.</P>

      @param  es_config  The ESConfig to copy.  May not be null.
    **/
   public ESConfig(ESConfig es_config)  {
      try  {
         cEsc = es_config.cEsc;
      }  catch(NullPointerException npx)  {
         throwAX("constructor:  es_config is null.");
      }

      sEsc = es_config.sEsc;
      acToEscape = es_config.acToEscape;
      apcToEscape = es_config.apcToEscape.getAPCClone();
   }


   /**
      <P>Get the escape character.</P>

      @return  <B>c_escape</B>  Exactly as provided to the <A HREF="~JD~esc(c,c[])~EJD~">constructor</A>.
    **/
   public final char getEscapeChar()  {
      return cEsc;
   }

   /**
      <P>Get the escape character, translated to a string.</P>

      @return  <CODE>(new <A HREF="~JD~C#C(c)~EJD~">Character</A>(c_escape)).<A HREF="~JD~C~EJD~#toString()">toString</A>()</CODE>  Where c_escape is exactly as provided to the <A HREF="~JD~esc(c,c[])~EJD~">constructor</A>.  Note:  This translation only happens once, in the constructor.
    **/
   public final String getEscapeCharAsString()  {
      return sEsc;
   }

   /**
      <P>Get the array of chars that must be escaped by getEscapeChar, as an APChar.</P>

      @return  <CODE>(new <A HREF="~JD~apc#apc(c[])~EJD~">APChar</A>(ac_toEscape))</CODE>  Where ac_toEscape is exactly as provided to the <A HREF="~JD~esc(c,c[])~EJD~">constructor</A>.  Note that the APChar object is only created once.
    **/
   public final APChar getAPCToEscape()  {
      return apcToEscape;
   }

   /**
      <P>Is the provided character one that should be escaped?</P>

      @return  <CODE>(<A HREF="~JD~jua~EJD~">Arrays</A>.<A HREF="~JD~jua#binarySearch(c[],c)~EJD~">binarySearch</A>(ac_toEscape, c_har) &gt; -1)</CODE>, where ac_toEscape is exactly as provided to the <A HREF="~JD~esc(c,c[])~EJD~">constructor</A>.
    **/
   public final boolean isToBeEscaped(char c_har)  {
      return (Arrays.binarySearch(acToEscape, c_har) > -1);
   }

   /**
      <P>Get some information about this ESConfig.</P>
    **/
   public String toString()  {
      return this.getClass().getName() + ":  getEscapeChar()='" + getEscapeCharAsString() + "', getAPCToEscape()=" + getAPCToEscape().getList("['", "', '", "']");
   }

   /**
      <P>When none is provided, what is the escape character used by default?</P>

      @return '\\\\'
    **/
   public static final char getEscapeCharDefault()  {
      return '\\';
   }
}