feat(ngCookies): support passing path/expires attributes to cookies

$cookieStore service had no way to set cookie attributes (such as expires).
The api for $cookieStore.put and $cookieStore.remove now has a third argument-
options,which allows setting cookie attributes, or deleting cookies under a
specific path.
- to change the path and/or expiration date of a cookie, you can pass an
  options object as the third argument to cookies(name,value).
  the options object can override Path and Expires when adding a value.
  You can pass either path, expires,none or both.
- the path option is checked to be a string and be partial to window.location
  otherwise, the default path is used. (warning is logged)
- the expires option is checked to be a Date and in the future,
  otherwise no expiration is set. (warning is logged)
- you can now delete a cookie on a specific path by calling
  cookie(name,undefined,{path:x})

The $cookie service remains unchanged since supporting cookie attributes
would mean serious backward comptability issues.
Foundations were put in place to make supporting $cookie easier.
GENERIC TEST CHANGE:
To support checking cookie path, all unit-tests now run on path "/karma/tests"
Documentation was updated for both $cookie and $cookieStore with examples.

closes	angular#1786, angular#1320
BREAKING CHANGE: As part of the change, deleting a cookie  now deletes
   cookies set in multiple paths (and duplicate cookies if exists).
   Previously only cookies set in the / path were deleted.
   Since it is not intutive, if this change breaks someones code, it is
   probably as an accidental side-effect.
   It is reasonable to assume that most people actually wanted to delete the
   cookie even if it wasn't set in the same path (since they can see it).
   So while this is a breaking change, it fixes bad behaviour.
   If needed, you can delete the cookie in a specific path using $cookieStore.

Author: alonbardavid

Gruntfile.js

@@ -137,7 +137,7 @@ module.exports = function(grunt) {
       resource: 'build/angular-resource.js',
       sanitize: 'build/angular-sanitize.js',
       bootstrap: 'build/angular-bootstrap.js',
-      bootstrapPrettify: 'build/angular-bootstrap-prettify.js',
+      bootstrapPrettify: 'build/angular-bootstrap-prettify.js'
     },
 
 

karma-jqlite.conf.js

@@ -7,6 +7,7 @@ autoWatch = true;
 logLevel = LOG_INFO;
 logColors = true;
 browsers = ['Chrome'];
