+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);
+ my $cmdstr = $exename;
+
+ if (ref($argv) eq 'ARRAY') {
+ my $expanded_last_arg;
+ my $last_arg_id = scalar(@$argv) - 1;
+
+ for my $i (0..$last_arg_id) {
+ $cmd = $expand_command_name->($def, $argv->[$i]);
+ if (defined($cmd)) {
+ # If the argument was expanded (or was already complete) and it
+ # is the final argument, tell our caller about it:
+ $expanded_last_arg = $cmd if $i == $last_arg_id;
+ } else {
+ # Otherwise continue with the unexpanded version of it.
+ $cmd = $argv->[$i];
+ }
+ $cmdstr .= " $cmd";
+ $def = $def->{$cmd};
+ last if !defined($def);
+
+ 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_last_arg, $cmdstr);
+ }
+
+ 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_last_arg, $cmdstr);
+ }
+ return ($cmd, $def, undef, undef, $cmdstr);
+}
+
+sub generate_usage_str {
+ my ($format, $cmd, $indent, $separator, $sortfunc) = @_;
+
+ $assert_initialized->();
+ die 'format required' if !$format;
+
+ $sortfunc //= sub { sort keys %{$_[0]} };
+ $separator //= '';
+ $indent //= '';
+
+ my $param_cb = $gen_param_mapping_func->($cli_handler_class);
+
+ my ($subcmd, $def, undef, undef, $cmdstr) = resolve_cmd($cmd);
+ $abort->("unknown command '$cmdstr'") if !defined($def) && ref($cmd) eq 'ARRAY';
+
+ my $generate;
+ $generate = sub {
+ my ($indent, $separator, $def, $prefix) = @_;
+
+ my $str = '';
+ if (ref($def) eq 'HASH') {
+ my $oldclass = undef;
+ foreach my $cmd (&$sortfunc($def)) {
+
+ if (ref($def->{$cmd}) eq 'ARRAY') {
+ my ($class, $name, $arg_param, $fixed_param) = @{$def->{$cmd}};
+
+ $str .= $separator if $oldclass && $oldclass ne $class;
+ $str .= $indent;
+ $str .= $class->usage_str($name, "$prefix $cmd", $arg_param,
+ $fixed_param, $format, $param_cb);
+ $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;
+ }
+ }
+
+ }
+ } else {
+ my ($class, $name, $arg_param, $fixed_param) = @$def;
+ $abort->("unknown command '$cmd'") if !$class;
+
+ $str .= $indent;
+ $str .= $class->usage_str($name, $prefix, $arg_param, $fixed_param, $format, $param_cb);
+ }
+ return $str;
+ };
+
+ return $generate->($indent, $separator, $def, $cmdstr);
+}
+