2021-06-04 15:47:16 +00:00
|
|
|
---
|
|
|
|
title: preserves-tool
|
|
|
|
---
|
|
|
|
|
2021-09-02 11:46:49 +00:00
|
|
|
The `preserves-tool` program is a swiss army knife for working with
|
|
|
|
Preserves documents.
|
2021-06-04 15:47:16 +00:00
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
```
|
|
|
|
preserves-tool 4.992.0
|
|
|
|
Swiss-army knife tool for working with Preserves data.
|
|
|
|
See https://preserves.dev/. If no subcommand is specified, the default
|
|
|
|
subcommand will be `convert`.
|
2021-09-02 11:46:49 +00:00
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
USAGE:
|
|
|
|
preserves-tool [OPTIONS]
|
|
|
|
preserves-tool <SUBCOMMAND>
|
2021-09-02 11:46:49 +00:00
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
OPTIONS:
|
|
|
|
-h, --help Print help information
|
|
|
|
-V, --version Print version information
|
2021-09-02 11:46:49 +00:00
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
OPTIONS FOR DEFAULT SUBCOMMAND convert:
|
|
|
|
[...]
|
|
|
|
|
|
|
|
SUBCOMMANDS:
|
|
|
|
completions
|
|
|
|
convert
|
|
|
|
help Print this message or the help of the given subcommand(s)
|
|
|
|
quote
|
|
|
|
```
|
2021-06-04 15:47:16 +00:00
|
|
|
|
|
|
|
## Installation
|
|
|
|
|
2021-09-02 11:46:49 +00:00
|
|
|
The tool is
|
|
|
|
[written in Rust](https://crates.io/crates/preserves-tools).
|
|
|
|
[Install `cargo`.](https://doc.rust-lang.org/cargo/getting-started/installation.html)
|
|
|
|
Then, `cargo install preserves-tools`.
|
|
|
|
|
|
|
|
## Subcommands
|
|
|
|
|
|
|
|
The tool includes three subcommands.
|
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
### `preserves-tool convert`, `preserves-tool`
|
2021-09-02 11:46:49 +00:00
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
This is the main tool, and is also the default if no subcommand is
|
|
|
|
explicitly specified. It can
|
2021-09-02 11:46:49 +00:00
|
|
|
|
|
|
|
- translate between the various Preserves text and binary document
|
|
|
|
syntaxes;
|
|
|
|
- strip annotations;
|
|
|
|
- pretty-print; and
|
2022-05-24 11:32:54 +00:00
|
|
|
- break down and filter documents using [preserves path](..{% link preserves-path.md %}) selectors.
|
2021-09-02 11:46:49 +00:00
|
|
|
|
|
|
|
#### Usage
|
|
|
|
|
|
|
|
preserves-tool-convert
|
|
|
|
|
|
|
|
USAGE:
|
|
|
|
preserves-tool convert [FLAGS] [OPTIONS]
|
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
OPTIONS:
|
|
|
|
--bundle <filename>
|
|
|
|
|
|
|
|
|
|
|
|
-c, --commas <COMMAS>
|
|
|
|
[default: none] [possible values: none, separating, terminating]
|
|
|
|
|
2021-09-02 11:46:49 +00:00
|
|
|
--collect
|
2023-11-03 12:07:05 +00:00
|
|
|
|
|
|
|
|
2021-09-02 11:46:49 +00:00
|
|
|
--escape-spaces
|
|
|
|
|
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
-h, --help
|
|
|
|
Print help information
|
2021-09-02 11:46:49 +00:00
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
-i, --input-format <INPUT_FORMAT>
|
2022-06-08 14:12:51 +00:00
|
|
|
[default: auto-detect] [possible values: auto-detect, text, binary]
|
2021-09-02 11:46:49 +00:00
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
--indent <on/off>
|
|
|
|
[default: on] [possible values: disabled, enabled]
|
|
|
|
|
|
|
|
--limit <LIMIT>
|
|
|
|
|
|
|
|
|
|
|
|
-o, --output-format <OUTPUT_FORMAT>
|
2021-09-02 11:46:49 +00:00
|
|
|
[default: text] [possible values: text, binary, unquoted]
|
2023-11-03 12:07:05 +00:00
|
|
|
|
2021-09-30 10:41:29 +00:00
|
|
|
--read-annotations <on/off>
|
2023-11-03 12:07:05 +00:00
|
|
|
[default: on] [possible values: disabled, enabled]
|
|
|
|
|
|
|
|
--select <SELECT_EXPR>
|
|
|
|
[default: *]
|
2021-09-30 10:41:29 +00:00
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
--select-output <SELECT_OUTPUT>
|
2021-09-02 11:46:49 +00:00
|
|
|
[default: sequence] [possible values: sequence, set]
|
2023-11-03 12:07:05 +00:00
|
|
|
|
2021-09-30 10:41:29 +00:00
|
|
|
--write-annotations <on/off>
|
2023-11-03 12:07:05 +00:00
|
|
|
[default: on] [possible values: disabled, enabled]
|
2021-09-30 10:41:29 +00:00
|
|
|
|
2021-09-02 11:46:49 +00:00
|
|
|
### `preserves-tool quote`
|
|
|
|
|
|
|
|
This subcommand reads chunks from standard input and outputs each one
|
|
|
|
as a Preserves `String`, `Symbol`, or `ByteString` using either the
|
|
|
|
text or binary Preserves surface syntax.
|
|
|
|
|
|
|
|
This is useful when writing shell scripts that interact with other
|
|
|
|
programs using Preserves as an interchange format.
|
|
|
|
|
|
|
|
It defaults to taking the entirety of standard input as a single large
|
|
|
|
chunk, but it can also work with newline- or `nul`-delimited chunks.
|
|
|
|
|
|
|
|
#### Usage
|
|
|
|
|
|
|
|
```
|
|
|
|
preserves-tool-quote
|
|
|
|
|
|
|
|
USAGE:
|
|
|
|
preserves-tool quote [OPTIONS] <SUBCOMMAND>
|
|
|
|
|
|
|
|
OPTIONS:
|
2023-11-03 12:07:05 +00:00
|
|
|
-h, --help Print help information
|
|
|
|
-o, --output-format <OUTPUT_FORMAT> [default: text] [possible values: text,
|
|
|
|
binary, unquoted]
|
2021-09-02 11:46:49 +00:00
|
|
|
|
|
|
|
SUBCOMMANDS:
|
|
|
|
byte-string
|
|
|
|
help Print this message or the help of the given subcommand(s)
|
|
|
|
string
|
|
|
|
symbol
|
|
|
|
```
|
|
|
|
|
|
|
|
```
|
|
|
|
preserves-tool-quote-string
|
|
|
|
|
|
|
|
USAGE:
|
2023-11-03 12:07:05 +00:00
|
|
|
preserves-tool quote string [OPTIONS]
|
2021-09-02 11:46:49 +00:00
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
OPTIONS:
|
2021-09-02 11:46:49 +00:00
|
|
|
--escape-spaces
|
2023-11-03 12:07:05 +00:00
|
|
|
-h, --help Print help information
|
2021-09-02 11:46:49 +00:00
|
|
|
--include-terminator
|
2023-11-03 12:07:05 +00:00
|
|
|
--input-terminator <INPUT_TERMINATOR> [default: eof] [possible values:
|
|
|
|
eof, newline, nul]
|
2021-09-02 11:46:49 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
```
|
|
|
|
preserves-tool-quote-symbol
|
|
|
|
|
|
|
|
USAGE:
|
2023-11-03 12:07:05 +00:00
|
|
|
preserves-tool quote symbol [OPTIONS]
|
2021-09-02 11:46:49 +00:00
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
OPTIONS:
|
2021-09-02 11:46:49 +00:00
|
|
|
--escape-spaces
|
2023-11-03 12:07:05 +00:00
|
|
|
-h, --help Print help information
|
2021-09-02 11:46:49 +00:00
|
|
|
--include-terminator
|
2023-11-03 12:07:05 +00:00
|
|
|
--input-terminator <INPUT_TERMINATOR> [default: eof] [possible values:
|
|
|
|
eof, newline, nul]
|
2021-09-02 11:46:49 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
```
|
|
|
|
preserves-tool-quote-byte-string
|
|
|
|
|
|
|
|
USAGE:
|
|
|
|
preserves-tool quote byte-string
|
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
OPTIONS:
|
|
|
|
-h, --help Print help information
|
2021-09-02 11:46:49 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### `preserves-tool completions`
|
|
|
|
|
|
|
|
This subcommand outputs Bash completion code to stdout, for sourcing
|
|
|
|
at shell startup time.
|
|
|
|
|
|
|
|
#### Usage
|
|
|
|
|
|
|
|
Add the following to your `.profile` or similar:
|
|
|
|
|
|
|
|
eval "$(preserves-tool completions bash 2>/dev/null)"
|
|
|
|
|
|
|
|
Multiple shell dialects are supported (courtesy of
|
|
|
|
[`clap`](https://crates.io/crates/clap)):
|
|
|
|
|
|
|
|
```
|
|
|
|
preserves-tool-completions
|
|
|
|
|
|
|
|
USAGE:
|
2023-11-03 12:07:05 +00:00
|
|
|
preserves-tool completions <SHELL>
|
2021-09-02 11:46:49 +00:00
|
|
|
|
|
|
|
ARGS:
|
2023-11-03 12:07:05 +00:00
|
|
|
<SHELL> [possible values: bash, elvish, fish, powershell, zsh]
|
2021-09-02 11:46:49 +00:00
|
|
|
|
2023-11-03 12:07:05 +00:00
|
|
|
OPTIONS:
|
|
|
|
-h, --help Print help information
|
2021-09-02 11:46:49 +00:00
|
|
|
```
|