Add docs for command-based querying

LucasPickering · Jan 2, 2025 · 9f82df9 · 9f82df9
1 parent 6f0e524
commit 9f82df9
Show file tree

Hide file tree

Showing 16 changed files with 102 additions and 119 deletions.
diff --git a/README.md b/README.md
@@ -23,7 +23,7 @@ Slumber is a TUI (terminal user interface) HTTP client. Define, execute, and sha
 - Source-first configuration, for easy persistence and sharing
 - [Import from external formats (e.g. Insomnia)](https://slumber.lucaspickering.me/book/user_guide/import.html)
 - [Build requests dynamically from other requests, files, and shell commands](https://slumber.lucaspickering.me/book/user_guide/templates.html)
-- [Browse response data using JSONPath selectors](https://slumber.lucaspickering.me/book/user_guide/filter_query.html)
+- [Browse response data using JSONPath selectors](https://slumber.lucaspickering.me/book/user_guide/tui/filter_query.html)
 - Switch between different environments easily using [profiles](https://slumber.lucaspickering.me/book/api/request_collection/profile.html)
 - And more!
 

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -9,11 +9,11 @@
 - [Key Concepts](./user_guide/key_concepts.md)
 - [Terminal User Interface (TUI)](./user_guide/tui/index.md)
   - [In-App Editing & File Viewing](./user_guide/tui/editor.md)
+  - [Data Filtering & Querying](./user_guide/tui/filter_query.md)
 - [Command Line Interface (CLI)](./user_guide/cli.md)
 - [Templates](./user_guide/templates.md)
   - [Chains - Complex Template Values](./user_guide/chains.md)
 - [Collection Reuse & Inheritance](./user_guide/inheritance.md)
-- [Data Filtering & Querying](./user_guide/filter_query.md)
 - [Importing External Collections](./user_guide/import.md)
 
 # CLI Commands

diff --git a/docs/src/api/configuration/index.md b/docs/src/api/configuration/index.md
@@ -40,15 +40,15 @@ The following fields are available in `config.yml`:
 
 **Default:** `[sh, -c]` (Unix), `[cmd, /S, /C]` (Windows)
 
-Shell used to execute commands within the TUI. [More info](#commands)
+Shell used to execute commands within the TUI. Use `[]` for no shell (commands will be parsed and executed directly). [More info](../../user_guide/tui/filter_query.md)
 
 ### `commands.query_default`
 
 **Type:** `string`
 
 **Default:** `""`
 
-Default query command for all responses. [More info](#commands)
+Default query command for all responses. [More info](../../user_guide/tui/filter_query.md)
 
 ### `debug`
 

diff --git a/docs/src/api/request_collection/chain.md b/docs/src/api/request_collection/chain.md
@@ -6,6 +6,8 @@ To use a chain in a template, reference it as `{{chains.<id>}}`.
 
 ## Fields
 
+<!-- TODO update filter_query link -->
+
 | Field           | Type                                                                                   | Description                                                                                                                                                                                          | Default  |
 | --------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
 | `source`        | [`ChainSource`](./chain_source.md)                                                     | Source of the chained value                                                                                                                                                                          | Required |

diff --git a/docs/src/api/request_collection/content_type.md b/docs/src/api/request_collection/content_type.md
@@ -1,6 +1,6 @@
 # Content Type
 
-Content type defines the various data formats that Slumber recognizes and can manipulate. Slumber is capable of displaying any text-based data format, but only specific formats support additional features such as [querying](../../user_guide/filter_query.md) and formatting.
+Content type defines the various data formats that Slumber recognizes and can manipulate. Slumber is capable of displaying any text-based data format, but only specific formats support additional features such as [querying](../../user_guide/tui/filter_query.md) and formatting.
 
 ## Auto-detection
 

diff --git a/docs/src/images/query.gif b/docs/src/images/query.gif
diff --git a/docs/src/images/query_error.gif b/docs/src/images/query_error.gif
diff --git a/docs/src/images/query_jq.gif b/docs/src/images/query_jq.gif
diff --git a/docs/src/images/query_pipe.gif b/docs/src/images/query_pipe.gif
diff --git a/docs/src/user_guide/chains.md b/docs/src/user_guide/chains.md
@@ -1,5 +1,7 @@
 # Chains
 
+<!-- TODO split this up -->
+
 Chains are Slumber's most powerful feature. They allow you to dynamically build requests based on other responses, shell commands, and more.
 
 ## Chains in Practice
@@ -36,6 +38,7 @@ requests:
     authentication: !bearer "{{chains.auth_token}}"
 ```
 
+<!-- TODO update this link -->
 > For more info on the `selector` field, see [Data Filtering & Querying](./filter_query.md)
 
 ### Automatically Executing the Upstream Request

diff --git a/docs/src/user_guide/filter_query.md b/docs/src/user_guide/filter_query.md
diff --git a/docs/src/user_guide/tui/filter_query.md b/docs/src/user_guide/tui/filter_query.md
@@ -0,0 +1,32 @@
+# Data Filtering & Querying
+
+When browsing an HTTP response in Slumber, you may want to filter, query, or otherwise transform the response to make it easier to view. Slumber supports this via embedded shell commands. The query box at the bottom of the response pane allows you to execute any shell command, which will be passed the response body via stdin and its output will be shown in the response pane. You can use `grep`, `jq`, `sed`, or any other text processing tool.
+
+![Querying response via jq](../../images/query_jq.gif)
+
+_Example of querying with jq_
+
+![Querying response with pipes](../../images/query_pipe.gif)
+
+_Example of using pipes in a query command_
+
+## Side Effects
+
+Keep in mind that your queries are being executed as shell commands on your system. You should avoid running any commands that interact with the file system, such as using `>` or `<` to pipe to/from files. TODO add more about side-effect commands once implemented
+
+## Errors
+
+We can't all be perfect. Sometimes you run a command that fails. To view the error, press `?` (make sure you exit the text box first!).
+
+![View query error](../../images/query_error.gif)
+
+## Which shell does Slumber use?
+
+By default, Slumber executes your command via `sh -c` on Unix and `cmd /S /C` on Windows. You can customize this via the [`commands.shell` configuration field](../../api/configuration/index.md#commandsshell). For example, to use `fish` instead of `sh`:
+
+```yaml
+commands:
+  shell: [fish, -c]
+```
+
+If you don't want to execute via _any_ shell, you can set it to `[]`. In this case, query commands will be parsed via [shell-words](https://docs.rs/shell-words/latest/shell_words/) and executed directly. For example, `jq .args` will be parsed into `["jq", ".args"]`, then `jq` will be executed with a single argument: `.args`.
diff --git a/gifs.py b/gifs.py
@@ -35,18 +35,15 @@ def generate_all(tapes: list[str]) -> None:
         tapes = get_tapes()
     print(f"Generating GIFs for: {tapes}")
 
-    print("Deleting data/")
-    shutil.rmtree("data/")
-
     run(["cargo", "build"])
     for tape in tapes:
         generate(tape)
     print("Don't forget to check all GIFs before pushing!")
 
 
 def generate(tape: str) -> None:
-    gif = get_gif_path(tape)
-    print(f"Generating {tape} -> {gif}")
+    print("Deleting data/")
+    shutil.rmtree("data/")
     run(["vhs", tape])
 
 

diff --git a/tapes/query_error.tape b/tapes/query_error.tape
@@ -0,0 +1,29 @@
+Output "docs/src/images/query_error.gif"
+Set Shell bash
+Set Width 1200
+Set Height 800
+Set FontSize 18
+Set Framerate 24
+Set Margin 0
+Set Padding 10
+Set Theme "MaterialDark"
+
+Hide
+Type "cargo run"
+Enter
+Sleep 2s
+
+Enter # Send login request
+Type "hunter2"
+Enter
+Sleep 2s
+Type "rf" # Fullscreen response pane
+Show
+
+Type "/"
+Sleep 1s
+Type "jq error!"
+Enter
+Sleep 1s
+Type "?"
+Sleep 3s
diff --git a/tapes/query.tape → tapes/query_jq.tape b/tapes/query.tape → tapes/query_jq.tape
@@ -1,4 +1,4 @@
-Output "docs/src/images/query.gif"
+Output "docs/src/images/query_jq.gif"
 Set Shell bash
 Set Width 1200
 Set Height 800
@@ -12,6 +12,7 @@ Hide
 Type "cargo run"
 Enter
 Sleep 2s
+
 Enter # Send login request
 Type "hunter2"
 Enter
@@ -22,7 +23,7 @@ Show
 Sleep 1s
 Type "/"
 Sleep 1s
-Type "$.args"
+Type "jq .args"
 Sleep 2s
 Type ".fast"
 Sleep 2s
diff --git a/tapes/query_pipe.tape b/tapes/query_pipe.tape
@@ -0,0 +1,26 @@
+Output "docs/src/images/query_pipe.gif"
+Set Shell bash
+Set Width 1200
+Set Height 800
+Set FontSize 18
+Set Framerate 24
+Set Margin 0
+Set Padding 10
+Set Theme "MaterialDark"
+
+Hide
+Type "cargo run"
+Enter
+Sleep 2s
+
+Enter # Send login request
+Type "hunter2"
+Enter
+Sleep 2s
+Type "rf" # Fullscreen response pane
+Show
+
+Type "/"
+Sleep 1s
+Type "jq .args | head -n 3"
+Sleep 2s