[svn] Doc updates for explicit behavior and unicode settings.v1.7

--HG--
branch : trunk

2 files changed, 68 insertions, 2 deletions

diff --git a/docs/manual.txt b/docs/manual.txt
index 7232dab..c7e4445 100644
--- a/docs/manual.txt
+++ b/docs/manual.txt
@@ -477,6 +477,32 @@ Let's try one more time, but put in a `static part`_ between the
     # /some/long/url/user/george           /some/long/url            george
     # /some/other/stuff/user/fred          /some/other/stuff         fred
 
+Unicode
+-------
+
+Routes by default will assume that incoming parameters are UTF-8 encoded and 
+handle the appropriate encoding/decoding. This means that *all* route variables
+will be unicode objects. Should you wish to change the encoding or turn it off
+altogether:
+
+.. code-block:: Python
+    
+    map = Mapper()
+    map.encoding = None # defaults to 'utf-8'
+    
+    map.connect(':controller/:action/:id')
+
+Individual routes can have their encoding options toggled as well, should a
+specific route want an raw string from the browser. Just add the ``_encoding`` 
+option to the route:
+
+.. code-block:: Python
+    
+    map = Mapper()
+    
+    map.connect('myapp', controller='myapp', action='wsgi', _encoding=None)
+    map.connect(':controller/:action/:id')
+
 ------------
 Using Routes
 ------------
@@ -582,6 +608,32 @@ The route memory is always used for values with the following conditions:
   to 'index'
 * If you use `named routes`_, no values from the Route dict are used
 
+Overriding Route Memory
+-----------------------
+
+Sometimes one doesn't want to have `Route Memory`_ present, as well as removing
+the `Implicit Defaults`_. Routes can disable route memory and implicit defaults
+either globally, or on a per-route basis. Setting explicit routes:
+
+.. code-block:: Python
+    
+    m = Mapper(explicit=True)
+
+When toggling explicit behavior for individual routes, only the implicit route
+defaults will be de-activated. ``url_for`` behavior can only be set globally 
+with the mapper explicit keyword. Setting explicit behavior for a route:
+
+.. code-block:: Python
+    
+    m = Mapper()
+    
+    # Note no 'id' value will be assumed for a default
+    m.connect('archives/:year', controller='archives', action='view',
+              _explicit=True)
+    
+    # This will now require an action and id present
+    m.connect(':controller/:action/:id', _explicit=True)
+
 ------------------
 Sub-domain Support
 ------------------
diff --git a/routes/base.py b/routes/base.py
index d1e3498..4018e89 100644
--- a/routes/base.py
+++ b/routes/base.py
@@ -584,6 +584,18 @@ class Mapper(object):
             
             When set to True, these defaults will not be added to route
             connections and ``url_for`` will not use Route memory.
+        
+        Additional attributes that may be set after mapper initialization (ie,
+        map.ATTRIBUTE = 'something'):
+        
+        ``encoding``
+            Used to indicate alternative encoding/decoding systems to use with
+            both incoming URL's, and during Route generation when passed a 
+            Unicode string. Defaults to 'utf-8'.
+        
+        ``decode_errors``
+            How to handle errors in the encoding, generally ignoring any chars 
+            that don't convert should be sufficient. Defaults to 'ignore'.
         """
         self.matchlist = []
         self.maxkeys = {}
@@ -643,8 +655,10 @@ class Mapper(object):
             kargs['_explicit'] = self.explicit
         route = Route(*args, **kargs)
         
-        # Apply encoding and errors if its not the defaults
-        if self.encoding != 'utf-8' or self.decode_errors != 'ignore':
+        # Apply encoding and errors if its not the defaults and the route 
+        # didn't have one passed in.
+        if (self.encoding != 'utf-8' or self.decode_errors != 'ignore') and \
+           '_encoding' not in kargs:
             route.encoding = self.encoding
             route.decode_errors = self.decode_errors