preserves/doc/preserves-tool.md

title
preserves-tool

The preserves-tool program is a swiss army knife for working with Preserves documents.

preserves-tools 1.0.0

USAGE:
    preserves-tool <SUBCOMMAND>

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

SUBCOMMANDS:
    completions
    convert
    help           Print this message or the help of the given subcommand(s)
    quote

Installation

The tool is written in Rust. Install cargo. Then, cargo install preserves-tools.

Subcommands

The tool includes three subcommands.

preserves-tool convert

This is the main tool. It can

• translate between the various Preserves text and binary document syntaxes;
• strip annotations;
• pretty-print; and
• break down and filter documents using [preserves path]({{ site.baseurl }}{% link preserves-path.md %}) selectors.

Usage

preserves-tool-convert

USAGE:
    preserves-tool convert [FLAGS] [OPTIONS]

FLAGS:
        --collect
        --escape-spaces
    -h, --help             Print help information
    -V, --version          Print version information

OPTIONS:
    -i, --input-format <INPUT_FORMAT>
            [default: auto-detect] [possible values: auto-detect, text, binary]

        --indent <on/off>
            [default: on] [possible values: disabled, no, n, off, 0, false,
            enabled, yes, y, on, 1, true]

        --limit <LIMIT>


    -o, --output-format <OUTPUT_FORMAT>
            [default: text] [possible values: text, binary, unquoted]

        --read-annotations <on/off>
            [default: on] [possible values: disabled, no, n, off, 0, false,
            enabled, yes, y, on, 1, true]

        --select <SELECT>
            [default: *]

        --select-output <SELECT_OUTPUT>
            [default: sequence] [possible values: sequence, set]

        --write-annotations <on/off>
            [default: on] [possible values: disabled, no, n, off, 0, false,
            enabled, yes, y, on, 1, true]

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>

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

OPTIONS:
    -o, --output-format <OUTPUT_FORMAT>    [default: text] [possible values: text, binary, unquoted]

SUBCOMMANDS:
    byte-string
    help           Print this message or the help of the given subcommand(s)
    string
    symbol

preserves-tool-quote-string

USAGE:
    preserves-tool quote string [FLAGS] [OPTIONS]

FLAGS:
        --escape-spaces
    -h, --help                  Print help information
        --include-terminator
    -V, --version               Print version information

OPTIONS:
        --input-terminator <INPUT_TERMINATOR>    [default: eof] [possible values: eof, newline, nul]

preserves-tool-quote-symbol

USAGE:
    preserves-tool quote symbol [FLAGS] [OPTIONS]

FLAGS:
        --escape-spaces
    -h, --help                  Print help information
        --include-terminator
    -V, --version               Print version information

OPTIONS:
        --input-terminator <INPUT_TERMINATOR>    [default: eof] [possible values: eof, newline, nul]

preserves-tool-quote-byte-string

USAGE:
    preserves-tool quote byte-string

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

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):

preserves-tool-completions

USAGE:
    preserves-tool completions <dialect>

ARGS:
    <dialect>    [possible values: bash, zsh, power-shell, fish, elvish]

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information