Mercurial > repo

annotate perl-5.22.2/autodoc.pl @ 8045:a16537d2fe07

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
<xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
author HackBot
date Sat, 14 May 2016 14:54:38 +0000
parents
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8045
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
1 #!/usr/bin/perl -w
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
2 #
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
3 # Unconditionally regenerate:
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
4 #
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
5 # pod/perlintern.pod
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
6 # pod/perlapi.pod
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
7 #
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
8 # from information stored in
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
9 #
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
10 # embed.fnc
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
11 # plus all the .c and .h files listed in MANIFEST
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
12 #
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
13 # Has an optional arg, which is the directory to chdir to before reading
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
14 # MANIFEST and *.[ch].
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
15 #
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
16 # This script is invoked as part of 'make all'
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
17 #
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
18 # '=head1' are the only headings looked for. If the first non-blank line after
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
19 # the heading begins with a word character, it is considered to be the first
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
20 # line of documentation that applies to the heading itself. That is, it is
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
21 # output immediately after the heading, before the first function, and not
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
22 # indented. The next input line that is a pod directive terminates this
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
23 # heading-level documentation.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
24
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
25 use strict;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
26
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
27 if (@ARGV) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
28 my $workdir = shift;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
29 chdir $workdir
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
30 or die "Couldn't chdir to '$workdir': $!";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
31 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
32 require 'regen/regen_lib.pl';
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
33 require 'regen/embed_lib.pl';
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
34
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
35 #
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
36 # See database of global and static function prototypes in embed.fnc
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
37 # This is used to generate prototype headers under various configurations,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
38 # export symbols lists for different platforms, and macros to provide an
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
39 # implicit interpreter context argument.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
40 #
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
41
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
42 my %docs;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
43 my %funcflags;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
44 my %macro = (
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
45 ax => 1,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
46 items => 1,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
47 ix => 1,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
48 svtype => 1,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
49 );
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
50 my %missing;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
51
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
52 my $curheader = "Unknown section";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
53
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
54 sub autodoc ($$) { # parse a file and extract documentation info
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
55 my($fh,$file) = @_;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
56 my($in, $doc, $line, $header_doc);
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
57
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
58 # Count lines easier
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
59 my $get_next_line = sub { $line++; return <$fh> };
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
60
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
61 FUNC:
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
62 while (defined($in = $get_next_line->())) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
63 if ($in =~ /^#\s*define\s+([A-Za-z_][A-Za-z_0-9]+)\(/ &&
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
64 ($file ne 'embed.h' || $file ne 'proto.h')) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
65 $macro{$1} = $file;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
66 next FUNC;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
67 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
68 if ($in=~ /^=head1 (.*)/) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
69 $curheader = $1;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
70
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
71 # If the next non-space line begins with a word char, then it is
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
72 # the start of heading-ldevel documentation.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
73 if (defined($doc = $get_next_line->())) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
74 # Skip over empty lines
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
75 while ($doc =~ /^\s+$/) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
76 if (! defined($doc = $get_next_line->())) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
77 next FUNC;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
78 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
79 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
80
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
81 if ($doc !~ /^\w/) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
82 $in = $doc;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
83 redo FUNC;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
84 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
85 $header_doc = $doc;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
86
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
87 # Continue getting the heading-level documentation until read
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
88 # in any pod directive (or as a fail-safe, find a closing
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
89 # comment to this pod in a C language file
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
90 HDR_DOC:
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
91 while (defined($doc = $get_next_line->())) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
92 if ($doc =~ /^=\w/) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
93 $in = $doc;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
94 redo FUNC;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
95 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
96
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
97 if ($doc =~ m:^\s*\*/$:) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
98 warn "=cut missing? $file:$line:$doc";;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
99 last HDR_DOC;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
100 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
101 $header_doc .= $doc;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
102 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
103 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
104 next FUNC;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
105 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
106 if ($in =~ /^=for\s+apidoc\s+(.*?)\s*\n/) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
107 my $proto = $1;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
108 $proto = "||$proto" unless $proto =~ /\|/;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
109 my($flags, $ret, $name, @args) = split /\|/, $proto;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
110 my $docs = "";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
111 DOC:
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
112 while (defined($doc = $get_next_line->())) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
113 last DOC if $doc =~ /^=\w+/;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
114 if ($doc =~ m:^\*/$:) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
115 warn "=cut missing? $file:$line:$doc";;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
116 last DOC;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
117 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
118 $docs .= $doc;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
119 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
120 $docs = "\n$docs" if $docs and $docs !~ /^\n/;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
121
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
122 # Check the consistency of the flags
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
123 my ($embed_where, $inline_where);
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
124 my ($embed_may_change, $inline_may_change);
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
125
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
126 my $docref = delete $funcflags{$name};
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
127 if ($docref and %$docref) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
128 $embed_where = $docref->{flags} =~ /A/ ? 'api' : 'guts';
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
129 $embed_may_change = $docref->{flags} =~ /M/;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
130 $flags .= 'D' if $docref->{flags} =~ /D/;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
131 } else {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
132 $missing{$name} = $file;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
133 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
134 if ($flags =~ /m/) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
135 $inline_where = $flags =~ /A/ ? 'api' : 'guts';
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
136 $inline_may_change = $flags =~ /x/;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
137
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
138 if (defined $embed_where && $inline_where ne $embed_where) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
139 warn "Function '$name' inconsistency: embed.fnc says $embed_where, Pod says $inline_where";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
140 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
141
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
142 if (defined $embed_may_change
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
143 && $inline_may_change ne $embed_may_change) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
144 my $message = "Function '$name' inconsistency: ";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
145 if ($embed_may_change) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
146 $message .= "embed.fnc says 'may change', Pod does not";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
147 } else {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
148 $message .= "Pod says 'may change', embed.fnc does not";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
149 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
150 warn $message;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
151 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
152 } elsif (!defined $embed_where) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
153 warn "Unable to place $name!\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
154 next;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
155 } else {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
156 $inline_where = $embed_where;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
157 $flags .= 'x' if $embed_may_change;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
158 @args = @{$docref->{args}};
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
159 $ret = $docref->{retval};
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
160 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
161
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
162 if (exists $docs{$inline_where}{$curheader}{$name}) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
163 warn "$0: duplicate API entry for '$name' in $inline_where/$curheader\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
164 next;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
165 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
166 $docs{$inline_where}{$curheader}{$name}
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
167 = [$flags, $docs, $ret, $file, @args];
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
168
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
169 # Create a special entry with an empty-string name for the
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
170 # heading-level documentation.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
171 if (defined $header_doc) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
172 $docs{$inline_where}{$curheader}{""} = $header_doc;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
173 undef $header_doc;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
174 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
175
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
176 if (defined $doc) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
177 if ($doc =~ /^=(?:for|head)/) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
178 $in = $doc;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
179 redo FUNC;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
180 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
181 } else {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
182 warn "$file:$line:$in";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
183 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
184 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
185 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
186 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
187
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
188 sub docout ($$$) { # output the docs for one function
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
189 my($fh, $name, $docref) = @_;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
190 my($flags, $docs, $ret, $file, @args) = @$docref;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
191 $name =~ s/\s*$//;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
192
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
193 if ($flags =~ /D/) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
194 $docs = "\n\nDEPRECATED! It is planned to remove this function from a
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
195 future release of Perl. Do not use it for new code; remove it from
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
196 existing code.\n\n$docs";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
197 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
198 else {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
199 $docs = "\n\nNOTE: this function is experimental and may change or be
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
200 removed without notice.\n\n$docs" if $flags =~ /x/;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
201 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
202 $docs .= "NOTE: the perl_ form of this function is deprecated.\n\n"
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
203 if $flags =~ /p/;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
204 $docs .= "NOTE: this function must be explicitly called as Perl_$name with an aTHX_ parameter.\n\n"
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
205 if $flags =~ /o/;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
206
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
207 print $fh "=item $name\nX<$name>\n$docs";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
208
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
209 if ($flags =~ /U/) { # no usage
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
210 # nothing
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
211 } elsif ($flags =~ /s/) { # semicolon ("dTHR;")
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
212 print $fh "\t\t$name;\n\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
213 } elsif ($flags =~ /n/) { # no args
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
214 print $fh "\t$ret\t$name\n\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
215 } else { # full usage
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
216 my $p = $flags =~ /o/; # no #define foo Perl_foo
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
217 my $n = "Perl_"x$p . $name;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
218 my $large_ret = length $ret > 7;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
219 my $indent_size = 7+8 # nroff: 7 under =head + 8 under =item
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
220 +8+($large_ret ? 1 + length $ret : 8)
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
221 +length($n) + 1;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
222 my $indent;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
223 print $fh "\t$ret" . ($large_ret ? ' ' : "\t") . "$n(";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
224 my $long_args;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
225 for (@args) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
226 if ($indent_size + 2 + length > 79) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
227 $long_args=1;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
228 $indent_size -= length($n) - 3;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
229 last;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
230 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
231 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
232 my $args = '';
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
233 if ($p) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
234 $args = @args ? "pTHX_ " : "pTHX";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
235 if ($long_args) { print $fh $args; $args = '' }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
236 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
237 $long_args and print $fh "\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
238 my $first = !$long_args;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
239 while () {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
240 if (!@args or
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
241 length $args
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
242 && $indent_size + 3 + length($args[0]) + length $args > 79
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
243 ) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
244 print $fh
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
245 $first ? '' : (
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
246 $indent //=
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
247 "\t".($large_ret ? " " x (1+length $ret) : "\t")
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
248 ." "x($long_args ? 4 : 1 + length $n)
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
249 ),
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
250 $args, (","x($args ne 'pTHX_ ') . "\n")x!!@args;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
251 $args = $first = '';
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
252 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
253 @args or last;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
254 $args .= ", "x!!(length $args && $args ne 'pTHX_ ')
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
255 . shift @args;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
256 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
257 if ($long_args) { print $fh "\n", substr $indent, 0, -4 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
258 print $fh ")\n\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
259 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
260 print $fh "=for hackers\nFound in file $file\n\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
261 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
262
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
263 sub sort_helper {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
264 # Do a case-insensitive dictionary sort, with only alphabetics
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
265 # significant, falling back to using everything for determinancy
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
266 return (uc($a =~ s/[[^:alpha]]//r) cmp uc($b =~ s/[[^:alpha]]//r))
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
267 || uc($a) cmp uc($b)
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
268 || $a cmp $b;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
269 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
270
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
271 sub output {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
272 my ($podname, $header, $dochash, $missing, $footer) = @_;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
273 my $fh = open_new("pod/$podname.pod", undef,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
274 {by => "$0 extracting documentation",
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
275 from => 'the C source files'}, 1);
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
276
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
277 print $fh $header;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
278
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
279 my $key;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
280 for $key (sort sort_helper keys %$dochash) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
281 my $section = $dochash->{$key};
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
282 print $fh "\n=head1 $key\n\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
283
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
284 # Output any heading-level documentation and delete so won't get in
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
285 # the way later
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
286 if (exists $section->{""}) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
287 print $fh $section->{""} . "\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
288 delete $section->{""};
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
289 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
290 print $fh "=over 8\n\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
291
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
292 for my $key (sort sort_helper keys %$section) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
293 docout($fh, $key, $section->{$key});
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
294 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
295 print $fh "\n=back\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
296 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
297
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
298 if (@$missing) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
299 print $fh "\n=head1 Undocumented functions\n\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
300 print $fh $podname eq 'perlapi' ? <<'_EOB_' : <<'_EOB_';
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
301 The following functions have been flagged as part of the public API,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
302 but are currently undocumented. Use them at your own risk, as the
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
303 interfaces are subject to change. Functions that are not listed in this
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
304 document are not intended for public use, and should NOT be used under any
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
305 circumstances.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
306
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
307 If you use one of the undocumented functions below, you may wish to consider
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
308 creating and submitting documentation
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
309 for it. If your patch is accepted, this
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
310 will indicate that the interface is stable (unless it is explicitly marked
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
311 otherwise).
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
312
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
313 =over
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
314
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
315 _EOB_
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
316 The following functions are currently undocumented. If you use one of
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
317 them, you may wish to consider creating and submitting documentation for
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
318 it.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
319
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
320 =over
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
321
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
322 _EOB_
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
323 for my $missing (sort @$missing) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
324 print $fh "=item $missing\nX<$missing>\n\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
325 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
326 print $fh "=back\n\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
327 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
328 print $fh $footer, "=cut\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
329
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
330 read_only_bottom_close_and_rename($fh);
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
331 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
332
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
333 foreach (@{(setup_embed())[0]}) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
334 next if @$_ < 2;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
335 my ($flags, $retval, $func, @args) = @$_;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
336 s/\b(?:NN|NULLOK)\b\s+//g for @args;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
337
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
338 $funcflags{$func} = {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
339 flags => $flags,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
340 retval => $retval,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
341 args => \@args,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
342 };
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
343 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
344
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
345 # glob() picks up docs from extra .c or .h files that may be in unclean
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
346 # development trees.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
347 open my $fh, '<', 'MANIFEST'
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
348 or die "Can't open MANIFEST: $!";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
349 while (my $line = <$fh>) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
350 next unless my ($file) = $line =~ /^(\S+\.[ch])\t/;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
351
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
352 open F, "< $file" or die "Cannot open $file for docs: $!\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
353 $curheader = "Functions in file $file\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
354 autodoc(\*F,$file);
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
355 close F or die "Error closing $file: $!\n";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
356 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
357 close $fh or die "Error whilst reading MANIFEST: $!";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
358
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
359 for (sort keys %funcflags) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
360 next unless $funcflags{$_}{flags} =~ /d/;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
361 warn "no docs for $_\n"
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
362 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
363
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
364 foreach (sort keys %missing) {
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
365 next if $macro{$_};
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
366 # Heuristics for known not-a-function macros:
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
367 next if /^[A-Z]/;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
368 next if /^dj?[A-Z]/;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
369
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
370 warn "Function '$_', documented in $missing{$_}, not listed in embed.fnc";
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
371 }
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
372
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
373 # walk table providing an array of components in each line to
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
374 # subroutine, printing the result
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
375
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
376 # List of funcs in the public API that aren't also marked as experimental nor
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
377 # deprecated.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
378 my @missing_api = grep $funcflags{$_}{flags} =~ /A/ && $funcflags{$_}{flags} !~ /[MD]/ && !$docs{api}{$_}, keys %funcflags;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
379 output('perlapi', <<'_EOB_', $docs{api}, \@missing_api, <<'_EOE_');
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
380 =head1 NAME
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
381
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
382 perlapi - autogenerated documentation for the perl public API
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
383
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
384 =head1 DESCRIPTION
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
385 X<Perl API> X<API> X<api>
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
386
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
387 This file contains the documentation of the perl public API generated by
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
388 F<embed.pl>, specifically a listing of functions, macros, flags, and variables
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
389 that may be used by extension writers. L<At the end|/Undocumented functions>
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
390 is a list of functions which have yet to be documented. The interfaces of
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
391 those are subject to change without notice. Anything not listed here is
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
392 not part of the public API, and should not be used by extension writers at
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
393 all. For these reasons, blindly using functions listed in proto.h is to be
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
394 avoided when writing extensions.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
395
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
396 Note that all Perl API global variables must be referenced with the C<PL_>
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
397 prefix. Again, those not listed here are not to be used by extension writers,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
398 and can be changed or removed without notice; same with macros.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
399 Some macros are provided for compatibility with the older,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
400 unadorned names, but this support may be disabled in a future release.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
401
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
402 Perl was originally written to handle US-ASCII only (that is characters
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
403 whose ordinal numbers are in the range 0 - 127).
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
404 And documentation and comments may still use the term ASCII, when
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
405 sometimes in fact the entire range from 0 - 255 is meant.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
406
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
407 Note that Perl can be compiled and run under either ASCII or EBCDIC (See
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
408 L<perlebcdic>). Most of the documentation (and even comments in the code)
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
409 ignore the EBCDIC possibility.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
410 For almost all purposes the differences are transparent.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
411 As an example, under EBCDIC,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
412 instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
413 whenever this documentation refers to C<utf8>
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
414 (and variants of that name, including in function names),
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
415 it also (essentially transparently) means C<UTF-EBCDIC>.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
416 But the ordinals of characters differ between ASCII, EBCDIC, and
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
417 the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
418 than in UTF-8.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
419
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
420 The listing below is alphabetical, case insensitive.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
421
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
422 _EOB_
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
423
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
424 =head1 AUTHORS
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
425
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
426 Until May 1997, this document was maintained by Jeff Okamoto
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
427 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
428
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
429 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
430 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
431 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
432 Stephen McCamant, and Gurusamy Sarathy.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
433
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
434 API Listing originally by Dean Roehrich <roehrich@cray.com>.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
435
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
436 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
437
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
438 =head1 SEE ALSO
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
439
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
440 L<perlguts>, L<perlxs>, L<perlxstut>, L<perlintern>
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
441
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
442 _EOE_
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
443
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
444 # List of non-static internal functions
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
445 my @missing_guts =
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
446 grep $funcflags{$_}{flags} !~ /[As]/ && !$docs{guts}{$_}, keys %funcflags;
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
447
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
448 output('perlintern', <<'END', $docs{guts}, \@missing_guts, <<'END');
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
449 =head1 NAME
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
450
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
451 perlintern - autogenerated documentation of purely B<internal>
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
452 Perl functions
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
453
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
454 =head1 DESCRIPTION
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
455 X<internal Perl functions> X<interpreter functions>
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
456
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
457 This file is the autogenerated documentation of functions in the
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
458 Perl interpreter that are documented using Perl's internal documentation
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
459 format but are not marked as part of the Perl API. In other words,
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
460 B<they are not for use in extensions>!
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
461
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
462 END
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
463
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
464 =head1 AUTHORS
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
465
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
466 The autodocumentation system was originally added to the Perl core by
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
467 Benjamin Stuhl. Documentation is by whoever was kind enough to
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
468 document their functions.
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
469
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
470 =head1 SEE ALSO
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
471
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
472 L<perlguts>, L<perlapi>
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
473
a16537d2fe07 <xfix> tar xf perl-5.22.2.tar.gz # Ah, whatever, I\'m doing it anyway
HackBot
parents:
diff changeset
474 END