3 require 5.003; # keep this compatible, an old perl is all we may have before
7 # See database of global and static function prototypes at the __END__.
8 # This is used to generate prototype headers under various configurations,
9 # export symbols lists for different platforms, and macros to provide an
10 # implicit interpreter context argument.
13 open IN, "embed.fnc" or die $!;
15 # walk table providing an array of components in each line to
16 # subroutine, printing the result
19 my $filename = shift || '-';
24 if (ref $filename) { # filehandle
28 open F, ">$filename" or die "Can't open $filename: $!";
31 print $F $leader if $leader;
32 seek IN, 0, 0; # so we may restart
45 @args = split /\s*\|\s*/, $_;
47 print $F $function->(@args);
49 print $F $trailer if $trailer;
50 close $F unless ref $filename;
57 my $curheader = "Unknown section";
59 sub autodoc ($$) { # parse a file and extract documentation info
63 while (defined($in = <$fh>)) {
64 if ($in=~ /^=head1 (.*)/) {
69 if ($in =~ /^=for\s+apidoc\s+(.*)\n/) {
71 $proto = "||$proto" unless $proto =~ /\|/;
72 my($flags, $ret, $name, @args) = split /\|/, $proto;
75 while (defined($doc = <$fh>)) {
76 if ($doc =~ /^=head1 (.*)/) {
81 last DOC if $doc =~ /^=\w+/;
82 if ($doc =~ m:^\*/$:) {
83 warn "=cut missing? $file:$line:$doc";;
88 $docs = "\n$docs" if $docs and $docs !~ /^\n/;
91 $apidocs{$curheader}{$name} = [$flags, $docs, $ret, $file, @args];
94 $gutsdocs{$curheader}{$name} = [$flags, $docs, $ret, $file, @args];
98 $docfuncs{$name} = [$flags, $docs, $ret, $file, $curheader, @args];
101 if ($doc =~ /^=for/) {
106 warn "$file:$line:$in";
112 sub docout ($$$) { # output the docs for one function
113 my($fh, $name, $docref) = @_;
114 my($flags, $docs, $ret, $file, @args) = @$docref;
116 $docs .= "NOTE: this function is experimental and may change or be
117 removed without notice.\n\n" if $flags =~ /x/;
118 $docs .= "NOTE: the perl_ form of this function is deprecated.\n\n"
121 print $fh "=item $name\n$docs";
123 if ($flags =~ /U/) { # no usage
125 } elsif ($flags =~ /s/) { # semicolon ("dTHR;")
126 print $fh "\t\t$name;\n\n";
127 } elsif ($flags =~ /n/) { # no args
128 print $fh "\t$ret\t$name\n\n";
129 } else { # full usage
130 print $fh "\t$ret\t$name";
131 print $fh "(" . join(", ", @args) . ")";
134 print $fh "=for hackers\nFound in file $file\n\n";
138 for $file (glob('*.c'), glob('*.h')) {
139 open F, "< $file" or die "Cannot open $file for docs: $!\n";
140 $curheader = "Functions in file $file\n";
142 close F or die "Error closing $file: $!\n";
145 unlink "pod/perlapi.pod";
146 open (DOC, ">pod/perlapi.pod") or
147 die "Can't create pod/perlapi.pod: $!\n";
149 walk_table { # load documented functions into approriate hash
151 my($flags, $retval, $func, @args) = @_;
152 return "" unless $flags =~ /d/;
153 $func =~ s/\t//g; $flags =~ s/p//; # clean up fields from embed.pl
156 my $docref = delete $docfuncs{$func};
157 warn "no docs for $func\n" unless $docref and @$docref;
158 $docref->[0].="x" if $flags =~ /M/;
159 $apidocs{$docref->[4]}{$func} =
160 [$docref->[0] . 'A', $docref->[1], $retval, $docref->[3], @args];
162 my $docref = delete $docfuncs{$func};
163 $gutsdocs{$docref->[4]}{$func} =
164 [$docref->[0], $docref->[1], $retval, $docref->[3], @args];
170 for (sort keys %docfuncs) {
171 # Have you used a full for apidoc or just a func name?
172 # Have you used Ap instead of Am in the for apidoc?
173 warn "Unable to place $_!\n";
179 perlapi - autogenerated documentation for the perl public API
183 This file contains the documentation of the perl public API generated by
184 embed.pl, specifically a listing of functions, macros, flags, and variables
185 that may be used by extension writers. The interfaces of any functions that
186 are not listed here are subject to change without notice. For this reason,
187 blindly using functions listed in proto.h is to be avoided when writing
190 Note that all Perl API global variables must be referenced with the C<PL_>
191 prefix. Some macros are provided for compatibility with the older,
192 unadorned names, but this support may be disabled in a future release.
194 The listing is alphabetical, case insensitive.
199 for $key (sort { uc($a) cmp uc($b); } keys %apidocs) { # case insensitive sort
200 my $section = $apidocs{$key};
201 print DOC "\n=head1 $key\n\n=over 8\n\n";
202 for my $key (sort { uc($a) cmp uc($b); } keys %$section) {
203 docout(\*DOC, $key, $section->{$key});
205 print DOC "\n=back\n";
212 Until May 1997, this document was maintained by Jeff Okamoto
213 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
215 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
216 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
217 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
218 Stephen McCamant, and Gurusamy Sarathy.
220 API Listing originally by Dean Roehrich <roehrich@cray.com>.
222 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
226 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
233 open(GUTS, ">pod/perlintern.pod") or
234 die "Unable to create pod/perlintern.pod: $!\n";
238 perlintern - autogenerated documentation of purely B<internal>
243 This file is the autogenerated documentation of functions in the
244 Perl interpreter that are documented using Perl's internal documentation
245 format but are not marked as part of the Perl API. In other words,
246 B<they are not for use in extensions>!
250 for $key (sort { uc($a) cmp uc($b); } keys %gutsdocs) {
251 my $section = $gutsdocs{$key};
252 print GUTS "\n=head1 $key\n\n=over 8\n\n";
253 for my $key (sort { uc($a) cmp uc($b); } keys %$section) {
254 docout(\*GUTS, $key, $section->{$key});
256 print GUTS "\n=back\n";
263 The autodocumentation system was originally added to the Perl core by
264 Benjamin Stuhl. Documentation is by whoever was kind enough to
265 document their functions.
269 perlguts(1), perlapi(1)