/*
   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.config;
   import xbn.XBNObject;
   import xbn.string.SOBString;

/**
   <P>Configuration related to variables in a ConfigReader, provided via CRConfig.  Provided to <A HREF="~JD~cr~EJD~">ConfigReader</A> via <A HREF="~JD~crc~EJD~">CRConfig</A>.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/config/CRCVariable.java">CRCVariable.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 CRCVariable extends XBNObject  {
   private CRCVTrim crcvt = null;
   private CRCVUnescape crcvu = null;
   private boolean b1stLineWSIsES = false;
   private String sNullValue = null;

   /**
      <P>Create a CRCVariable with default settings.</P>

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt)~EJD~">CRCVariable</A>(new <A HREF="~JD~crcvt#crcvt()~EJD~">CRCVTrim</A>())</CODE></P>
    **/
   public CRCVariable()  {
      this(new CRCVTrim());
   }

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

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt,crcvu)~EJD~">CRCVariable</A>(crcv_trim, (new <A HREF="~JD~crcvu#crcvu()~EJD~">CRCVUnescape</A>()))</CODE></P>
    **/
   public CRCVariable(CRCVTrim crcv_trim)  {
      this(crcv_trim, (new CRCVUnescape()));
   }

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

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt,crcvu)~EJD~">CRCVariable</A>((new <A HREF="~JD~crcvt#crcvt()~EJD~">CRCVTrim</A>()), crcv_unescape)</CODE></P>
    **/
   public CRCVariable(CRCVUnescape crcv_unescape)  {
      this((new CRCVTrim()), crcv_unescape);
   }

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

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt,s)~EJD~">CRCVariable</A>((new <A HREF="~JD~crcvt#crcvt()~EJD~">CRCVTrim</A>()), s_nullValue)</CODE></P>
    **/
   public CRCVariable(String s_nullValue)  {
      this((new CRCVTrim()), s_nullValue);
   }

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

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt,b)~EJD~">CRCVariable</A>((new <A HREF="~JD~crcvt#crcvt()~EJD~">CRCVTrim</A>()), b_1stLineWSIsEmptyString)</CODE></P>
    **/
   public CRCVariable(boolean b_1stLineWSIsEmptyString)  {
      this((new CRCVTrim()), b_1stLineWSIsEmptyString);
   }

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

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt,crcvu,s)~EJD~">CRCVariable</A>(crcv_trim, crcv_unescape, "__NULL__")</CODE></P>
    **/
   public CRCVariable(CRCVTrim crcv_trim, CRCVUnescape crcv_unescape)  {
      this(crcv_trim, crcv_unescape, "__NULL__");
   }

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

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt,crcvu,s)~EJD~">CRCVariable</A>(crcv_trim, (new <A HREF="~JD~crcvu#crcvu()~EJD~">CRCVUnescape</A>()), s_nullValue)</CODE></P>
    **/
   public CRCVariable(CRCVTrim crcv_trim, String s_nullValue)  {
      this(crcv_trim, (new CRCVUnescape()), s_nullValue);
   }

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

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt,crcvu,b)~EJD~">CRCVariable</A>(crcv_trim, (new <A HREF="~JD~crcvu#crcvu()~EJD~">CRCVUnescape</A>()), b_1stLineWSIsEmptyString)</CODE></P>
    **/
   public CRCVariable(CRCVTrim crcv_trim, boolean b_1stLineWSIsEmptyString)  {
      this(crcv_trim, (new CRCVUnescape()), b_1stLineWSIsEmptyString);
   }

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

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt,crcvu,s)~EJD~">CRCVariable</A>((new <A HREF="~JD~crcvt#crcvt()~EJD~">CRCVTrim</A>()), crcv_unescape, s_nullValue)</CODE></P>
    **/
   public CRCVariable(CRCVUnescape crcv_unescape, String s_nullValue)  {
      this((new CRCVTrim()), crcv_unescape, s_nullValue);
   }

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

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt,crcvu,b)~EJD~">CRCVariable</A>((new <A HREF="~JD~crcvt#crcvt()~EJD~">CRCVTrim</A>()), crcv_unescape, b_1stLineWSIsEmptyString)</CODE></P>
    **/
   public CRCVariable(CRCVUnescape crcv_unescape, boolean b_1stLineWSIsEmptyString)  {
      this((new CRCVTrim()), crcv_unescape, b_1stLineWSIsEmptyString);
   }

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

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt,s,b)~EJD~">CRCVariable</A>((new <A HREF="~JD~crcvt#crcvt()~EJD~">CRCVTrim</A>()), s_nullValue, b_1stLineWSIsEmptyString)</CODE></P>
    **/
   public CRCVariable(String s_nullValue, boolean b_1stLineWSIsEmptyString)  {
      this((new CRCVTrim()), s_nullValue, b_1stLineWSIsEmptyString);
   }

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

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt,crcvu,s,b)~EJD~">CRCVariable</A>(crcv_trim, crcv_unescape, s_nullValue, true)</CODE></P>
    **/
   public CRCVariable(CRCVTrim crcv_trim, CRCVUnescape crcv_unescape, String s_nullValue)  {
      this(crcv_trim, crcv_unescape, s_nullValue, true);
   }

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

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt,crcvu,s,b)~EJD~">CRCVariable</A>(crcv_trim, crcv_unescape, "__NULL__", b_1stLineWSIsEmptyString)</CODE></P>
    **/
   public CRCVariable(CRCVTrim crcv_trim, CRCVUnescape crcv_unescape, boolean b_1stLineWSIsEmptyString)  {
      this(crcv_trim, crcv_unescape, "__NULL__", b_1stLineWSIsEmptyString);
   }

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

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt,crcvu,s,b)~EJD~">CRCVariable</A>(crcv_trim, (new <A HREF="~JD~crcvu#crcvu()~EJD~">CRCVUnescape</A>()), "__NULL__", b_1stLineWSIsEmptyString)</CODE></P>
    **/
   public CRCVariable(CRCVTrim crcv_trim, String s_nullValue, boolean b_1stLineWSIsEmptyString)  {
      this(crcv_trim, (new CRCVUnescape()), s_nullValue, b_1stLineWSIsEmptyString);
   }

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

      <P>Equal to <CODE><A HREF="~JD~crcv(crcvt,crcvu,s,b)~EJD~">CRCVariable</A>((new <A HREF="~JD~crcvt#crcvt()~EJD~">CRCVTrim</A>()), crcv_unescape, s_nullValue, b_1stLineWSIsEmptyString)</CODE></P>
    **/
   public CRCVariable(CRCVUnescape crcv_unescape, String s_nullValue, boolean b_1stLineWSIsEmptyString)  {
      this((new CRCVTrim()), crcv_unescape, s_nullValue, b_1stLineWSIsEmptyString);
   }

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

      <P>This object, as a whole, is provided to the <A HREF="~JD~crc~EJD~">CRConfig</A> <A HREF="~JD~crc#crc(crcd,crcv)~EJD~">constructor</A>.  Some of these requirements are enforced there, some here.</P>

      <P>Regarding these characters:<UL>
         <LI><CODE>crcv_trim.<A HREF="~JD~crcvt~EJD~#getESChar()">getESChar</A>()</CODE> (only if <CODE>crcv_trim.<A HREF="~JD~crcvt~EJD~#doUseESChar()">doUseESChar</A>()</CODE> equals true)</LI>
         <LI><CODE>crcv_unescape.<A HREF="~JD~crcvu~EJD~#getEscapeChar()">getEscapeChar</A>()</CODE></LI>
         <LI>All the <I>unique</I> characters in s_nullValue.</LI>
      </UL></P>

      <P>They must all be unique, not <A HREF="~JD~utilc~EJD~#getAOCInvisible()">invisible</A>, and <CODE>crcv_unescape.<A HREF="~JD~crcvu~EJD~#getUSCIgnore()">getUSCIgnore</A>().<A HREF="~JD~usci#isSpcfcIgnored(c)~EJD~">isSpcfcIgnored</A>(THE_CHAR)</CODE> must equal false.</P>

      @param  crcv_trim  Configuration regarding trimming the name and value lines.  May not be null.  See <a href="#getCRCVTrim()">getCRCVTrim</a>.
      @param  crcv_unescape  Configuration regarding what and how characters should be unescaped.  May not be null.  See <a href="#getCRCVUnescape()">getCRCVUnescape</a>.
      @param  s_nullValue  The special string to be defined as (truly) null, when the <I>first line</I> of a value is equal to it.  May not be null or zero characters in length.  See <A HREF="#getNullValue()">getNullValue</A>.
      @param  b_1stLineWSIsEmptyString  If the first line of a variable's value is nothing but whitespace, should it be considered as empty string?  See <A HREF="#is1stLineWSEmptyString()">is1stLineWSEmptyString</A>.
    **/
   public CRCVariable(CRCVTrim crcv_trim, CRCVUnescape crcv_unescape, String s_nullValue, boolean b_1stLineWSIsEmptyString)  {

      SOBString ssNV = new SOBString(s_nullValue);
      ZCICharErr cice = new ZCICharErr();

      try  {
         if(crcv_trim.doUseESChar())  {
            cice.ciCharErr(crcv_trim.getESChar(), "crcv_trim.getESChar()", crcv_unescape, ssNV);
         }
      }  catch(NullPointerException npx)  {
         throwAXIfNull(crcv_trim, "crcv_trim", sCNSTR);
         throwAXIfNull(crcv_unescape, "crcv_unescape", sCNSTR);
      }

      //1/2:  Putting this first avoids 2/2 from checking
      //invisible chars against one another (and therefore
      //presenting invisible strings in the error message).
      cice.ciCharErr(crcv_unescape.getEscapeChar(), "crcv_unescape.getEscapeChar()", null, ssNV);

      //2/2
      if(crcv_trim.doUseESChar()  &&
            crcv_trim.getESChar() == crcv_unescape.getEscapeChar())  {
         throwAX("constructor:  crcv_trim.doUseESChar() equals true, and crcv_trim.getESChar() ('" + crcv_trim.getESChar() + "') equals crcv_unescape.getEscapeChar() ('" + crcv_unescape.getEscapeChar() + "').");
      }

      crcvt = crcv_trim;
      crcvu = crcv_unescape;
      sNullValue = s_nullValue;
      b1stLineWSIsES = b_1stLineWSIsEmptyString;
   }

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

      @return <B>crcv_trim</B>  Exactly as provided to the <A HREF="~JD~crcv(crcvt,crcvu,s,b)~EJD~">constructor</A>.
    **/
   public final CRCVTrim getCRCVTrim()  {
      return crcvt;
   }


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

      @return <B>crcv_unescape</B>  Exactly as provided to the <A HREF="~JD~crcv(crcvt,crcvu,s,b)~EJD~">constructor</A>.
    **/
   public final CRCVUnescape getCRCVUnescape()  {
      return crcvu;
   }

   /**
      <P>Get the special string defined as <I>null</I>.</P>

      <P>When the first line of the value of a variable is equal to this, the value is equal to null.</P>

      <H5>How to make a value literally equal to this string?</H5>

      <P><I>For the sake of this documentation section, assume this string and the special empty string character equal their default values ("<CODE>__NULL__</CODE>" and '<CODE>|</CODE>', respectively).</I></P>

      <P>To make a variable's value literally equal to "<CODE>__NULL__</CODE>", you must trim value lines (<CODE><a href="#getCRCVTrim()">getCRCVTrim</a>().<A HREF="~JD~crcvt~EJD~#doTrimVLs()">doTrimVLs</A>()</CODE> must equal true).</P>

      <P>If the <A HREF="~JD~crcvt~EJD~#getESChar()">empty string character</A> is being used (<CODE>getCRCVTrim().<A HREF="~JD~crcvt~EJD~#doUseESChar()">doUseESChar</A>()</CODE> equals true), set your variable's value equal to <B><CODE>__NU\\|LL__</CODE></B>.</P>

      <P>If the empty string character is not being used, set the <I>second or subsequent line</I> of the value equal to <B><CODE>__NULL__</CODE></B>.  This method requires that <a href="#is1stLineWSEmptyString()">is1stLineWSEmptyString</a> equals false.</P>

      @return  <B>s_nullValue</B>  Exactly as provided to the <A HREF="~JD~crcv(crcvt,crcvu,s,b)~EJD~">constructor</A>.
    **/
   public final String getNullValue()  {
      return sNullValue;
   }


   /**
      <P>If the first line of a variable's value is nothing but whitespace, should it be considered as empty string?</P>

      <P>For example, take this variable:</P>

      <PRE>name_of_variable1  =

This

is an "X":  x
and the
value "one":  1

name_of_variable2=  Value of 2</PRE>

      <P>The first line of this variable's value is only spaces or tabs, or nothing (empty string).  If this function returns true, you'll get a "stray text found" error, when CRLineAnalyzer attempts to process the "This" line.</P>

      <P>If this function returns false, then the value is "...This...is...the...value of 1".</P>

      <P>I personally prefer the former:  The user gets an error.  In order to make the first line of the value have whitespace only, configure <A HREF="~JD~crcvt~EJD~">CRCVTrim</A> to <A HREF="~JD~crcvt~EJD~#doTrimVLs()">trim value lines</A> and to <A HREF="~JD~crcvt~EJD~#doUseESChar()">use the special empty string character</A>:</P>

      <PRE>name_of_variable1  =		|

This

is a pipe \\|
and the
value of 1
</PRE>

      <P>For whitespace on the first line:</P>

      <PRE>name_of_variable1  =		|   		|

This

is a pipe \\|
and the
value of 1
</PRE>

      @return  <B>b_1stLineWSIsEmptyString</B>  Exactly as provided to the <A HREF="~JD~crcv(crcvt,crcvu,s,b)~EJD~">constructor</A>.
    **/
   public final boolean is1stLineWSEmptyString()  {
      return b1stLineWSIsES;
   }

   /**
      <P>Get some information about this CRCVariable.</P>
    **/
   public String toString()  {
      return this.getClass().getName() + ":  getNullValue()='" + getNullValue() + "', is1stLineWSEmptyString()=" + is1stLineWSEmptyString() + ", [" + getCRCVTrim().toString() + "], [" + getCRCVUnescape().toString() + "]";
   }
}