Starts tests and docs on JSONPath len extension

I'm not entirely happy with the docs page, but decided something was
better than nothing.

docs/source/format.rst

@@ -101,8 +101,7 @@ processed in the order given.
 * ``$HEADERS['<header>']``: The value of any header from the
   prior response.
 * ``$RESPONSE['<json path>']``: A JSONPath query into the prior
-  response. See http://jsonpath-rw.readthedocs.org/en/latest/ for
-  jsonpath-rw formatting.
+  response. See :doc:`jsonpath` for more on formatting.
 
 Where a single-quote character, ``'``, is shown above you may also use a
 double-quote character, ``"``, but in any given expression the same

docs/source/index.rst

@@ -9,6 +9,7 @@
 
    format
    example
+   jsonpath
    host
    fixtures
    handlers

docs/source/jsonpath.rst

@@ -0,0 +1,41 @@
+
+JSONPath
+========
+
+Gabbi makes extensive use of JSONPath to provide a tool for
+validating response bodies that are formatted as JSON and making
+reference to that JSON in subsequent queries. `jsonpath_rw`_ is used
+to process the JSONPath expressions.
+
+To address a common requirement when evaluting JSON responses, an
+extension has been made to the default implementation of JSONPath.
+This extension is ``len`` and will return the length of the current
+datum in the JSONPath expression.
+
+Here is a simple JSONPath example, including use of ``len``. Given JSON data
+as follows::
+
+    {
+        "alpha": ["one", "two"],
+        "beta": "hello"
+    }
+
+it is possible to get information about the values and length as
+follows::
+
+    response_json_paths:
+        # the dict has two keys
+        $.`len`: 2
+        # The elements of the alpha list
+        $.alpha[0]: one
+        $.alpha.[1]: two
+        # the alpha list has two items
+        $.alpha.`len`: 2
+        # The string at beta is hello
+        $.beta: hello
+        # The string at beta has five chars
+        $.beta.`len`: 5
+
+There are more JSONPath examples in :doc:`example`.
+
+.. _jsonpath_rw: http://jsonpath-rw.readthedocs.org/en/latest/

gabbi/gabbits_intercept/json_extensions.yaml

@@ -0,0 +1,27 @@
+#
+# Gabbi has extensions to JSONPath, so far just `len`,
+# we need to test it.
+#
+
+tests:
+
+    - name: test len
+      url: /foobar
+      method: POST
+      request_headers:
+          content-type: application/json
+      data:
+          alpha:
+              - one
+              - two
+          beta: hello
+      response_json_paths:
+          # the dict has two keys
+          $.`len`: 2
+          $.alpha[0]: one
+          $.alpha.[1]: two
+          # the list at alpha has two items
+          $.alpha.`len`: 2
+          $.beta: hello
+          # the string at beta has five chars
+          $.beta.`len`: 5