+urlRoot = "/karma/tests/"
 
 junitReporter = {
   outputFile: 'test_out/jqlite.xml',

karma-jquery.conf.js

@@ -7,6 +7,7 @@ autoWatch = true;
 logLevel = LOG_INFO;
 logColors = true;
 browsers = ['Chrome'];
+urlRoot = "/karma/tests/"
 
 junitReporter = {
   outputFile: 'test_out/jquery.xml',

karma-modules.conf.js

@@ -7,6 +7,7 @@ autoWatch = true;
 logLevel = LOG_INFO;
 logColors = true;
 browsers = ['Chrome'];
+urlRoot = "/karma/tests/"
 
 junitReporter = {
   outputFile: 'test_out/modules.xml',

src/ng/browser.js

@@ -245,15 +245,19 @@ function Browser(window, document, $log, $sniffer) {
   //////////////////////////////////////////////////////////////
   var lastCookies = {};
   var lastCookieString = '';
-  var cookiePath = self.baseHref();
 
   /**
    * @name ng.$browser#cookies
    * @methodOf ng.$browser
    *
    * @param {string=} name Cookie name
    * @param {string=} value Cookie value
-   *
+   * @param {object} options Object allowing additional control on how a cookie is created
+   *    - **expires** - `{date}` - date for cookie to expire.
+   *      If not passed, the object is not a date or the date is in the past, the cookie expiration
+   *      date will not be set, so that the cookie will expire at the end of the session.
+   *    - **path** - `{string}` - the path to set the cookie on.
+   *      Defaults to {@link #baseHref baseHref}   
    * @description
    * The cookies method provides a 'private' low level access to browser cookies.
    * It is not meant to be used directly, use the $cookie service instead.
@@ -262,49 +266,113 @@ function Browser(window, document, $log, $sniffer) {
    * <ul>
    *   <li>cookies() -> hash of all cookies, this is NOT a copy of the internal state, so do not modify it</li>
    *   <li>cookies(name, value) -> set name to value, if value is undefined delete the cookie</li>
+   *   <li>cookies(name, value,options) -> same as (name, value), but allows more granular control of the cookie</li>
+   *   <li>cookies(name,undefined,options) -> deletes a cookie. allows passing path in options to delete only 
+   *                                          cookie under that path</li>
    *   <li>cookies(name) -> the same as (name, undefined) == DELETES (no one calls it right now that way)</li>
    * </ul>
    *
    * @returns {Object} Hash of all cookies (if called without any parameter)
-   */
-  self.cookies = function(name, value) {
-    var cookieLength, cookieArray, cookie, i, index;
-
-    if (name) {
-      if (value === undefined) {
-        rawDocument.cookie = escape(name) + "=;path=" + cookiePath + ";expires=Thu, 01 Jan 1970 00:00:00 GMT";
-      } else {
-        if (isString(value)) {
-          cookieLength = (rawDocument.cookie = escape(name) + '=' + escape(value) + ';path=' + cookiePath).length + 1;
-
-          // per http://www.ietf.org/rfc/rfc2109.txt browser must allow at minimum:
-          // - 300 cookies
-          // - 20 cookies per unique domain
-          // - 4096 bytes per cookie
-          if (cookieLength > 4096) {
-            $log.warn("Cookie '"+ name +"' possibly not set or overflowed because it was too large ("+
-              cookieLength + " > 4096 bytes)!");
-          }
-        }
-      }
-    } else {
-      if (rawDocument.cookie !== lastCookieString) {
-        lastCookieString = rawDocument.cookie;
-        cookieArray = lastCookieString.split("; ");
-        lastCookies = {};
-
-        for (i = 0; i < cookieArray.length; i++) {
-          cookie = cookieArray[i];
-          index = cookie.indexOf('=');
-          if (index > 0) { //ignore nameless cookies
-            lastCookies[unescape(cookie.substring(0, index))] = unescape(cookie.substring(index + 1));
-          }
-        }
-      }
-      return lastCookies;
-    }
-  };
-
+   */
+  self.cookies = (function () {
+      var cookies = function (name, value, options) {
+          if (!angular.isDefined(options) || options == null) options = {};
+          if (name) {
+              if (value === undefined) {
+                  deleteCookie(name, options);
+              } else {
+                  if (isString(value)) {
+                      setCookie(name, value, options);
+                  }
+              }
+          } else {
+              return getAllCookies();
+          }
+      }
+
+      var defaultPath = self.baseHref;
+
+      function deleteCookie(name, options) {
+          if (options.path) {
+              cookies._setCookie(escape(name) + "=;path=" + options.path + ";expires=Thu, 01 Jan 1970 00:00:00 GMT");
+          } else {
+              cookies._setCookie(escape(name) + "=;path=" + defaultPath() + ";expires=Thu, 01 Jan 1970 00:00:00 GMT");
+              var path = location.pathname;
+              //delete cookies under different paths
+              while (rawDocument.cookie.indexOf(name + "=") >= 0 && path && path != '') {
+                  cookies._setCookie(escape(name) + "=;path=" + path + ";expires=Thu, 01 Jan 1970 00:00:00 GMT");
+                  path = path.replace(/\/$|[^\/]*[^\/]$/, "");
+              }
+          }
+      }
+      function setCookie(name, value, options) {
+          var newCookie = escape(name) + '=' + escape(value)
+                + resolvePathString(name, options)
+                + resolveExpirationString(name, options);
+
+          cookies._setCookie(newCookie);
+          alertOnLength(name, newCookie);
+      }
+      function resolvePathString(name, options) {
+          var path = defaultPath();
+          if (options.path) {
+              if (angular.isString(options.path) && location.pathname.indexOf(options.path) >= 0) {
+                  path = options.path;
+              } else {
+                  $log.warn("Cookie '" + name + "' was not set with requested path '" + options.path +
+                "' since path is not a String or not partial to window.location, which is " + location.pathname)
+              }
+          }
+          return ";path=" + path;
+      }
+      function resolveExpirationString(name, options) {
+          if (options.expires) {
+              if (angular.isDate(options.expires) && options.expires > new Date()) {
+                  return ";expires=" + options.expires.toUTCString();
+              } else {
+                  $log.warn("Cookie '" + name + "' was not set with requested expiration '" + options.expires +
+                "' since date is in the past or object is not a date")
+              }
+          }
+          return "";
+      }
+      function alertOnLength(name, cookieString) {
+          var cookieLength = (cookieString).length + 1;
+
+          // per http://www.ietf.org/rfc/rfc2109.txt browser must allow at minimum:
+          // - 300 cookies
+          // - 20 cookies per unique domain
+          // - 4096 bytes per cookie
+          if (cookieLength > 4096) {
+              $log.warn("Cookie '" + name + "' possibly not set or overflowed because it was too large (" +
+            cookieLength + " > 4096 bytes)!");
+          }
+      }
+      function getAllCookies() {
+          if (rawDocument.cookie !== lastCookieString) {
+              lastCookieString = rawDocument.cookie;
+              var cookieArray = lastCookieString.split("; ");
+              lastCookies = {};
+              var cookie, i, index;
+              for (i = 0; i < cookieArray.length; i++) {
+                  cookie = cookieArray[i];
+                  index = cookie.indexOf('=');
+                  if (index > 0) { //ignore nameless cookies
+                      lastCookies[unescape(cookie.substring(0, index))] = unescape(cookie.substring(index + 1));
+                  }
+              }
+          }
+          return lastCookies;
+      }
+
+      //shameless plug for unit testing, since there's no way to access a cookie's path and expiration date
+      //and mocking the document.cookie object is too troublesome.
+      //Always use this function to set a cookie.
+      cookies._setCookie = function (value) {
+          rawDocument.cookie = value;
+      }
+      return cookies;
+  })();
 
   /**
    * @name ng.$browser#defer