PL_scopestack_name needs to be present, -DDEBUGGING or not.
[p5sagit/p5-mst-13.2.git] / autodoc.pl
CommitLineData
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 19use 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 28my %apidocs;
29my %gutsdocs;
30my %docfuncs;
7eb550cf 31my %seenfuncs;
94bdecf9 32
33my $curheader = "Unknown section";
34
35sub autodoc ($$) { # parse a file and extract documentation info
36 my($fh,$file) = @_;
37 my($in, $doc, $line);
38FUNC:
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 = "";
50DOC:
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
85sub 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
91removed 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 111sub 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 !!!!!!!
120This file is built by $0 extracting documentation from the C source
121files.
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 146if (@ARGV) {
147 my $workdir = shift;
148 chdir $workdir
149 or die "Couldn't chdir to '$workdir': $!";
150}
151
94bdecf9 152my $file;
69e39a9a 153# glob() picks up docs from extra .c or .h files that may be in unclean
154# development trees.
155my $MANIFEST = do {
156 local ($/, *FH);
157 open FH, "MANIFEST" or die "Can't open MANIFEST: $!";
158 <FH>;
159};
160
161for $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 168open IN, "embed.fnc" or die $!;
169
170# walk table providing an array of components in each line to
171# subroutine, printing the result
172
173while (<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
209for (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 215output('perlapi', <<'_EOB_', \%apidocs, <<'_EOE_');
94bdecf9 216=head1 NAME
217
218perlapi - autogenerated documentation for the perl public API
219
220=head1 DESCRIPTION
d8c40edc 221X<Perl API> X<API> X<api>
94bdecf9 222
223This file contains the documentation of the perl public API generated by
224embed.pl, specifically a listing of functions, macros, flags, and variables
225that may be used by extension writers. The interfaces of any functions that
226are not listed here are subject to change without notice. For this reason,
227blindly using functions listed in proto.h is to be avoided when writing
228extensions.
229
230Note that all Perl API global variables must be referenced with the C<PL_>
231prefix. Some macros are provided for compatibility with the older,
232unadorned names, but this support may be disabled in a future release.
233
2bbc8d55 234Perl was originally written to handle US-ASCII only (that is characters
235whose ordinal numbers are in the range 0 - 127).
236And documentation and comments may still use the term ASCII, when
237sometimes in fact the entire range from 0 - 255 is meant.
238
239Note that Perl can be compiled and run under EBCDIC (See L<perlebcdic>)
240or ASCII. Most of the documentation (and even comments in the code)
241ignore the EBCDIC possibility.
242For almost all purposes the differences are transparent.
243As an example, under EBCDIC,
244instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so
245whenever this documentation refers to C<utf8>
246(and variants of that name, including in function names),
247it also (essentially transparently) means C<UTF-EBCDIC>.
248But the ordinals of characters differ between ASCII, EBCDIC, and
249the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes
250than in UTF-8.
251
252Also, on some EBCDIC machines, functions that are documented as operating on
253US-ASCII (or Basic Latin in Unicode terminology) may in fact operate on all
254256 characters in the EBCDIC range, not just the subset corresponding to
255US-ASCII.
256
257The listing below is alphabetical, case insensitive.
94bdecf9 258
259_EOB_
260
94bdecf9 261=head1 AUTHORS
262
263Until May 1997, this document was maintained by Jeff Okamoto
264<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
265
266With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
267Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
268Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
269Stephen McCamant, and Gurusamy Sarathy.
270
271API Listing originally by Dean Roehrich <roehrich@cray.com>.
272
273Updated to be autogenerated from comments in the source by Benjamin Stuhl.
274
275=head1 SEE ALSO
276
277perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
278
279_EOE_
280
7b73ff98 281output('perlintern', <<'END', \%gutsdocs, <<'END');
94bdecf9 282=head1 NAME
283
284perlintern - autogenerated documentation of purely B<internal>
285 Perl functions
286
287=head1 DESCRIPTION
d8c40edc 288X<internal Perl functions> X<interpreter functions>
94bdecf9 289
290This file is the autogenerated documentation of functions in the
291Perl interpreter that are documented using Perl's internal documentation
292format but are not marked as part of the Perl API. In other words,
293B<they are not for use in extensions>!
294
295END
296
94bdecf9 297=head1 AUTHORS
298
299The autodocumentation system was originally added to the Perl core by
300Benjamin Stuhl. Documentation is by whoever was kind enough to
301document their functions.
302
303=head1 SEE ALSO
304
305perlguts(1), perlapi(1)
306
307END