Skip to content

Commit 260aa0a

Browse files
antongolubantongolub
authored
docs: sync docs with impl (#1025)
1 parent 80fc17a commit 260aa0a

File tree

2 files changed

+125
-5
lines changed

2 files changed

+125
-5
lines changed

‎docs/cli.md‎

Lines changed: 43 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,9 @@ Evaluate the following argument as a script.
4444
cat package.json | zx --eval 'const v = JSON.parse(await stdin()).version; echo(v)'
4545
```
4646

47+
## --repl
48+
Starts zx in [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) mode.
49+
4750
## --install
4851

4952
```js
@@ -67,6 +70,14 @@ the import.
6770
import sh from 'tinysh' // @^1
6871
```
6972

73+
## --registry
74+
75+
By default, `zx` uses `https://registry.npmjs.org` as a registry. Customize if needed.
76+
77+
```bash
78+
zx --registry=https://registry.yarnpkg.com script.mjs
79+
```
80+
7081
## --quiet
7182

7283
Suppress any outputs.
@@ -83,6 +94,14 @@ Specify a custom shell binary.
8394
zx --shell=/bin/bash script.mjs
8495
```
8596

97+
## --prefer-local, -l
98+
99+
Prefer locally installed packages bins.
100+
101+
```bash
102+
zx --shell=/bin/bash script.mjs
103+
```
104+
86105
## --prefix & --postfix
87106

88107
Attach a command to the beginning or the end of every command.
@@ -99,13 +118,33 @@ Set the current working directory.
99118
zx --cwd=/foo/bar script.mjs
100119
```
101120

102-
## --version
121+
## --ext
122+
123+
Override the default (temp) script extension. Default is `.mjs`.
124+
125+
## --version, -v
126+
127+
Print the current `zx` version.
103128

104-
Print the current version of `zx`.
129+
## --help, -h
105130

106-
## --help
131+
Print help notes.
107132

108-
Print help.
133+
## Environment variables
134+
All the previously mentioned options can be set via the corresponding `ZX_`-prefixed environment variables.
135+
136+
```bash
137+
ZX_VERBOSE=true ZX_SHELL='/bin/bash' zx script.mjs
138+
```
139+
140+
```yaml
141+
steps:
142+
- name: Run script
143+
run: zx script.mjs
144+
env:
145+
ZX_VERBOSE: true
146+
ZX_SHELL: '/bin/bash'
147+
```
109148
110149
## __filename & __dirname
111150

‎docs/process-promise.md‎

Lines changed: 82 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ await $`echo '{"foo": "bar"}'`.json() // {foo: 'bar'}
6161

6262
## `pipe()`
6363

64-
Redirects the stdout of the process.
64+
Redirects the output of the process.
6565

6666
```js
6767
await $`echo "Hello, stdout!"`
@@ -70,20 +70,43 @@ await $`echo "Hello, stdout!"`
7070
await $`cat /tmp/output.txt`
7171
```
7272

73+
`pipe()` accepts any kind `Writable`, `ProcessPromise` or a file path.
7374
You can pass a string to `pipe()` to implicitly create a receiving file. The previous example is equivalent to:
7475

7576
```js
7677
await $`echo "Hello, stdout!"`
7778
.pipe('/tmp/output.txt')
7879
```
7980

81+
Chained streams becomes _thenables_, so you can `await` them:
82+
83+
```js
84+
const p = $`echo "hello"`
85+
.pipe(getUpperCaseTransform())
86+
.pipe(fs.createWriteStream(tempfile())) // <- stream
87+
const o = await p
88+
```
89+
8090
Pipes can be used to show a real-time output of the process:
8191

8292
```js
8393
await $`echo 1; sleep 1; echo 2; sleep 1; echo 3;`
8494
.pipe(process.stdout)
8595
```
8696

97+
And the time machine is in stock! You can pipe the process at any phase: on start, in the middle, or even after the end. All chunks will be buffered and processed in the right order.
98+
99+
```js
100+
const result = $`echo 1; sleep 1; echo 2; sleep 1; echo 3`
101+
const piped1 = result.pipe`cat`
102+
let piped2
103+
104+
setTimeout(() => { piped2 = result.pipe`cat` }, 1500)
105+
106+
(await piped1).toString() // '1\n2\n3\n'
107+
(await piped2).toString() // '1\n2\n3\n'
108+
```
109+
87110
The `pipe()` method can combine `$` processes. Same as `|` in bash:
88111

89112
```js
@@ -102,6 +125,64 @@ await $`find ./examples -type f -print0`
102125
.pipe($`wc -l`)
103126
```
104127

128+
And literals! Pipe does support them too:
129+
130+
```js
131+
await $`printf "hello"`
132+
.pipe`awk '{printf $1", world!"}'`
133+
.pipe`tr '[a-z]' '[A-Z]'`
134+
```
135+
136+
By default, `pipe()` API operates with `stdout` stream, but you can specify `stderr` as well:
137+
138+
```js
139+
const p = $`echo foo >&2; echo bar`
140+
const o1 = (await p.pipe.stderr`cat`).toString() // 'foo\n'
141+
const o2 = (await p.pipe.stdout`cat`).toString() // 'bar\n'
142+
```
143+
144+
Btw, the signal, if specified, will be transmitted through pipeline.
145+
146+
```js
147+
const ac = new AbortController()
148+
const { signal } = ac
149+
const p = $({ signal, nothrow: true })`echo test`.pipe`sleep 999`
150+
setTimeout(() => ac.abort(), 50)
151+
152+
try {
153+
await p
154+
} catch ({ message }) {
155+
message // The operation was aborted
156+
}
157+
```
158+
159+
In short, combine anything you want:
160+
161+
```js
162+
const getUpperCaseTransform = () => new Transform({
163+
transform(chunk, encoding, callback) {
164+
callback(null, String(chunk).toUpperCase())
165+
},
166+
})
167+
168+
// $ > stream (promisified) > $
169+
const o1 = await $`echo "hello"`
170+
.pipe(getUpperCaseTransform())
171+
.pipe($`cat`)
172+
173+
o1.stdout // 'HELLO\n'
174+
175+
// stream > $
176+
const file = tempfile()
177+
await fs.writeFile(file, 'test')
178+
const o2 = await fs
179+
.createReadStream(file)
180+
.pipe(getUpperCaseTransform())
181+
.pipe($`cat`)
182+
183+
o2.stdout // 'TEST'
184+
```
185+
105186
## `kill()`
106187

107188
Kills the process and all children.

0 commit comments

Comments
 (0)