From 57af17cfa6e08a6fe9bf6d73d401af17dccfa3bb Mon Sep 17 00:00:00 2001
From: Guillaume Pasquet <dev@etenil.net>
Date: Thu, 3 Mar 2022 23:18:08 +0000
Subject: Introduce JSONPath and potentially break old stuff.

---
 README.md | 44 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index c9d9e41..5af2e03 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,20 @@ BARB
 
 Barb is a file-based API query tool that works nicely with version control and fits into UNIX terminal usage.
 
+## Installation
+
+Barb is only available through `Cargo` at this time. To install the default version with JSONPath only, [install rust with rustup](https://rustup.rs).do like so:
+
+```
+cargo install barb
+```
+
+If you'd like to have JQ filtering; ensure the `libjq` is installed on your machine, then run:
+
+```
+cargo install barb --features jq
+```
+
 ## Example usage
 
 ```
@@ -19,6 +33,8 @@ barb [options] <file 1> <file 2> ... <file n>
 - `-r, --raw`: Don't format the response body
 - `-V, --version`: Print the software version
 - `-n, --no-color`: Don't use color output
+- `-f, --filter`: A JSON path to override any filters defined in the barb file
+- `--help`: Displays the help page
 
 ## Barb format
 
@@ -27,7 +43,7 @@ Barb uses a custom file format to perform requests. Each file contains _one_ req
 ```
 #POST^http://my-blog.com/posts
 #Authorization: TOKEN {API_TOKEN}
-#|jq.filter
+#$$.filter
 
 {
     "title": "A post",
@@ -70,6 +86,26 @@ There can be none or many headers.
 
 ### Filter
 
+Barb supports [JSONPath](https://goessner.net/articles/JsonPath/) filtering by default, and optionally JQ.
+
+#### JSONPath
+
+Barb supports filtering of the response body with JSONPath. This has the following format:
+
+```
+#$<JSON path>
+```
+
+The `PATH` supports variable substitution. Refer to the [JSONPath](https://goessner.net/articles/JsonPath/) for more information on the filters and their syntax.
+
+Filters can be named to populate execution variables by extracting values. Consider the following that will set the value of variable FOOBAR:
+
+```
+#FOOBAR$<JSON path>
+```
+
+#### JQ
+
 Barb supports JQ filtering of the response body. This has the following format:
 
 ```
@@ -78,6 +114,12 @@ Barb supports JQ filtering of the response body. This has the following format:
 
 The `JQ FILTER` supports variable substitution. Refer to the [JQ manual](https://stedolan.github.io/jq/manual/#Basicfilters) for more information on the filters and their syntax.
 
+Filters can be named to populate execution variables by extracting values. Consider the following that will set the value of variable FOOBAR:
+
+```
+#FOOBAR|<JQ FILTER>
+```
+
 ### Body
 
 Anything after the preamble is considered as a body and will be send in the request for the following methods:
-- 
cgit v1.2.3