//-----------------------------------------------------------------------
// Module name   : lcookie.js
// Author        : Paul Battersby
// Creation Date : Oct 15/05
// Description   :
//  These functions (although renamed) were taken from the book
//   Professional Javascript 2nd edition (pg 528)
//
// NOTE: if cookies are to be used, call LCOOKIE_enabled() to check and
//       warn user
//
//  $Log: Lcookie.js $
//  Revision 1.4  2009-11-10 11:57:44-04  Battersby
//  - replaced != with !== to pass lint processing
//
//  Revision 1.3  2009-05-13 12:38:27-04  Battersby
//  - cleaned up documentation
//
//------------------------------------------------------------------------*/

/*---------------------------- INCLUDE FILES ----------------------------*/


/*----------------------------- CONSTANTS -------------------------------*/


/*----------------------------- VARIABLES -------------------------------*/


/*----------------------------- FUNCTIONS -------------------------------*/

//************************************************************************
// Name   : LCOOKIE_write
//  This writes an entire cookie
//
//  (string) cookieName  - name of the cookie to be written
//  (string) cookieValue - value of the cookie to be written
//  (Date)   expires     - date on which the cookie should expire
//                ex: to expire a year from now
//                    var expireDate = new Date();
//                    expireDate.setDate(expireDate.getFullYear() + 1);
//                    writeCookie("Name","Fred",expireDate);
//                setting expires to null, means the cookie will expire at
//                the end of the browser session
//  (string) domain      - the url of the web page to which the cookie applies
//                 (seldom used)
//  (string) path        - a sub directory within the domain to which the cookie applies
//                 (seldom used)
// Post   :
//  A cookie has been written
//*************************************************************************/
function LCOOKIE_write(cookieName, cookieValue, expires, domain, path, secureFlag)
{
  if ( cookieName ) {
    var cookieDetails = cookieName + "=" + escape(cookieValue);
    cookieDetails += (expires ? "; expires=" + expires.toGMTString() : '');
    cookieDetails += (domain ? "; domain=" + domain : '');
    cookieDetails += (path ? "; path=" + path : '');
    cookieDetails += (secureFlag ? "; secure" : '');
    document.cookie = cookieDetails;
  } /* endif */
} /* end of LCOOKIE_write */

//************************************************************************
// Name   : LCOOKIE_readUnescaped
//  This reads and returns the entire value if a cookie in its unescaped
//  state
//
//  (string) cookieName  - name of the cookie to be read
//
// Post   :
//  (nothing)
//
// Returns :
//  string - unescaped value of the entire cookie
//*************************************************************************/
function LCOOKIE_readUnescaped(cookieName)
{
  var cookieValue = document.cookie;
  var cookieRegExp = new RegExp("\\b" + cookieName + "=([^;]*)");

  cookieValue = cookieRegExp.exec(cookieValue);

  if ( cookieValue !== null ) {
    cookieValue = cookieValue[1];
  } /* endif */

  return cookieValue;
} /* end of LCOOKIE_readUnescaped */

//************************************************************************
// Name   : LCOOKIE_read
//  This reads and returns the entire value if a cookie in its escaped
//  state (i.e. spaces and special characters replaced by web safe hex codes)
//
//  (string) cookieName  - name of the cookie to be read
//
// Returns :
//  (string) - escaped value of the entire cookie
//    null   - cookie does not exist
//*************************************************************************/
function LCOOKIE_read(cookieName)
{
  var cookieValue = LCOOKIE_readUnescaped(cookieName);
  if ( cookieValue !== null ) {
    cookieValue = unescape(cookieValue);
  } /* endif */

  return cookieValue;
} /* end of LCOOKIE_read */

//************************************************************************
// Name   : LCOOKIE_delete
//  This deletes an entire cookie
//
//  (string) cookieName  - name of the cookie to be deleted
//
// Post   :
//  cookie expiry date has been set to one month prior to the beginning of this
//  current year which means it will expire immediately
//*************************************************************************/
function LCOOKIE_delete(cookieName)
{
  var expiredDate = new Date();
  expiredDate.setMonth(-1);
  LCOOKIE_write(cookieName,"",expiredDate);
} /* end of LCOOKIE_delete */

