fix spelling errors
[pve-common.git] / 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 generate_typetext {
48     my ($schema) = @_;
49     my $typetext = '';
50     my (@optional, @required);
51     foreach my $key (sort keys %$schema) {
52         next if !$schema->{$key}->{format_description} &&
53                 !$schema->{$key}->{typetext};
54         if ($schema->{$key}->{optional}) {
55             push @optional, $key;
56         } else {
57             push @required, $key;
58         }
59     }
60     my ($pre, $post) = ('', '');
61     my $add = sub {
62         my ($key) = @_;
63         $typetext .= $pre;
64         my $entry = $schema->{$key};
65         if (my $alias = $entry->{alias}) {
66             $key = $alias;
67             $entry = $schema->{$key};
68         }
69         if (my $desc = $entry->{format_description}) {
70             $typetext .= $entry->{default_key} ? "[$key=]" : "$key=";
71             $typetext .= "<$desc>";
72         } elsif (my $text = $entry->{typetext}) {
73             $typetext .= $text;
74         } else {
75             die "internal error: neither format_description nor typetext found";
76         }
77         $typetext .= $post;
78     };
79     foreach my $key (@required) {
80         &$add($key);
81         $pre = ', ';
82     }
83     $pre = $pre ? ' [,' : '[';
84     $post = ']';
85     foreach my $key (@optional) {
86         &$add($key);
87         $pre = ' [,';
88     }
89     return $typetext;
90 }
91
92 sub schema_get_type_text {
93     my ($phash) = @_;
94
95     if ($phash->{typetext}) {
96         return $phash->{typetext};
97     } elsif ($phash->{enum}) {
98         return "(" . join(' | ', sort @{$phash->{enum}}) . ")";
99     } elsif ($phash->{pattern}) {
100         return $phash->{pattern};
101     } elsif ($phash->{type} eq 'integer' || $phash->{type} eq 'number') {
102         if (defined($phash->{minimum}) && defined($phash->{maximum})) {
103             return "$phash->{type} ($phash->{minimum} - $phash->{maximum})";
104         } elsif (defined($phash->{minimum})) {
105             return "$phash->{type} ($phash->{minimum} - N)";
106         } elsif (defined($phash->{maximum})) {
107             return "$phash->{type} (-N - $phash->{maximum})";
108         }
109     } elsif ($phash->{type} eq 'string') {
110         if (my $format = $phash->{format}) {
111             $format = PVE::JSONSchema::get_format($format) if ref($format) ne 'HASH';
112             if (ref($format) eq 'HASH') {
113                 return generate_typetext($format);
114             }
115         }
116     }
117
118     my $type = $phash->{type} || 'string';
119
120     return $type;
121 }
122
123 sub generate_property_text {
124     my ($schema) = @_;
125     my $data = '';
126     foreach my $key (sort keys %$schema) {
127         my $d = $schema->{$key};
128         next if $d->{alias};
129         my $desc = $d->{description};
130         my $typetext = schema_get_type_text($d);
131         $desc = 'No description available' if !$desc;
132         $data .= "=item $key: $typetext\n\n$desc\n\n";
133     }
134     return $data;
135 }
136
137 # generate pod from JSON schema properties
138 sub dump_properties {
139     my ($properties) = @_;
140
141     my $data = "=over 1\n\n";
142
143     my $idx_param = {}; # -vlan\d+ -scsi\d+
144
145     foreach my $key (sort keys %$properties) {
146         my $d = $properties->{$key};
147         my $base = $key;
148         if ($key =~ m/^([a-z]+)(\d+)$/) {
149             my $name = $1;
150             next if $idx_param->{$name};
151             $idx_param->{$name} = 1;
152             $base = "${name}[n]";
153         }
154
155         my $descr = $d->{description} || 'No description avalable.';
156         chomp $descr;
157
158         if (defined(my $dv = $d->{default})) {
159             my $multi = $descr =~ m/\n\n/; # multi paragraph ?
160             $descr .= $multi ? "\n\n" : " ";
161             $descr .= "Default value is '$dv'.";
162         }
163
164         my $typetext = schema_get_type_text($d);
165         $data .= "=item $base: $typetext\n\n";
166         $data .= "$descr\n\n";
167
168         if ($d->{type} eq 'string') {
169             my $format = $d->{format};
170             if ($format && ref($format) eq 'HASH') {
171                 $data .= "=over 1.1\n\n";
172                 $data .= generate_property_text($format);
173                 $data .= "=back\n\n";
174             }
175         }
176     }
177
178     $data .= "=back";
179
180     return $data;
181 }
182
183 1;