/*
   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.string.SOBString;
   import xbn.string.StringOrBuffer;
   import xbn.string.UtilString;
   import xbn.string.UtilStringBuffer;

/**
   <P>Unescape characters in a string.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../../CODE/xbn/string/escape/UnescapeString.java">UnescapeString.java</A></I></CODE></P>

   <P>"UnescapeString", meaning:  Delete the <A HREF="~JD~esc~EJD~#getEscapeChar()">escape character</A> existing immediately before another character.</P>

   @version  0.9b
   @author  Jeff Epstein, <A HREF="http://sourceforge.net/projects/xbnjava">http://sourceforge.net/projects/xbnjava</A>.
 **/
public class UnescapeString extends EscapeUnescapeString  {
   private UtilString uStr = new UtilString();
   private UtilStringBuffer uSB = new UtilStringBuffer();

   /**
      <P>Create an EscapeUnescapeString.</P>
      <P>Equal to <CODE><A HREF="~JD~eus#eus(esc)~EJD~">EscapeUnescapeString</A>(us_config)</CODE></P>
    **/
   public UnescapeString(USConfig us_config)  {
      super(us_config);
   }

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

      <P>Equal to <CODE><A HREF="~JD~eus#eus(eus)~EJD~">EscapeUnescapeString</A>(unescape_string)</CODE></P>
    **/
   public UnescapeString(UnescapeString unescape_string)  {
      super(unescape_string);
   }

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

      @return <CODE>(USConfig)<A HREF="~JD~eus~EJD~#getESConfig()">getESConfig</A>()</CODE>
    **/
   public final USConfig getUSConfig()  {
      return (USConfig)getESConfig();
   }

   /**
      <P>Get a copy of the string where all characters that need to be escaped, are.</P>

      @return  The contents of getSOBS:  <CODE><A HREF="~JD~unescape(sob)~EJD~">unescape</A>([<A HREF="~JD~utils~EJD~">UtilString</A>].<A HREF="~JD~utils#getSOBS(s,s)~EJD~">getSOBSB</A>(s_tr, "get"))</CODE>
    **/
   public final String get(String s_tr) throws UnescapeStringException  {
      SOBString ss = uStr.getSOBS(s_tr, "get");

      //We don't care what it returns, this is just to indicate that it *does* return something.
      int iUNRTRND = unescape(ss);
      return ss.toString();
   }
   /**
      <P>Get a copy of the string where all characters that need to be escaped, are.</P>

      @return  The contents of getSOBS:  <CODE><A HREF="~JD~unescape(sob,i)~EJD~">unescape</A>([<A HREF="~JD~utils~EJD~">UtilString</A>].<A HREF="~JD~utils#getSOBS(s,s)~EJD~">getSOBSB</A>(s_tr, "get"), i_idxErrOffset)</CODE>
    **/
   public final String get(String s_tr, int i_idxErrOffset) throws UnescapeStringException  {
      SOBString ss = uStr.getSOBS(s_tr, "get");

      //We don't care what it returns, this is just to indicate that it *does* return something.
      int iUNRTRND = unescape(ss, i_idxErrOffset);
      return ss.toString();
   }
   /**
      <P>UnescapeString all characters that need to be.</P>

      @return <CODE><A HREF="~JD~unescape(sob)~EJD~">unescape</A>([<A HREF="~JD~utilsb~EJD~">UtilStringBuffer</A>].<A HREF="~JD~utilsb#getSOBSB(sb,s)~EJD~">getSOBSB</A>(str_buffer, "unescape"))</CODE>
    **/
   public final int unescape(StringBuffer str_buffer) throws UnescapeStringException  {
      return unescape(uSB.getSOBSB(str_buffer, "unescape"));
   }
   /**
      <P>UnescapeString all characters that need to be.</P>

      @return <CODE><A HREF="~JD~unescape(sob,i)~EJD~">unescape</A>([<A HREF="~JD~utilsb~EJD~">UtilStringBuffer</A>].<A HREF="~JD~utilsb#getSOBSB(sb,s)~EJD~">getSOBSB</A>(str_buffer, "unescape"), i_idxErrOffset)</CODE>
    **/
   public final int unescape(StringBuffer str_buffer, int i_idxErrOffset) throws UnescapeStringException  {
      return unescape(uSB.getSOBSB(str_buffer, "unescape"), i_idxErrOffset);
   }


   /**
      <P>UnescapeString all characters that need to be.</P>

      @return <CODE><A HREF="~JD~unescape(sob,i)~EJD~">unescape</A>(str_orBfr, 0)</CODE>
    **/
   public final int unescape(StringOrBuffer str_orBfr) throws UnescapeStringException  {
      return unescape(str_orBfr, 0);
   }


