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,

    YLang       = Y.Lang,

    YObject     = Y.Object,

    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

    **/

    /**

    Map which holds the registered param handlers in the form:

    `name` -> RegExp | Function.

    @property _params

    @type Object

    @protected

    @since 3.12.0

    **/

    /**

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

    @property _ready

    @type Boolean

    @default undefined

    @protected

    **/

    /**

    Regex used to break up a URL string around the URL's path.

    Subpattern captures:

      1. Origin, everything before the URL's path-part.

      2. The URL's path-part.

      3. The URL's query.

      4. The URL's hash fragment.

    @property _regexURL

    @type RegExp

    @protected

    @since 3.5.0

    **/

    _regexURL: /^((?:[^\/#?:]+:\/\/|\/\/)[^\/]*)?([^?#]*)(\?[^#]*)?(#.*)?$/,

    /**

    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: /^(?:[^\/#?:]+:\/\/|\/\/)[^\/]*/,

    /**

    Collection of registered routes.

    @property _routes

    @type Array

    @protected

    **/

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

    initializer: function (config) {

        var self = this;

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

        self._params = {};

        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 () {

            var req, res;

            this._ready = true;

            if (!this.upgrade()) {

                req = this._getRequest('dispatch');

                res = this._getResponse(req);

                this._dispatch(req, res);

            }

        });

        return this;

    },

    /**

    Gets the current route path.

    @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);

        }

        // Get just the path portion of the specified `url`.

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

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

    },

    /**

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

    If this router has a `root`, then the specified `path` _must_ be

    semantically within the `root` path to match any routes.

    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. This should be an absolute path that

        starts with a slash: "/".

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

    **/

    match: function (path) {

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

        if (root) {

            // The `path` must be semantically within this router's `root` path

            // or mount point, if it's not then no routes should be considered a

            // match.

            if (!this._pathHasRoot(root, path)) {

                return [];

            }

            // Remove this router's `root` from the `path` before checking the

            // routes for any matches.

            path = this.removeRoot(path);

        }

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

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

        });

    },

    /**

    Adds a handler for a route param specified by _name_.

    Param handlers can be registered via this method and are used to

    validate/format values of named params in routes before dispatching to the

    route's handler functions. Using param handlers allows routes to defined

    using string paths which allows for `req.params` to use named params, but

    still applying extra validation or formatting to the param values parsed

    from the URL.

    If a param handler regex or function returns a value of `false`, `null`,

    `undefined`, or `NaN`, the current route will not match and be skipped. All

    other return values will be used in place of the original param value parsed

    from the URL.

    @example

        router.param('postId', function (value) {

            return parseInt(value, 10);

        });

        router.param('username', /^\w+$/);

        router.route('/posts/:postId', function (req) {

            Y.log('Post: ' + req.params.id);

        });

        router.route('/users/:username', function (req) {

            // `req.params.username` is an array because the result of calling

            // `exec()` on the regex is assigned as the param's value.

            Y.log('User: ' + req.params.username[0]);

        });

        router.route('*', function () {

            Y.log('Catch-all no routes matched!');

        });

        // URLs which match routes:

        router.save('/posts/1');     // => "Post: 1"

        router.save('/users/ericf'); // => "User: ericf"

        // URLs which do not match routes because params fail validation:

        router.save('/posts/a');            // => "Catch-all no routes matched!"

        router.save('/users/ericf,rgrove'); // => "Catch-all no routes matched!"

    @method param

    @param {String} name Name of the param used in route paths.

    @param {Function|RegExp} handler Function to invoke or regular expression to

        `exec()` during route dispatching whose return value is used as the new

        param value. Values of `false`, `null`, `undefined`, or `NaN` will cause

        the current route to not match and be skipped. When a function is

        specified, it will be invoked in the context of this instance with the

        following parameters:

      @param {String} handler.value The current param value parsed from the URL.

      @param {String} handler.name The name of the param.

    @chainable

    @since 3.12.0

    **/

    param: function (name, handler) {

        this._params[name] = handler;

        return this;

    },

    /**

    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'),

            path;

        // 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, '');

        // Return the host-less URL if there's no `root` path to further remove.

        if (!root) {

            return url;

        }