diff --git a/doc/preserves-tool.md b/doc/preserves-tool.md index f9f6f61..b6413ad 100644 --- a/doc/preserves-tool.md +++ b/doc/preserves-tool.md @@ -5,20 +5,29 @@ title: preserves-tool The `preserves-tool` program is a swiss army knife for working with Preserves documents. - preserves-tools 1.0.0 +``` +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`. - USAGE: - preserves-tool +USAGE: + preserves-tool [OPTIONS] + preserves-tool - FLAGS: - -h, --help Print help information - -V, --version Print version information +OPTIONS: + -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 +OPTIONS FOR DEFAULT SUBCOMMAND convert: + [...] + +SUBCOMMANDS: + completions + convert + help Print this message or the help of the given subcommand(s) + quote +``` ## Installation @@ -31,9 +40,10 @@ Then, `cargo install preserves-tools`. The tool includes three subcommands. -### `preserves-tool convert` +### `preserves-tool convert`, `preserves-tool` -This is the main tool. It can +This is the main tool, and is also the default if no subcommand is +explicitly specified. It can - translate between the various Preserves text and binary document syntaxes; @@ -48,38 +58,45 @@ This is the main tool. It can USAGE: preserves-tool convert [FLAGS] [OPTIONS] - FLAGS: - --collect - --escape-spaces - -h, --help Prints help information - -V, --version Prints version information - OPTIONS: - --bundle ... - -c, --commas + --bundle + + + -c, --commas [default: none] [possible values: none, separating, terminating] - --indent - [default: on] [possible values: disabled, no, n, off, 0, false, - enabled, yes, y, on, 1, true] + --collect - -i, --input-format + + --escape-spaces + + + -h, --help + Print help information + + -i, --input-format [default: auto-detect] [possible values: auto-detect, text, binary] - --limit - -o, --output-format - [default: text] [possible values: text, binary, unquoted] - --read-annotations - [default: on] [possible values: disabled, no, n, off, 0, false, - enabled, yes, y, on, 1, true] + --indent + [default: on] [possible values: disabled, enabled] - --schema - --select [default: *] - --select-output + --limit + + + -o, --output-format + [default: text] [possible values: text, binary, unquoted] + + --read-annotations + [default: on] [possible values: disabled, enabled] + + --select + [default: *] + + --select-output [default: sequence] [possible values: sequence, set] + --write-annotations - [default: on] [possible values: disabled, no, n, off, 0, false, - enabled, yes, y, on, 1, true] + [default: on] [possible values: disabled, enabled] ### `preserves-tool quote` @@ -101,12 +118,10 @@ preserves-tool-quote USAGE: preserves-tool quote [OPTIONS] -FLAGS: - -h, --help Print help information - -V, --version Print version information - OPTIONS: - -o, --output-format [default: text] [possible values: text, binary, unquoted] + -h, --help Print help information + -o, --output-format [default: text] [possible values: text, + binary, unquoted] SUBCOMMANDS: byte-string @@ -119,32 +134,28 @@ SUBCOMMANDS: 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 + preserves-tool quote string [OPTIONS] OPTIONS: - --input-terminator [default: eof] [possible values: eof, newline, nul] + --escape-spaces + -h, --help Print help information + --include-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 + preserves-tool quote symbol [OPTIONS] OPTIONS: - --input-terminator [default: eof] [possible values: eof, newline, nul] + --escape-spaces + -h, --help Print help information + --include-terminator + --input-terminator [default: eof] [possible values: + eof, newline, nul] ``` ``` @@ -153,9 +164,8 @@ preserves-tool-quote-byte-string USAGE: preserves-tool quote byte-string -FLAGS: - -h, --help Print help information - -V, --version Print version information +OPTIONS: + -h, --help Print help information ``` ### `preserves-tool completions` @@ -176,12 +186,11 @@ Multiple shell dialects are supported (courtesy of preserves-tool-completions USAGE: - preserves-tool completions + preserves-tool completions ARGS: - [possible values: bash, zsh, power-shell, fish, elvish] + [possible values: bash, elvish, fish, powershell, zsh] -FLAGS: - -h, --help Print help information - -V, --version Print version information +OPTIONS: + -h, --help Print help information ``` diff --git a/implementations/rust/preserves-tools/src/bin/preserves-tool.rs b/implementations/rust/preserves-tools/src/bin/preserves-tool.rs index a95234e..7909c11 100644 --- a/implementations/rust/preserves-tools/src/bin/preserves-tool.rs +++ b/implementations/rust/preserves-tools/src/bin/preserves-tool.rs @@ -177,9 +177,16 @@ enum Subcommand { #[derive(Clone, Debug, Parser)] #[clap(name = "preserves-tool")] #[clap(version)] +#[clap(args_conflicts_with_subcommands = true)] +/// Swiss-army knife tool for working with Preserves data. +/// See https://preserves.dev/. +/// If no subcommand is specified, the default subcommand will be `convert`. struct CommandLine { #[clap(subcommand)] - command: Subcommand, + command: Option, + + #[clap(flatten, next_help_heading="OPTIONS FOR DEFAULT SUBCOMMAND convert")] + convert: Convert, } fn print_completions(gen: G, cmd: &mut Command) { @@ -189,12 +196,15 @@ fn print_completions(gen: G, cmd: &mut Command) { fn main() -> io::Result<()> { let args = CommandLine::parse(); Ok(match args.command { - Subcommand::Completions { shell } => { - let mut cmd = CommandLine::into_app(); - print_completions(shell, &mut cmd); + Some(subcommand) => match subcommand { + Subcommand::Completions { shell } => { + let mut cmd = CommandLine::into_app(); + print_completions(shell, &mut cmd); + } + Subcommand::Convert(c) => convert(c)?, + Subcommand::Quote(q) => quote(q)?, } - Subcommand::Convert(c) => convert(c)?, - Subcommand::Quote(q) => quote(q)?, + None => convert(args.convert)?, }) }