   /**
      <P>UnescapeString all characters that need to be.  This removes the <A HREF="~JD~esc~EJD~#getEscapeChar()">escape character</A> from before the <A HREF="~JD~esc~EJD~#getAPCToEscape()">characters it is escaping</A>.  See <A HREF="~JD~usc~EJD~">USConfig</A> for more information.</P>

      @param  str_orBfr  Contains the string that needs to have its characters un-escaped.  May not be null.
      @param  i_idxErrOffset  For use only in error messages.  This number is the offset to make the error messages display the proper--overall--character array index.  When str_orBfr is actually a part of a larger string, use this to make error messages display the <I>original</I> character array index, as if str_orBfr were still part of the larger string.
      @return  The number of (escape) characters deleted.
      @exception  UnescapeStringException  If either condition is true:<UL>
         <LI>A character that <A HREF="~JD~esc#isToBeEscaped(c)~EJD~">should be escaped</A> (including a stray escape character) is not escaped (is not preceded by an escape character).</LI>
         <LI>A character that is escaped is not among those characters that should be, and that character is not <A HREF="~JD~usci~EJD~">ignored</A>.</LI>
      </UL>
    **/
   public final int unescape(StringOrBuffer str_orBfr, int i_idxErrOffset) throws UnescapeStringException  {
      throwAXIfNull(str_orBfr, "str_orBfr", "unescape");

      int iCharsDeleted = 0;

      StringOrBuffer sob = str_orBfr;

      //Note this is initialized to false.  The first character
      //in the string is definitely not escaped.
      boolean bPrecededByEscChar = false;
      for(int i = 0; i < sob.length(); i++)  {
         char c = sob.charAt(i);
         if(c != getUSConfig().getEscapeChar())  {
            //The current character is not the escape character.
            if(getUSConfig().isToBeEscaped(c))  {
               //This character is not the escape character, but
               //is one that must be escaped...

               if(!bPrecededByEscChar)  {
                  //...but it is not escaped (it is preceded by a
                  //character other than the escape character, or
                  //this character is the first one).
                  throwEUSUX("unescape (1):  An unescaped '" + c + "' was found at index " + (i + iCharsDeleted + i_idxErrOffset) + ".  [" + getUSConfig().toString() + "]");

               }
               //... and it is escaped.

               //Delete the escape character.
               sob.deleteCharAt(i - 1);
               iCharsDeleted++;
               bPrecededByEscChar = false;

               //i is now pointing to the character *after* the one
               //being escaped.  Decrement i to point to the character
               //being escaped, so when it is incremented at the top of the
               //for loop, it *then* points to that same next character.
               i--;

               continue;

            }  else if(bPrecededByEscChar)  {
               //This character is not the escape character, and not one
               //that must be escaped...but it *is* escaped.
               bPrecededByEscChar = false;

               if(!getUSConfig().getUSCIgnore().doIgnoreAll()  &&
                     !getUSConfig().getUSCIgnore().isSpcfcIgnored(c))  {
                  throwEUSUX("unescape (3):  An escaped '" + c + "' was found at index " + (i + iCharsDeleted + i_idxErrOffset) + ".  '" + c + "' is not among the characters that should be escaped.  [" + getUSConfig().toString() + "]");
               }

            }

         }  else  {
            //The current character is an escape character...
            if(bPrecededByEscChar  &&  i > 0)  {
               //...and it itself is escaped.
               sob.deleteCharAt(i - 1);
               iCharsDeleted++;
               bPrecededByEscChar = false;

               //i is now pointing to the character *after* the one
               //being escaped.  Decrement i to point to the character
               //being escaped, so when it is incremented at the top of the
               //for loop, it *then* points to the next character.
               i--;

               continue;
            }

            //...but it is not escaped.  Perhaps it is escaping
            //   something else?
            if(i == (sob.length() - 1))  {
               //This escape character is the last character in the
               //string, is not escaping anything, and is not
               //escaped itself.
               throwEUSUX("unescape (2):  An unescaped '" + getUSConfig().getEscapeChar() + "' was found at index " + (i + iCharsDeleted + i_idxErrOffset) + ".  [" + getUSConfig().toString() + "]");
            }

            //The next char is preceded by an escape char (this
            //one).
            bPrecededByEscChar = true;
         }
      }
      return iCharsDeleted;
   }

   private void throwEUSUX(String s_currently) throws UnescapeStringException  {
      throw new UnescapeStringException(getXMsgPrefix() + "unescape:  " + s_currently + "  [" + getUSConfig().toString() + "]");
   }
}