add m.route() overload to retrieve current route

docs/layout/api.html

@@ -39,6 +39,7 @@
 									<ul>
 										<li><a href="mithril.route.html#defining-routes">m.route(rootElement, defaultRoute, routes)</a></li>
 										<li><a href="mithril.route.html#redirecting">m.route(path)</a></li>
+										<li><a href="mithril.route.html#reading-current-route">m.route()</a></li>
 										<li><a href="mithril.route.html#mode-abstraction">m.route(element)</a></li>
 										<li><a href="mithril.route.html#mode">m.route.mode</a></li>
 										<li><a href="mithril.route.html#param">m.route.param</a></li>

docs/mithril.route.md

@@ -4,12 +4,14 @@ Routing is a system that allows creating Single-Page-Applications (SPA), i.e. ap
 
 It enables seamless navigability while preserving the ability to bookmark each page individually, and the ability to navigate the application via the browser's history mechanism.
 
-This method overloads 3 different units of functionality:
+This method overloads 4 different units of functionality:
 
 - `m.route(rootElement, defaultRoute, routes)` - defines the available URLs in an application, and their respective modules
 
 - `m.route(path)` - redirects to another route
 
+- `m.route()` - returns the currently active route
+
 - `m.route(element)` - an extension to link elements that unobtrusively abstracts away the routing mode
 
 Routing is single-page-application (SPA) friendly, and can be implemented using either `location.hash`, HTML5 URL rewriting or `location.querystring`. See [`m.route.mode`](#mode) for the caveats of each implementation.
@@ -189,6 +191,39 @@ void route(String path)
 
 ---
 
+<a name="reading-current-route"></a>
+
+### Reading the currently active route
+
+#### Usage
+
+Mithril updates the native `location` object after rendering in order to allow the browser's `history.pushState` API to correctly show descriptive history entries (e.g. for Chrome's Ctrl+H page).
+
+In order to retrieve the currently active route in a controller, you can use `m.route()`. This returns the portion of the URL determined by `m.route.mode` (minus the `?` or `#` symbols for the `search` and `hash` modes, respectively).
+
+```javascript
+//if the location bar is "http://example.com/?/foo/bar"
+//and m.route.mode is `search`
+//then `currentRoute == "/foo/bar"`
+var currentRoute = m.route();
+```
+
+---
+
+#### Signature
+
+[How to read signatures](how-to-read-signatures.md)
+
+```clike
+String route()
+```
+
+-	**returns String route**
+
+	returns the currently active route
+
+---
+
 <a name="mode-abstraction"></a>
 
 ### Mode abstraction