From e8992654a064d128d8f58d18743fb7aca751c63f Mon Sep 17 00:00:00 2001
From: David Sherret <dsherret@gmail.com>
Date: Sun, 28 Jan 2024 18:47:59 -0500
Subject: [PATCH] docs: update for 0.38

---
 README.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 mod.ts    | 11 +++++----
 2 files changed, 74 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 281b7c7..a3cb81a 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,7 @@ Cross platform shell tools for Deno inspired by [zx](https://github.com/google/z
    - Makes more code work on Windows.
    - Allows exporting the shell's environment to the current process.
    - Uses [deno_task_shell](https://github.com/denoland/deno_task_shell)'s parser.
+   - Has common commands built-in for better Windows support.
 1. Minimal globals or global configuration.
    - Only a default instance of `$`, but it's not mandatory to use this.
 1. No custom CLI.
@@ -27,8 +28,8 @@ import $ from "https://deno.land/x/dax/mod.ts";
 // run a command
 await $`echo 5`; // outputs: 5
 
-// more complex example outputting 1 to stdout and 2 to stderr
-await $`echo 1 && deno eval 'console.error(2);'`;
+// outputting 1 to stdout and running a sub process
+await $`echo 1 && deno run main.ts`;
 
 // parallel
 await Promise.all([
@@ -57,8 +58,8 @@ console.log(result.prop); // 5
 Get the result of stdout as bytes (makes stdout "quiet"):
 
 ```ts
-const result = await $`echo 'test'`.bytes();
-console.log(result); // Uint8Array(5) [ 116, 101, 115, 116, 10 ]
+const bytes = await $`gzip < file.txt`.bytes();
+console.log(bytes);
 ```
 
 Get the result of stdout as a list of lines (makes stdout "quiet"):
@@ -106,12 +107,31 @@ Piping to a `WritableStream`:
 await $`echo 1`.stdout(Deno.stderr.writable, { preventClose: true });
 ```
 
-Or to a file:
+To a file path:
 
 ```ts
 await $`echo 1`.stdout($.path("data.txt"));
 ```
 
+To a file:
+
+```ts
+using file = $.path("data.txt").openSync({ write: true, create: true });
+await $`echo 1`.stdout(file);
+```
+
+From one command to another:
+
+```ts
+const output = await $`echo foo && echo bar`
+  .pipe($`grep foo`)
+  .text();
+
+// or using a pipe sequence
+const output = await $`echo foo && echo bar | grep foo`
+  .text();
+```
+
 ### Providing arguments to a command
 
 Use an expression in a template literal to provide a single argument to a command:
@@ -159,6 +179,19 @@ const finalText = await $`echo ${result}`.text();
 console.log(finalText); // 1
 ```
 
+You can also provide JavaScript objects to shell output redirects:
+
+```ts
+const buffer = new Uint8Array(2);
+await $`echo 1 && (echo 2 > ${buffer}) && echo 3`;
+console.log(buffer); // Uint8Array(2) [ 50, 10 ]
+```
+
+Or input redirects:
+
+```ts
+```
+
 ### Providing stdin
 
 ```ts
@@ -670,6 +703,17 @@ console.log(response.code);
 console.log(await response.json());
 ```
 
+Requests can be piped to commands:
+
+```ts
+const request = $.request("https://plugins.dprint.dev/info.json");
+await $`deno run main.ts`.stdin(request);
+
+// or as a redirect... this sleeps 5 seconds, then makes
+// request and redirects the output to the command
+await $`sleep 5 && deno run main.ts < ${request}`;
+```
+
 See the [documentation on `RequestBuilder`](https://deno.land/x/dax/src/request.ts?s=RequestBuilder) for more details. It should be as flexible as `fetch`, but uses a builder API (ex. set headers via `.header(...)`).
 
 ### Showing progress
@@ -703,6 +747,25 @@ await $`echo 1 && echo 2`;
 await $`echo 1 || echo 2`;
 ```
 
+Pipe sequences:
+
+```ts
+await $`echo 1 | deno run main.ts`;
+```
+
+Redirects:
+
+```ts
+await $`echo 1 > output.txt`;
+const gzippedBytes = await $`gzip < input.txt`.bytes();
+```
+
+Sub shells:
+
+```ts
+await $`(echo 1 && echo 2) > output.txt`;
+```
+
 Setting env var for command in the shell (generally you can just use `.env(...)` though):
 
 ```ts
diff --git a/mod.ts b/mod.ts
index ebd95f9..9d21aba 100644
--- a/mod.ts
+++ b/mod.ts
@@ -79,14 +79,15 @@ export type {
  *
  * Differences:
  *
- * 1. Minimal globals or global configuration.
- *    - Only a default instance of `$`, but it's not mandatory to use this.
- * 1. No custom CLI.
  * 1. Cross platform shell.
  *    - Makes more code work on Windows.
- *    - Uses [deno_task_shell](https://github.com/denoland/deno_task_shell)'s parser.
  *    - Allows exporting the shell's environment to the current process.
- * 1. Good for application code in addition to use as a shell script replacement
+ *    - Uses [deno_task_shell](https://github.com/denoland/deno_task_shell)'s parser.
+ *    - Has common commands built-in for better Windows support.
+ * 1. Minimal globals or global configuration.
+ *    - Only a default instance of `$`, but it's not mandatory to use this.
+ * 1. No custom CLI.
+ * 1. Good for application code in addition to use as a shell script replacement.
  * 1. Named after my cat.
  *
  * ## Example