From: Nicolas Williams <nico@cryptonector.com>
Date: Mon, 7 Jul 2014 22:13:51 +0000 (-0500)
Subject: Document `path(path_expression)` builtin
X-Git-Tag: jq-1.5rc1~139
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=ef9b5912158c4f9ead75053c08c209c981d56a40;p=jq

Document `path(path_expression)` builtin
---

diff --git a/docs/content/3.manual/manual.yml b/docs/content/3.manual/manual.yml
index cc2d5a2..4704254 100644
--- a/docs/content/3.manual/manual.yml
+++ b/docs/content/3.manual/manual.yml
@@ -618,6 +618,33 @@ sections:
             input: '[[0,1], ["a","b","c"]]'
             output: ['[false, true]']
 
+      - title: "`path(path_expression)`"
+        body: |
+
+          Outputs array representations of the given path expression
+          in `.`.  The outputs are arrays of strings (keys in objects0
+          and/or numbers (array indices.
+
+          Path expressions are jq expressions like `.a`, but also `.[]`.
+          There are two types of path expressions: ones that can match
+          exactly, and ones that cannot.  For example, `.a.b.c` is an
+          exact match path expression, while `.a[].b` is not.
+
+          `path(exact_path_expression)` will produce the array
+          representation of the path expression even if it does not
+          exist in `.`, if `.` is `null` or an array or an object.
+
+          `path(pattern)` will produce array representations of the
+          paths matching `pattern` if the paths exist in `.`.
+
+        examples:
+          - program: 'path(.a[0].b)'
+            input: 'null'
+            output: ['["a",0,"b"]']
+          - program: '[path(..)]'
+            input: '{"a":[{"b":1}]}'
+            output: ['[[],["a"],["a",0],["a",0,"b"]]']
+
       - title: "`del(path_expression)`"
         body: |