This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlapi: Document IN_LOCALE, and related
[perl5.git] / autodoc.pl
CommitLineData
94bdecf9 1#!/usr/bin/perl -w
6294c161
DM
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#
52a9d53b 16# This script is invoked as part of 'make all'
151c3fe5 17#
f554dfc5
MH
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.
94bdecf9 24
1fcde0e9
KW
25# The meanings of the flags fields in embed.fnc and the source code is
26# documented at the top of embed.fnc.
27
56a0c332 28use strict;
a64c954a 29
7882b24a
NC
30if (@ARGV) {
31 my $workdir = shift;
32 chdir $workdir
33 or die "Couldn't chdir to '$workdir': $!";
34}
3d7c117d
MB
35require './regen/regen_lib.pl';
36require './regen/embed_lib.pl';
7882b24a 37
7b1f0a98
KW
38my @specialized_docs = sort qw( perlguts
39 perlxs
40 perlxstut
41 );
42my $other_places_api = join " ", map { "L<$_>" } sort @specialized_docs, 'perlintern';
43my $other_places_intern = join " ", map { "L<$_>" } sort @specialized_docs, 'perlapi';
44
94bdecf9 45#
346f75ff 46# See database of global and static function prototypes in embed.fnc
94bdecf9
JH
47# This is used to generate prototype headers under various configurations,
48# export symbols lists for different platforms, and macros to provide an
49# implicit interpreter context argument.
50#
51
6a235718 52my %docs;
5ce57792 53my %funcflags;
5ce57792 54my %missing;
94bdecf9
JH
55
56my $curheader = "Unknown section";
57
58sub autodoc ($$) { # parse a file and extract documentation info
59 my($fh,$file) = @_;
151c3fe5 60 my($in, $doc, $line, $header_doc);
f554dfc5
MH
61
62 # Count lines easier
63 my $get_next_line = sub { $line++; return <$fh> };
64
94bdecf9 65FUNC:
f554dfc5 66 while (defined($in = $get_next_line->())) {
94bdecf9
JH
67 if ($in=~ /^=head1 (.*)/) {
68 $curheader = $1;
151c3fe5 69
f554dfc5 70 # If the next non-space line begins with a word char, then it is
1c82f4a4 71 # the start of heading-level documentation.
20046047 72 if (defined($doc = $get_next_line->())) {
f554dfc5
MH
73 # Skip over empty lines
74 while ($doc =~ /^\s+$/) {
75 if (! defined($doc = $get_next_line->())) {
76 next FUNC;
77 }
78 }
79
151c3fe5
KW
80 if ($doc !~ /^\w/) {
81 $in = $doc;
82 redo FUNC;
83 }
84 $header_doc = $doc;
151c3fe5
KW
85
86 # Continue getting the heading-level documentation until read
87 # in any pod directive (or as a fail-safe, find a closing
88 # comment to this pod in a C language file
89HDR_DOC:
f554dfc5 90 while (defined($doc = $get_next_line->())) {
151c3fe5
KW
91 if ($doc =~ /^=\w/) {
92 $in = $doc;
93 redo FUNC;
94 }
151c3fe5
KW
95
96 if ($doc =~ m:^\s*\*/$:) {
97 warn "=cut missing? $file:$line:$doc";;
98 last HDR_DOC;
99 }
100 $header_doc .= $doc;
101 }
102 }
94bdecf9
JH
103 next FUNC;
104 }
20046047
KE
105 if ($in =~ /^=for\s+apidoc\s+(.*?)\s*\n/) {
106 my $proto_in_file = $1;
107 my $proto = $proto_in_file;
108 $proto = "||$proto" unless $proto =~ /\|/;
109 my($flags, $ret, $name, @args) = split /\s*\|\s*/, $proto;
256dda50
TC
110 $name or die <<EOS;
111Bad apidoc at $file line $.:
112 $in
113Expected:
114 =for apidoc flags|returntype|name|arg|arg|...
115 =for apidoc flags|returntype|name
116 =for apidoc name
117EOS
0a60f600
KW
118 warn ("'$name' not \\w+ in '$proto_in_file' in $file")
119 if $flags !~ /N/ && $name !~ / ^ [_[:alpha:]] \w* $ /x;
20046047 120 my $docs = "";
94bdecf9 121DOC:
20046047 122 while (defined($doc = $get_next_line->())) {
72d4186d
KW
123
124 # Other pod commands are considered part of the current
125 # function's docs, so can have lists, etc.
126 last DOC if $doc =~ /^=(cut|for\s+apidoc|head)/;
20046047
KE
127 if ($doc =~ m:^\*/$:) {
128 warn "=cut missing? $file:$line:$doc";;
129 last DOC;
72d4186d 130 }
20046047
KE
131 $docs .= $doc;
132 }
133 $docs = "\n$docs" if $docs and $docs !~ /^\n/;
5ce57792 134
20046047 135 # If the entry is also in embed.fnc, it should be defined
8902d554 136 # completely there, but not here
20046047
KE
137 my $embed_docref = delete $funcflags{$name};
138 if ($embed_docref and %$embed_docref) {
8902d554
KW
139 warn "embed.fnc entry overrides redundant information in"
140 . " '$proto_in_file' in $file" if $flags || $ret || @args;
141 $flags = $embed_docref->{'flags'};
5514c4f1
KW
142 warn "embed.fnc entry '$name' missing 'd' flag"
143 unless $flags =~ /d/;
8902d554 144 $ret = $embed_docref->{'retval'};
20046047 145 @args = @{$embed_docref->{args}};
5514c4f1
KW
146 } elsif ($flags !~ /m/) { # Not in embed.fnc, is missing if not a
147 # macro
20046047
KE
148 $missing{$name} = $file;
149 }
5ce57792 150
8902d554 151 my $inline_where = $flags =~ /A/ ? 'api' : 'guts';
5ce57792 152
20046047 153 if (exists $docs{$inline_where}{$curheader}{$name}) {
7a6610ca
DM
154 warn "$0: duplicate API entry for '$name' in $inline_where/$curheader\n";
155 next;
156 }
20046047
KE
157 $docs{$inline_where}{$curheader}{$name}
158 = [$flags, $docs, $ret, $file, @args];
5ce57792 159
151c3fe5
KW
160 # Create a special entry with an empty-string name for the
161 # heading-level documentation.
20046047 162 if (defined $header_doc) {
151c3fe5
KW
163 $docs{$inline_where}{$curheader}{""} = $header_doc;
164 undef $header_doc;
165 }
166
20046047
KE
167 if (defined $doc) {
168 if ($doc =~ /^=(?:for|head)/) {
169 $in = $doc;
170 redo FUNC;
171 }
172 } else {
173 warn "$file:$line:$in";
174 }
175 }
94bdecf9
JH
176 }
177}
178
179sub docout ($$$) { # output the docs for one function
180 my($fh, $name, $docref) = @_;
181 my($flags, $docs, $ret, $file, @args) = @$docref;
d8c40edc 182 $name =~ s/\s*$//;
94bdecf9 183
d4e99c76
KW
184 if ($flags =~ /D/) {
185 $docs = "\n\nDEPRECATED! It is planned to remove this function from a
186future release of Perl. Do not use it for new code; remove it from
187existing code.\n\n$docs";
188 }
189 else {
58a428bb
KW
190 $docs = "\n\nNOTE: this function is experimental and may change or be
191removed without notice.\n\n$docs" if $flags =~ /x/;
d4e99c76 192 }
54c193ae
KW
193
194 # Is Perl_, but no #define foo # Perl_foo
195 my $p = $flags =~ /p/ && $flags =~ /o/ && $flags !~ /M/;
196
94bdecf9 197 $docs .= "NOTE: the perl_ form of this function is deprecated.\n\n"
20046047 198 if $flags =~ /O/;
54c193ae
KW
199 if ($p) {
200 $docs .= "NOTE: this function must be explicitly called as Perl_$name";
d7cc3209 201 $docs .= " with an aTHX_ parameter" if $flags !~ /T/;
54c193ae
KW
202 $docs .= ".\n\n"
203 }
94bdecf9 204
d8c40edc 205 print $fh "=item $name\nX<$name>\n$docs";
94bdecf9
JH
206
207 if ($flags =~ /U/) { # no usage
8b5ff177 208 warn("U and s flags are incompatible") if $flags =~ /s/;
20046047 209 # nothing
05ca4832 210 } else {
8b5ff177 211 if ($flags =~ /n/) { # no args
1fcde0e9
KW
212 warn("n flag without m") unless $flags =~ /m/;
213 warn("n flag but apparently has args") if @args;
1ded1f42
KW
214 print $fh "\t$ret\t$name";
215 } else { # full usage
1ded1f42
KW
216 my $n = "Perl_"x$p . $name;
217 my $large_ret = length $ret > 7;
218 my $indent_size = 7+8 # nroff: 7 under =head + 8 under =item
219 +8+($large_ret ? 1 + length $ret : 8)
220 +length($n) + 1;
221 my $indent;
222 print $fh "\t$ret" . ($large_ret ? ' ' : "\t") . "$n(";
223 my $long_args;
224 for (@args) {
225 if ($indent_size + 2 + length > 79) {
226 $long_args=1;
227 $indent_size -= length($n) - 3;
228 last;
229 }
230 }
231 my $args = '';
d7cc3209 232 if ($p && $flags !~ /T/) {
1ded1f42
KW
233 $args = @args ? "pTHX_ " : "pTHX";
234 if ($long_args) { print $fh $args; $args = '' }
235 }
236 $long_args and print $fh "\n";
237 my $first = !$long_args;
238 while () {
239 if (!@args or
240 length $args
241 && $indent_size + 3 + length($args[0]) + length $args > 79
242 ) {
243 print $fh
244 $first ? '' : (
245 $indent //=
246 "\t".($large_ret ? " " x (1+length $ret) : "\t")
247 ." "x($long_args ? 4 : 1 + length $n)
248 ),
249 $args, (","x($args ne 'pTHX_ ') . "\n")x!!@args;
250 $args = $first = '';
251 }
252 @args or last;
253 $args .= ", "x!!(length $args && $args ne 'pTHX_ ')
254 . shift @args;
255 }
256 if ($long_args) { print $fh "\n", substr $indent, 0, -4 }
257 print $fh ")";
258 }
8b5ff177 259 print $fh ";" if $flags =~ /s/; # semicolon "dTHR;"
1ded1f42 260 print $fh "\n\n";
94bdecf9
JH
261 }
262 print $fh "=for hackers\nFound in file $file\n\n";
263}
264
f83c6033
KW
265sub sort_helper {
266 # Do a case-insensitive dictionary sort, with only alphabetics
267 # significant, falling back to using everything for determinancy
1354d57e 268 return (uc($a =~ s/[[:^alpha:]]//r) cmp uc($b =~ s/[[:^alpha:]]//r))
f83c6033
KW
269 || uc($a) cmp uc($b)
270 || $a cmp $b;
271}
272
7b73ff98 273sub output {
5a0155e6 274 my ($podname, $header, $dochash, $missing, $footer) = @_;
6a4c4cd4
DM
275 #
276 # strip leading '|' from each line which had been used to hide
277 # pod from pod checkers.
278 s/^\|//gm for $header, $footer;
279
7882b24a 280 my $fh = open_new("pod/$podname.pod", undef,
20046047 281 {by => "$0 extracting documentation",
f1f44974 282 from => 'the C source files'}, 1);
e0492643 283
7882b24a 284 print $fh $header;
e0492643 285
7b73ff98 286 my $key;
f83c6033 287 for $key (sort sort_helper keys %$dochash) {
20046047
KE
288 my $section = $dochash->{$key};
289 print $fh "\n=head1 $key\n\n";
151c3fe5
KW
290
291 # Output any heading-level documentation and delete so won't get in
292 # the way later
293 if (exists $section->{""}) {
294 print $fh $section->{""} . "\n";
295 delete $section->{""};
296 }
20046047 297 print $fh "=over 8\n\n";
151c3fe5 298
20046047
KE
299 for my $key (sort sort_helper keys %$section) {
300 docout($fh, $key, $section->{$key});
301 }
302 print $fh "\n=back\n";
7b73ff98
NC
303 }
304
5a0155e6 305 if (@$missing) {
a23e6e20 306 print $fh "\n=head1 Undocumented functions\n\n";
2616800a 307 print $fh $podname eq 'perlapi' ? <<'_EOB_' : <<'_EOB_';
474d0ac8 308The following functions have been flagged as part of the public API,
72d33970 309but are currently undocumented. Use them at your own risk, as the
ba4591a5
KW
310interfaces are subject to change. Functions that are not listed in this
311document are not intended for public use, and should NOT be used under any
312circumstances.
313
5a4fed09
KW
314If you feel you need to use one of these functions, first send email to
315L<perl5-porters@perl.org|mailto:perl5-porters@perl.org>. It may be
316that there is a good reason for the function not being documented, and it
317should be removed from this list; or it may just be that no one has gotten
318around to documenting it. In the latter case, you will be asked to submit a
319patch to document the function. Once your patch is accepted, it will indicate
320that the interface is stable (unless it is explicitly marked otherwise) and
321usable by you.
cf5f2f8f 322_EOB_
2616800a
FC
323The following functions are currently undocumented. If you use one of
324them, you may wish to consider creating and submitting documentation for
325it.
2616800a 326_EOB_
6a4c4cd4
DM
327 print $fh "\n=over\n\n";
328
cf5f2f8f
KW
329 for my $missing (sort @$missing) {
330 print $fh "=item $missing\nX<$missing>\n\n";
5a0155e6 331 }
cf5f2f8f
KW
332 print $fh "=back\n\n";
333}
7882b24a 334 print $fh $footer, "=cut\n";
5a0155e6 335
7882b24a 336 read_only_bottom_close_and_rename($fh);
cd093254
MM
337}
338
e8e591c9
NC
339foreach (@{(setup_embed())[0]}) {
340 next if @$_ < 2;
341 my ($flags, $retval, $func, @args) = @$_;
342 s/\b(?:NN|NULLOK)\b\s+//g for @args;
bc350081 343
5ce57792 344 $funcflags{$func} = {
20046047
KE
345 flags => $flags,
346 retval => $retval,
347 args => \@args,
348 };
5ce57792
NC
349}
350
5ce57792
NC
351# glob() picks up docs from extra .c or .h files that may be in unclean
352# development trees.
741c0772
NC
353open my $fh, '<', 'MANIFEST'
354 or die "Can't open MANIFEST: $!";
355while (my $line = <$fh>) {
356 next unless my ($file) = $line =~ /^(\S+\.[ch])\t/;
5ce57792 357
1ae6ead9 358 open F, '<', $file or die "Cannot open $file for docs: $!\n";
5ce57792
NC
359 $curheader = "Functions in file $file\n";
360 autodoc(\*F,$file);
361 close F or die "Error closing $file: $!\n";
362}
741c0772 363close $fh or die "Error whilst reading MANIFEST: $!";
5ce57792
NC
364
365for (sort keys %funcflags) {
366 next unless $funcflags{$_}{flags} =~ /d/;
367 warn "no docs for $_\n"
bc350081 368}
94bdecf9 369
5ce57792 370foreach (sort keys %missing) {
5ce57792 371 warn "Function '$_', documented in $missing{$_}, not listed in embed.fnc";
94bdecf9
JH
372}
373
5ce57792
NC
374# walk table providing an array of components in each line to
375# subroutine, printing the result
376
8c869419
KW
377# List of funcs in the public API that aren't also marked as experimental nor
378# deprecated.
e4aeb12f 379my @missing_api = grep $funcflags{$_}{flags} =~ /A/ && $funcflags{$_}{flags} !~ /[xD]/ && !$docs{api}{$_}, keys %funcflags;
7b1f0a98 380output('perlapi', <<'_EOB_', $docs{api}, \@missing_api, <<"_EOE_");
6a4c4cd4
DM
381|=encoding UTF-8
382|
383|=head1 NAME
384|
385|perlapi - autogenerated documentation for the perl public API
386|
387|=head1 DESCRIPTION
388|X<Perl API> X<API> X<api>
389|
390|This file contains the documentation of the perl public API generated by
391|F<embed.pl>, specifically a listing of functions, macros, flags, and variables
392|that may be used by extension writers. L<At the end|/Undocumented functions>
393|is a list of functions which have yet to be documented. The interfaces of
394|those are subject to change without notice. Anything not listed here is
395|not part of the public API, and should not be used by extension writers at
396|all. For these reasons, blindly using functions listed in proto.h is to be
397|avoided when writing extensions.
398|
399|In Perl, unlike C, a string of characters may generally contain embedded
400|C<NUL> characters. Sometimes in the documentation a Perl string is referred
401|to as a "buffer" to distinguish it from a C string, but sometimes they are
402|both just referred to as strings.
403|
404|Note that all Perl API global variables must be referenced with the C<PL_>
405|prefix. Again, those not listed here are not to be used by extension writers,
406|and can be changed or removed without notice; same with macros.
407|Some macros are provided for compatibility with the older,
408|unadorned names, but this support may be disabled in a future release.
409|
410|Perl was originally written to handle US-ASCII only (that is characters
411|whose ordinal numbers are in the range 0 - 127).
412|And documentation and comments may still use the term ASCII, when
413|sometimes in fact the entire range from 0 - 255 is meant.
414|
415|The non-ASCII characters below 256 can have various meanings, depending on
416|various things. (See, most notably, L<perllocale>.) But usually the whole
417|range can be referred to as ISO-8859-1. Often, the term "Latin-1" (or
418|"Latin1") is used as an equivalent for ISO-8859-1. But some people treat
419|"Latin1" as referring just to the characters in the range 128 through 255, or
420|somethimes from 160 through 255.
421|This documentation uses "Latin1" and "Latin-1" to refer to all 256 characters.
422|
423|Note that Perl can be compiled and run under either ASCII or EBCDIC (See
424|L<perlebcdic>). Most of the documentation (and even comments in the code)
425|ignore the EBCDIC possibility.
426|For almost all purposes the differences are transparent.
427|As an example, under EBCDIC,
428|instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so
429|whenever this documentation refers to C<utf8>
430|(and variants of that name, including in function names),
431|it also (essentially transparently) means C<UTF-EBCDIC>.
432|But the ordinals of characters differ between ASCII, EBCDIC, and
433|the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy a different
434|number of bytes than in UTF-8.
435|
436|The listing below is alphabetical, case insensitive.
437|
94bdecf9 438_EOB_
6a4c4cd4
DM
439|
440|=head1 AUTHORS
441|
442|Until May 1997, this document was maintained by Jeff Okamoto
7b1f0a98 443|<okamoto\@corp.hp.com>. It is now maintained as part of Perl itself.
6a4c4cd4
DM
444|
445|With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
446|Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
447|Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
448|Stephen McCamant, and Gurusamy Sarathy.
449|
7b1f0a98 450|API Listing originally by Dean Roehrich <roehrich\@cray.com>.
6a4c4cd4
DM
451|
452|Updated to be autogenerated from comments in the source by Benjamin Stuhl.
453|
454|=head1 SEE ALSO
455|
7b1f0a98 456$other_places_api
94bdecf9
JH
457_EOE_
458
79fc8511
FC
459# List of non-static internal functions
460my @missing_guts =
9f589e47 461 grep $funcflags{$_}{flags} !~ /[AS]/ && !$docs{guts}{$_}, keys %funcflags;
5a0155e6 462
7b1f0a98 463output('perlintern', <<'_EOB_', $docs{guts}, \@missing_guts, <<"_EOE_");
6a4c4cd4
DM
464|=head1 NAME
465|
466|perlintern - autogenerated documentation of purely B<internal>
20046047 467|Perl functions
6a4c4cd4
DM
468|
469|=head1 DESCRIPTION
470|X<internal Perl functions> X<interpreter functions>
471|
472|This file is the autogenerated documentation of functions in the
473|Perl interpreter that are documented using Perl's internal documentation
474|format but are not marked as part of the Perl API. In other words,
475|B<they are not for use in extensions>!
476|
7b1f0a98 477_EOB_
6a4c4cd4
DM
478|
479|=head1 AUTHORS
480|
481|The autodocumentation system was originally added to the Perl core by
482|Benjamin Stuhl. Documentation is by whoever was kind enough to
483|document their functions.
484|
485|=head1 SEE ALSO
486|
7b1f0a98
KW
487$other_places_intern
488_EOE_