Added a chapter for parameter modifications

1 files changed, 55 insertions, 0 deletions

diff --git a/docs/advanced.rst b/docs/advanced.rst
index a087c1a..77174e4 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -62,6 +62,61 @@ And it can then be used like this:
     def pop():
         pass
 
+Parameter Modifications
+-----------------------
+
+Parameters (options and arguments) are forwarded to the command callbacks
+as you have seen.  One common way to prevent a parameter from being passed
+to the callback is the `expose_value` argument to a parameter which hides
+the parameter entirely.  The way this works is that the :class:`Context`
+object has a :attr:`~Context.params` attribute which is a dictionary of
+all parameters.  Whatever is in that dictionary is being passed to the
+callbacks.
+
+This can be used to make up addition parameters.  Generally this pattern
+is not recommended but in some cases it can be useful.  At the very least
+it's good to know that the system works this way.
+
+.. click:example::
+
+    import urllib
+
+    def open_url(ctx, param, value):
+        if value is not None:
+            ctx.params['fp'] = urllib.urlopen(value)
+            return value
+
+    @click.command()
+    @click.option('--url', callback=open_url)
+    def cli(url, fp=None):
+        if fp is not None:
+            click.echo('%s: %s' % (url, fp.code))
+
+In this case the callback returns the URL unchanged but also passes a
+second ``fp`` value to the callback.  What's more recommended is to pass
+the information in a wrapper however:
+
+.. click:example::
+
+    import urllib
+
+    class URL(object):
+
+        def __init__(self, url, fp):
+            self.url = url
+            self.fp = fp
+
+    def open_url(ctx, param, value):
+        if value is not None:
+            return URL(value, urllib.urlopen(value))
+
+    @click.command()
+    @click.option('--url', callback=open_url)
+    def cli(url):
+        if url is not None:
+            click.echo('%s: %s' % (url.url, url.fp.code))
+
+
 Token Normalization
 -------------------