refactor($route): pull $route and friends into angular-route.js

$route, $routeParams and ngView have been pulled from core angular.js
to angular-route.js/ngRoute module.

This is was done to in order keep the core focused on most commonly
used functionality and allow community routers to be freely used
instead of $route service.

There is no need to panic, angular-route will keep on being supported
by the angular team.

Note: I'm intentionally not fixing tutorial links. Tutorial will need
bigger changes and those should be done when we update tutorial to
1.2.

BREAKING CHANGE: applications that use $route will now need to load
angular-route.js file and define dependency on ngRoute module.

Before:

```
...
<script src="angular.js"></script>
...
var myApp = angular.module('myApp', ['someOtherModule']);
...
```

After:

```
...
<script src="angular.js"></script>
<script src="angular-route.js"></script>
...
var myApp = angular.module('myApp', ['ngRoute', 'someOtherModule']);
...
```

Closes #2804

9 files changed, 92 insertions, 65 deletions

diff --git a/src/AngularPublic.js b/src/AngularPublic.js
index 1fd18ce2..8330c067 100755
--- a/src/AngularPublic.js
+++ b/src/AngularPublic.js
@@ -95,7 +95,6 @@ function publishExternalAPI(angular){
             ngSwitchWhen: ngSwitchWhenDirective,
             ngSwitchDefault: ngSwitchDefaultDirective,
             ngOptions: ngOptionsDirective,
-            ngView: ngViewDirective,
             ngTransclude: ngTranscludeDirective,
             ngModel: ngModelDirective,
             ngList: ngListDirective,
@@ -122,8 +121,6 @@ function publishExternalAPI(angular){
         $location: $LocationProvider,
         $log: $LogProvider,
         $parse: $ParseProvider,
-        $route: $RouteProvider,
-        $routeParams: $RouteParamsProvider,
         $rootScope: $RootScopeProvider,
         $q: $QProvider,
         $sniffer: $SnifferProvider,
diff --git a/src/ng/animator.js b/src/ng/animator.js
index a9ec1616..d8495f2d 100644
--- a/src/ng/animator.js
+++ b/src/ng/animator.js
@@ -18,7 +18,7 @@
  * | Directive                                                 | Supported Animations                               |
  * |========================================================== |====================================================|
  * | {@link ng.directive:ngRepeat#animations ngRepeat}         | enter, leave and move                              |
- * | {@link ng.directive:ngView#animations ngView}             | enter and leave                                    |
+ * | {@link ngRoute.directive:ngView#animations ngView}        | enter and leave                                    |
  * | {@link ng.directive:ngInclude#animations ngInclude}       | enter and leave                                    |
  * | {@link ng.directive:ngSwitch#animations ngSwitch}         | enter and leave                                    |
  * | {@link ng.directive:ngIf#animations ngIf}                 | enter and leave                                    |
@@ -183,7 +183,7 @@ var $AnimatorProvider = function() {
      */
      var AnimatorService = function(scope, attrs) {
         var animator = {};
-  
+
         /**
          * @ngdoc function
          * @name ng.animator#enter
@@ -198,7 +198,7 @@ var $AnimatorProvider = function() {
          * @param {jQuery/jqLite element} after the sibling element (which is the previous element) of the element that will be the focus of the enter animation
         */
         animator.enter = animateActionFactory('enter', insert, noop);
-  
+
         /**
          * @ngdoc function
          * @name ng.animator#leave
@@ -212,7 +212,7 @@ var $AnimatorProvider = function() {
          * @param {jQuery/jqLite element} parent the parent element of the element that will be the focus of the leave animation
         */
         animator.leave = animateActionFactory('leave', noop, remove);
-  
+
         /**
          * @ngdoc function
          * @name ng.animator#move
@@ -228,7 +228,7 @@ var $AnimatorProvider = function() {
          * @param {jQuery/jqLite element} after the sibling element (which is the previous element) of the element that will be the focus of the move animation
         */
         animator.move = animateActionFactory('move', move, noop);
-  
+
         /**
          * @ngdoc function
          * @name ng.animator#show
@@ -241,7 +241,7 @@ var $AnimatorProvider = function() {
          * @param {jQuery/jqLite element} element the element that will be rendered visible or hidden
         */
         animator.show = animateActionFactory('show', show, noop);
-  
+
         /**
          * @ngdoc function
          * @name ng.animator#hide
@@ -262,14 +262,14 @@ var $AnimatorProvider = function() {
          * @description
          * Triggers a custom animation event to be executed on the given element
          *
-         * @param {string} event the name of the custom event 
+         * @param {string} event the name of the custom event
          * @param {jQuery/jqLite element} element the element that will be animated
         */
         animator.animate = function(event, element) {
           animateActionFactory(event, noop, noop)(element);
         }
         return animator;
-  
+
         function animateActionFactory(type, beforeFn, afterFn) {
           return function(element, parent, after) {
             var ngAnimateValue = scope.$eval(attrs.ngAnimate);
@@ -329,10 +329,10 @@ var $AnimatorProvider = function() {
                 polyfillStart(element, done, memento);
               } else if (isFunction($window.getComputedStyle)) {
                 //one day all browsers will have these properties
-                var w3cAnimationProp = 'animation'; 
+                var w3cAnimationProp = 'animation';
                 var w3cTransitionProp = 'transition';
 
-                //but some still use vendor-prefixed styles 
+                //but some still use vendor-prefixed styles
                 var vendorAnimationProp = $sniffer.vendorPrefix + 'Animation';
                 var vendorTransitionProp = $sniffer.vendorPrefix + 'Transition';
 
@@ -340,7 +340,7 @@ var $AnimatorProvider = function() {
                     delayKey = 'Delay',
                     animationIterationCountKey = 'IterationCount',
                     duration = 0;
-                
+
                 //we want all the styles defined before and after
                 var ELEMENT_NODE = 1;
                 forEach(element, function(element) {
@@ -387,15 +387,15 @@ var $AnimatorProvider = function() {
             }
           };
         }
-  
+
         function show(element) {
           element.css('display', '');
         }
-  
+
         function hide(element) {
           element.css('display', 'none');
         }
-  
+
         function insert(element, parent, after) {
           var afterNode = after && after[after.length - 1];
           var parentNode = parent && parent[0] || afterNode && afterNode.parentNode;
@@ -408,11 +408,11 @@ var $AnimatorProvider = function() {
             }
           });
         }
-  
+
         function remove(element) {
           element.remove();
         }
-  
+
         function move(element, parent, after) {
           // Do not remove element before insert. Removing will cause data associated with the
           // element to be dropped. Insert will implicitly do the remove.
diff --git a/src/ng/compile.js b/src/ng/compile.js
index 2dddf82d..d231fb40 100644
--- a/src/ng/compile.js
+++ b/src/ng/compile.js
@@ -172,7 +172,7 @@ function $CompileProvider($provide) {
    */
    this.directive = function registerDirective(name, directiveFactory) {
     if (isString(name)) {
-      assertArg(directiveFactory, 'directive');
+      assertArg(directiveFactory, 'directiveFactory');
       if (!hasDirectives.hasOwnProperty(name)) {
         hasDirectives[name] = [];
         $provide.factory(name + Suffix, ['$injector', '$exceptionHandler',
diff --git a/src/ng/directive/ngController.js b/src/ng/directive/ngController.js
index 289ee034..47b233f9 100644
--- a/src/ng/directive/ngController.js
+++ b/src/ng/directive/ngController.js
@@ -15,7 +15,7 @@
  * * Controller — The `ngController` directive specifies a Controller class; the class has
  *   methods that typically express the business logic behind the application.
  *
- * Note that an alternative way to define controllers is via the {@link ng.$route $route} service.
+ * Note that an alternative way to define controllers is via the {@link ngRoute.$route $route} service.
  *
  * @element ANY
  * @scope
diff --git a/src/ngResource/resource.js b/src/ngResource/resource.js
index abb2bc56..827886a3 100644
--- a/src/ngResource/resource.js
+++ b/src/ngResource/resource.js
@@ -34,9 +34,9 @@
  *   `http://example.com:8080/api`), you'll need to escape the colon character before the port
  *   number, like this: `$resource('http://example.com\\:8080/api')`.
  *
- *   If you are using a url with a suffix, just add the suffix, like this: 
+ *   If you are using a url with a suffix, just add the suffix, like this:
  *   `$resource('http://example.com/resource.json')` or `$resource('http://example.com/:id.json')
- *   or even `$resource('http://example.com/resource/:resource_id.:format')` 
+ *   or even `$resource('http://example.com/resource/:resource_id.:format')`
  *   If the parameter before the suffix is empty, :resource_id in this case, then the `/.` will be
  *   collapsed down to a single `.`.  If you need this sequence to appear and not collapse then you
  *   can escape it with `/\.`.
@@ -146,7 +146,7 @@
  *
  *     On success, the promise is resolved with the same resource instance or collection object,
  *     updated with data from server. This makes it easy to use in
- *     {@link ng.$routeProvider resolve section of $routeProvider.when()} to defer view rendering
+ *     {@link ngRoute.$routeProvider resolve section of $routeProvider.when()} to defer view rendering
  *     until the resource(s) are loaded.
  *
  *     On failure, the promise is resolved with the {@link ng.$http http response} object,
@@ -376,7 +376,7 @@ angular.module('ngResource', ['ng']).
         url = url.replace(/\/\.(?=\w+($|\?))/, '.');
         // replace escaped `/\.` with `/.`
         config.url = url.replace(/\/\\\./, '/.');
-          
+
 
         // set params - delegate param encoding to $http
         forEach(params, function(value, key){
diff --git a/src/ng/directive/ngView.js b/src/ngRoute/directive/ngView.js
index 9b5694dd..935ba05d 100644
--- a/src/ng/directive/ngView.js
+++ b/src/ngRoute/directive/ngView.js
@@ -1,13 +1,15 @@
 'use strict';
 
+ngRouteModule.directive('ngView', ngViewFactory);
+
 /**
  * @ngdoc directive
- * @name ng.directive:ngView
+ * @name ngRoute.directive:ngView
  * @restrict ECA
  *
  * @description
  * # Overview
- * `ngView` is a directive that complements the {@link ng.$route $route} service by
+ * `ngView` is a directive that complements the {@link ngRoute.$route $route} service by
  * including the rendered template of the current route into the main layout (`index.html`) file.
  * Every time the current route changes, the included view changes with it according to the
  * configuration of the `$route` service.
@@ -21,7 +23,7 @@
  *
  * @scope
  * @example
-    <example module="ngView" animations="true">
+    <example module="ngViewExample" deps="angular-route.js" animations="true">
       <file name="index.html">
         <div ng-controller="MainCntl as main">
           Choose:
@@ -101,7 +103,7 @@
       </file>
 
       <file name="script.js">
-        angular.module('ngView', [], function($routeProvider, $locationProvider) {
+        angular.module('ngViewExample', ['ngRoute'], function($routeProvider, $locationProvider) {
           $routeProvider.when('/Book/:bookId', {
             templateUrl: 'book.html',
             controller: BookCntl,
@@ -154,16 +156,14 @@
 
 /**
  * @ngdoc event
- * @name ng.directive:ngView#$viewContentLoaded
- * @eventOf ng.directive:ngView
+ * @name ngRoute.directive:ngView#$viewContentLoaded
+ * @eventOf ngRoute.directive:ngView
  * @eventType emit on the current ngView scope
  * @description
  * Emitted every time the ngView content is reloaded.
  */
-var ngViewDirective = ['$http', '$templateCache', '$route', '$anchorScroll', '$compile',
-                       '$controller', '$animator',
-               function($http,   $templateCache,   $route,   $anchorScroll,   $compile,
-                        $controller,  $animator) {
+ngViewFactory.$inject = ['$route', '$anchorScroll', '$compile', '$controller', '$animator'];
+function ngViewFactory(   $route,   $anchorScroll,   $compile,   $controller,   $animator) {
   return {
     restrict: 'ECA',
     terminal: true,
@@ -223,4 +223,4 @@ var ngViewDirective = ['$http', '$templateCache', '$route', '$anchorScroll', '$c
       }
     }
   };
-}];
+}
diff --git a/src/ng/route.js b/src/ngRoute/route.js
index 12e560c7..32b7c626 100644
--- a/src/ng/route.js
+++ b/src/ngRoute/route.js
@@ -1,22 +1,32 @@
 'use strict';
 
+/**
+ * @ngdoc overview
+ * @name ngRoute
+ * @description
+ *
+ * Module that provides routing and deeplinking services and directives for angular apps.
+ */
+
+var ngRouteModule = angular.module('ngRoute', ['ng']).
+                        provider('$route', $RouteProvider);
 
 /**
  * @ngdoc object
- * @name ng.$routeProvider
+ * @name ngRoute.$routeProvider
  * @function
  *
  * @description
  *
- * Used for configuring routes. See {@link ng.$route $route} for an example.
+ * Used for configuring routes. See {@link ngRoute.$route $route} for an example.
  */
 function $RouteProvider(){
   var routes = {};
 
   /**
    * @ngdoc method
-   * @name ng.$routeProvider#when
-   * @methodOf ng.$routeProvider
+   * @name ngRoute.$routeProvider#when
+   * @methodOf ngRoute.$routeProvider
    *
    * @param {string} path Route path (matched against `$location.path`). If `$location.path`
    *    contains redundant trailing slash or is missing one, the route will still match and the
@@ -47,7 +57,7 @@ function $RouteProvider(){
    *    - `controllerAs` – `{string=}` – A controller alias name. If present the controller will be
    *      published to scope under the `controllerAs` name.
    *    - `template` – `{string=|function()=}` – html template as a string or function that returns
-   *      an html template as a string which should be used by {@link ng.directive:ngView ngView} or
+   *      an html template as a string which should be used by {@link ngRoute.directive:ngView ngView} or
    *      {@link ng.directive:ngInclude ngInclude} directives.
    *      This property takes precedence over `templateUrl`.
    *
@@ -57,7 +67,7 @@ function $RouteProvider(){
    *        `$location.path()` by applying the current route
    *
    *    - `templateUrl` – `{string=|function()=}` – path or function that returns a path to an html
-   *      template that should be used by {@link ng.directive:ngView ngView}.
+   *      template that should be used by {@link ngRoute.directive:ngView ngView}.
    *
    *      If `templateUrl` is a function, it will be called with the following parameters:
    *
@@ -121,8 +131,8 @@ function $RouteProvider(){
 
   /**
    * @ngdoc method
-   * @name ng.$routeProvider#otherwise
-   * @methodOf ng.$routeProvider
+   * @name ngRoute.$routeProvider#otherwise
+   * @methodOf ngRoute.$routeProvider
    *
    * @description
    * Sets route definition that will be used on route change when no other route definition
@@ -142,7 +152,7 @@ function $RouteProvider(){
 
     /**
      * @ngdoc object
-     * @name ng.$route
+     * @name ngRoute.$route
      * @requires $location
      * @requires $routeParams
      *
@@ -163,10 +173,10 @@ function $RouteProvider(){
      * Is used for deep-linking URLs to controllers and views (HTML partials).
      * It watches `$location.url()` and tries to map the path to an existing route definition.
      *
-     * You can define routes through {@link ng.$routeProvider $routeProvider}'s API.
+     * You can define routes through {@link ngRoute.$routeProvider $routeProvider}'s API.
      *
-     * The `$route` service is typically used in conjunction with {@link ng.directive:ngView ngView}
-     * directive and the {@link ng.$routeParams $routeParams} service.
+     * The `$route` service is typically used in conjunction with {@link ngRoute.directive:ngView ngView}
+     * directive and the {@link ngRoute.$routeParams $routeParams} service.
      *
      * @example
        This example shows how changing the URL hash causes the `$route` to match a route against the
@@ -175,7 +185,7 @@ function $RouteProvider(){
        Note that this example is using {@link ng.directive:script inlined templates}
        to get it working on jsfiddle as well.
 
-     <example module="ngView">
+     <example module="ngView" deps="angular-route.js">
        <file name="index.html">
          <div ng-controller="MainCntl">
            Choose:
@@ -208,7 +218,7 @@ function $RouteProvider(){
        </file>
 
        <file name="script.js">
-         angular.module('ngView', [], function($routeProvider, $locationProvider) {
+         angular.module('ngView', ['ngRoute'], function($routeProvider, $locationProvider) {
            $routeProvider.when('/Book/:bookId', {
              templateUrl: 'book.html',
              controller: BookCntl,
@@ -267,8 +277,8 @@ function $RouteProvider(){
 
     /**
      * @ngdoc event
-     * @name ng.$route#$routeChangeStart
-     * @eventOf ng.$route
+     * @name ngRoute.$route#$routeChangeStart
+     * @eventOf ngRoute.$route
      * @eventType broadcast on root scope
      * @description
      * Broadcasted before a route change. At this  point the route services starts
@@ -283,12 +293,12 @@ function $RouteProvider(){
 
     /**
      * @ngdoc event
-     * @name ng.$route#$routeChangeSuccess
-     * @eventOf ng.$route
+     * @name ngRoute.$route#$routeChangeSuccess
+     * @eventOf ngRoute.$route
      * @eventType broadcast on root scope
      * @description
      * Broadcasted after a route dependencies are resolved.
-     * {@link ng.directive:ngView ngView} listens for the directive
+     * {@link ngRoute.directive:ngView ngView} listens for the directive
      * to instantiate the controller and render the view.
      *
      * @param {Object} angularEvent Synthetic event object.
@@ -298,8 +308,8 @@ function $RouteProvider(){
 
     /**
      * @ngdoc event
-     * @name ng.$route#$routeChangeError
-     * @eventOf ng.$route
+     * @name ngRoute.$route#$routeChangeError
+     * @eventOf ngRoute.$route
      * @eventType broadcast on root scope
      * @description
      * Broadcasted if any of the resolve promises are rejected.
@@ -311,8 +321,8 @@ function $RouteProvider(){
 
     /**
      * @ngdoc event
-     * @name ng.$route#$routeUpdate
-     * @eventOf ng.$route
+     * @name ngRoute.$route#$routeUpdate
+     * @eventOf ngRoute.$route
      * @eventType broadcast on root scope
      * @description
      *
@@ -326,14 +336,14 @@ function $RouteProvider(){
 
           /**
            * @ngdoc method
-           * @name ng.$route#reload
-           * @methodOf ng.$route
+           * @name ngRoute.$route#reload
+           * @methodOf ngRoute.$route
            *
            * @description
            * Causes `$route` service to reload the current route even if
            * {@link ng.$location $location} hasn't changed.
            *
-           * As a result of that, {@link ng.directive:ngView ngView}
+           * As a result of that, {@link ngRoute.directive:ngView ngView}
            * creates new scope, reinstantiates the controller.
            */
           reload: function() {
diff --git a/src/ng/routeParams.js b/src/ngRoute/routeParams.js
index 0202f8e5..0c86e89d 100644
--- a/src/ng/routeParams.js
+++ b/src/ngRoute/routeParams.js
@@ -1,14 +1,17 @@
 'use strict';
 
+ngRouteModule.provider('$routeParams', $RouteParamsProvider);
+
+
 /**
  * @ngdoc object
- * @name ng.$routeParams
+ * @name ngRoute.$routeParams
  * @requires $route
  *
  * @description
  * Current set of route parameters. The route parameters are a combination of the
  * {@link ng.$location $location} `search()`, and `path()`. The `path` parameters
- * are extracted when the {@link ng.$route $route} path is matched.
+ * are extracted when the {@link ngRoute.$route $route} path is matched.
  *
  * In case of parameter name collision, `path` params take precedence over `search` params.
  *
@@ -26,5 +29,5 @@
  * </pre>
  */
 function $RouteParamsProvider() {
-  this.$get = valueFn({});
+  this.$get = function() { return {}; };
 }
diff --git a/src/ngRoute/routeUtils.js b/src/ngRoute/routeUtils.js
new file mode 100644
index 00000000..0cff7213
--- /dev/null
+++ b/src/ngRoute/routeUtils.js
@@ -0,0 +1,17 @@
+'use strict';
+
+var copy = angular.copy,
+    equals = angular.equals,
+    extend = angular.extend,
+    forEach = angular.forEach,
+    isDefined = angular.isDefined,
+    isFunction = angular.isFunction,
+    isString = angular.isString,
+    jqLite = angular.element,
+    noop = angular.noop,
+    toJson = angular.toJson;
+
+
+function inherit(parent, extra) {
+  return extend(new (extend(function() {}, {prototype:parent}))(), extra);
+}