1package OpenXPKI::Server::API2::Plugin::Api::api_help;
2use OpenXPKI::Server::API2::EasyPlugin;
3
4=head1 NAME
5
6OpenXPKI::Server::API2::Plugin::Api::api_help
7
8=cut
9
10# CPAN modules
11use Pod::POM;
12
13# Project modules
14use OpenXPKI::Server::API2::Plugin::Api::Util::ModuleFinder;
15use OpenXPKI::Server::API2::Plugin::Api::Util::PodPOMView;
16
17=head1 COMMANDS
18
19=head2 api_help
20
21Returns a description of the given API command.
22
23The documentation is read from the source code POD documentation.
24
25B<Parameters>
26
27=over
28
29=item * C<command> I<Str> - name of the API command
30
31=back
32
33=cut
34command "api_help" => {
35    command => { isa => 'Str', required => 1 },
36} => sub {
37    my ($self, $params) = @_;
38
39    my $command = $params->command;
40
41    # query the 'command => package' mapping
42    my $package = $self->rawapi->commands->{$command};
43    return "ERROR: Unknown API command '$command'" unless $package;
44
45    # find module path
46    my $path = OpenXPKI::Server::API2::Plugin::Api::Util::ModuleFinder
47        ->new
48        ->find($package);
49    return "ERROR: Could not find module with package '$package'" unless $path;
50
51    # format module POD
52    my $pom = Pod::POM->new;
53    my $view = OpenXPKI::Server::API2::Plugin::Api::Util::PodPOMView->new;
54
55    my $tree = $pom->parse_file($path)
56        or return "ERROR: ".$pom->error();
57
58    my @heading_blocks = grep { $_->title eq "COMMANDS" } $tree->head1;
59    return "ERROR: Missing section COMMANDS in $path" unless scalar @heading_blocks;
60
61    my @cmd_blocks = grep { $_->title eq $command } $heading_blocks[0]->head2;
62    return "ERROR: No description found for '$command' in $path" unless scalar @cmd_blocks;
63
64    return sprintf "%s\n", $cmd_blocks[0]->present($view);
65};
66
67__PACKAGE__->meta->make_immutable;
68