3 # Unconditionally regenerate:
8 # from information stored in
11 # plus all the .c and .h files listed in MANIFEST
13 # Has an optional arg, which is the directory to chdir to before reading
14 # MANIFEST and *.[ch].
16 # This script is normally invoked as part of 'make all', but is also
17 # called from regen.pl.
19 # '=head1' are the only headings looked for. If the next line after the
20 # heading begins with a word character, it is considered to be the first line
21 # of documentation that applies to the heading itself. That is, it is output
22 # immediately after the heading, before the first function, and not indented.
23 # The next input line that is a pod directive terminates this heading-level
31 or die "Couldn't chdir to '$workdir': $!";
33 require 'regen/regen_lib.pl';
34 require 'regen/embed_lib.pl';
37 # See database of global and static function prototypes in embed.fnc
38 # This is used to generate prototype headers under various configurations,
39 # export symbols lists for different platforms, and macros to provide an
40 # implicit interpreter context argument.
53 my $curheader = "Unknown section";
55 sub autodoc ($$) { # parse a file and extract documentation info
57 my($in, $doc, $line, $header_doc);
59 while (defined($in = <$fh>)) {
60 if ($in =~ /^#\s*define\s+([A-Za-z_][A-Za-z_0-9]+)\(/ &&
61 ($file ne 'embed.h' || $file ne 'proto.h')) {
65 if ($in=~ /^=head1 (.*)/) {
68 # If the next line begins with a word char, then is the start of
69 # heading-level documentation.
70 if (defined($doc = <$fh>)) {
78 # Continue getting the heading-level documentation until read
79 # in any pod directive (or as a fail-safe, find a closing
80 # comment to this pod in a C language file
82 while (defined($doc = <$fh>)) {
89 if ($doc =~ m:^\s*\*/$:) {
90 warn "=cut missing? $file:$line:$doc";;
99 if ($in =~ /^=for\s+apidoc\s+(.*?)\s*\n/) {
101 $proto = "||$proto" unless $proto =~ /\|/;
102 my($flags, $ret, $name, @args) = split /\|/, $proto;
105 while (defined($doc = <$fh>)) {
107 last DOC if $doc =~ /^=\w+/;
108 if ($doc =~ m:^\*/$:) {
109 warn "=cut missing? $file:$line:$doc";;
114 $docs = "\n$docs" if $docs and $docs !~ /^\n/;
116 # Check the consistency of the flags
117 my ($embed_where, $inline_where);
118 my ($embed_may_change, $inline_may_change);
120 my $docref = delete $funcflags{$name};
121 if ($docref and %$docref) {
122 $embed_where = $docref->{flags} =~ /A/ ? 'api' : 'guts';
123 $embed_may_change = $docref->{flags} =~ /M/;
124 $flags .= 'D' if $docref->{flags} =~ /D/;
126 $missing{$name} = $file;
129 $inline_where = $flags =~ /A/ ? 'api' : 'guts';
130 $inline_may_change = $flags =~ /x/;
132 if (defined $embed_where && $inline_where ne $embed_where) {
133 warn "Function '$name' inconsistency: embed.fnc says $embed_where, Pod says $inline_where";
136 if (defined $embed_may_change
137 && $inline_may_change ne $embed_may_change) {
138 my $message = "Function '$name' inconsistency: ";
139 if ($embed_may_change) {
140 $message .= "embed.fnc says 'may change', Pod does not";
142 $message .= "Pod says 'may change', embed.fnc does not";
146 } elsif (!defined $embed_where) {
147 warn "Unable to place $name!\n";
150 $inline_where = $embed_where;
151 $flags .= 'x' if $embed_may_change;
152 @args = @{$docref->{args}};
153 $ret = $docref->{retval};
156 $docs{$inline_where}{$curheader}{$name}
157 = [$flags, $docs, $ret, $file, @args];
159 # Create a special entry with an empty-string name for the
160 # heading-level documentation.
161 if (defined $header_doc) {
162 $docs{$inline_where}{$curheader}{""} = $header_doc;
167 if ($doc =~ /^=(?:for|head)/) {
172 warn "$file:$line:$in";
178 sub docout ($$$) { # output the docs for one function
179 my($fh, $name, $docref) = @_;
180 my($flags, $docs, $ret, $file, @args) = @$docref;
184 $docs = "\n\nDEPRECATED! It is planned to remove this function from a
185 future release of Perl. Do not use it for new code; remove it from
186 existing code.\n\n$docs";
189 $docs = "\n\nNOTE: this function is experimental and may change or be
190 removed without notice.\n\n$docs" if $flags =~ /x/;
192 $docs .= "NOTE: the perl_ form of this function is deprecated.\n\n"
194 $docs .= "NOTE: this function must be explicitly called as Perl_$name with an aTHX_ parameter.\n\n"
197 print $fh "=item $name\nX<$name>\n$docs";
199 if ($flags =~ /U/) { # no usage
201 } elsif ($flags =~ /s/) { # semicolon ("dTHR;")
202 print $fh "\t\t$name;\n\n";
203 } elsif ($flags =~ /n/) { # no args
204 print $fh "\t$ret\t$name\n\n";
205 } else { # full usage
206 my $p = $flags =~ /o/; # no #define foo Perl_foo
207 my $n = "Perl_"x$p . $name;
208 my $large_ret = length $ret > 7;
209 my $indent_size = 7+8 # nroff: 7 under =head + 8 under =item
210 +8+($large_ret ? 1 + length $ret : 8)
213 print $fh "\t$ret" . ($large_ret ? ' ' : "\t") . "$n(";
216 if ($indent_size + 2 + length > 79) {
218 $indent_size -= length($n) - 3;
224 $args = @args ? "pTHX_ " : "pTHX";
225 if ($long_args) { print $fh $args; $args = '' }
227 $long_args and print $fh "\n";
228 my $first = !$long_args;
232 && $indent_size + 3 + length($args[0]) + length $args > 79
237 "\t".($large_ret ? " " x (1+length $ret) : "\t")
238 ." "x($long_args ? 4 : 1 + length $n)
240 $args, (","x($args ne 'pTHX_ ') . "\n")x!!@args;
244 $args .= ", "x!!(length $args && $args ne 'pTHX_ ')
247 if ($long_args) { print $fh "\n", substr $indent, 0, -4 }
250 print $fh "=for hackers\nFound in file $file\n\n";
254 my ($podname, $header, $dochash, $missing, $footer) = @_;
255 my $fh = open_new("pod/$podname.pod", undef,
256 {by => "$0 extracting documentation",
257 from => 'the C source files'});
262 # case insensitive sort, with fallback for determinacy
263 for $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %$dochash) {
264 my $section = $dochash->{$key};
265 print $fh "\n=head1 $key\n\n";
267 # Output any heading-level documentation and delete so won't get in
269 if (exists $section->{""}) {
270 print $fh $section->{""} . "\n";
271 delete $section->{""};
273 print $fh "=over 8\n\n";
275 # Again, fallback for determinacy
276 for my $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %$section) {
277 docout($fh, $key, $section->{$key});
279 print $fh "\n=back\n";
283 print $fh "\n=head1 Undocumented functions\n\n";
284 print $fh $podname eq 'perlapi' ? <<'_EOB_' : <<'_EOB_';
285 The following functions have been flagged as part of the public API,
286 but are currently undocumented. Use them at your own risk, as the
287 interfaces are subject to change. Functions that are not listed in this
288 document are not intended for public use, and should NOT be used under any
291 If you use one of the undocumented functions below, you may wish to consider
292 creating and submitting documentation for it. If your patch is accepted, this
293 will indicate that the interface is stable (unless it is explicitly marked
299 The following functions are currently undocumented. If you use one of
300 them, you may wish to consider creating and submitting documentation for
306 for my $missing (sort @$missing) {
307 print $fh "=item $missing\nX<$missing>\n\n";
309 print $fh "=back\n\n";
311 print $fh $footer, "=cut\n";
313 read_only_bottom_close_and_rename($fh);
316 foreach (@{(setup_embed())[0]}) {
318 my ($flags, $retval, $func, @args) = @$_;
319 s/\b(?:NN|NULLOK)\b\s+//g for @args;
321 $funcflags{$func} = {
328 # glob() picks up docs from extra .c or .h files that may be in unclean
330 open my $fh, '<', 'MANIFEST'
331 or die "Can't open MANIFEST: $!";
332 while (my $line = <$fh>) {
333 next unless my ($file) = $line =~ /^(\S+\.[ch])\t/;
335 open F, "< $file" or die "Cannot open $file for docs: $!\n";
336 $curheader = "Functions in file $file\n";
338 close F or die "Error closing $file: $!\n";
340 close $fh or die "Error whilst reading MANIFEST: $!";
342 for (sort keys %funcflags) {
343 next unless $funcflags{$_}{flags} =~ /d/;
344 warn "no docs for $_\n"
347 foreach (sort keys %missing) {
349 # Heuristics for known not-a-function macros:
353 warn "Function '$_', documented in $missing{$_}, not listed in embed.fnc";
356 # walk table providing an array of components in each line to
357 # subroutine, printing the result
359 # List of funcs in the public API that aren't also marked as experimental nor
361 my @missing_api = grep $funcflags{$_}{flags} =~ /A/ && $funcflags{$_}{flags} !~ /[MD]/ && !$docs{api}{$_}, keys %funcflags;
362 output('perlapi', <<'_EOB_', $docs{api}, \@missing_api, <<'_EOE_');
365 perlapi - autogenerated documentation for the perl public API
368 X<Perl API> X<API> X<api>
370 This file contains the documentation of the perl public API generated by
371 F<embed.pl>, specifically a listing of functions, macros, flags, and variables
372 that may be used by extension writers. L<At the end|/Undocumented functions>
373 is a list of functions which have yet to be documented. The interfaces of
374 those are subject to change without notice. Any functions not listed here are
375 not part of the public API, and should not be used by extension writers at
376 all. For these reasons, blindly using functions listed in proto.h is to be
377 avoided when writing extensions.
379 Note that all Perl API global variables must be referenced with the C<PL_>
380 prefix. Some macros are provided for compatibility with the older,
381 unadorned names, but this support may be disabled in a future release.
383 Perl was originally written to handle US-ASCII only (that is characters
384 whose ordinal numbers are in the range 0 - 127).
385 And documentation and comments may still use the term ASCII, when
386 sometimes in fact the entire range from 0 - 255 is meant.
388 Note that Perl can be compiled and run under EBCDIC (See L<perlebcdic>)
389 or ASCII. Most of the documentation (and even comments in the code)
390 ignore the EBCDIC possibility.
391 For almost all purposes the differences are transparent.
392 As an example, under EBCDIC,
393 instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so
394 whenever this documentation refers to C<utf8>
395 (and variants of that name, including in function names),
396 it also (essentially transparently) means C<UTF-EBCDIC>.
397 But the ordinals of characters differ between ASCII, EBCDIC, and
398 the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes
401 The listing below is alphabetical, case insensitive.
407 Until May 1997, this document was maintained by Jeff Okamoto
408 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
410 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
411 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
412 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
413 Stephen McCamant, and Gurusamy Sarathy.
415 API Listing originally by Dean Roehrich <roehrich@cray.com>.
417 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
421 L<perlguts>, L<perlxs>, L<perlxstut>, L<perlintern>
425 # List of non-static internal functions
427 grep $funcflags{$_}{flags} !~ /[As]/ && !$docs{guts}{$_}, keys %funcflags;
429 output('perlintern', <<'END', $docs{guts}, \@missing_guts, <<'END');
432 perlintern - autogenerated documentation of purely B<internal>
436 X<internal Perl functions> X<interpreter functions>
438 This file is the autogenerated documentation of functions in the
439 Perl interpreter that are documented using Perl's internal documentation
440 format but are not marked as part of the Perl API. In other words,
441 B<they are not for use in extensions>!
447 The autodocumentation system was originally added to the Perl core by
448 Benjamin Stuhl. Documentation is by whoever was kind enough to
449 document their functions.
453 L<perlguts>, L<perlapi>