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 invoked as part of 'make all'
18 # '=head1' are the only headings looked for. If the first non-blank line after
19 # the heading begins with a word character, it is considered to be the first
20 # line of documentation that applies to the heading itself. That is, it is
21 # output immediately after the heading, before the first function, and not
22 # indented. The next input line that is a pod directive terminates this
23 # heading-level documentation.
25 # The meanings of the flags fields in embed.fnc and the source code is
26 # documented at the top of embed.fnc.
33 or die "Couldn't chdir to '$workdir': $!";
35 require './regen/regen_lib.pl';
36 require './regen/embed_lib.pl';
39 # See database of global and static function prototypes in embed.fnc
40 # This is used to generate prototype headers under various configurations,
41 # export symbols lists for different platforms, and macros to provide an
42 # implicit interpreter context argument.
55 my $curheader = "Unknown section";
57 sub autodoc ($$) { # parse a file and extract documentation info
59 my($in, $doc, $line, $header_doc);
62 my $get_next_line = sub { $line++; return <$fh> };
65 while (defined($in = $get_next_line->())) {
66 if ($in =~ /^#\s*define\s+([A-Za-z_][A-Za-z_0-9]+)\(/ &&
67 ($file ne 'embed.h' || $file ne 'proto.h')) {
71 if ($in=~ /^=head1 (.*)/) {
74 # If the next non-space line begins with a word char, then it is
75 # the start of heading-ldevel documentation.
76 if (defined($doc = $get_next_line->())) {
77 # Skip over empty lines
78 while ($doc =~ /^\s+$/) {
79 if (! defined($doc = $get_next_line->())) {
90 # Continue getting the heading-level documentation until read
91 # in any pod directive (or as a fail-safe, find a closing
92 # comment to this pod in a C language file
94 while (defined($doc = $get_next_line->())) {
100 if ($doc =~ m:^\s*\*/$:) {
101 warn "=cut missing? $file:$line:$doc";;
109 if ($in =~ /^=for\s+apidoc\s+(.*?)\s*\n/) {
110 my $proto_in_file = $1;
111 my $proto = $proto_in_file;
112 $proto = "||$proto" unless $proto =~ /\|/;
113 my($flags, $ret, $name, @args) = split /\s*\|\s*/, $proto;
114 warn ("'$name' not \\w+ in '$proto_in_file' in $file")
115 if $flags !~ /N/ && $name !~ / ^ [_[:alpha:]] \w* $ /x;
118 while (defined($doc = $get_next_line->())) {
120 # Other pod commands are considered part of the current
121 # function's docs, so can have lists, etc.
122 last DOC if $doc =~ /^=(cut|for\s+apidoc|head)/;
123 if ($doc =~ m:^\*/$:) {
124 warn "=cut missing? $file:$line:$doc";;
129 $docs = "\n$docs" if $docs and $docs !~ /^\n/;
131 # If the entry is also in embed.fnc, it should be defined
132 # completely there, but not here
133 my $embed_docref = delete $funcflags{$name};
134 if ($embed_docref and %$embed_docref) {
135 warn "embed.fnc entry overrides redundant information in"
136 . " '$proto_in_file' in $file" if $flags || $ret || @args;
137 $flags = $embed_docref->{'flags'};
138 $ret = $embed_docref->{'retval'};
139 @args = @{$embed_docref->{args}};
141 $missing{$name} = $file;
144 my $inline_where = $flags =~ /A/ ? 'api' : 'guts';
146 if (exists $docs{$inline_where}{$curheader}{$name}) {
147 warn "$0: duplicate API entry for '$name' in $inline_where/$curheader\n";
150 $docs{$inline_where}{$curheader}{$name}
151 = [$flags, $docs, $ret, $file, @args];
153 # Create a special entry with an empty-string name for the
154 # heading-level documentation.
155 if (defined $header_doc) {
156 $docs{$inline_where}{$curheader}{""} = $header_doc;
161 if ($doc =~ /^=(?:for|head)/) {
166 warn "$file:$line:$in";
172 sub docout ($$$) { # output the docs for one function
173 my($fh, $name, $docref) = @_;
174 my($flags, $docs, $ret, $file, @args) = @$docref;
178 $docs = "\n\nDEPRECATED! It is planned to remove this function from a
179 future release of Perl. Do not use it for new code; remove it from
180 existing code.\n\n$docs";
183 $docs = "\n\nNOTE: this function is experimental and may change or be
184 removed without notice.\n\n$docs" if $flags =~ /x/;
187 # Is Perl_, but no #define foo # Perl_foo
188 my $p = $flags =~ /p/ && $flags =~ /o/ && $flags !~ /M/;
190 $docs .= "NOTE: the perl_ form of this function is deprecated.\n\n"
193 $docs .= "NOTE: this function must be explicitly called as Perl_$name";
194 $docs .= " with an aTHX_ parameter" if $flags !~ /T/;
198 print $fh "=item $name\nX<$name>\n$docs";
200 if ($flags =~ /U/) { # no usage
201 warn("U and s flags are incompatible") if $flags =~ /s/;
204 if ($flags =~ /n/) { # no args
205 warn("n flag without m") unless $flags =~ /m/;
206 warn("n flag but apparently has args") if @args;
207 print $fh "\t$ret\t$name";
208 } else { # full usage
209 my $n = "Perl_"x$p . $name;
210 my $large_ret = length $ret > 7;
211 my $indent_size = 7+8 # nroff: 7 under =head + 8 under =item
212 +8+($large_ret ? 1 + length $ret : 8)
215 print $fh "\t$ret" . ($large_ret ? ' ' : "\t") . "$n(";
218 if ($indent_size + 2 + length > 79) {
220 $indent_size -= length($n) - 3;
225 if ($p && $flags !~ /T/) {
226 $args = @args ? "pTHX_ " : "pTHX";
227 if ($long_args) { print $fh $args; $args = '' }
229 $long_args and print $fh "\n";
230 my $first = !$long_args;
234 && $indent_size + 3 + length($args[0]) + length $args > 79
239 "\t".($large_ret ? " " x (1+length $ret) : "\t")
240 ." "x($long_args ? 4 : 1 + length $n)
242 $args, (","x($args ne 'pTHX_ ') . "\n")x!!@args;
246 $args .= ", "x!!(length $args && $args ne 'pTHX_ ')
249 if ($long_args) { print $fh "\n", substr $indent, 0, -4 }
252 print $fh ";" if $flags =~ /s/; # semicolon "dTHR;"
255 print $fh "=for hackers\nFound in file $file\n\n";
259 # Do a case-insensitive dictionary sort, with only alphabetics
260 # significant, falling back to using everything for determinancy
261 return (uc($a =~ s/[[:^alpha:]]//r) cmp uc($b =~ s/[[:^alpha:]]//r))
267 my ($podname, $header, $dochash, $missing, $footer) = @_;
269 # strip leading '|' from each line which had been used to hide
270 # pod from pod checkers.
271 s/^\|//gm for $header, $footer;
273 my $fh = open_new("pod/$podname.pod", undef,
274 {by => "$0 extracting documentation",
275 from => 'the C source files'}, 1);
280 for $key (sort sort_helper keys %$dochash) {
281 my $section = $dochash->{$key};
282 print $fh "\n=head1 $key\n\n";
284 # Output any heading-level documentation and delete so won't get in
286 if (exists $section->{""}) {
287 print $fh $section->{""} . "\n";
288 delete $section->{""};
290 print $fh "=over 8\n\n";
292 for my $key (sort sort_helper keys %$section) {
293 docout($fh, $key, $section->{$key});
295 print $fh "\n=back\n";
299 print $fh "\n=head1 Undocumented functions\n\n";
300 print $fh $podname eq 'perlapi' ? <<'_EOB_' : <<'_EOB_';
301 The following functions have been flagged as part of the public API,
302 but are currently undocumented. Use them at your own risk, as the
303 interfaces are subject to change. Functions that are not listed in this
304 document are not intended for public use, and should NOT be used under any
307 If you feel you need to use one of these functions, first send email to
308 L<perl5-porters@perl.org|mailto:perl5-porters@perl.org>. It may be
309 that there is a good reason for the function not being documented, and it
310 should be removed from this list; or it may just be that no one has gotten
311 around to documenting it. In the latter case, you will be asked to submit a
312 patch to document the function. Once your patch is accepted, it will indicate
313 that the interface is stable (unless it is explicitly marked otherwise) and
316 The following functions are currently undocumented. If you use one of
317 them, you may wish to consider creating and submitting documentation for
320 print $fh "\n=over\n\n";
322 for my $missing (sort @$missing) {
323 print $fh "=item $missing\nX<$missing>\n\n";
325 print $fh "=back\n\n";
327 print $fh $footer, "=cut\n";
329 read_only_bottom_close_and_rename($fh);
332 foreach (@{(setup_embed())[0]}) {
334 my ($flags, $retval, $func, @args) = @$_;
335 s/\b(?:NN|NULLOK)\b\s+//g for @args;
337 $funcflags{$func} = {
344 # glob() picks up docs from extra .c or .h files that may be in unclean
346 open my $fh, '<', 'MANIFEST'
347 or die "Can't open MANIFEST: $!";
348 while (my $line = <$fh>) {
349 next unless my ($file) = $line =~ /^(\S+\.[ch])\t/;
351 open F, '<', $file or die "Cannot open $file for docs: $!\n";
352 $curheader = "Functions in file $file\n";
354 close F or die "Error closing $file: $!\n";
356 close $fh or die "Error whilst reading MANIFEST: $!";
358 for (sort keys %funcflags) {
359 next unless $funcflags{$_}{flags} =~ /d/;
360 warn "no docs for $_\n"
363 foreach (sort keys %missing) {
365 # Heuristics for known not-a-function macros:
369 warn "Function '$_', documented in $missing{$_}, not listed in embed.fnc";
372 # walk table providing an array of components in each line to
373 # subroutine, printing the result
375 # List of funcs in the public API that aren't also marked as experimental nor
377 my @missing_api = grep $funcflags{$_}{flags} =~ /A/ && $funcflags{$_}{flags} !~ /[xD]/ && !$docs{api}{$_}, keys %funcflags;
378 output('perlapi', <<'_EOB_', $docs{api}, \@missing_api, <<'_EOE_');
383 |perlapi - autogenerated documentation for the perl public API
386 |X<Perl API> X<API> X<api>
388 |This file contains the documentation of the perl public API generated by
389 |F<embed.pl>, specifically a listing of functions, macros, flags, and variables
390 |that may be used by extension writers. L<At the end|/Undocumented functions>
391 |is a list of functions which have yet to be documented. The interfaces of
392 |those are subject to change without notice. Anything not listed here is
393 |not part of the public API, and should not be used by extension writers at
394 |all. For these reasons, blindly using functions listed in proto.h is to be
395 |avoided when writing extensions.
397 |In Perl, unlike C, a string of characters may generally contain embedded
398 |C<NUL> characters. Sometimes in the documentation a Perl string is referred
399 |to as a "buffer" to distinguish it from a C string, but sometimes they are
400 |both just referred to as strings.
402 |Note that all Perl API global variables must be referenced with the C<PL_>
403 |prefix. Again, those not listed here are not to be used by extension writers,
404 |and can be changed or removed without notice; same with macros.
405 |Some macros are provided for compatibility with the older,
406 |unadorned names, but this support may be disabled in a future release.
408 |Perl was originally written to handle US-ASCII only (that is characters
409 |whose ordinal numbers are in the range 0 - 127).
410 |And documentation and comments may still use the term ASCII, when
411 |sometimes in fact the entire range from 0 - 255 is meant.
413 |The non-ASCII characters below 256 can have various meanings, depending on
414 |various things. (See, most notably, L<perllocale>.) But usually the whole
415 |range can be referred to as ISO-8859-1. Often, the term "Latin-1" (or
416 |"Latin1") is used as an equivalent for ISO-8859-1. But some people treat
417 |"Latin1" as referring just to the characters in the range 128 through 255, or
418 |somethimes from 160 through 255.
419 |This documentation uses "Latin1" and "Latin-1" to refer to all 256 characters.
421 |Note that Perl can be compiled and run under either ASCII or EBCDIC (See
422 |L<perlebcdic>). Most of the documentation (and even comments in the code)
423 |ignore the EBCDIC possibility.
424 |For almost all purposes the differences are transparent.
425 |As an example, under EBCDIC,
426 |instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so
427 |whenever this documentation refers to C<utf8>
428 |(and variants of that name, including in function names),
429 |it also (essentially transparently) means C<UTF-EBCDIC>.
430 |But the ordinals of characters differ between ASCII, EBCDIC, and
431 |the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy a different
432 |number of bytes than in UTF-8.
434 |The listing below is alphabetical, case insensitive.
440 |Until May 1997, this document was maintained by Jeff Okamoto
441 |<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
443 |With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
444 |Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
445 |Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
446 |Stephen McCamant, and Gurusamy Sarathy.
448 |API Listing originally by Dean Roehrich <roehrich@cray.com>.
450 |Updated to be autogenerated from comments in the source by Benjamin Stuhl.
454 |L<perlguts>, L<perlxs>, L<perlxstut>, L<perlintern>
458 # List of non-static internal functions
460 grep $funcflags{$_}{flags} !~ /[AS]/ && !$docs{guts}{$_}, keys %funcflags;
462 output('perlintern', <<'END', $docs{guts}, \@missing_guts, <<'END');
465 |perlintern - autogenerated documentation of purely B<internal>
469 |X<internal Perl functions> X<interpreter functions>
471 |This file is the autogenerated documentation of functions in the
472 |Perl interpreter that are documented using Perl's internal documentation
473 |format but are not marked as part of the Perl API. In other words,
474 |B<they are not for use in extensions>!
480 |The autodocumentation system was originally added to the Perl core by
481 |Benjamin Stuhl. Documentation is by whoever was kind enough to
482 |document their functions.
486 |L<perlguts>, L<perlapi>