/*

YUI 3.10.3 (build 2fb5187)

Copyright 2013 Yahoo! Inc. All rights reserved.

Licensed under the BSD License.

http://yuilibrary.com/license/

*/

YUI.add('router', function (Y, NAME) {

/**

Provides URL-based routing using HTML5 `pushState()` or the location hash.

@module app

@submodule router

@since 3.4.0

**/

var HistoryHash = Y.HistoryHash,

    QS          = Y.QueryString,

    YArray      = Y.Array,

    win = Y.config.win,

    // Holds all the active router instances. This supports the static

    // `dispatch()` method which causes all routers to dispatch.

    instances = [],

    // We have to queue up pushState calls to avoid race conditions, since the

    // popstate event doesn't actually provide any info on what URL it's

    // associated with.

    saveQueue = [],

    /**

    Fired when the router is ready to begin dispatching to route handlers.

    You shouldn't need to wait for this event unless you plan to implement some

    kind of custom dispatching logic. It's used internally in order to avoid

    dispatching to an initial route if a browser history change occurs first.

    @event ready

    @param {Boolean} dispatched `true` if routes have already been dispatched

      (most likely due to a history change).

    @fireOnce

    **/

    EVT_READY = 'ready';

/**

Provides URL-based routing using HTML5 `pushState()` or the location hash.

This makes it easy to wire up route handlers for different application states

while providing full back/forward navigation support and bookmarkable, shareable

URLs.

@class Router

@param {Object} [config] Config properties.

    @param {Boolean} [config.html5] Overrides the default capability detection

        and forces this router to use (`true`) or not use (`false`) HTML5

        history.

    @param {String} [config.root=''] Root path from which all routes should be

        evaluated.

    @param {Array} [config.routes=[]] Array of route definition objects.

@constructor

@extends Base

@since 3.4.0

**/

function Router() {

    Router.superclass.constructor.apply(this, arguments);

}

Y.Router = Y.extend(Router, Y.Base, {

    // -- Protected Properties -------------------------------------------------

    /**

    Whether or not `_dispatch()` has been called since this router was

    instantiated.

    @property _dispatched

    @type Boolean

    @default undefined

    @protected

    **/

    /**

    Whether or not we're currently in the process of dispatching to routes.

    @property _dispatching

    @type Boolean

    @default undefined

    @protected

    **/

    /**

    History event handle for the `history:change` or `hashchange` event

    subscription.

    @property _historyEvents

    @type EventHandle

    @protected

    **/

    /**

    Cached copy of the `html5` attribute for internal use.

    @property _html5

    @type Boolean

    @protected

    **/

    /**

    Whether or not the `ready` event has fired yet.

    @property _ready

    @type Boolean

    @default undefined

    @protected

    **/

    /**

    Regex used to match parameter placeholders in route paths.

    Subpattern captures:

      1. Parameter prefix character. Either a `:` for subpath parameters that

         should only match a single level of a path, or `*` for splat parameters

         that should match any number of path levels.

      2. Parameter name, if specified, otherwise it is a wildcard match.

    @property _regexPathParam

    @type RegExp

    @protected

    **/

    _regexPathParam: /([:*])([\w\-]+)?/g,

    /**

    Regex that matches and captures the query portion of a URL, minus the

    preceding `?` character, and discarding the hash portion of the URL if any.

    @property _regexUrlQuery

    @type RegExp

    @protected

    **/

    _regexUrlQuery: /\?([^#]*).*$/,

    /**

    Regex that matches everything before the path portion of a URL (the origin).

    This will be used to strip this part of the URL from a string when we

    only want the path.

    @property _regexUrlOrigin

    @type RegExp

    @protected

    **/

    _regexUrlOrigin: /^(?:[^\/#?:]+:\/\/|\/\/)[^\/]*/,

    // -- Lifecycle Methods ----------------------------------------------------

    initializer: function (config) {

        var self = this;

        self._html5  = self.get('html5');

        self._routes = [];

        self._url    = self._getURL();

        // Necessary because setters don't run on init.

        self._setRoutes(config && config.routes ? config.routes :

                self.get('routes'));

        // Set up a history instance or hashchange listener.

        if (self._html5) {

            self._history       = new Y.HistoryHTML5({force: true});

            self._historyEvents =

                    Y.after('history:change', self._afterHistoryChange, self);

        } else {

            self._historyEvents =

                    Y.on('hashchange', self._afterHistoryChange, win, self);

        }

        // Fire a `ready` event once we're ready to route. We wait first for all

        // subclass initializers to finish, then for window.onload, and then an

        // additional 20ms to allow the browser to fire a useless initial

        // `popstate` event if it wants to (and Chrome always wants to).

        self.publish(EVT_READY, {

            defaultFn  : self._defReadyFn,

            fireOnce   : true,

            preventable: false

        });

        self.once('initializedChange', function () {

            Y.once('load', function () {

                setTimeout(function () {

                    self.fire(EVT_READY, {dispatched: !!self._dispatched});

                }, 20);

            });

        });

        // Store this router in the collection of all active router instances.

        instances.push(this);

    },

    destructor: function () {

        var instanceIndex = YArray.indexOf(instances, this);

        // Remove this router from the collection of active router instances.

        if (instanceIndex > -1) {

            instances.splice(instanceIndex, 1);

        }

        if (this._historyEvents) {

            this._historyEvents.detach();

        }

    },

    // -- Public Methods -------------------------------------------------------

    /**

    Dispatches to the first route handler that matches the current URL, if any.

    If `dispatch()` is called before the `ready` event has fired, it will

    automatically wait for the `ready` event before dispatching. Otherwise it

    will dispatch immediately.

    @method dispatch

    @chainable

    **/

    dispatch: function () {

        this.once(EVT_READY, function () {

            this._ready = true;

            if (!this.upgrade()) {

                this._dispatch(this._getPath(), this._getURL());

            }

        });

        return this;

    },

    /**

    Gets the current route path, relative to the `root` (if any).

    @method getPath

    @return {String} Current route path.

    **/

    getPath: function () {

        return this._getPath();

    },

    /**

    Returns `true` if this router has at least one route that matches the

    specified URL, `false` otherwise.

    This method enforces the same-origin security constraint on the specified

    `url`; any URL which is not from the same origin as the current URL will

    always return `false`.

    @method hasRoute

    @param {String} url URL to match.

    @return {Boolean} `true` if there's at least one matching route, `false`

      otherwise.

    **/

    hasRoute: function (url) {

        var path;

        if (!this._hasSameOrigin(url)) {

            return false;

        }

        if (!this._html5) {

            url = this._upgradeURL(url);

        }

        path = this.removeQuery(this.removeRoot(url));

        return !!this.match(path).length;

    },

    /**

    Returns an array of route objects that match the specified URL path.

    This method is called internally to determine which routes match the current

    path whenever the URL changes. You may override it if you want to customize

    the route matching logic, although this usually shouldn't be necessary.

    Each returned route object has the following properties:

      * `callback`: A function or a string representing the name of a function

        this router that should be executed when the route is triggered.

      * `keys`: An array of strings representing the named parameters defined in

        the route's path specification, if any.

      * `path`: The route's path specification, which may be either a string or

        a regex.

      * `regex`: A regular expression version of the route's path specification.

        This regex is used to determine whether the route matches a given path.

    @example

        router.route('/foo', function () {});

        router.match('/foo');

        // => [{callback: ..., keys: [], path: '/foo', regex: ...}]

    @method match

    @param {String} path URL path to match.

    @return {Object[]} Array of route objects that match the specified path.

    **/

    match: function (path) {

        return YArray.filter(this._routes, function (route) {

            return path.search(route.regex) > -1;

        });

    },

    /**

    Removes the `root` URL from the front of _url_ (if it's there) and returns

    the result. The returned path will always have a leading `/`.

    @method removeRoot

    @param {String} url URL.

    @return {String} Rootless path.

    **/

    removeRoot: function (url) {

        var root = this.get('root');

        // Strip out the non-path part of the URL, if any (e.g.

        // "http://foo.com"), so that we're left with just the path.

        url = url.replace(this._regexUrlOrigin, '');

        if (root && url.indexOf(root) === 0) {

            url = url.substring(root.length);

        }

        return url.charAt(0) === '/' ? url : '/' + url;

    },

    /**

    Removes a query string from the end of the _url_ (if one exists) and returns

    the result.

    @method removeQuery

    @param {String} url URL.

    @return {String} Queryless path.

    **/

    removeQuery: function (url) {

        return url.replace(/\?.*$/, '');

    },

    /**

    Replaces the current browser history entry with a new one, and dispatches to

    the first matching route handler, if any.

    Behind the scenes, this method uses HTML5 `pushState()` in browsers that

    support it (or the location hash in older browsers and IE) to change the

    URL.

    The specified URL must share the same origin (i.e., protocol, host, and

    port) as the current page, or an error will occur.

    @example

        // Starting URL: http://example.com/

        router.replace('/path/');

        // New URL: http://example.com/path/

        router.replace('/path?foo=bar');

        // New URL: http://example.com/path?foo=bar

        router.replace('/');

        // New URL: http://example.com/

    @method replace

    @param {String} [url] URL to set. This URL needs to be of the same origin as

      the current URL. This can be a URL relative to the router's `root`

      attribute. If no URL is specified, the page's current URL will be used.

    @chainable

    @see save()

    **/

    replace: function (url) {

        return this._queue(url, true);

    },

    /**

    Adds a route handler for the specified URL _path_.

    The _path_ parameter may be either a string or a regular expression. If it's

    a string, it may contain named parameters: `:param` will match any single

    part of a URL path (not including `/` characters), and `*param` will match

    any number of parts of a URL path (including `/` characters). These named

    parameters will be made available as keys on the `req.params` object that's

    passed to route handlers.

    If the _path_ parameter is a regex, all pattern matches will be made

    available as numbered keys on `req.params`, starting with `0` for the full

    match, then `1` for the first subpattern match, and so on.

    Here's a set of sample routes along with URL paths that they match:

      * Route: `/photos/:tag/:page`

        * URL: `/photos/kittens/1`, params: `{tag: 'kittens', page: '1'}`

        * URL: `/photos/puppies/2`, params: `{tag: 'puppies', page: '2'}`

      * Route: `/file/*path`

        * URL: `/file/foo/bar/baz.txt`, params: `{path: 'foo/bar/baz.txt'}`

        * URL: `/file/foo`, params: `{path: 'foo'}`

    **Middleware**: Routes also support an arbitrary number of callback

    functions. This allows you to easily reuse parts of your route-handling code

    with different route. This method is liberal in how it processes the

    specified `callbacks`, you can specify them as separate arguments, or as

    arrays, or both.

    If multiple route match a given URL, they will be executed in the order they

    were added. The first route that was added will be the first to be executed.

    **Passing Control**: Invoking the `next()` function within a route callback

    will pass control to the next callback function (if any) or route handler

    (if any). If a value is passed to `next()`, it's assumed to be an error,

    therefore stopping the dispatch chain, unless that value is: `"route"`,

    which is special case and dispatching will skip to the next route handler.

    This allows middleware to skip any remaining middleware for a particular

    route.

    @example

        router.route('/photos/:tag/:page', function (req, res, next) {

        });

        // Using middleware.

        router.findUser = function (req, res, next) {

            req.user = this.get('users').findById(req.params.user);

            next();

        };

        router.route('/users/:user', 'findUser', function (req, res, next) {

            // The `findUser` middleware puts the `user` object on the `req`.

        });

    @method route

    @param {String|RegExp} path Path to match. May be a string or a regular

      expression.

    @param {Array|Function|String} callbacks* Callback functions to call

        whenever this route is triggered. These can be specified as separate

        arguments, or in arrays, or both. If a callback is specified as a

        string, the named function will be called on this router instance.

      @param {Object} callbacks.req Request object containing information about

          the request. It contains the following properties.

        @param {Array|Object} callbacks.req.params Captured parameters matched by

          the route path specification. If a string path was used and contained

          named parameters, then this will be a key/value hash mapping parameter

          names to their matched values. If a regex path was used, this will be

          an array of subpattern matches starting at index 0 for the full match,

          then 1 for the first subpattern match, and so on.

        @param {String} callbacks.req.path The current URL path.