]> git.proxmox.com Git - pve-common.git/blame - src/PVE/RESTHandler.pm
print_text_table: align numbers to the right side
[pve-common.git] / src / PVE / RESTHandler.pm
CommitLineData
e143e9d8
DM
1package PVE::RESTHandler;
2
3use strict;
4no strict 'refs'; # our autoload requires this
e143e9d8
DM
5use warnings;
6use PVE::SafeSyslog;
7use PVE::Exception qw(raise raise_param_exc);
8use PVE::JSONSchema;
dfc6cff8 9use PVE::Tools;
e143e9d8
DM
10use HTTP::Status qw(:constants :is status_message);
11use Text::Wrap;
4be9b5f7 12use Clone qw(clone);
e143e9d8
DM
13
14my $method_registry = {};
15my $method_by_name = {};
c1089794 16my $method_path_lookup = {};
e143e9d8
DM
17
18our $AUTOLOAD; # it's a package global
19
62c66c47
DM
20our $standard_output_options = {
21 'output-format' => PVE::JSONSchema::get_standard_option('pve-output-format'),
22 noheader => {
23 description => "Do not show column headers (for 'text' format).",
24 type => 'boolean',
25 optional => 1,
26 default => 1,
27 },
28 noborder => {
29 description => "Do not draw borders (for 'text' format).",
30 type => 'boolean',
31 optional => 1,
32 default => 1,
33 },
34 quiet => {
35 description => "Suppress printing results.",
36 type => 'boolean',
37 optional => 1,
38 },
39 'human-readable' => {
40 description => "Call output rendering functions to produce human readable text.",
41 type => 'boolean',
42 optional => 1,
43 default => 1,
44 }
45};
46
e143e9d8
DM
47sub api_clone_schema {
48 my ($schema) = @_;
49
50 my $res = {};
51 my $ref = ref($schema);
52 die "not a HASH reference" if !($ref && $ref eq 'HASH');
53
54 foreach my $k (keys %$schema) {
55 my $d = $schema->{$k};
56 if ($k ne 'properties') {
4be9b5f7 57 $res->{$k} = ref($d) ? clone($d) : $d;
e143e9d8
DM
58 next;
59 }
60 # convert indexed parameters like -net\d+ to -net[n]
61 foreach my $p (keys %$d) {
62 my $pd = $d->{$p};
63 if ($p =~ m/^([a-z]+)(\d+)$/) {
b546f33e 64 my ($name, $idx) = ($1, $2);
b54ad320 65 if ($idx == 0 && defined($d->{"${name}1"})) {
b546f33e 66 $p = "${name}[n]";
34d89996 67 } elsif ($idx > 0 && defined($d->{"${name}0"})) {
2c2a5fd3 68 next; # only handle once for -xx0, but only if -xx0 exists
e143e9d8
DM
69 }
70 }
534d4270
DM
71 my $tmp = ref($pd) ? clone($pd) : $pd;
72 # NOTE: add typetext property for more complex types, to
73 # make the web api viewer code simpler
74 if (!(defined($tmp->{enum}) || defined($tmp->{pattern}))) {
75 my $typetext = PVE::JSONSchema::schema_get_type_text($tmp);
76 if ($tmp->{type} && ($tmp->{type} ne $typetext)) {
77 $tmp->{typetext} = $typetext;
78 }
79 }
80 $res->{$k}->{$p} = $tmp;
e143e9d8
DM
81 }
82 }
83
84 return $res;
85}
86
87sub api_dump_full {
1e5ecf7b 88 my ($tree, $index, $class, $prefix, $raw_dump) = @_;
e143e9d8
DM
89
90 $prefix = '' if !$prefix;
91
92 my $ma = $method_registry->{$class};
93
94 foreach my $info (@$ma) {
95
96 my $path = "$prefix/$info->{path}";
97 $path =~ s/\/+$//;
98
99 if ($info->{subclass}) {
1e5ecf7b 100 api_dump_full($tree, $index, $info->{subclass}, $path, $raw_dump);
e143e9d8
DM
101 } else {
102 next if !$path;
103
104 # check if method is unique
105 my $realpath = $path;
106 $realpath =~ s/\{[^\}]+\}/\{\}/g;
107 my $fullpath = "$info->{method} $realpath";
108 die "duplicate path '$realpath'" if $index->{$fullpath};
109 $index->{$fullpath} = $info;
110
111 # insert into tree
112 my $treedir = $tree;
113 my $res;
114 my $sp = '';
115 foreach my $dir (split('/', $path)) {
116 next if !$dir;
117 $sp .= "/$dir";
118 $res = (grep { $_->{text} eq $dir } @$treedir)[0];
119 if ($res) {
120 $res->{children} = [] if !$res->{children};
121 $treedir = $res->{children};
122 } else {
123 $res = {
124 path => $sp,
125 text => $dir,
126 children => [],
127 };
128 push @$treedir, $res;
129 $treedir = $res->{children};
130 }
131 }
132
133 if ($res) {
134 my $data = {};
135 foreach my $k (keys %$info) {
136 next if $k eq 'code' || $k eq "match_name" || $k eq "match_re" ||
137 $k eq "path";
138
139 my $d = $info->{$k};
e143e9d8 140
1e5ecf7b
DM
141 if ($raw_dump) {
142 $data->{$k} = $d;
143 } else {
144 if ($k eq 'parameters') {
145 $data->{$k} = api_clone_schema($d);
146 } else {
147 $data->{$k} = ref($d) ? clone($d) : $d;
148 }
e143e9d8
DM
149 }
150 }
151 $res->{info}->{$info->{method}} = $data;
152 };
153 }
154 }
155};
156
157sub api_dump_cleanup_tree {
158 my ($tree) = @_;
159
160 foreach my $rec (@$tree) {
161 delete $rec->{children} if $rec->{children} && !scalar(@{$rec->{children}});
162 if ($rec->{children}) {
163 $rec->{leaf} = 0;
164 api_dump_cleanup_tree($rec->{children});
165 } else {
166 $rec->{leaf} = 1;
167 }
168 }
169
170}
171
903ea3ff
DM
172# api_dump_remove_refs: prepare API tree for use with to_json($tree)
173sub api_dump_remove_refs {
174 my ($tree) = @_;
175
176 my $class = ref($tree);
177 return $tree if !$class;
178
179 if ($class eq 'ARRAY') {
180 my $res = [];
181 foreach my $el (@$tree) {
182 push @$res, api_dump_remove_refs($el);
183 }
184 return $res;
185 } elsif ($class eq 'HASH') {
186 my $res = {};
187 foreach my $k (keys %$tree) {
188 if (my $itemclass = ref($tree->{$k})) {
189 if ($itemclass eq 'CODE') {
190 next if $k eq 'completion';
191 }
192 $res->{$k} = api_dump_remove_refs($tree->{$k});
193 } else {
194 $res->{$k} = $tree->{$k};
195 }
196 }
197 return $res;
198 } elsif ($class eq 'Regexp') {
199 return "$tree"; # return string representation
200 } else {
201 die "unknown class '$class'\n";
202 }
203}
204
e143e9d8 205sub api_dump {
1e5ecf7b 206 my ($class, $prefix, $raw_dump) = @_;
e143e9d8
DM
207
208 my $tree = [];
209
210 my $index = {};
1e5ecf7b 211 api_dump_full($tree, $index, $class, $prefix, $raw_dump);
e143e9d8
DM
212 api_dump_cleanup_tree($tree);
213 return $tree;
214};
215
216sub validate_method_schemas {
217
218 foreach my $class (keys %$method_registry) {
219 my $ma = $method_registry->{$class};
220
221 foreach my $info (@$ma) {
222 PVE::JSONSchema::validate_method_info($info);
223 }
224 }
225}
226
227sub register_method {
228 my ($self, $info) = @_;
229
230 my $match_re = [];
231 my $match_name = [];
232
c1089794
DM
233 my $errprefix;
234
235 my $method;
236 if ($info->{subclass}) {
237 $errprefix = "register subclass $info->{subclass} at ${self}/$info->{path} -";
238 $method = 'SUBCLASS';
239 } else {
240 $errprefix = "register method ${self}/$info->{path} -";
241 $info->{method} = 'GET' if !$info->{method};
242 $method = $info->{method};
243 }
244
245 $method_path_lookup->{$self} = {} if !defined($method_path_lookup->{$self});
246 my $path_lookup = $method_path_lookup->{$self};
247
248 die "$errprefix no path" if !defined($info->{path});
249
e143e9d8 250 foreach my $comp (split(/\/+/, $info->{path})) {
c1089794
DM
251 die "$errprefix path compoment has zero length\n" if $comp eq '';
252 my ($name, $regex);
e143e9d8 253 if ($comp =~ m/^\{(\w+)(:(.*))?\}$/) {
c1089794
DM
254 $name = $1;
255 $regex = $3 ? $3 : '\S+';
256 push @$match_re, $regex;
257 push @$match_name, $name;
e143e9d8 258 } else {
c1089794
DM
259 $name = $comp;
260 push @$match_re, $name;
261 push @$match_name, undef;
262 }
263
264 if ($regex) {
265 $path_lookup->{regex} = {} if !defined($path_lookup->{regex});
266
267 my $old_name = $path_lookup->{regex}->{match_name};
268 die "$errprefix found changed regex match name\n"
269 if defined($old_name) && ($old_name ne $name);
270 my $old_re = $path_lookup->{regex}->{match_re};
271 die "$errprefix found changed regex\n"
272 if defined($old_re) && ($old_re ne $regex);
273 $path_lookup->{regex}->{match_name} = $name;
274 $path_lookup->{regex}->{match_re} = $regex;
275
276 die "$errprefix path match error - regex and fixed items\n"
277 if defined($path_lookup->{folders});
278
279 $path_lookup = $path_lookup->{regex};
280
281 } else {
282 $path_lookup->{folders}->{$name} = {} if !defined($path_lookup->{folders}->{$name});
283
284 die "$errprefix path match error - regex and fixed items\n"
285 if defined($path_lookup->{regex});
286
287 $path_lookup = $path_lookup->{folders}->{$name};
e143e9d8
DM
288 }
289 }
290
c1089794
DM
291 die "$errprefix duplicate method definition\n"
292 if defined($path_lookup->{$method});
293
1dad1ca5
DM
294 if ($method eq 'SUBCLASS') {
295 foreach my $m (qw(GET PUT POST DELETE)) {
296 die "$errprefix duplicate method definition SUBCLASS and $m\n" if $path_lookup->{$m};
297 }
298 }
c1089794
DM
299 $path_lookup->{$method} = $info;
300
e143e9d8
DM
301 $info->{match_re} = $match_re;
302 $info->{match_name} = $match_name;
303
304 $method_by_name->{$self} = {} if !defined($method_by_name->{$self});
305
306 if ($info->{name}) {
c1089794 307 die "$errprefix method name already defined\n"
e143e9d8
DM
308 if defined($method_by_name->{$self}->{$info->{name}});
309
310 $method_by_name->{$self}->{$info->{name}} = $info;
311 }
312
313 push @{$method_registry->{$self}}, $info;
314}
315
f1fb34a0
DM
316sub DESTROY {}; # avoid problems with autoload
317
e143e9d8
DM
318sub AUTOLOAD {
319 my ($this) = @_;
320
321 # also see "man perldiag"
322
323 my $sub = $AUTOLOAD;
324 (my $method = $sub) =~ s/.*:://;
325
e143e9d8
DM
326 my $info = $this->map_method_by_name($method);
327
328 *{$sub} = sub {
329 my $self = shift;
330 return $self->handle($info, @_);
331 };
332 goto &$AUTOLOAD;
333}
334
335sub method_attributes {
336 my ($self) = @_;
337
338 return $method_registry->{$self};
339}
340
341sub map_method_by_name {
342 my ($self, $name) = @_;
343
344 my $info = $method_by_name->{$self}->{$name};
345 die "no such method '${self}::$name'\n" if !$info;
346
347 return $info;
348}
349
c1089794 350sub map_path_to_methods {
39313ced 351 my ($class, $stack, $uri_param, $pathmatchref) = @_;
e143e9d8 352
c1089794 353 my $path_lookup = $method_path_lookup->{$class};
e143e9d8 354
39313ced
DM
355 # Note: $pathmatchref can be used to obtain path including
356 # uri patterns like '/cluster/firewall/groups/{group}'.
357 # Used by pvesh to display help
358 if (defined($pathmatchref)) {
359 $$pathmatchref = '' if !$$pathmatchref;
360 }
361
844a246d 362 while (defined(my $comp = shift @$stack)) {
c1089794
DM
363 return undef if !$path_lookup; # not registerd?
364 if ($path_lookup->{regex}) {
365 my $name = $path_lookup->{regex}->{match_name};
366 my $regex = $path_lookup->{regex}->{match_re};
e143e9d8 367
c1089794
DM
368 return undef if $comp !~ m/^($regex)$/;
369 $uri_param->{$name} = $1;
370 $path_lookup = $path_lookup->{regex};
39313ced 371 $$pathmatchref .= '/{' . $name . '}' if defined($pathmatchref);
c1089794
DM
372 } elsif ($path_lookup->{folders}) {
373 $path_lookup = $path_lookup->{folders}->{$comp};
39313ced 374 $$pathmatchref .= '/' . $comp if defined($pathmatchref);
e143e9d8 375 } else {
c1089794 376 die "internal error";
e143e9d8 377 }
c1089794
DM
378
379 return undef if !$path_lookup;
e143e9d8 380
c1089794
DM
381 if (my $info = $path_lookup->{SUBCLASS}) {
382 $class = $info->{subclass};
e143e9d8 383
c1089794 384 my $fd = $info->{fragmentDelimiter};
e143e9d8 385
c1089794
DM
386 if (defined($fd)) {
387 # we only support the empty string '' (match whole URI)
388 die "unsupported fragmentDelimiter '$fd'"
389 if $fd ne '';
e143e9d8 390
c1089794
DM
391 $stack = [ join ('/', @$stack) ] if scalar(@$stack) > 1;
392 }
393 $path_lookup = $method_path_lookup->{$class};
e143e9d8 394 }
c1089794 395 }
e143e9d8 396
c1089794 397 return undef if !$path_lookup;
e143e9d8 398
c1089794
DM
399 return ($class, $path_lookup);
400}
e143e9d8 401
c1089794 402sub find_handler {
39313ced 403 my ($class, $method, $path, $uri_param, $pathmatchref) = @_;
e143e9d8 404
c1089794 405 my $stack = [ grep { length($_) > 0 } split('\/+' , $path)]; # skip empty fragments
e143e9d8 406
c1089794
DM
407 my ($handler_class, $path_info);
408 eval {
39313ced 409 ($handler_class, $path_info) = $class->map_path_to_methods($stack, $uri_param, $pathmatchref);
c1089794
DM
410 };
411 my $err = $@;
412 syslog('err', $err) if $err;
e143e9d8 413
c1089794 414 return undef if !($handler_class && $path_info);
e143e9d8 415
c1089794 416 my $method_info = $path_info->{$method};
e143e9d8 417
c1089794 418 return undef if !$method_info;
e143e9d8 419
c1089794 420 return ($handler_class, $method_info);
e143e9d8
DM
421}
422
423sub handle {
4cbcd138 424 my ($self, $info, $param) = @_;
e143e9d8
DM
425
426 my $func = $info->{code};
427
428 if (!($info->{name} && $func)) {
429 raise("Method lookup failed ('$info->{name}')\n",
430 code => HTTP_INTERNAL_SERVER_ERROR);
431 }
432
433 if (my $schema = $info->{parameters}) {
434 # warn "validate ". Dumper($param}) . "\n" . Dumper($schema);
435 PVE::JSONSchema::validate($param, $schema);
436 # untaint data (already validated)
5851be88 437 my $extra = delete $param->{'extra-args'};
e143e9d8
DM
438 while (my ($key, $val) = each %$param) {
439 ($param->{$key}) = $val =~ /^(.*)$/s;
440 }
5851be88 441 $param->{'extra-args'} = [map { /^(.*)$/ } @$extra] if $extra;
e143e9d8
DM
442 }
443
4cbcd138 444 my $result = &$func($param);
e143e9d8
DM
445
446 # todo: this is only to be safe - disable?
447 if (my $schema = $info->{returns}) {
9030a7d7 448 PVE::JSONSchema::validate($result, $schema, "Result verification failed\n");
e143e9d8
DM
449 }
450
451 return $result;
452}
453
8fa050cd 454# format option, display type and description
921f91d1
DM
455# $name: option name
456# $display_name: for example "-$name" of "<$name>", pass undef to use "$name:"
8fa050cd 457# $phash: json schema property hash
b0e5e9fa 458# $format: 'asciidoc', 'short', 'long' or 'full'
abc1afd8 459# $style: 'config', 'config-sub', 'arg' or 'fixed'
dfc6cff8 460# $mapdef: parameter mapping ({ desc => XXX, func => sub {...} })
8fa050cd 461my $get_property_description = sub {
4842b651 462 my ($name, $style, $phash, $format, $mapdef) = @_;
8fa050cd
DM
463
464 my $res = '';
465
466 $format = 'asciidoc' if !defined($format);
467
468 my $descr = $phash->{description} || "no description available";
469
32f8e0c7
DM
470 if ($phash->{verbose_description} &&
471 ($style eq 'config' || $style eq 'config-sub')) {
472 $descr = $phash->{verbose_description};
473 }
474
8fa050cd
DM
475 chomp $descr;
476
77096a6f 477 my $type_text = PVE::JSONSchema::schema_get_type_text($phash, $style);
8fa050cd 478
dfc6cff8
DM
479 if ($mapdef && $phash->{type} eq 'string') {
480 $type_text = $mapdef->{desc};
4845032a
FG
481 }
482
8fa050cd
DM
483 if ($format eq 'asciidoc') {
484
df79b428 485 if ($style eq 'config') {
921f91d1 486 $res .= "`$name`: ";
32f8e0c7
DM
487 } elsif ($style eq 'config-sub') {
488 $res .= "`$name`=";
df79b428 489 } elsif ($style eq 'arg') {
a4f181a3 490 $res .= "`--$name` ";
df79b428 491 } elsif ($style eq 'fixed') {
abc1afd8 492 $res .= "`<$name>`: ";
df79b428
DM
493 } else {
494 die "unknown style '$style'";
8fa050cd
DM
495 }
496
77096a6f 497 $res .= "`$type_text` " if $type_text;
8fa050cd
DM
498
499 if (defined(my $dv = $phash->{default})) {
25d9bda9 500 $res .= "('default =' `$dv`)";
8fa050cd 501 }
a736ac99 502
32f8e0c7
DM
503 if ($style eq 'config-sub') {
504 $res .= ";;\n\n";
505 } else {
506 $res .= "::\n\n";
507 }
508
509 my $wdescr = $descr;
a736ac99
DM
510 chomp $wdescr;
511 $wdescr =~ s/^$/+/mg;
512
513 $res .= $wdescr . "\n";
8fa050cd
DM
514
515 if (my $req = $phash->{requires}) {
516 my $tmp .= ref($req) ? join(', ', @$req) : $req;
517 $res .= "+\nNOTE: Requires option(s): `$tmp`\n";
518 }
519 $res .= "\n";
520
b0e5e9fa 521 } elsif ($format eq 'short' || $format eq 'long' || $format eq 'full') {
8fa050cd
DM
522
523 my $defaulttxt = '';
524 if (defined(my $dv = $phash->{default})) {
525 $defaulttxt = " (default=$dv)";
526 }
527
df79b428
DM
528 my $display_name;
529 if ($style eq 'config') {
530 $display_name = "$name:";
531 } elsif ($style eq 'arg') {
532 $display_name = "-$name";
533 } elsif ($style eq 'fixed') {
534 $display_name = "<$name>";
535 } else {
536 die "unknown style '$style'";
537 }
8fa050cd 538
77096a6f 539 my $tmp = sprintf " %-10s %s$defaulttxt\n", $display_name, "$type_text";
8fa050cd
DM
540 my $indend = " ";
541
542 $res .= Text::Wrap::wrap('', $indend, ($tmp));
543 $res .= "\n",
544 $res .= Text::Wrap::wrap($indend, $indend, ($descr)) . "\n\n";
545
546 if (my $req = $phash->{requires}) {
547 my $tmp = "Requires option(s): ";
548 $tmp .= ref($req) ? join(', ', @$req) : $req;
549 $res .= Text::Wrap::wrap($indend, $indend, ($tmp)). "\n\n";
550 }
551
552 } else {
553 die "unknown format '$format'";
554 }
555
556 return $res;
557};
558
dfc6cff8
DM
559# translate parameter mapping definition
560# $mapping_array is a array which can contain:
561# strings ... in that case we assume it is a parameter name, and
562# we want to load that parameter from a file
563# [ param_name, func, desc] ... allows you to specify a arbitrary
564# mapping func for any param
565#
566# Returns: a hash indexed by parameter_name,
567# i.e. { param_name => { func => .., desc => ... } }
568my $compute_param_mapping_hash = sub {
569 my ($mapping_array) = @_;
570
571 my $res = {};
572
573 return $res if !defined($mapping_array);
574
575 foreach my $item (@$mapping_array) {
c7171ff2 576 my ($name, $func, $desc, $interactive);
dfc6cff8 577 if (ref($item) eq 'ARRAY') {
c7171ff2 578 ($name, $func, $desc, $interactive) = @$item;
a1c7edda
DC
579 } elsif (ref($item) eq 'HASH') {
580 # just use the hash
581 $res->{$item->{name}} = $item;
582 next;
dfc6cff8
DM
583 } else {
584 $name = $item;
585 $func = sub { return PVE::Tools::file_get_contents($_[0]) };
586 }
587 $desc //= '<filepath>';
c7171ff2 588 $res->{$name} = { desc => $desc, func => $func, interactive => $interactive };
dfc6cff8
DM
589 }
590
591 return $res;
592};
593
e143e9d8
DM
594# generate usage information for command line tools
595#
c03b7509 596# $info ... method info
e143e9d8 597# $prefix ... usually something like "$exename $cmd" ('pvesm add')
1d21344c
DM
598# $arg_param ... list of parameters we want to get as ordered arguments
599# on the command line (or single parameter name for lists)
e143e9d8
DM
600# $fixed_param ... do not generate and info about those parameters
601# $format:
b0e5e9fa
DM
602# 'long' ... default (text, list all options)
603# 'short' ... command line only (text, one line)
604# 'full' ... text, include description
fe3f1fde 605# 'asciidoc' ... generate asciidoc for man pages (like 'full')
9da27228
DM
606# $param_cb ... mapping for string parameters to file path parameters
607# $formatter_properties ... additional property definitions (passed to output formatter)
c03b7509 608sub getopt_usage {
9da27228 609 my ($info, $prefix, $arg_param, $fixed_param, $format, $param_cb, $formatter_properties) = @_;
e143e9d8
DM
610
611 $format = 'long' if !$format;
612
e143e9d8 613 my $schema = $info->{parameters};
c03b7509 614 my $name = $info->{name};
9da27228 615 my $prop = { %{$schema->{properties}} }; # copy
62c66c47
DM
616
617 my $has_output_format_option = $formatter_properties->{'output-format'} ? 1 : 0;
618
619 if ($formatter_properties) {
620 foreach my $key (keys %$formatter_properties) {
621 if (!$standard_output_options->{$key}) {
622 $prop->{$key} = $formatter_properties->{$key};
623 }
5c59d8f9
DM
624 }
625 }
626
627 # also remove $standard_output_options from $prop (pvesh, pveclient)
628 if ($prop->{'output-format'}) {
629 $has_output_format_option = 1;
630 foreach my $key (keys %$prop) {
631 if ($standard_output_options->{$key}) {
632 delete $prop->{$key};
633 }
62c66c47
DM
634 }
635 }
e143e9d8
DM
636
637 my $out = '';
638
639 my $arg_hash = {};
640
641 my $args = '';
1d21344c
DM
642
643 $arg_param = [ $arg_param ] if $arg_param && !ref($arg_param);
644
e143e9d8
DM
645 foreach my $p (@$arg_param) {
646 next if !$prop->{$p}; # just to be sure
1d21344c 647 my $pd = $prop->{$p};
e143e9d8
DM
648
649 $arg_hash->{$p} = 1;
650 $args .= " " if $args;
1d21344c 651 if ($pd->{format} && $pd->{format} =~ m/-list/) {
7f0f0610 652 $args .= "{<$p>}";
1d21344c
DM
653 } else {
654 $args .= $pd->{optional} ? "[<$p>]" : "<$p>";
655 }
e143e9d8
DM
656 }
657
e143e9d8
DM
658 my $argdescr = '';
659 foreach my $k (@$arg_param) {
660 next if defined($fixed_param->{$k}); # just to be sure
661 next if !$prop->{$k}; # just to be sure
4842b651 662 $argdescr .= $get_property_description->($k, 'fixed', $prop->{$k}, $format);
e143e9d8
DM
663 }
664
665 my $idx_param = {}; # -vlan\d+ -scsi\d+
666
667 my $opts = '';
668 foreach my $k (sort keys %$prop) {
669 next if $arg_hash->{$k};
670 next if defined($fixed_param->{$k});
671
77096a6f 672 my $type_text = $prop->{$k}->{type} || 'string';
e143e9d8 673
968bcf45 674 my $param_map = {};
4842b651 675
968bcf45
TL
676 if (defined($param_cb)) {
677 my $mapping = $param_cb->($name);
678 $param_map = $compute_param_mapping_hash->($mapping);
679 next if $k eq 'password' && $param_map->{$k} && !$prop->{$k}->{optional};
4842b651 680 }
e143e9d8
DM
681
682 my $base = $k;
683 if ($k =~ m/^([a-z]+)(\d+)$/) {
b546f33e 684 my ($name, $idx) = ($1, $2);
e143e9d8 685 next if $idx_param->{$name};
b54ad320 686 if ($idx == 0 && defined($prop->{"${name}1"})) {
f922b8a8
FG
687 $idx_param->{$name} = 1;
688 $base = "${name}[n]";
689 }
e143e9d8
DM
690 }
691
dfc6cff8 692
968bcf45 693 $opts .= $get_property_description->($base, 'arg', $prop->{$k}, $format, $param_map->{$k});
e143e9d8
DM
694
695 if (!$prop->{$k}->{optional}) {
696 $args .= " " if $args;
a4f181a3 697 $args .= "--$base <$type_text>"
e143e9d8
DM
698 }
699 }
700
fe3f1fde
DM
701 if ($format eq 'asciidoc') {
702 $out .= "*${prefix}*";
703 $out .= " `$args`" if $args;
62c66c47
DM
704 $out .= " `[OPTIONS]`" if $opts;
705 $out .= " `[FORMAT_OPTIONS]`" if $has_output_format_option;
706 $out .= "\n";
fe3f1fde
DM
707 } else {
708 $out .= "USAGE: " if $format ne 'short';
709 $out .= "$prefix $args";
62c66c47
DM
710 $out .= " [OPTIONS]" if $opts;
711 $out .= " [FORMAT_OPTIONS]" if $has_output_format_option;
712 $out .= "\n";
fe3f1fde 713 }
e143e9d8
DM
714
715 return $out if $format eq 'short';
716
fe3f1fde
DM
717 if ($info->{description}) {
718 if ($format eq 'asciidoc') {
719 my $desc = Text::Wrap::wrap('', '', ($info->{description}));
720 $out .= "\n$desc\n\n";
721 } elsif ($format eq 'full') {
722 my $desc = Text::Wrap::wrap(' ', ' ', ($info->{description}));
723 $out .= "\n$desc\n\n";
724 }
e143e9d8
DM
725 }
726
727 $out .= $argdescr if $argdescr;
728
729 $out .= $opts if $opts;
730
731 return $out;
732}
733
c03b7509 734sub usage_str {
9da27228 735 my ($self, $name, $prefix, $arg_param, $fixed_param, $format, $param_cb, $formatter_properties) = @_;
c03b7509
DM
736
737 my $info = $self->map_method_by_name($name);
738
9da27228 739 return getopt_usage($info, $prefix, $arg_param, $fixed_param, $format, $param_cb, $formatter_properties);
c03b7509
DM
740}
741
8fa050cd
DM
742# generate docs from JSON schema properties
743sub dump_properties {
df79b428 744 my ($prop, $format, $style, $filterFn) = @_;
8fa050cd
DM
745
746 my $raw = '';
747
df79b428
DM
748 $style //= 'config';
749
8fa050cd
DM
750 my $idx_param = {}; # -vlan\d+ -scsi\d+
751
752 foreach my $k (sort keys %$prop) {
753 my $phash = $prop->{$k};
754
755 next if defined($filterFn) && &$filterFn($k, $phash);
32f8e0c7 756 next if $phash->{alias};
8fa050cd
DM
757
758 my $base = $k;
759 if ($k =~ m/^([a-z]+)(\d+)$/) {
b546f33e 760 my ($name, $idx) = ($1, $2);
8fa050cd 761 next if $idx_param->{$name};
b54ad320 762 if ($idx == 0 && defined($prop->{"${name}1"})) {
f922b8a8
FG
763 $idx_param->{$name} = 1;
764 $base = "${name}[n]";
765 }
8fa050cd
DM
766 }
767
4842b651 768 $raw .= $get_property_description->($base, $style, $phash, $format);
32f8e0c7
DM
769
770 next if $style ne 'config';
771
772 my $prop_fmt = $phash->{format};
773 next if !$prop_fmt;
774
775 if (ref($prop_fmt) ne 'HASH') {
776 $prop_fmt = PVE::JSONSchema::get_format($prop_fmt);
777 }
778
779 next if !(ref($prop_fmt) && (ref($prop_fmt) eq 'HASH'));
780
781 $raw .= dump_properties($prop_fmt, $format, 'config-sub')
782
8fa050cd 783 }
b0e5e9fa 784
8fa050cd
DM
785 return $raw;
786}
787
408976c6 788my $replace_file_names_with_contents = sub {
968bcf45 789 my ($param, $param_map) = @_;
408976c6 790
968bcf45 791 while (my ($k, $d) = each %$param_map) {
c7171ff2 792 next if $d->{interactive}; # handled by the JSONSchema's get_options code
dfc6cff8
DM
793 $param->{$k} = $d->{func}->($param->{$k})
794 if defined($param->{$k});
408976c6
FG
795 }
796
797 return $param;
798};
799
4cbcd138
DM
800sub add_standard_output_properties {
801 my ($propdef, $list) = @_;
0adee985 802
4cbcd138 803 $propdef //= {};
0adee985 804
4cbcd138
DM
805 $list //= [ keys %$standard_output_options ];
806
807 my $res = { %$propdef }; # copy
808
809 foreach my $opt (@$list) {
810 die "no such standard output option '$opt'\n" if !defined($standard_output_options->{$opt});
811 die "detected overwriten standard CLI parameter '$opt'\n" if defined($res->{$opt});
812 $res->{$opt} = $standard_output_options->{$opt};
813 }
814
815 return $res;
816}
817
818sub extract_standard_output_properties {
819 my ($data) = @_;
820
821 my $options = {};
822 foreach my $opt (keys %$standard_output_options) {
823 $options->{$opt} = delete $data->{$opt} if defined($data->{$opt});
824 }
825
826 return $options;
827}
0adee985 828
e143e9d8 829sub cli_handler {
9da27228 830 my ($self, $prefix, $name, $args, $arg_param, $fixed_param, $param_cb, $formatter_properties) = @_;
e143e9d8
DM
831
832 my $info = $self->map_method_by_name($name);
e143e9d8 833 my $res;
9da27228
DM
834 my $fmt_param = {};
835
e143e9d8 836 eval {
968bcf45
TL
837 my $param_map = {};
838 $param_map = $compute_param_mapping_hash->($param_cb->($name)) if $param_cb;
9da27228
DM
839 my $schema = { %{$info->{parameters}} }; # copy
840 $schema->{properties} = { %{$schema->{properties}}, %$formatter_properties } if $formatter_properties;
841 my $param = PVE::JSONSchema::get_options($schema, $args, $arg_param, $fixed_param, $param_map);
842
843 if ($formatter_properties) {
844 foreach my $opt (keys %$formatter_properties) {
845 $fmt_param->{$opt} = delete $param->{$opt} if defined($param->{$opt});
846 }
847 }
dfc6cff8 848
968bcf45
TL
849 if (defined($param_map)) {
850 $replace_file_names_with_contents->($param, $param_map);
dfc6cff8
DM
851 }
852
4cbcd138 853 $res = $self->handle($info, $param);
e143e9d8
DM
854 };
855 if (my $err = $@) {
856 my $ec = ref($err);
857
858 die $err if !$ec || $ec ne "PVE::Exception" || !$err->is_param_exc();
859
9da27228 860 $err->{usage} = $self->usage_str($name, $prefix, $arg_param, $fixed_param, 'short', $param_cb, $formatter_properties);
e143e9d8
DM
861
862 die $err;
863 }
864
9da27228 865 return wantarray ? ($res, $fmt_param) : $res;
e143e9d8
DM
866}
867
868# utility methods
869# note: this modifies the original hash by adding the id property
870sub hash_to_array {
871 my ($hash, $idprop) = @_;
872
873 my $res = [];
874 return $res if !$hash;
875
876 foreach my $k (keys %$hash) {
877 $hash->{$k}->{$idprop} = $k;
878 push @$res, $hash->{$k};
879 }
880
881 return $res;
882}
883
8841;