Skip to content

Commit 0082131

Browse files
c4sparc4spar
authored
docs: update readme (#84)
1 parent 7a216e6 commit 0082131

File tree

1 file changed

+135
-72
lines changed

1 file changed

+135
-72
lines changed

‎README.md‎

Lines changed: 135 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,14 @@
2626
</p>
2727

2828
```typescript
29-
#!/usr/bin/env dzx
30-
/// <reference path="https://deno.land/x/[email protected]/types.d.ts" />
29+
import {
30+
$,
31+
asny,
32+
cd,
33+
fs,
34+
io,
35+
path,
36+
} from "https://deno.land/x/[email protected]/mod.ts";
3137

3238
$.verbose = true;
3339
$.shell = "/usr/local/bin/zsh";
@@ -37,9 +43,10 @@ console.log(`Hello from ${$.blue.bold("dzx")}!`);
3743
const branch = await $`git branch --show-current`;
3844
await $`dep deploy --branch=${branch}`;
3945

40-
// Print command output to stdout. Will be reverted to "piped" after all async ops are done.
46+
// Print command output to stdout and stderr.
4147
$.stdout = "inherit";
4248
$.stderr = "inherit";
49+
4350
await Promise.all([
4451
$`deno lint`,
4552
$`deno fmt --check`,
@@ -66,89 +73,90 @@ await fs.ensureDir("./tmp");
6673
- [Install](#install)
6774
- [Usage](#usage)
6875
- [Permissions](#permissions)
69-
- [Worker](#worker)
7076
- [Markdown](#markdown)
7177
- [Methods](#methods)
7278
- [Modules](#modules)
7379
- [Variables](#variables)
80+
- [Experimental](#experimental)
81+
- [Worker](#worker)
7482
- [CLI](#cli)
7583
- [Contributing](#contributing)
7684
- [License](#license)
7785

7886
## Install
7987

8088
```
81-
deno install --allow-all --unstable -f https://deno.land/x/[email protected].1/dzx.ts
89+
deno install --allow-all --unstable -f https://deno.land/x/[email protected].2/dzx.ts
8290
```
8391

8492
> `--unstable` is required for the `bundle` command which uses `Deno.emit`, for
8593
> `std/fs/copy` and for web workers.
8694
8795
## Usage
8896

89-
To start writing a dzx script, add next shebang at the beginning of your script:
97+
### Module usage
9098

91-
```
92-
#!/usr/bin/env dzx
99+
The default way is to just import the modules you need from the `dzx/mod.ts`
100+
module. This doesn't inject any globals into your script.
101+
102+
```ts
103+
import { $, cd, fs, io, log, path } from "https://deno.land/x/[email protected]/mod.ts";
93104
```
94105

95-
To enable typings for typescript in your IDE, you can add a tripple slash
96-
reference to the top of the file,
106+
### Globals usage
97107

98-
```
99-
#!/usr/bin/env dzx
100-
/// <reference path="https://deno.land/x/[email protected]/types.d.ts" />
108+
To avoid importing modules you can also import the `globals.ts` file. This makes
109+
all exports from `mod.ts` globally available.
110+
111+
```ts
112+
import from "https://deno.land/x/[email protected]/globals.ts";
101113
```
102114

103-
or you can import all symbol directly from the `dzx/mod.ts` module instead of
104-
using globals.
115+
### CLI usage
105116

106-
```ts
117+
When a dzx script is executed via CLI, you don't need to import anything. All
118+
exports are automatically global available. This applies also to commands like
119+
`dzx eval "console.log($)"`.
120+
121+
To start writing a dzx script, add next shebang at the beginning of your script:
122+
123+
```
107124
#!/usr/bin/env dzx
108-
import { $, cd, fs, io, log, path } from "https://deno.land/x/[email protected]/mod.ts";
109125
```
110126

111127
After making your script executable,
112128

113129
```shell
114-
chmod +x ./script.ts
130+
chmod +x ./script.js
115131
```
116132

117133
you can simply run it with:
118134

119135
```shell
120-
./script.ts
136+
./script.js
121137
```
122138

123-
## Permissions
124-
125-
You can use `dzx` without installation by using next shebang. This also allows
126-
you to explicitly set the permissions for your script.
127-
128-
```typescript
129-
#!/usr/bin/env deno run --allow-run --allow-read --allow-env https://deno.land/x/[email protected]/dzx.ts
130-
/// <reference path="https://deno.land/x/[email protected]/types.d.ts" />
139+
To enable typescript support in your IDE, you can optionally add a tripple slash
140+
reference to the top of the file.
131141

132-
console.log(`Hello ${$.blue.bold("world")}!`);
142+
```
143+
#!/usr/bin/env dzx
144+
/// <reference path="https://deno.land/x/[email protected]/types.d.ts" />
133145
```
134146

135-
## Worker
136-
137-
> This is currently an exerminental feature. Permission flags doens't support
138-
> values currently. Read permissions are required by default.
147+
### Permissions
139148

140-
If `dzx` is called with `-w` or `--worker`, the script is executed inside an
141-
isolated web worker. If enabled, you can pass explicit permissions directly to
142-
the `dzx` cli.
149+
You can use `dzx` without installation by using next shebang. This also allows
150+
you to explicitly set the permissions for your script.
143151

144152
```typescript
145-
#!/usr/bin/env dzx --worker --allow-read
146-
/// <reference path="https://deno.land/x/[email protected].1/types.d.ts" />
153+
#!/usr/bin/env deno run --allow-run --allow-read --allow-env https://deno.land/x/[email protected]/dzx.ts
154+
/// <reference path="https://deno.land/x/[email protected].2/types.d.ts" />
147155

148-
console.log(`Hello from ${$.blue.bold("worker")}!`);
156+
console.log(`Hello ${$.blue.bold("world")}!`);
149157
```
150158

151-
## Markdown
159+
### Markdown
152160

153161
With `dzx` you can run the `js`/`ts` code blocks from a Markdown file as if they
154162
were a regular script. This is very convenient when you want to blend some
@@ -163,9 +171,10 @@ dzx ./examples/markdown.md
163171
See the [markdown example](./examples/markdown.md) for further documentation and
164172
notes.
165173

166-
## Methods
174+
### Methods
167175

168-
- `` $`command` ``: Executes a shell command.
176+
- `` $`command` ``: Executes a shell command and returns a `Process` instance.
177+
The [`Process`](#process) class has several chainable methods.
169178

170179
```ts
171180
const count = parseInt(await $`ls -1 | wc -l`);
@@ -253,7 +262,34 @@ notes.
253262
- `` quote`string` ``: The quote methods quotes safly a string. by default the
254263
`shq` package is used. Can be overidden with `$.quote`.
255264

256-
## Modules
265+
### Process
266+
267+
Methods and properties of the `Process` class which implements
268+
`Promise<ProcessOutput>` and is returned by the `$` method.
269+
270+
- `.pid`: Returns the process id of the executed command.
271+
272+
- `.noThrow`: If invoked the command doesn't throw an error if the command
273+
returns a none-zero exit code.
274+
275+
- `.statusCode`: Returns the status code of the executed command and calls
276+
`.noThrow` internally to catch the error and return the status code.
277+
278+
- `.stdout` Returns `Promise<string>` and resolves with the stdout output.
279+
280+
- `.stderr` Returns `Promise<string>` and resolves with the stderr output.
281+
282+
- `.retry(retries: number)` Retry the command `n` times if it fails.
283+
284+
- `.delay(delay: number)` Number of milliseconds to delay the retry of a failed
285+
command. Default: `500`
286+
287+
- `.timeout(timeout: number)` Throws an error if the command takes longer than
288+
the provided `timeout` in milliseconds.
289+
290+
- `.kill(signal: Deno.Signal)` Kills the running process.
291+
292+
### Modules
257293

258294
- **$.\[style]:** Cliffy's color module. A chainable wrapper for Deno's
259295
`std/fmt/colors` module. Available on the global `$` symbol.
@@ -309,7 +345,7 @@ notes.
309345
const args: flags.Args = flags.parse($.args);
310346
```
311347

312-
## Variables
348+
### Variables
313349

314350
- **$.shell:** Set the shell that is used by `` $`command` ``. Default:
315351
`/bin/bash`
@@ -328,37 +364,64 @@ notes.
328364
- **$.quote:** Parser method that is used to safely quote strings. Used by:
329365
`` $`command` ``
330366

331-
# CLI
367+
## Experimental
368+
369+
### Worker
370+
371+
> This is currently an exerminental feature. Permission flags doesn't support
372+
> values currently. Read permissions are required by default.
373+
374+
If `dzx` is called with `-w` or `--worker`, the script is executed inside an
375+
isolated web worker. If enabled, you can pass explicit permissions directly to
376+
the `dzx` cli.
377+
378+
```typescript
379+
#!/usr/bin/env dzx --worker --allow-read
380+
/// <reference path="https://deno.land/x/[email protected]/types.d.ts" />
381+
382+
console.log(`Hello from ${$.blue.bold("worker")}!`);
383+
```
384+
385+
## CLI
332386

333387
```
334-
Usage: dzx [script] [args...]
335-
Version: 0.3.1
336-
337-
Description:
338-
339-
🦕 A custom deno runtime for fun.
340-
341-
Options:
342-
343-
-h, --help - Show this help.
344-
-V, --version - Show the version number for this program.
345-
-A, --allow-all - Allow all permissions. (Depends: --worker)
346-
--allow-env - Allow environment access. (Depends: --worker)
347-
--allow-hrtime - Allow high resolution time measurement. (Depends: --worker)
348-
--allow-net - Allow network access. (Depends: --worker)
349-
--allow-ffi - Allow loading dynamic libraries. (Depends: --worker)
350-
--allow-read - Allow file system read access. (Depends: --worker)
351-
--allow-run - Allow running subprocesses. (Depends: --worker)
352-
--allow-write - Allow file system write access. (Depends: --worker)
353-
-w, --worker - Run script in an isolated web worker with it's own permissions.
354-
355-
Commands:
356-
357-
bundle [script] - Bundle an dzx script to a standalone deno sript.
358-
compile [compile-options...] [script] [script-options...] - Combile an dzx script to a standalone binary.
359-
eval <code> - Evaluate a dzx script from the command line.
360-
repl - Start a dzx repl.
361-
upgrade - Upgrade dzx executable to latest or given version.
388+
Usage: dzx [script] [args...]
389+
Version: 0.3.1 (New version available: 0.3.2. Run 'dzx upgrade' to upgrade to the latest version!)
390+
391+
Description:
392+
393+
A custom deno runtime for fun.
394+
395+
Options:
396+
397+
-h, --help - Show this help.
398+
-V, --version - Show the version number for this program.
399+
-A, --allow-all - Allow all permissions. (Depends: --worker)
400+
--allow-env - Allow environment access. (Depends: --worker)
401+
--allow-hrtime - Allow high resolution time measurement. (Depends: --worker)
402+
--allow-net - Allow network access. (Depends: --worker)
403+
--allow-ffi - Allow loading dynamic libraries. (Depends: --worker)
404+
--allow-read - Allow file system read access. (Depends: --worker)
405+
--allow-run - Allow running subprocesses. (Depends: --worker)
406+
--allow-write - Allow file system write access. (Depends: --worker)
407+
--compat - Node compatibility mode. Currently only enables built-in node modules like 'fs'
408+
and globals like 'process'.
409+
--inspect <host> - Activate inspector on host:port. (default: 127.0.0.1:9229)
410+
--inspect-brk <host> - Activate inspector on host:port and break at start of user script.
411+
-w, --worker - Run script in an isolated web worker with it's own permissions. (experimental)
412+
-v, --verbose - Enable verbose mode. This option can appear up to three times. (Default: 1)
413+
-v: Print executed commands and script execution time.
414+
-vv: Print also stdout and stderr.
415+
-vvv: Print internal debug information.
416+
--no-verbose - Disable stdout output.
417+
418+
Commands:
419+
420+
bundle [script] - Bundle a dzx script to a standalone deno script.
421+
compile [script] - Compile a dzx script to a standalone binary.
422+
eval [code] - Evaluate a dzx script from the command line.
423+
repl - Start a dzx repl.
424+
upgrade - Upgrade dzx executable to latest or given version.
362425
```
363426

364427
- **dzx** `[script] [...args]`: Run a local or remote dzx script (optional in a

0 commit comments

Comments
 (0)