src/cli: improve docs

This commit is contained in:
Dietmar Maurer
2019-12-01 16:41:49 +01:00
parent 3bf920527c
commit 28c855c0a2
5 changed files with 80 additions and 6 deletions

View File

@ -14,12 +14,18 @@ use super::getopts;
use super::{CommandLineInterface, CliCommand, CliCommandMap, completion::*};
use super::format::*;
/// Schema definition for ``--output-format`` parameter.
///
/// - ``text``: command specific text format.
/// - ``json``: JSON, single line.
/// - ``json-pretty``: JSON, human readable.
///
pub const OUTPUT_FORMAT: Schema =
StringSchema::new("Output format.")
.format(&ApiStringFormat::Enum(&["text", "json", "json-pretty"]))
.schema();
pub fn handle_simple_command(
fn handle_simple_command(
_top_def: &CommandLineInterface,
prefix: &str,
cli_cmd: &CliCommand,
@ -69,7 +75,7 @@ pub fn handle_simple_command(
Ok(())
}
pub fn handle_nested_command(
fn handle_nested_command(
top_def: &CommandLineInterface,
prefix: &str,
def: &CliCommandMap,
@ -172,11 +178,15 @@ fn set_help_context(def: Option<Arc<CommandLineInterface>>) {
HELP_CONTEXT.with(|ctx| { *ctx.borrow_mut() = def; });
}
pub fn help_command_def() -> CliCommand {
pub(crate) fn help_command_def() -> CliCommand {
CliCommand::new(&API_METHOD_COMMAND_HELP)
.arg_param(&["command"])
}
/// Handle command invocation.
///
/// This command gets the command line ``args`` and tries to invoke
/// the corresponding API handler.
pub fn handle_command(
def: Arc<CommandLineInterface>,
prefix: &str,
@ -199,6 +209,18 @@ pub fn handle_command(
result
}
/// Helper to get arguments and invoke the command.
///
/// This helper reads arguments with ``std::env::args()``. The first
/// argument is assumed to be the program name, and is passed as ``prefix`` to
/// ``handle_command()``.
///
/// This helper automatically add the help command, and two special
/// sub-command:
///
/// - ``bashcomplete``: Output bash completions instead of running the command.
/// - ``printdoc``: Output ReST documentation.
///
pub fn run_cli_command(def: CommandLineInterface) {
let def = match def {

View File

@ -189,6 +189,12 @@ fn get_nested_completion(
}
}
/// Helper to generate bash completions.
///
/// This helper extracts the command line from environment variable
/// set by ``bash``, namely ``COMP_LINE`` and ``COMP_POINT``. This is
/// passed to ``get_completions()``. Returned values are printed to
/// ``stdout``.
pub fn print_bash_completion(def: &CommandLineInterface) {
let comp_point: usize = match std::env::var("COMP_POINT") {
@ -213,6 +219,7 @@ pub fn print_bash_completion(def: &CommandLineInterface) {
}
}
/// Compute possible completions for a partial command
pub fn get_completions(
cmd_def: &CommandLineInterface,
line: &str,

View File

@ -7,7 +7,7 @@ use proxmox::api::format::*;
use super::{CommandLineInterface, CliCommand, CliCommandMap};
/// Helper function to format and print result
/// Helper function to format and print result.
///
/// This is implemented for machine generatable formats 'json' and
/// 'json-pretty'. The 'text' format needs to be handled somewhere
@ -26,6 +26,7 @@ pub fn format_and_print_result(
}
}
/// Helper to generate command usage text for simple commands.
pub fn generate_usage_str(
prefix: &str,
cli_cmd: &CliCommand,
@ -115,6 +116,7 @@ pub fn generate_usage_str(
text
}
/// Print command usage for simple commands to ``stderr``.
pub fn print_simple_usage_error(
prefix: &str,
cli_cmd: &CliCommand,
@ -124,6 +126,7 @@ pub fn print_simple_usage_error(
eprint!("Error: {}\nUsage: {}", err_msg, usage);
}
/// Print command usage for nested commands to ``stderr``.
pub fn print_nested_usage_error(
prefix: &str,
def: &CliCommandMap,
@ -133,6 +136,7 @@ pub fn print_nested_usage_error(
eprintln!("Error: {}\n\nUsage:\n\n{}", err_msg, usage);
}
/// Helper to generate command usage text for nested commands.
pub fn generate_nested_usage(
prefix: &str,
def: &CliCommandMap,
@ -163,6 +167,7 @@ pub fn generate_nested_usage(
usage
}
/// Print help text to ``stderr``.
pub fn print_help(
top_def: &CommandLineInterface,
mut prefix: String,

View File

@ -2,6 +2,11 @@ use std::sync::Arc;
use super::*;
/// Helper trait implementation for ``rustyline``.
///
/// This can be used to generate interactive commands using
/// ``rustyline`` (readline implementation).
///
pub struct CliHelper {
cmd_def: Arc<CommandLineInterface>,
}