From d08b1cda638102e8f9c13fde1689438e2823220c Mon Sep 17 00:00:00 2001
From: PJ Dietz <pjdietz@gmail.com>
Date: Mon, 25 May 2015 10:43:46 -0400
Subject: [PATCH] Add documentation for URI Templates (Advanced)

---
 docs/source/index.rst                  |   1 +
 docs/source/uri-templates-advanced.rst | 144 +++++++++++++++++++++++++
 2 files changed, 145 insertions(+)
 create mode 100644 docs/source/uri-templates-advanced.rst

diff --git a/docs/source/index.rst b/docs/source/index.rst
index fed70b7..84a462a 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -106,6 +106,7 @@ Contents
    middleware
    router
    uri-templates
+   uri-templates-advanced
    dependency-injection
    web-server-configuration
 
diff --git a/docs/source/uri-templates-advanced.rst b/docs/source/uri-templates-advanced.rst
new file mode 100644
index 0000000..284a1fd
--- /dev/null
+++ b/docs/source/uri-templates-advanced.rst
@@ -0,0 +1,144 @@
+URI Templates (Advanced)
+========================
+
+In `URI Templates`_, we looked at the most common ways to use URI Templates. In this chapter, we'll look at some of the extended syntaxes that URI Templates provide.
+
+Path Components
+^^^^^^^^^^^^^^^
+
+To matching a path componenent, include a slash ``/`` at the beginning of the variable expression. This instructs the template to match the variable if it:
+
+- Begins with ``/``
+- Contains only unreserved and percent-encoded characters
+
+You may also use the explode (``*``) modifier to match a variable number of path components and provide them as an array. When using the exlode (``*``) modifier to match paths components, the ``/`` character serves as the delimiter instead of a comma.
+
+.. list-table:: Matching path components
+    :header-rows: 1
+
+    *   - Template
+        - Path
+        - Match?
+        - Attributes
+    *   - {/path}
+        - /hello.html
+        - Yes
+        - :path: ``"hello.html"``
+    *   - {/path}
+        - /too/many/parts.jpg
+        - No
+        -
+    *   - {/one}{/two}{/three}
+        - /just/enough/parts.jpg
+        - Yes
+        - :one: ``"just"``
+          :two: ``"enough"``
+          :three: ``"parts.jpg"``
+    *   - {/path*}
+        - /any/number/of/parts.jpg
+        - Yes
+        - :path: ``["any", "number", "of", "parts"]``
+    *   - /image{/image*}.jpg
+        - /image/with/any/path.jpg
+        - Yes
+        - :image: ``["with", "any", "path"]``
+
+.. note::
+
+    The template ``{/path}`` fails to match the path ``/too/many/parts.jpg``. Although the path does begin with a slash, the subsequent slashes are reserved characters, and therefore the match fails. To match a variable number of path components, use the explode ``*`` modifier (e.g, ``{/paths*}``), or use the reserved (``+``) operator (e.g., ``/{+paths}``).
+
+Dot Prefixes
+^^^^^^^^^^^^
+
+Dot prefixes work similarly to matching path components, but a dot ``.`` is the prefix character in place of a slash. This may be useful for file extensions, etc.
+
+Including a dot ``.`` at the beginning of the variable expression instructs the template to match the variable if it:
+
+- Begins with ``.``
+- Contains only unreserved (including ``.``) and percent-encoded characters
+
+You may also use the explode (``*``) modifier to match a variable number of dot-prefixed segements and store them to an array. When using the exlode (``*``) modifier to match paths components, the ``.`` character serves as the delimiter instead of a comma.
+
+.. list-table:: Matching dot prefixes
+    :header-rows: 1
+
+    *   - Template
+        - Path
+        - Match?
+        - Attributes
+    *   - /file{.ext}
+        - /file.jpg
+        - Yes
+        - :ext: ``"jpg"``
+    *   - /file{.ext}
+        - /file.tar.gz
+        - Yes
+        - :ext: ``"tar.gz"``
+    *   - /file{.ext1}{.ext2}
+        - /file.tar.gz
+        - Yes
+        - :ext1: ``"tar"``
+          :ext2: ``"gz"``
+    *   - /file{.ext*}
+        - /file.tar.gz
+        - Yes
+        - :ext: ``["tar", "gz"]``
+
+.. note::
+
+    Because ``.`` is an unreserved character, the template ``/file{.ext}`` matches the path ``/file.tar.gz`` and provides the value ``"tar.gz"``. This is different from the behavior of the slash prefix, where an unexpected slash causes the match to fail.
+
+Multiple-variable Expressions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An expression in a URI template may contain more than one variable. For example, the template ``/aliases/{one},{two},{three}`` can be written as ``/aliases/{one,two,three}``.
+
+The delimiter between the matched variables is the same as when matching with the explode (``*``) modifier:
+
+.. list-table::
+    :header-rows: 1
+
+    *   - Type
+        - Delimiter
+    *   - Simple String
+        - Comma ``,``
+    *   - Reserved
+        - Comma ``,``
+    *   - Path Components
+        - Slash ``/``
+    *   - Dot Prefix
+        - Dot ``.``
+
+.. list-table:: Multiple-variable expressions
+    :header-rows: 1
+
+    *   - Template
+        - Path
+        - Attributes
+    *   - /{one,two,three}
+        - /fry,leela,bender
+        - :one: ``"fry"``
+          :two: ``"leela"``
+          :three: ``"bender"``
+    *   - /{one,two,three}
+        - /fry,leela,Nixon%27s%20head
+        - :one: ``"fry"``
+          :two: ``"leela"``
+          :three: ``"Nixon's head"``
+    *   - /{+one,two,three}
+        - /fry,leela,Nixon's+head
+        - :one: ``"fry"``
+          :two: ``"leela"``
+          :three: ``"Nixon's head"``
+    *   - /{/one,two,three}
+        - /fry/leela/bender
+        - :one: ``"fry"``
+          :two: ``"leela"``
+          :three: ``"bender"``
+    *   - /file{.one,two,three}
+        - /file.fry.leela.bender
+        - :one: ``"fry"``
+          :two: ``"leela"``
+          :three: ``"bender"``
+
+.. _URI Templates: uri-templates.html