]>
Commit | Line | Data |
---|---|---|
d08a7e4c RJ |
1 | #!/usr/bin/perl |
2 | # Generate the Summary of Library Facilities (summary.texi). | |
3 | ||
2b778ceb | 4 | # Copyright (C) 2017-2021 Free Software Foundation, Inc. |
d08a7e4c | 5 | # This file is part of the GNU C Library. |
d08a7e4c RJ |
6 | |
7 | # The GNU C Library is free software; you can redistribute it and/or | |
8 | # modify it under the terms of the GNU Lesser General Public License | |
9 | # as published by the Free Software Foundation; either version 2.1 of | |
10 | # the License, or (at your option) any later version. | |
11 | ||
12 | # The GNU C Library is distributed in the hope that it will be useful, | |
13 | # but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
15 | # Lesser General Public License for more details. | |
16 | ||
17 | # You should have received a copy of the GNU Lesser General Public | |
18 | # License along with the GNU C Library; if not, see | |
5a82c748 | 19 | # <https://www.gnu.org/licenses/>. |
d08a7e4c RJ |
20 | |
21 | # Anything declared in a header or defined in a standard should have | |
22 | # its origins annotated using the @standards macro (see macro.texi). | |
23 | # This script checks all such elements in the manual (generally, | |
24 | # @def|item*-commands), ensuring annotations are present and correct. | |
25 | # If any errors are detected, they are all reported at the end and | |
26 | # failure is indicated. | |
27 | ||
28 | use strict; | |
29 | use warnings; | |
30 | use locale; | |
31 | use File::Basename; | |
32 | ||
33 | $| = 1; | |
34 | my $script = basename $0; | |
35 | ||
36 | &help if $ARGV[0] eq "--help"; # Will exit(0). | |
37 | ||
38 | my @texis = @ARGV; | |
39 | ||
40 | # Various regexes. | |
41 | my $nde = qr/^\@node /; | |
42 | my $def = qr/^\@def/; | |
43 | my $itm = qr/^\@item /; | |
44 | my $itms = qr/^\@itemx? /; # Don't match @itemize. | |
45 | my $ann = qr/^\@(def\w+|item)x? /; # Annotatable. | |
46 | my $std = qr/^\@standards\{/; | |
47 | my $stx = qr/^\@standardsx\{/; | |
48 | my $stds = qr/^\@standardsx?\{/; | |
49 | my $strict_std = qr/^\@standards\{([^,]+, )[^,\}]+\}$/; | |
50 | my $strict_stx = qr/^\@standardsx\{([^,]+, ){2}[^,\}]+\}$/; | |
51 | my $lcon = qr/([vf]?table|itemize|enumerate)/; | |
52 | my $list = qr/^\@${lcon}/; | |
53 | my $endl = qr/^\@end ${lcon}/; | |
54 | my $ign = qr/^\@ignore/; | |
55 | my $eig = qr/^\@end ignore/; | |
56 | ||
57 | # Global scope. | |
58 | my $node; | |
59 | our $texi; | |
60 | my $input; | |
61 | my %entries; | |
62 | my %errors; | |
63 | ||
64 | for $texi (@texis) { | |
65 | open $input, '<', $texi or die "open $texi: $!"; | |
66 | while (my $line = <$input>) { | |
67 | if ($line =~ $nde) { | |
68 | $node = &get_node($line); | |
69 | } elsif ($line =~ $def) { | |
70 | &process_annotation($line); | |
71 | } elsif ($line =~ $list) { | |
72 | &process_list($1); # @items occur in list or table context. | |
73 | } elsif ($line =~ $stds) { | |
74 | &record_error("Misplaced annotation", ["[$.] ".$line]); | |
75 | } elsif ($line =~ $ign) { | |
76 | while (<$input> !~ $eig) {} | |
77 | } | |
78 | } | |
79 | close $input or die "close $texi: $!"; | |
80 | } | |
81 | ||
82 | # Disabled until annotations are complete. | |
83 | &print_errors() if %errors && 0; # Will exit(1). | |
84 | ||
85 | print("\@c DO NOT EDIT THIS FILE!\n". | |
86 | "\@c This file is generated by $script from the Texinfo sources.\n". | |
87 | "\@c The \@items are \@include'd from a \@table in header.texi.\n\n"); | |
88 | ||
89 | &print_entry($_) for sort keys %entries; | |
90 | ||
91 | # Processes an annotatable element, including any subsequent elements | |
92 | # in an @*x chain, ensuring @standards are present, with valid syntax, | |
93 | # either recording any errors detected or creating Summary entries. | |
94 | # This function is the heart of the script. | |
95 | # | |
96 | # Prototypes and standards are gathered into separate lists and used | |
97 | # to evaluate the completeness and correctness of annotations before | |
98 | # generating the Summary entries. "Prototype" is used to refer to an | |
99 | # element's entire definition while avoiding conflation with | |
100 | # @def*-commands. "Element" is strictly used here to refer to the | |
101 | # name extracted from the prototype, as used in @standardsx, for | |
102 | # sorting the Summary. | |
103 | sub process_annotation | |
104 | { | |
105 | my $line = shift; | |
106 | my (@prototypes, @standards, $i, @tmp); | |
107 | ||
108 | # Gather prototypes and standards. | |
109 | push @prototypes, $line; | |
110 | while ($line = <$input>) { | |
111 | last if $line !~ $ann; | |
112 | push @prototypes, $line; | |
113 | } | |
114 | if ($line !~ $stds) { # The fundamental error. | |
115 | return &record_error('Missing annotation', \@prototypes); | |
116 | } | |
117 | push @standards, $line; | |
118 | push @standards, $line while ($line = <$input>) =~ $stds; | |
119 | ||
120 | # If next line is an @item, seek back to catch it on the next | |
121 | # iteration. This avoids imposing a non-Texinfo syntax | |
122 | # requirement of blank lines between consecutive annotated @items. | |
123 | if ($line =~ $itm) { | |
124 | seek $input, -length($line), 1 or die "seek: $!"; | |
125 | } | |
126 | ||
127 | # Strict check for syntax errors. Other matches are loose, which | |
128 | # aids error detection and reporting by ensuring things that look | |
129 | # like standards aren't simply passed over, but caught here. | |
130 | for ($i=0; $i<@standards; ++$i) { | |
131 | my $standard = $standards[$i]; | |
132 | if ($standard !~ $strict_std && $standard !~ $strict_stx) { | |
133 | push @tmp, $standard; | |
134 | } | |
135 | } | |
136 | return &record_error('Invalid syntax', \@tmp) if @tmp; | |
137 | ||
138 | # @standardsx should not be in non-@*x chains. | |
139 | if (@prototypes == 1) { | |
140 | for ($i=0; $i<@standards; ++$i) { | |
141 | return &record_error('Misplaced @standardsx', \@prototypes) | |
142 | if $standards[$i] =~ $stx; | |
143 | } | |
144 | } | |
145 | # @standards may only occur once in @*x chains, at the beginning. | |
146 | if (@prototypes > 1) { | |
147 | for ($i=1; $i<@standards; ++$i) { | |
148 | return &record_error('Misplaced @standards', \@prototypes) | |
149 | if $standards[$i] =~ $std; | |
150 | } | |
151 | } | |
152 | ||
153 | # The @standards are aligned. | |
154 | &add_entries(\@prototypes, \@standards); | |
155 | } | |
156 | ||
157 | # Goes through the prototypes, cleaning them up and extracting the | |
158 | # elements, pairing them with the appropriate annotations to create | |
159 | # Summary entries. | |
160 | sub add_entries | |
161 | { | |
162 | my ($prototypes, $standards) = @_; | |
163 | my $isx = @{$prototypes} > 1 ? 1 : 0; | |
164 | my $allx = $standards->[0] =~ $stx ? 1 : 0; | |
165 | my ($defstd, $defhdr, %standardsx, $i, $j); | |
166 | ||
167 | # Grab the default annotation and index any @standardsx. Take | |
168 | # care in case there is no default. | |
169 | if ($isx) { | |
170 | if (!$allx) { | |
171 | ($defstd, $defhdr) | |
172 | = $standards->[0] =~ /${std}([^,]+), (.*)\}$/; | |
173 | } | |
174 | for ($i = $allx ? 0 : 1; $i<@{$standards}; ++$i) { | |
175 | my ($e, $s, $h) | |
176 | = $standards->[$i] =~ /${stx}([^,]+), ([^,]+), (.*)\}$/; | |
177 | push @{$standardsx{$e}{hs}}, [$h, $s]; | |
178 | } | |
179 | } | |
180 | ||
181 | for ($i=0; $i<@{$prototypes}; ++$i) { | |
182 | my $e = &get_element($prototypes->[$i]); | |
183 | my $p = &get_prototype($prototypes->[$i]); | |
184 | my ($s, $h); | |
185 | if ($isx && exists $standardsx{$e}) { | |
186 | for ($j=0; $j<@{$standardsx{$e}{hs}}; ++$j) { | |
187 | $h = $standardsx{$e}{hs}[$j]->[0]; | |
188 | $s = $standardsx{$e}{hs}[$j]->[1]; | |
189 | &record_entry($e, $p, $h, $s, $node); | |
190 | ++$standardsx{$e}{seen}; | |
191 | } | |
192 | } elsif ($isx && $allx) { | |
193 | &record_error('Missing annotation', [$prototypes->[$i]]); | |
194 | } elsif ($isx) { | |
195 | &record_entry($e, $p, $defhdr, $defstd, $node); | |
196 | } else { | |
197 | for ($j=0; $j<@{$standards}; ++$j) { | |
198 | ($s, $h) = $standards->[$j] =~ /${std}([^,]+), ([^,\}]+)\}$/; | |
199 | &record_entry($e, $p, $h, $s, $node); | |
200 | } | |
201 | } | |
202 | } | |
203 | ||
204 | # Check if there were any unmatched @standardsx. | |
205 | for my $e (keys %standardsx) { | |
206 | if (!exists $standardsx{$e}{seen}) { | |
207 | &record_error('Spurious @standardsx', [$e."\n"]) | |
208 | } | |
209 | } | |
210 | } | |
211 | ||
212 | # Stores a Summary entry in %entries. May be called multiple times | |
213 | # per element if multiple header and standard annotations exist. Also | |
214 | # keys on prototypes, as some elements have multiple prototypes. See | |
215 | # isnan in arith.texi for one example. | |
216 | sub record_entry | |
217 | { | |
218 | my ($ele, $proto, $hdr, $std, $node) = @_; | |
219 | push @{$entries{$ele}{$proto}}, [$hdr, $std, $node]; | |
220 | } | |
221 | ||
222 | # Processes list or table contexts, with nesting. | |
223 | sub process_list | |
224 | { | |
225 | my $type = shift; | |
226 | my $in_vtbl = $type eq "vtable" ? 1 : 0; | |
227 | ||
228 | while (my $line = <$input>) { | |
229 | if ($line =~ $itms) { | |
230 | next if ! $in_vtbl; # Not an annotatable context. | |
231 | &process_annotation($line); | |
232 | } elsif ($line =~ $def) { | |
233 | &process_annotation($line); | |
234 | } elsif ($line =~ $stds) { | |
235 | &record_error('Misplaced annotation', ["[$.] ".$line]); | |
236 | } elsif ($line =~ $endl) { | |
237 | return; # All done. | |
238 | } elsif ($line =~ $list) { | |
239 | &process_list($1); # Nested list. | |
240 | } | |
241 | } | |
242 | } | |
243 | ||
244 | # Returns the current node from an @node line. Used for referencing | |
245 | # from the Summary. | |
246 | sub get_node | |
247 | { | |
248 | my $line = shift; | |
249 | chomp $line; | |
250 | $line =~ s/$nde//; | |
251 | my ($n) = split ',', $line; | |
252 | return $n | |
253 | } | |
254 | ||
255 | # Returns the cleaned up prototype from @def|item* lines. | |
256 | sub get_prototype | |
257 | { | |
258 | my $dfn = shift; | |
259 | chomp $dfn; | |
260 | $dfn =~ s/\s+/ /g; # Collapse whitespace. | |
261 | $dfn =~ s/ \{([^\}]*)\} / $1 /g; # Remove grouping braces. | |
262 | $dfn =~ s/^\@\S+ //; # Remove @-command. | |
263 | $dfn =~ s/^Macro //i; # Scrape off cruft... | |
264 | $dfn =~ s/^Data Type //i; | |
265 | $dfn =~ s/^Variable //i; | |
266 | $dfn =~ s/^Deprecated Function //i; | |
267 | $dfn =~ s/^SVID Macro //i; | |
268 | $dfn =~ s/^Obsolete function //i; | |
269 | $dfn =~ s/^Constant //i; | |
270 | $dfn =~ s/^Type //i; | |
271 | $dfn =~ s/^Function //i; | |
272 | $dfn =~ s/^\{(.*)\}$/$1/; # Debrace yourself. | |
273 | $dfn =~ s/^\{([^\}]*)\} /$1 /; # These ones too. | |
274 | return $dfn; | |
275 | } | |
276 | ||
277 | # Returns an annotated element's name. | |
278 | # | |
279 | # Takes a line defining an annotatable element (e.g., @def|item*), | |
280 | # splitting it on whitespace. The element is generally detected as | |
281 | # the member immediately preceding the first parenthesized expression | |
282 | # (e.g., a function), or the last token in the list. Some additional | |
283 | # cleanup is applied to the element before returning it. | |
284 | sub get_element | |
285 | { | |
286 | my $i = 0; | |
287 | my @toks = split /\s+/, shift; | |
288 | # tzname array uses '['; don't match function pointers. | |
289 | ++$i while $toks[$i] && $toks[$i] !~ /^[\(\[](?!\*)/; | |
290 | $toks[$i-1] =~ s/^\*//; # Strip pointer type syntax. | |
291 | $toks[$i-1] =~ s/^\{?([^\}]+)\}?$/$1/; # Strip braces. | |
292 | $toks[$i-1] =~ s/^\(\*([^\)]+)\)$/$1/; # Function pointers. | |
293 | return $toks[$i-1]; | |
294 | } | |
295 | ||
296 | # Records syntax errors detected in the manual related to @standards. | |
297 | # The @def|item*s are grouped by file, then errors, to make it easier | |
298 | # to track down exactly where and what the problems are. | |
299 | sub record_error | |
300 | { | |
301 | my ($err, $list) = @_; | |
302 | push @{$errors{$texi}{$err}}, $_ for (@{$list}); | |
303 | return 0; | |
304 | } | |
305 | ||
306 | # Reports all detected errors and exits with failure. Indentation is | |
307 | # used for readability, and "ERROR" is used for visibility. | |
308 | sub print_errors | |
309 | { | |
310 | for $texi (sort keys %errors) { | |
311 | print STDERR "ERRORS in $texi:\n"; | |
312 | for my $err (sort keys %{$errors{$texi}}) { | |
313 | print STDERR " $err:\n"; | |
314 | print STDERR " $_" for (@{$errors{$texi}{$err}}); | |
315 | } | |
316 | } | |
317 | print(STDERR "\nFor a description of expected syntax, see ". | |
318 | "\`$script --help'\n\n"); | |
319 | exit 1; | |
320 | } | |
321 | ||
322 | # Prints an entry in the Summary. | |
323 | # | |
324 | # All the blank lines in summary.texi may seem strange at first, but | |
325 | # they have significant impact on how Texinfo renders the output. | |
326 | # Essentially, each line is its own paragraph. There is a @comment | |
327 | # with the element name, arguably unnecessary, but useful for seeing | |
328 | # the sorting order and extracted element names, and maintains the | |
329 | # format established by summary.awk. Each @item in the @table is the | |
330 | # prototype, which may be anything from just a variable name to a | |
331 | # function declaration. The body of each @item contains lines | |
332 | # annotating the headers and standards each element is declared | |
333 | # in/comes from, with a reference to the @node documenting the element | |
334 | # wrt. each header and standard combination. | |
335 | sub print_entry | |
336 | { | |
337 | my $element = shift; | |
338 | for my $prototype (sort keys %{$entries{$element}}) { | |
339 | print "\@comment $element\n\@item $prototype\n\n"; | |
340 | for (@{$entries{$element}{$prototype}}) { | |
341 | my ($header, $standard, $node) | |
342 | = ($_->[0], $_->[1], $_->[2]); | |
343 | if ($header =~ /^\(none\)$/i) { | |
344 | $header = "\@emph{no header}"; | |
345 | } elsif ($header =~ /\(optional\)$/) { | |
346 | $header =~ s/^(\S+) \((.*)\)$/\@file{$1} \@emph{$2}/; | |
347 | } elsif ($header ne '???') { | |
348 | $header = "\@file{$header}"; | |
349 | } | |
350 | print "$header ($standard): \@ref{$node}.\n\n"; | |
351 | } | |
352 | } | |
353 | } | |
354 | ||
355 | # Document the syntax of @standards. | |
356 | sub help | |
357 | { | |
358 | print "$script "; | |
359 | print <<'EOH'; | |
360 | generates the Summary of Library Facilities (summary.texi) | |
361 | from @standards and @standardsx macros in the Texinfo sources (see | |
362 | macros.texi). While generating the Summary, it also checks that | |
363 | @standards are used, correctly. | |
364 | ||
365 | In general, any @def*-command or @item in a @vtable is considered | |
366 | annotatable. "Misplaced annotation" refers to @standards macros | |
367 | detected outside an annotatable context. "Missing annotation" refers | |
368 | to annotatable elements without @standards. @standards are expected | |
369 | to immediately follow the elements being annotated. In @*x lists, | |
370 | @standards sets the default annotation and may only occur as the first | |
371 | annotation ("Misplaced @standards"). @standardsx may not be used | |
372 | outside @*x lists ("Misplaced @standardsx"). "Spurious @standardsx" | |
373 | refers to otherwise valid @standardsx macros that were not matched to | |
374 | an element in an @*x list. "Invalid syntax" means just that. | |
375 | ||
5295172e | 376 | The syntax of @standards annotations is designed to accommodate |
d08a7e4c RJ |
377 | multiple header and standards annotations, as necessary. |
378 | ||
379 | Examples: | |
380 | ||
381 | @deftp FOO | |
382 | @standards{STD, HDR} | |
383 | ||
384 | @defvar BAR | |
385 | @standards{STD, HDR1} | |
386 | @standards{STD, HDR2} | |
387 | ||
388 | @deftypefun foo | |
389 | @deftypefunx fool | |
390 | @standards{STD, HDR} | |
391 | ||
392 | @item bar | |
393 | @itemx baz | |
394 | @standardsx{bar, STD1, HDR1} | |
395 | @standardsx{baz, STD1, HDR1} | |
396 | @standardsx{baz, STD2, HDR2} | |
397 | ||
398 | Note that @standardsx deviates from the usual Texinfo syntax in that | |
399 | it is optional and may be used without @standards. | |
400 | EOH | |
401 | ; exit 0; | |
402 | } |