X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=src%2FPVE%2FRESTHandler.pm;h=e395b95d5c6ea02a1f63b8c50e96440d71191755;hb=62c66c47fb838e50a468f60cabff67011a9d0fcf;hp=c303c389e4da1273122786a2e9274ccd00c4a0d6;hpb=968bcf45be81faba6dbcb3357de725a94a34d09d;p=pve-common.git diff --git a/src/PVE/RESTHandler.pm b/src/PVE/RESTHandler.pm index c303c38..e395b95 100644 --- a/src/PVE/RESTHandler.pm +++ b/src/PVE/RESTHandler.pm @@ -17,6 +17,33 @@ my $method_path_lookup = {}; our $AUTOLOAD; # it's a package global +our $standard_output_options = { + 'output-format' => PVE::JSONSchema::get_standard_option('pve-output-format'), + noheader => { + description => "Do not show column headers (for 'text' format).", + type => 'boolean', + optional => 1, + default => 1, + }, + noborder => { + description => "Do not draw borders (for 'text' format).", + type => 'boolean', + optional => 1, + default => 1, + }, + quiet => { + description => "Suppress printing results.", + type => 'boolean', + optional => 1, + }, + 'human-readable' => { + description => "Call output rendering functions to produce human readable text.", + type => 'boolean', + optional => 1, + default => 1, + } +}; + sub api_clone_schema { my ($schema) = @_; @@ -37,7 +64,7 @@ sub api_clone_schema { my ($name, $idx) = ($1, $2); if ($idx == 0 && defined($d->{"${name}1"})) { $p = "${name}[n]"; - } elsif (defined($d->{"${name}0"})) { + } elsif ($idx > 0 && defined($d->{"${name}0"})) { next; # only handle once for -xx0, but only if -xx0 exists } } @@ -414,7 +441,7 @@ sub handle { $param->{'extra-args'} = [map { /^(.*)$/ } @$extra] if $extra; } - my $result = &$func($param); + my $result = &$func($param); # todo: this is only to be safe - disable? if (my $schema = $info->{returns}) { @@ -566,7 +593,7 @@ my $compute_param_mapping_hash = sub { # generate usage information for command line tools # -# $name ... the name of the method +# $info ... method info # $prefix ... usually something like "$exename $cmd" ('pvesm add') # $arg_param ... list of parameters we want to get as ordered arguments # on the command line (or single parameter name for lists) @@ -576,15 +603,26 @@ my $compute_param_mapping_hash = sub { # 'short' ... command line only (text, one line) # 'full' ... text, include description # 'asciidoc' ... generate asciidoc for man pages (like 'full') -# $param_cb ... mapping for string parameters to file path parameters -sub usage_str { - my ($self, $name, $prefix, $arg_param, $fixed_param, $format, $param_cb) = @_; +# $param_cb ... mapping for string parameters to file path parameters +# $formatter_properties ... additional property definitions (passed to output formatter) +sub getopt_usage { + my ($info, $prefix, $arg_param, $fixed_param, $format, $param_cb, $formatter_properties) = @_; $format = 'long' if !$format; - my $info = $self->map_method_by_name($name); my $schema = $info->{parameters}; - my $prop = $schema->{properties}; + my $name = $info->{name}; + my $prop = { %{$schema->{properties}} }; # copy + + my $has_output_format_option = $formatter_properties->{'output-format'} ? 1 : 0; + + if ($formatter_properties) { + foreach my $key (keys %$formatter_properties) { + if (!$standard_output_options->{$key}) { + $prop->{$key} = $formatter_properties->{$key}; + } + } + } my $out = ''; @@ -653,11 +691,15 @@ sub usage_str { if ($format eq 'asciidoc') { $out .= "*${prefix}*"; $out .= " `$args`" if $args; - $out .= $opts ? " `[OPTIONS]`\n" : "\n"; + $out .= " `[OPTIONS]`" if $opts; + $out .= " `[FORMAT_OPTIONS]`" if $has_output_format_option; + $out .= "\n"; } else { $out .= "USAGE: " if $format ne 'short'; $out .= "$prefix $args"; - $out .= $opts ? " [OPTIONS]\n" : "\n"; + $out .= " [OPTIONS]" if $opts; + $out .= " [FORMAT_OPTIONS]" if $has_output_format_option; + $out .= "\n"; } return $out if $format eq 'short'; @@ -679,6 +721,14 @@ sub usage_str { return $out; } +sub usage_str { + my ($self, $name, $prefix, $arg_param, $fixed_param, $format, $param_cb, $formatter_properties) = @_; + + my $info = $self->map_method_by_name($name); + + return getopt_usage($info, $prefix, $arg_param, $fixed_param, $format, $param_cb, $formatter_properties); +} + # generate docs from JSON schema properties sub dump_properties { my ($prop, $format, $style, $filterFn) = @_; @@ -737,16 +787,54 @@ my $replace_file_names_with_contents = sub { return $param; }; +sub add_standard_output_properties { + my ($propdef, $list) = @_; + + $propdef //= {}; + + $list //= [ keys %$standard_output_options ]; + + my $res = { %$propdef }; # copy + + foreach my $opt (@$list) { + die "no such standard output option '$opt'\n" if !defined($standard_output_options->{$opt}); + die "detected overwriten standard CLI parameter '$opt'\n" if defined($res->{$opt}); + $res->{$opt} = $standard_output_options->{$opt}; + } + + return $res; +} + +sub extract_standard_output_properties { + my ($data) = @_; + + my $options = {}; + foreach my $opt (keys %$standard_output_options) { + $options->{$opt} = delete $data->{$opt} if defined($data->{$opt}); + } + + return $options; +} + sub cli_handler { - my ($self, $prefix, $name, $args, $arg_param, $fixed_param, $param_cb) = @_; + my ($self, $prefix, $name, $args, $arg_param, $fixed_param, $param_cb, $formatter_properties) = @_; my $info = $self->map_method_by_name($name); - my $res; + my $fmt_param = {}; + eval { my $param_map = {}; $param_map = $compute_param_mapping_hash->($param_cb->($name)) if $param_cb; - my $param = PVE::JSONSchema::get_options($info->{parameters}, $args, $arg_param, $fixed_param, $param_map); + my $schema = { %{$info->{parameters}} }; # copy + $schema->{properties} = { %{$schema->{properties}}, %$formatter_properties } if $formatter_properties; + my $param = PVE::JSONSchema::get_options($schema, $args, $arg_param, $fixed_param, $param_map); + + if ($formatter_properties) { + foreach my $opt (keys %$formatter_properties) { + $fmt_param->{$opt} = delete $param->{$opt} if defined($param->{$opt}); + } + } if (defined($param_map)) { $replace_file_names_with_contents->($param, $param_map); @@ -759,12 +847,12 @@ sub cli_handler { die $err if !$ec || $ec ne "PVE::Exception" || !$err->is_param_exc(); - $err->{usage} = $self->usage_str($name, $prefix, $arg_param, $fixed_param, 'short', $param_cb); + $err->{usage} = $self->usage_str($name, $prefix, $arg_param, $fixed_param, 'short', $param_cb, $formatter_properties); die $err; } - return $res; + return wantarray ? ($res, $fmt_param) : $res; } # utility methods