//************************************************************************
// Name   : LCOOKIE_writeMultiValue
//  This allows the caller to write a sub value within a cookie instead of
//  writing an entire cookie. Only 20 cookies are allowed per domain, each of
//  these can be up to 4096 bytes in size so it makes sense to store multiple
//  variables within a cookie
//
//  (string) cookieName     - name of the cookie to be written
//  (string) multiValueName - name of the variable within the cookie to be written
//  (mixed)  value          - value of the variable within the cookie to be written
//  (Date)   expires        - date on which the cookie should expire
//                   ex: to expire a year from now
//                       var expireDate = new Date();
//                       expireDate.setDate(expireDate.getFullYear() + 1);
//                       writeCookie("Name","Fred",expireDate);
//                   setting expires to null, means the cookie will expire at
//                   the end of the browser session
//  (string) domain         - the url of the web page to which the cookie applies
//                           (seldom used)
//  string) path           - a sub directory within the domain to which the cookie applies
//                           (seldom used)
//
// Post   :
//  a variable within the given cookie has been written
//
// Returns :
//  (nothing)
//*************************************************************************/
function LCOOKIE_writeMultiValue(cookieName, multiValueName, value, expires,
domain, path, secureFlag)
{
  var cookieValue = LCOOKIE_readUnescaped(cookieName);
  if ( cookieValue ) {
    var stripAttributeRegExp = new RegExp("(^|&)" + multiValueName + "=[^&]*&?");
    cookieValue = cookieValue.replace(stripAttributeRegExp, "$1");
    if ( cookieValue.length !== 0 ) {
      cookieValue += "&";
    } /* endif */
  } else {
    cookieValue = "";
  } /* endif */

  cookieValue += multiValueName + "=" + escape(value);
  var cookieDetails = cookieName + "=" + cookieValue;

  cookieDetails += (expires ? "; expires=" + expires.toGMTString() : '');
  cookieDetails += (domain ? "; domain=" + domain : '');
  cookieDetails += (path ? "; path=" + path : '');
  cookieDetails += (secureFlag ? " ; secure" : '');
  document.cookie = cookieDetails;

} /* end of LCOOKIE_writeMultiValue */

//************************************************************************
// Name   : LCOOKIE_readMultiValue
//  This allows the caller to read a sub value within a cookie instead of
//  writing an entire cookie. Only 20 cookies are allowed per domain, each of
//  these can be up to 4096 bytes in size so it makes sense to store multiple
//  variables within a cookie
//
//  (string) cookieName     - name of the cookie to be read
//  (string) multiValueName - name of the variable within the cookie to be read
//
// Returns :
//  string - the value of the variable within the cookie
//   null  - if the variable does not exist
//*************************************************************************/
function LCOOKIE_readMultiValue(cookieName, multiValueName)
{
  var cookieValue = LCOOKIE_readUnescaped(cookieName);
  var extractMultiValueCookieRegExp = new RegExp("\\b" + multiValueName + "=([^;&]*)");

  cookieValue = extractMultiValueCookieRegExp.exec(cookieValue);

  if ( cookieValue !== null ) {
    cookieValue = unescape(cookieValue[1]);
  } /* endif */

  return cookieValue;
} /* end of LCOOKIE_readMultiValue */

//************************************************************************
// Name   : LCOOKIE_deleteMultiValue
//  This deletes a single cookie value from a multivalue cookie
//
//  (string) cookieName     - name of the cookie from which a variable is to be deleted
//  (string) multiValueName - name of the variable within the cookie to be deleted
//  (Date) expires        - date on which the cookie was to expire
//                   ex: to expire a year from now
//                       var expireDate = new Date();
//                       expireDate.setDate(expireDate.getFullYear() + 1);
//                       writeCookie("Name","Fred",expireDate);
//                   setting expires to null, means the cookie will expire at
//                   the end of the browser session
//  (string) domain         - the url of the web page to which the cookie applies
//                          (seldom used)
//  (string)path           - a sub directory within the domain to which the cookie applies
//                          (seldom used)
//
// Post   :
//  The given multiValueName was been deleted from the cookie.
//  If this multiValueName was the only remaining variable in the cookie
//  then the entire cookie is deleted
//
// Returns : (nothing)
//*************************************************************************/
function LCOOKIE_deleteMultiValue(cookieName, multiValueName, expires, domain, path, secureFlag)
{
  var cookieValue = LCOOKIE_readUnescaped(cookieName);
  if ( cookieValue ) {
    var stripAttributeRegExp = new RegExp("(^|&)" + multiValueName + "=[^&]*&?");
    cookieValue = cookieValue.replace(stripAttributeRegExp,"$1");

    if ( cookieValue.length !== 0 ) {
      var cookieDetails = cookieName + "=" + cookieValue;
      cookieDetails += (expires ? "; expires=" + expires.toGMTString() : '');
      cookieDetails += (domain ? "; domain=" + domain : '');
      cookieDetails += (path ? "; path=" + path : '');
      cookieDetails += (secureFlag ? "; secure" : '');

//alert(cookieDetails);

      document.cookie = cookieDetails;
    } else {
        LCOOKIE_delete(cookieName);
    } /* endif */
  } /* endif */
} /* end of LCOOKIE_deleteMultiValue */

//************************************************************************
// Name   : LCOOKIE_enabled
//  This checks to see if the user has cookies enabled
//
// Returns :
//  true  - if cookies are enabled
//  false - otherwise
//*************************************************************************/
function LCOOKIE_enabled()
{
  var cookiesEnabled = window.navigator.cookieEnabled;

  /* this is is a little trick to get around a problem with Netscape 4 */
  /* by creating a test cookie */
  if ( !cookiesEnabled ) {
    document.cookie = "cookiesEnabled=True";
    cookiesEnabled = new Boolean(document.cookie).valueOf();
  } /* endif */

  return cookiesEnabled;
} /* end of LCOOKIE_enabled */