src/cli: improve docs
This commit is contained in:
@ -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 {
|
||||
|
@ -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,
|
||||
|
@ -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,
|
||||
|
@ -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>,
|
||||
}
|
||||
|
Reference in New Issue
Block a user