src/PVE/PodParser.pm

   1 package PVE::PodParser;
   2
   3 use strict;
   4 use warnings;
   5 use Pod::Parser;
   6 use base qw(Pod::Parser);
   7
   8 my $currentYear = (localtime(time))[5] + 1900;
   9
  10 my $stdinclude = {
  11     pve_copyright => <<EODATA,
  12 \=head1 COPYRIGHT AND DISCLAIMER
  13
  14 Copyright (C) 2007-$currentYear Proxmox Server Solutions GmbH
  15
  16 This program is free software: you can redistribute it and\/or modify
  17 it under the terms of the GNU Affero General Public License as
  18 published by the Free Software Foundation, either version 3 of the
  19 License, or (at your option) any later version.
  20
  21 This program is distributed in the hope that it will be useful,
  22 but WITHOUT ANY WARRANTY; without even the implied warranty of
  23 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  24 GNU Affero General Public License for more details.
  25
  26 You should have received a copy of the GNU Affero General Public License
  27 along with this program.  If not, see L<http://www.gnu.org/licenses/>.
  28 EODATA
  29 };
  30
  31 sub command {
  32     my ($self, $cmd, $text, $line_num, $pod_para)  = @_;
  33
  34     if (($cmd eq 'include' && $text =~ m/^\s*(\S+)\s/)) {
  35         my $incl = $1;
  36         my $data = $stdinclude->{$incl} ? $stdinclude->{$incl} :
  37             $self->{include}->{$incl};
  38         chomp $data;
  39         $self->textblock("$data\n\n", $line_num, $pod_para);
  40     } else {
  41         $self->textblock($pod_para->raw_text(), $line_num, $pod_para);
  42     }
  43 }
  44
  45 # helpers used to generate our manual pages
  46
  47 sub schema_get_type_text {
  48     my ($phash) = @_;
  49
  50     if ($phash->{typetext}) {
  51         return $phash->{typetext};
  52     } elsif ($phash->{enum}) {
  53         return "(" . join(' | ', sort @{$phash->{enum}}) . ")";
  54     } elsif ($phash->{pattern}) {
  55         return $phash->{pattern};
  56     } elsif ($phash->{type} eq 'integer' || $phash->{type} eq 'number') {
  57         if (defined($phash->{minimum}) && defined($phash->{maximum})) {
  58             return "$phash->{type} ($phash->{minimum} - $phash->{maximum})";
  59         } elsif (defined($phash->{minimum})) {
  60             return "$phash->{type} ($phash->{minimum} - N)";
  61         } elsif (defined($phash->{maximum})) {
  62             return "$phash->{type} (-N - $phash->{maximum})";
  63         }
  64     }
  65
  66     my $type = $phash->{type} || 'string';
  67
  68     return $type;
  69 }
  70
  71 # generta epop from JSON schema properties
  72 sub dump_properties {
  73     my ($properties) = @_;
  74
  75     my $data = "=over 1\n\n";
  76
  77     my $idx_param = {}; # -vlan\d+ -scsi\d+
  78
  79     foreach my $key (sort keys %$properties) {
  80         my $d = $properties->{$key};
  81         my $base = $key;
  82         if ($key =~ m/^([a-z]+)(\d+)$/) {
  83             my $name = $1;
  84             next if $idx_param->{$name};
  85             $idx_param->{$name} = 1;
  86             $base = "${name}[n]";
  87         }
  88
  89         my $descr = $d->{description} || 'No description avalable.';
  90         chomp $descr;
  91
  92         if (defined(my $dv = $d->{default})) {
  93             my $multi = $descr =~ m/\n\n/; # multi paragraph ?
  94             $descr .= $multi ? "\n\n" : " ";
  95             $descr .= "Default value is '$dv'.";
  96         }
  97
  98         my $typetext = schema_get_type_text($d);
  99         $data .= "=item $base: $typetext\n\n";
 100         $data .= "$descr\n\n";
 101     }
 102
 103     $data .= "=back";
 104
 105     return $data;
 106 }
 107
 108 1;