X-Git-Url: https://git.proxmox.com/?p=pve-common.git;a=blobdiff_plain;f=src%2FPVE%2FCLIHandler.pm;h=45c0427b2faec2aed843db7c54ba40e665564e85;hp=c3e70fb21a82e34aef8c70ef951422ea770cfaf1;hb=b8dc43668bb64a28dd00b14022302ec8d932deff;hpb=4c802a572c726b3e7cb001308f38dee8de5b4060 diff --git a/src/PVE/CLIHandler.pm b/src/PVE/CLIHandler.pm index c3e70fb..45c0427 100644 --- a/src/PVE/CLIHandler.pm +++ b/src/PVE/CLIHandler.pm @@ -10,6 +10,29 @@ use PVE::INotify; use base qw(PVE::RESTHandler); +# $cmddef defines which (sub)commands are available in a specific CLI class. +# A real command is always an array consisting of its class, name, array of +# position fixed (required) parameters and hash of predefined parameters when +# mapping a CLI command t o an API call. Optionally an output method can be +# passed at the end, e.g., for formatting or transformation purpose. +# +# [class, name, fixed_params, API_pre-set params, output_sub ] +# +# In case of so called 'simple commands', the $cmddef can be also just an +# array. +# +# Examples: +# $cmddef = { +# command => [ 'PVE::API2::Class', 'command', [ 'arg1', 'arg2' ], { node => $nodename } ], +# do => { +# this => [ 'PVE::API2::OtherClass', 'method', [ 'arg1' ], undef, sub { +# my ($res) = @_; +# print "$res\n"; +# }], +# that => [ 'PVE::API2::OtherClass', 'subroutine' [] ], +# }, +# dothat => { alias => 'do that' }, +# } my $cmddef; my $exename; my $cli_handler_class; @@ -36,10 +59,54 @@ my $expand_command_name = sub { return $cmd; }; -my $complete_command_names = sub { - return [ sort keys %$cmddef ]; +my $get_commands = sub { + my $def = shift // die "no command definition passed!"; + return [ grep { !(ref($def->{$_}) eq 'HASH' && defined($def->{$_}->{alias})) } sort keys %$def ]; }; +my $complete_command_names = sub { $get_commands->($cmddef) }; + +# traverses the command definition using the $argv array, resolving one level +# of aliases. +# Returns the matching (sub) command and its definition, and argument array for +# this (sub) command and a hash where we marked which (sub) commands got +# expanded (e.g. st => status) while traversing +sub resolve_cmd { + my ($argv, $is_alias) = @_; + + my ($def, $cmd) = ($cmddef, $argv); + + if (ref($argv) eq 'ARRAY') { + my $expanded = {}; + my $last_arg_id = scalar(@$argv) - 1; + + for my $i (0..$last_arg_id) { + $cmd = $expand_command_name->($def, $argv->[$i]); + $expanded->{$argv->[$i]} = $cmd if $cmd ne $argv->[$i]; + last if !defined($def->{$cmd}); + $def = $def->{$cmd}; + + if (ref($def) eq 'ARRAY') { + # could expand to a real command, rest of $argv are its arguments + my $cmd_args = [ @$argv[$i+1..$last_arg_id] ]; + return ($cmd, $def, $cmd_args, $expanded); + } + + if (defined($def->{alias})) { + die "alias loop detected for '$cmd'" if $is_alias; # avoids cycles + # replace aliased (sub)command with the expanded aliased command + splice @$argv, $i, 1, split(/ +/, $def->{alias}); + return resolve_cmd($argv, 1); + } + } + # got either a special command (bashcomplete, verifyapi) or an unknown + # cmd, just return first entry as cmd and the rest of $argv as cmd_arg + my $cmd_args = [ @$argv[1..$last_arg_id] ]; + return ($argv->[0], $def, $cmd_args, $expanded); + } + return ($cmd, $def); +} + sub generate_usage_str { my ($format, $cmd, $indent, $separator, $sortfunc) = @_; @@ -53,8 +120,7 @@ sub generate_usage_str { my $can_read_pass = $cli_handler_class->can('read_password'); my $can_str_param_fmap = $cli_handler_class->can('string_param_file_mapping'); - my $def = $cmddef; - $def = $def->{$cmd} if $cmd && ref($def) eq 'HASH' && $def->{$cmd}; + my ($subcmd, $def) = resolve_cmd($cmd); my $generate; $generate = sub { @@ -74,6 +140,19 @@ sub generate_usage_str { $fixed_param, $format, $can_read_pass, $can_str_param_fmap); $oldclass = $class; + + } elsif (defined($def->{$cmd}->{alias}) && ($format eq 'asciidoc')) { + + $str .= "*$prefix $cmd*\n\nAn alias for '$exename $def->{$cmd}->{alias}'.\n\n"; + + } else { + next if $def->{$cmd}->{alias}; + + my $substr = $generate->($indent, $separator, $def->{$cmd}, "$prefix $cmd"); + if ($substr) { + $substr .= $separator if $substr !~ /\Q$separator\E{2}/; + $str .= $substr; + } } } @@ -88,7 +167,10 @@ sub generate_usage_str { return $str; }; - return $generate->($indent, $separator, $def, $exename); + my $cmdstr = $exename; + $cmdstr .= ' ' . join(' ', @$cmd) if defined($cmd); + + return $generate->($indent, $separator, $def, $cmdstr); } __PACKAGE__->register_method ({ @@ -99,12 +181,10 @@ __PACKAGE__->register_method ({ parameters => { additionalProperties => 0, properties => { - cmd => { - description => "Command name", - type => 'string', - optional => 1, + 'extra-args' => PVE::JSONSchema::get_standard_option('extra-args', { + description => 'Shows help for a specific command', completion => $complete_command_names, - }, + }), verbose => { description => "Verbose output format.", type => 'boolean', @@ -119,9 +199,9 @@ __PACKAGE__->register_method ({ $assert_initialized->(); - my $cmd = $param->{cmd}; + my $cmd = $param->{'extra-args'}; - my $verbose = defined($cmd) && $cmd; + my $verbose = defined($cmd) && $cmd; $verbose = $param->{verbose} if defined($param->{verbose}); if (!$cmd) { @@ -185,21 +265,24 @@ sub print_usage_verbose { } sub print_usage_short { - my ($fd, $msg) = @_; + my ($fd, $msg, $cmd) = @_; $assert_initialized->(); print $fd "ERROR: $msg\n" if $msg; print $fd "USAGE: $exename [ARGS] [OPTIONS]\n"; - print {$fd} generate_usage_str('short', undef, ' ' x 7, "\n", sub { + print {$fd} generate_usage_str('short', $cmd, ' ' x 7, "\n", sub { my ($h) = @_; return sort { if (ref($h->{$a}) eq 'ARRAY' && ref($h->{$b}) eq 'ARRAY') { # $a and $b are both real commands order them by their class return $h->{$a}->[0] cmp $h->{$b}->[0] || $a cmp $b; + } elsif (ref($h->{$a}) eq 'ARRAY' xor ref($h->{$b}) eq 'ARRAY') { + # real command and subcommand mixed, put sub commands first + return ref($h->{$b}) eq 'ARRAY' ? -1 : 1; } else { - # both are from the same class + # both are either from the same class or subcommands return $a cmp $b; } } keys %$h; @@ -228,13 +311,17 @@ my $print_bash_completion = sub { my ($cmd, $def) = ($simple_cmd, $cmddef); if (!$simple_cmd) { - if (!scalar(@$args)) { - &$print_result(keys %$def); + ($cmd, $def, $args, my $expaned) = resolve_cmd($args); + + if (ref($def) eq 'HASH') { + &$print_result(@{$get_commands->($def)}); + return; + } + if (my $expanded_cmd = $expaned->{$cur}) { + print "$expanded_cmd\n"; return; } - $cmd = $args->[0]; } - $def = $def->{$cmd}; return if !$def; my $pos = scalar(@$args) - 1; @@ -372,10 +459,11 @@ sub setup_environment { my $handle_cmd = sub { my ($args, $pwcallback, $preparefunc, $stringfilemap) = @_; - $cmddef->{help} = [ __PACKAGE__, 'help', ['cmd'] ]; + $cmddef->{help} = [ __PACKAGE__, 'help', ['extra-args'] ]; + my $cmd_str = join(' ', @$args); + my ($cmd, $def, $cmd_args) = resolve_cmd($args); - my $cmd = shift @$args; $abort->("no command specified") if !$cmd; # call verifyapi before setup_environment(), don't execute any real code in @@ -388,19 +476,20 @@ my $handle_cmd = sub { $cli_handler_class->setup_environment(); if ($cmd eq 'bashcomplete') { - &$print_bash_completion(undef, @$args); + &$print_bash_completion(undef, @$cmd_args); return; } - &$preparefunc() if $preparefunc; + # checked special commands, if def is still a hash we got an incomplete sub command + $abort->("incomplete command '$exename $cmd_str'") if ref($def) eq 'HASH'; - $cmd = &$expand_command_name($cmddef, $cmd); + &$preparefunc() if $preparefunc; - my ($class, $name, $arg_param, $uri_param, $outsub) = @{$cmddef->{$cmd} || []}; - $abort->("unknown command '$cmd'") if !$class; + my ($class, $name, $arg_param, $uri_param, $outsub) = @{$def || []}; + $abort->("unknown command '$cmd_str'") if !$class; - my $prefix = "$exename $cmd"; - my $res = $class->cli_handler($prefix, $name, \@ARGV, $arg_param, $uri_param, $pwcallback, $stringfilemap); + my $prefix = "$exename $cmd_str"; + my $res = $class->cli_handler($prefix, $name, $cmd_args, $arg_param, $uri_param, $pwcallback, $stringfilemap); &$outsub($res) if $outsub; };