Commit | Line | Data |
94bdecf9 |
1 | #!/usr/bin/perl -w |
6294c161 |
2 | # |
3 | # Unconditionally regenerate: |
4 | # |
5 | # pod/perlintern.pod |
6 | # pod/perlapi.pod |
7 | # |
8 | # from information stored in |
9 | # |
10 | # embed.fnc |
11 | # plus all the .c and .h files listed in MANIFEST |
12 | # |
13 | # Has an optional arg, which is the directory to chdir to before reading |
14 | # MANIFEST and *.[ch]. |
15 | # |
16 | # This script is normally invoked as part of 'make all', but is also |
17 | # called from from regen.pl. |
94bdecf9 |
18 | |
56a0c332 |
19 | use strict; |
a64c954a |
20 | |
94bdecf9 |
21 | # |
346f75ff |
22 | # See database of global and static function prototypes in embed.fnc |
94bdecf9 |
23 | # This is used to generate prototype headers under various configurations, |
24 | # export symbols lists for different platforms, and macros to provide an |
25 | # implicit interpreter context argument. |
26 | # |
27 | |
94bdecf9 |
28 | my %apidocs; |
29 | my %gutsdocs; |
30 | my %docfuncs; |
7eb550cf |
31 | my %seenfuncs; |
94bdecf9 |
32 | |
33 | my $curheader = "Unknown section"; |
34 | |
35 | sub autodoc ($$) { # parse a file and extract documentation info |
36 | my($fh,$file) = @_; |
37 | my($in, $doc, $line); |
38 | FUNC: |
39 | while (defined($in = <$fh>)) { |
40 | if ($in=~ /^=head1 (.*)/) { |
41 | $curheader = $1; |
42 | next FUNC; |
43 | } |
44 | $line++; |
78c9d763 |
45 | if ($in =~ /^=for\s+apidoc\s+(.*?)\s*\n/) { |
94bdecf9 |
46 | my $proto = $1; |
47 | $proto = "||$proto" unless $proto =~ /\|/; |
48 | my($flags, $ret, $name, @args) = split /\|/, $proto; |
49 | my $docs = ""; |
50 | DOC: |
51 | while (defined($doc = <$fh>)) { |
94bdecf9 |
52 | $line++; |
53 | last DOC if $doc =~ /^=\w+/; |
54 | if ($doc =~ m:^\*/$:) { |
55 | warn "=cut missing? $file:$line:$doc";; |
56 | last DOC; |
57 | } |
58 | $docs .= $doc; |
59 | } |
60 | $docs = "\n$docs" if $docs and $docs !~ /^\n/; |
61 | if ($flags =~ /m/) { |
62 | if ($flags =~ /A/) { |
63 | $apidocs{$curheader}{$name} = [$flags, $docs, $ret, $file, @args]; |
64 | } |
65 | else { |
66 | $gutsdocs{$curheader}{$name} = [$flags, $docs, $ret, $file, @args]; |
67 | } |
68 | } |
69 | else { |
70 | $docfuncs{$name} = [$flags, $docs, $ret, $file, $curheader, @args]; |
71 | } |
d65113e3 |
72 | $seenfuncs{$name} = 1; |
94bdecf9 |
73 | if (defined $doc) { |
e509e693 |
74 | if ($doc =~ /^=(?:for|head)/) { |
94bdecf9 |
75 | $in = $doc; |
76 | redo FUNC; |
77 | } |
78 | } else { |
79 | warn "$file:$line:$in"; |
80 | } |
81 | } |
82 | } |
83 | } |
84 | |
85 | sub docout ($$$) { # output the docs for one function |
86 | my($fh, $name, $docref) = @_; |
87 | my($flags, $docs, $ret, $file, @args) = @$docref; |
d8c40edc |
88 | $name =~ s/\s*$//; |
94bdecf9 |
89 | |
90 | $docs .= "NOTE: this function is experimental and may change or be |
91 | removed without notice.\n\n" if $flags =~ /x/; |
92 | $docs .= "NOTE: the perl_ form of this function is deprecated.\n\n" |
93 | if $flags =~ /p/; |
94 | |
d8c40edc |
95 | print $fh "=item $name\nX<$name>\n$docs"; |
94bdecf9 |
96 | |
97 | if ($flags =~ /U/) { # no usage |
98 | # nothing |
99 | } elsif ($flags =~ /s/) { # semicolon ("dTHR;") |
100 | print $fh "\t\t$name;\n\n"; |
101 | } elsif ($flags =~ /n/) { # no args |
102 | print $fh "\t$ret\t$name\n\n"; |
103 | } else { # full usage |
104 | print $fh "\t$ret\t$name"; |
105 | print $fh "(" . join(", ", @args) . ")"; |
106 | print $fh "\n\n"; |
107 | } |
108 | print $fh "=for hackers\nFound in file $file\n\n"; |
109 | } |
110 | |
7b73ff98 |
111 | sub output { |
112 | my ($podname, $header, $dochash, $footer) = @_; |
113 | my $filename = "pod/$podname.pod"; |
114 | open my $fh, '>', $filename or die "Can't open $filename: $!"; |
115 | |
116 | print $fh <<"_EOH_", $header; |
e0492643 |
117 | -*- buffer-read-only: t -*- |
118 | |
119 | !!!!!!! DO NOT EDIT THIS FILE !!!!!!! |
120 | This file is built by $0 extracting documentation from the C source |
121 | files. |
122 | |
123 | _EOH_ |
e0492643 |
124 | |
7b73ff98 |
125 | my $key; |
126 | # case insensitive sort, with fallback for determinacy |
127 | for $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %$dochash) { |
128 | my $section = $dochash->{$key}; |
129 | print $fh "\n=head1 $key\n\n=over 8\n\n"; |
130 | # Again, fallback for determinacy |
131 | for my $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %$section) { |
132 | docout($fh, $key, $section->{$key}); |
133 | } |
134 | print $fh "\n=back\n"; |
135 | } |
136 | |
137 | print $fh $footer, <<'_EOF_'; |
e0492643 |
138 | =cut |
139 | |
3f98fbb3 |
140 | ex: set ro: |
e0492643 |
141 | _EOF_ |
7b73ff98 |
142 | |
143 | close $fh or die "Can't close $filename: $!"; |
e0492643 |
144 | } |
145 | |
cd093254 |
146 | if (@ARGV) { |
147 | my $workdir = shift; |
148 | chdir $workdir |
149 | or die "Couldn't chdir to '$workdir': $!"; |
150 | } |
151 | |
94bdecf9 |
152 | my $file; |
69e39a9a |
153 | # glob() picks up docs from extra .c or .h files that may be in unclean |
154 | # development trees. |
155 | my $MANIFEST = do { |
156 | local ($/, *FH); |
157 | open FH, "MANIFEST" or die "Can't open MANIFEST: $!"; |
158 | <FH>; |
159 | }; |
160 | |
161 | for $file (($MANIFEST =~ /^(\S+\.c)\t/gm), ($MANIFEST =~ /^(\S+\.h)\t/gm)) { |
94bdecf9 |
162 | open F, "< $file" or die "Cannot open $file for docs: $!\n"; |
163 | $curheader = "Functions in file $file\n"; |
164 | autodoc(\*F,$file); |
165 | close F or die "Error closing $file: $!\n"; |
166 | } |
167 | |
bc350081 |
168 | open IN, "embed.fnc" or die $!; |
169 | |
170 | # walk table providing an array of components in each line to |
171 | # subroutine, printing the result |
172 | |
173 | while (<IN>) { |
174 | chomp; |
175 | next if /^:/; |
176 | while (s|\\\s*$||) { |
177 | $_ .= <IN>; |
178 | chomp; |
179 | } |
180 | s/\s+$//; |
181 | next if /^\s*(#|$)/; |
182 | |
183 | my ($flags, $retval, $func, @args) = split /\s*\|\s*/, $_; |
184 | |
185 | next unless $flags =~ /d/; |
186 | next unless $func; |
187 | |
188 | s/\b(NN|NULLOK)\b\s+//g for @args; |
189 | $func =~ s/\t//g; # clean up fields from embed.pl |
190 | $retval =~ s/\t//; |
191 | |
192 | my $docref = delete $docfuncs{$func}; |
bc350081 |
193 | if ($docref and @$docref) { |
194 | if ($flags =~ /A/) { |
195 | $docref->[0].="x" if $flags =~ /M/; |
196 | $apidocs{$docref->[4]}{$func} = |
197 | [$docref->[0] . 'A', $docref->[1], $retval, $docref->[3], |
198 | @args]; |
199 | } else { |
200 | $gutsdocs{$docref->[4]}{$func} = |
201 | [$docref->[0], $docref->[1], $retval, $docref->[3], @args]; |
94bdecf9 |
202 | } |
203 | } |
bc350081 |
204 | else { |
205 | warn "no docs for $func\n" unless $seenfuncs{$func}; |
206 | } |
207 | } |
94bdecf9 |
208 | |
209 | for (sort keys %docfuncs) { |
210 | # Have you used a full for apidoc or just a func name? |
211 | # Have you used Ap instead of Am in the for apidoc? |
212 | warn "Unable to place $_!\n"; |
213 | } |
214 | |
7b73ff98 |
215 | output('perlapi', <<'_EOB_', \%apidocs, <<'_EOE_'); |
94bdecf9 |
216 | =head1 NAME |
217 | |
218 | perlapi - autogenerated documentation for the perl public API |
219 | |
220 | =head1 DESCRIPTION |
d8c40edc |
221 | X<Perl API> X<API> X<api> |
94bdecf9 |
222 | |
223 | This file contains the documentation of the perl public API generated by |
224 | embed.pl, specifically a listing of functions, macros, flags, and variables |
225 | that may be used by extension writers. The interfaces of any functions that |
226 | are not listed here are subject to change without notice. For this reason, |
227 | blindly using functions listed in proto.h is to be avoided when writing |
228 | extensions. |
229 | |
230 | Note that all Perl API global variables must be referenced with the C<PL_> |
231 | prefix. Some macros are provided for compatibility with the older, |
232 | unadorned names, but this support may be disabled in a future release. |
233 | |
2bbc8d55 |
234 | Perl was originally written to handle US-ASCII only (that is characters |
235 | whose ordinal numbers are in the range 0 - 127). |
236 | And documentation and comments may still use the term ASCII, when |
237 | sometimes in fact the entire range from 0 - 255 is meant. |
238 | |
239 | Note that Perl can be compiled and run under EBCDIC (See L<perlebcdic>) |
240 | or ASCII. Most of the documentation (and even comments in the code) |
241 | ignore the EBCDIC possibility. |
242 | For almost all purposes the differences are transparent. |
243 | As an example, under EBCDIC, |
244 | instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so |
245 | whenever this documentation refers to C<utf8> |
246 | (and variants of that name, including in function names), |
247 | it also (essentially transparently) means C<UTF-EBCDIC>. |
248 | But the ordinals of characters differ between ASCII, EBCDIC, and |
249 | the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes |
250 | than in UTF-8. |
251 | |
252 | Also, on some EBCDIC machines, functions that are documented as operating on |
253 | US-ASCII (or Basic Latin in Unicode terminology) may in fact operate on all |
254 | 256 characters in the EBCDIC range, not just the subset corresponding to |
255 | US-ASCII. |
256 | |
257 | The listing below is alphabetical, case insensitive. |
94bdecf9 |
258 | |
259 | _EOB_ |
260 | |
94bdecf9 |
261 | =head1 AUTHORS |
262 | |
263 | Until May 1997, this document was maintained by Jeff Okamoto |
264 | <okamoto@corp.hp.com>. It is now maintained as part of Perl itself. |
265 | |
266 | With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, |
267 | Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil |
268 | Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, |
269 | Stephen McCamant, and Gurusamy Sarathy. |
270 | |
271 | API Listing originally by Dean Roehrich <roehrich@cray.com>. |
272 | |
273 | Updated to be autogenerated from comments in the source by Benjamin Stuhl. |
274 | |
275 | =head1 SEE ALSO |
276 | |
277 | perlguts(1), perlxs(1), perlxstut(1), perlintern(1) |
278 | |
279 | _EOE_ |
280 | |
7b73ff98 |
281 | output('perlintern', <<'END', \%gutsdocs, <<'END'); |
94bdecf9 |
282 | =head1 NAME |
283 | |
284 | perlintern - autogenerated documentation of purely B<internal> |
285 | Perl functions |
286 | |
287 | =head1 DESCRIPTION |
d8c40edc |
288 | X<internal Perl functions> X<interpreter functions> |
94bdecf9 |
289 | |
290 | This file is the autogenerated documentation of functions in the |
291 | Perl interpreter that are documented using Perl's internal documentation |
292 | format but are not marked as part of the Perl API. In other words, |
293 | B<they are not for use in extensions>! |
294 | |
295 | END |
296 | |
94bdecf9 |
297 | =head1 AUTHORS |
298 | |
299 | The autodocumentation system was originally added to the Perl core by |
300 | Benjamin Stuhl. Documentation is by whoever was kind enough to |
301 | document their functions. |
302 | |
303 | =head1 SEE ALSO |
304 | |
305 | perlguts(1), perlapi(1) |
306 | |
307 | END |