Skip to content

Commit

Permalink
docs: update readme (#84)
Browse files Browse the repository at this point in the history
  • Loading branch information
@c4spar
c4spar authored Jul 11, 2022
1 parent 7a216e6 commit 0082131
Showing 1 changed file with 135 additions and 72 deletions.
207 changes: 135 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,14 @@
</p>

```typescript
#!/usr/bin/env dzx
/// <reference path="https://deno.land/x/dzx@0.3.1/types.d.ts" />
import {
$,
asny,
cd,
fs,
io,
path,
} from "https://deno.land/x/dzx@0.3.2/mod.ts";

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

// Print command output to stdout. Will be reverted to "piped" after all async ops are done.
// Print command output to stdout and stderr.
$.stdout = "inherit";
$.stderr = "inherit";

await Promise.all([
$`deno lint`,
$`deno fmt --check`,
Expand All @@ -66,89 +73,90 @@ await fs.ensureDir("./tmp");
- [Install](#install)
- [Usage](#usage)
- [Permissions](#permissions)
- [Worker](#worker)
- [Markdown](#markdown)
- [Methods](#methods)
- [Modules](#modules)
- [Variables](#variables)
- [Experimental](#experimental)
- [Worker](#worker)
- [CLI](#cli)
- [Contributing](#contributing)
- [License](#license)

## Install

```
deno install --allow-all --unstable -f https://deno.land/x/dzx@0.3.1/dzx.ts
deno install --allow-all --unstable -f https://deno.land/x/dzx@0.3.2/dzx.ts
```

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

To start writing a dzx script, add next shebang at the beginning of your script:
### Module usage

```
#!/usr/bin/env dzx
The default way is to just import the modules you need from the `dzx/mod.ts`
module. This doesn't inject any globals into your script.

```ts
import { $, cd, fs, io, log, path } from "https://deno.land/x/dzx@0.3.2/mod.ts";
```

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

```
#!/usr/bin/env dzx
/// <reference path="https://deno.land/x/dzx@0.3.1/types.d.ts" />
To avoid importing modules you can also import the `globals.ts` file. This makes
all exports from `mod.ts` globally available.

```ts
import from "https://deno.land/x/dzx@0.3.2/globals.ts";
```

or you can import all symbol directly from the `dzx/mod.ts` module instead of
using globals.
### CLI usage

```ts
When a dzx script is executed via CLI, you don't need to import anything. All
exports are automatically global available. This applies also to commands like
`dzx eval "console.log($)"`.

To start writing a dzx script, add next shebang at the beginning of your script:

```
#!/usr/bin/env dzx
import { $, cd, fs, io, log, path } from "https://deno.land/x/dzx@0.3.1/mod.ts";
```

After making your script executable,

```shell
chmod +x ./script.ts
chmod +x ./script.js
```

you can simply run it with:

```shell
./script.ts
./script.js
```

## Permissions

You can use `dzx` without installation by using next shebang. This also allows
you to explicitly set the permissions for your script.

```typescript
#!/usr/bin/env deno run --allow-run --allow-read --allow-env https://deno.land/x/dzx@0.3.1/dzx.ts
/// <reference path="https://deno.land/x/dzx@0.3.1/types.d.ts" />
To enable typescript support in your IDE, you can optionally add a tripple slash
reference to the top of the file.

console.log(`Hello ${$.blue.bold("world")}!`);
```
#!/usr/bin/env dzx
/// <reference path="https://deno.land/x/dzx@0.3.2/types.d.ts" />
```

## Worker

> This is currently an exerminental feature. Permission flags doens't support
> values currently. Read permissions are required by default.
### Permissions

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

```typescript
#!/usr/bin/env dzx --worker --allow-read
/// <reference path="https://deno.land/x/dzx@0.3.1/types.d.ts" />
#!/usr/bin/env deno run --allow-run --allow-read --allow-env https://deno.land/x/dzx@0.3.2/dzx.ts
/// <reference path="https://deno.land/x/dzx@0.3.2/types.d.ts" />

console.log(`Hello from ${$.blue.bold("worker")}!`);
console.log(`Hello ${$.blue.bold("world")}!`);
```

## Markdown
### Markdown

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

## Methods
### Methods

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

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

## Modules
### Process

Methods and properties of the `Process` class which implements
`Promise<ProcessOutput>` and is returned by the `$` method.

- `.pid`: Returns the process id of the executed command.

- `.noThrow`: If invoked the command doesn't throw an error if the command
returns a none-zero exit code.

- `.statusCode`: Returns the status code of the executed command and calls
`.noThrow` internally to catch the error and return the status code.

- `.stdout` Returns `Promise<string>` and resolves with the stdout output.

- `.stderr` Returns `Promise<string>` and resolves with the stderr output.

- `.retry(retries: number)` Retry the command `n` times if it fails.

- `.delay(delay: number)` Number of milliseconds to delay the retry of a failed
command. Default: `500`

- `.timeout(timeout: number)` Throws an error if the command takes longer than
the provided `timeout` in milliseconds.

- `.kill(signal: Deno.Signal)` Kills the running process.

### Modules

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

## Variables
### Variables

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

# CLI
## Experimental

### Worker

> This is currently an exerminental feature. Permission flags doesn't support
> values currently. Read permissions are required by default.

If `dzx` is called with `-w` or `--worker`, the script is executed inside an
isolated web worker. If enabled, you can pass explicit permissions directly to
the `dzx` cli.

```typescript
#!/usr/bin/env dzx --worker --allow-read
/// <reference path="https://deno.land/x/dzx@0.3.2/types.d.ts" />
console.log(`Hello from ${$.blue.bold("worker")}!`);
```

## CLI

```
Usage: dzx [script] [args...]
Version: 0.3.1

Description:

🦕 A custom deno runtime for fun.

Options:

-h, --help - Show this help.
-V, --version - Show the version number for this program.
-A, --allow-all - Allow all permissions. (Depends: --worker)
--allow-env - Allow environment access. (Depends: --worker)
--allow-hrtime - Allow high resolution time measurement. (Depends: --worker)
--allow-net - Allow network access. (Depends: --worker)
--allow-ffi - Allow loading dynamic libraries. (Depends: --worker)
--allow-read - Allow file system read access. (Depends: --worker)
--allow-run - Allow running subprocesses. (Depends: --worker)
--allow-write - Allow file system write access. (Depends: --worker)
-w, --worker - Run script in an isolated web worker with it's own permissions.

Commands:

bundle [script] - Bundle an dzx script to a standalone deno sript.
compile [compile-options...] [script] [script-options...] - Combile an dzx script to a standalone binary.
eval <code> - Evaluate a dzx script from the command line.
repl - Start a dzx repl.
upgrade - Upgrade dzx executable to latest or given version.
Usage: dzx [script] [args...]
Version: 0.3.1 (New version available: 0.3.2. Run 'dzx upgrade' to upgrade to the latest version!)

Description:

A custom deno runtime for fun.

Options:

-h, --help - Show this help.
-V, --version - Show the version number for this program.
-A, --allow-all - Allow all permissions. (Depends: --worker)
--allow-env - Allow environment access. (Depends: --worker)
--allow-hrtime - Allow high resolution time measurement. (Depends: --worker)
--allow-net - Allow network access. (Depends: --worker)
--allow-ffi - Allow loading dynamic libraries. (Depends: --worker)
--allow-read - Allow file system read access. (Depends: --worker)
--allow-run - Allow running subprocesses. (Depends: --worker)
--allow-write - Allow file system write access. (Depends: --worker)
--compat - Node compatibility mode. Currently only enables built-in node modules like 'fs'
and globals like 'process'.
--inspect <host> - Activate inspector on host:port. (default: 127.0.0.1:9229)
--inspect-brk <host> - Activate inspector on host:port and break at start of user script.
-w, --worker - Run script in an isolated web worker with it's own permissions. (experimental)
-v, --verbose - Enable verbose mode. This option can appear up to three times. (Default: 1)
-v: Print executed commands and script execution time.
-vv: Print also stdout and stderr.
-vvv: Print internal debug information.
--no-verbose - Disable stdout output.

Commands:

bundle [script] - Bundle a dzx script to a standalone deno script.
compile [script] - Compile a dzx script to a standalone binary.
eval [code] - Evaluate a dzx script from the command line.
repl - Start a dzx repl.
upgrade - Upgrade dzx executable to latest or given version.
```
- **dzx** `[script] [...args]`: Run a local or remote dzx script (optional in a
Expand Down

0 comments on commit 0082131

Please sign in to comment.