}
$ret .= ")";
$ret .= " __attribute__((noreturn))" if $flags =~ /r/;
- if( $flags =~ /f/ ) {
+ if( $flags =~ /f/ ) {
my $prefix = $flags =~ /n/ ? '' : 'pTHX_';
- my $args = scalar @args;
+ my $args = scalar @args;
$ret .= "\n#ifdef CHECK_FORMAT\n";
$ret .= sprintf " __attribute__((format(printf,%s%d,%s%d)))",
- $prefix, $args - 1, $prefix, $args;
+ $prefix, $args - 1, $prefix, $args;
$ret .= "\n#endif\n";
}
$ret .= ";\n";
# hints
# copline
my @extvars = qw(sv_undef sv_yes sv_no na dowarn
- curcop compiling
+ curcop compiling
tainting tainted stack_base stack_sp sv_arenaroot
no_modify
curstash DBsub DBsingle debstash
- rsfp
+ rsfp
stdingv
defgv
errgv
open(EM, '> embed.h') or die "Can't create embed.h: $!\n";
print EM <<'END';
-/* !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
+/* !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
This file is built by embed.pl from data in embed.pl, pp.sym, intrpvar.h,
perlvars.h and thrdvar.h. Any changes made here will be lost!
*/
or die "Can't create embedvar.h: $!\n";
print EM <<'END';
-/* !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
+/* !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
This file is built by embed.pl from data in embed.pl, pp.sym, intrpvar.h,
perlvars.h and thrdvar.h. Any changes made here will be lost!
*/
or die "Can't create objXSUB.h: $!\n";
print OBX <<'EOT';
-/* !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
+/* !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
This file is built by embed.pl from data in embed.pl, pp.sym, intrpvar.h,
perlvars.h and thrdvar.h. Any changes made here will be lost!
*/
open(CAPIH, '> perlapi.h') or die "Can't create perlapi.h: $!\n";
print CAPIH <<'EOT';
-/* !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
+/* !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
This file is built by embed.pl from data in embed.pl, pp.sym, intrpvar.h,
perlvars.h and thrdvar.h. Any changes made here will be lost!
*/
close CAPIH;
print CAPI <<'EOT';
-/* !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
+/* !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
This file is built by embed.pl from data in embed.pl, pp.sym, intrpvar.h,
perlvars.h and thrdvar.h. Any changes made here will be lost!
*/
my %gutsdocs;
my %docfuncs;
-sub autodoc ($) { # parse a file and extract documentation info
- my($fh) = @_;
- my($in, $doc);
-
+sub autodoc ($$) { # parse a file and extract documentation info
+ my($fh,$file) = @_;
+ my($in, $doc, $line);
FUNC:
while (defined($in = <$fh>)) {
+ $line++;
if ($in =~ /^=for\s+apidoc\s+(.*)\n/) {
my $proto = $1;
$proto = "||$proto" unless $proto =~ /\|/;
my $docs = "";
DOC:
while (defined($doc = <$fh>)) {
+ $line++;
last DOC if $doc =~ /^=\w+/;
+ if ($doc =~ m:^\*/$:) {
+ warn "=cut missing? $file:$line:$doc";;
+ last DOC;
+ }
$docs .= $doc;
}
$docs = "\n$docs" if $docs and $docs !~ /^\n/;
if ($flags =~ /m/) {
if ($flags =~ /A/) {
- $apidocs{$name} = [$flags, $docs, $ret, @args];
+ $apidocs{$name} = [$flags, $docs, $ret, $file, @args];
}
else {
- $gutsdocs{$name} = [$flags, $docs, $ret, @args];
+ $gutsdocs{$name} = [$flags, $docs, $ret, $file, @args];
}
}
else {
- $docfuncs{$name} = [$flags, $docs, $ret, @args];
+ $docfuncs{$name} = [$flags, $docs, $ret, $file, @args];
}
- if ($doc =~ /^=for/) {
- $in = $doc;
- redo FUNC;
+ if (defined $doc) {
+ if ($doc =~ /^=for/) {
+ $in = $doc;
+ redo FUNC;
+ }
+ } else {
+ warn "$file:$line:$in";
}
}
}
sub docout ($$$) { # output the docs for one function
my($fh, $name, $docref) = @_;
- my($flags, $docs, $ret, @args) = @$docref;
+ my($flags, $docs, $ret, $file, @args) = @$docref;
- $docs .= "NOTE: the perl_ form of this function is deprecated.\n\n"
+ $docs .= "NOTE: this function is experimental and may change or be
+removed without notice.\n\n" if $flags =~ /x/;
+ $docs .= "NOTE: the perl_ form of this function is deprecated.\n\n"
if $flags =~ /p/;
print $fh "=item $name\n$docs";
print $fh "(" . join(", ", @args) . ")";
print $fh "\n\n";
}
+ print $fh "=for hackers\nFound in file $file\n\n";
}
my $file;
for $file (glob('*.c'), glob('*.h')) {
open F, "< $file" or die "Cannot open $file for docs: $!\n";
- autodoc(\*F);
+ autodoc(\*F,$file);
close F or die "Error closing $file: $!\n";
}
unlink "pod/perlapi.pod";
-open (DOC, ">pod/perlapi.pod") or
+open (DOC, ">pod/perlapi.pod") or
die "Can't create pod/perlapi.pod: $!\n";
walk_table { # load documented functions into approriate hash
if ($flags =~ /A/) {
my $docref = delete $docfuncs{$func};
warn "no docs for $func\n" unless $docref and @$docref;
- $apidocs{$func} = [$docref->[0] . 'A', $docref->[1], $retval, @args];
+ $docref->[0].="x" if $flags =~ /M/;
+ $apidocs{$func} = [$docref->[0] . 'A', $docref->[1], $retval,
+ $docref->[3], @args];
} else {
my $docref = delete $docfuncs{$func};
- $gutsdocs{$func} = [$docref->[0], $docref->[1], $retval, @args];
+ $gutsdocs{$func} = [$docref->[0], $docref->[1], $retval,
+ $docref->[3], @args];
}
}
return "";
} \*DOC;
for (sort keys %docfuncs) {
+ # Have you used a full for apidoc or just a func name?
+ # Have you used Ap instead of Am in the for apidoc?
warn "Unable to place $_!\n";
}
=head1 DESCRIPTION
-This file contains the documentation of the perl public API generated by
-embed.pl, specifically a listing of functions, macros, flags, and variables
-that may be used by extension writers. The interfaces of any functions that
+This file contains the documentation of the perl public API generated by
+embed.pl, specifically a listing of functions, macros, flags, and variables
+that may be used by extension writers. The interfaces of any functions that
are not listed here are subject to change without notice. For this reason,
blindly using functions listed in proto.h is to be avoided when writing
extensions.
close(DOC);
-open(GUTS, ">pod/perlintern.pod") or
+open(GUTS, ">pod/perlintern.pod") or
die "Unable to create pod/perlintern.pod: $!\n";
print GUTS <<'END';
=head1 NAME
-perlintern - autogenerated documentation of purely B<internal>
+perlintern - autogenerated documentation of purely B<internal>
Perl functions
=head1 DESCRIPTION
-This file is the autogenerated documentation of functions in the
+This file is the autogenerated documentation of functions in the
Perl interpreter that are documented using Perl's internal documentation
-format but are not marked as part of the Perl API. In other words,
+format but are not marked as part of the Perl API. In other words,
B<they are not for use in extensions>!
=over 8
=head1 AUTHORS
-The autodocumentation system was originally added to the Perl core by
-Benjamin Stuhl. Documentation is by whoever was kind enough to
+The autodocumentation system was originally added to the Perl core by
+Benjamin Stuhl. Documentation is by whoever was kind enough to
document their functions.
=head1 SEE ALSO
: o has no compatibility macro (#define foo Perl_foo)
: j not a member of CPerlObj
: x not exported
+: M may change
:
: Individual flags may be separated by whitespace.
:
p |OP* |append_elem |I32 optype|OP* head|OP* tail
p |OP* |append_list |I32 optype|LISTOP* first|LISTOP* last
p |I32 |apply |I32 type|SV** mark|SV** sp
+Ap |void |apply_attrs_string|char *stashpv|CV *cv|char *attrstr|STRLEN len
Ap |SV* |avhv_delete_ent|AV *ar|SV* keysv|I32 flags|U32 hash
Ap |bool |avhv_exists_ent|AV *ar|SV* keysv|U32 hash
Ap |SV** |avhv_fetch_ent |AV *ar|SV* keysv|I32 lval|U32 hash
Ap |SV* |avhv_iterval |AV *ar|HE* entry
Ap |HV* |avhv_keys |AV *ar
Apd |void |av_clear |AV* ar
-Ap |SV* |av_delete |AV* ar|I32 key|I32 flags
-Ap |bool |av_exists |AV* ar|I32 key
+Apd |SV* |av_delete |AV* ar|I32 key|I32 flags
+Apd |bool |av_exists |AV* ar|I32 key
Apd |void |av_extend |AV* ar|I32 key
-Ap |AV* |av_fake |I32 size|SV** svp
+p |AV* |av_fake |I32 size|SV** svp
Apd |SV** |av_fetch |AV* ar|I32 key|I32 lval
-Ap |void |av_fill |AV* ar|I32 fill
+Apd |void |av_fill |AV* ar|I32 fill
Apd |I32 |av_len |AV* ar
Apd |AV* |av_make |I32 size|SV** svp
Apd |SV* |av_pop |AV* ar
Apd |void |av_push |AV* ar|SV* val
-Ap |void |av_reify |AV* ar
+p |void |av_reify |AV* ar
Apd |SV* |av_shift |AV* ar
Apd |SV** |av_store |AV* ar|I32 key|SV* val
Apd |void |av_undef |AV* ar
Ap |void |gv_check |HV* stash
Ap |void |gv_efullname |SV* sv|GV* gv
Ap |void |gv_efullname3 |SV* sv|GV* gv|const char* prefix
+Ap |void |gv_efullname4 |SV* sv|GV* gv|const char* prefix|bool keepmain
Ap |GV* |gv_fetchfile |const char* name
Apd |GV* |gv_fetchmeth |HV* stash|const char* name|STRLEN len \
|I32 level
Ap |GV* |gv_fetchpv |const char* name|I32 add|I32 sv_type
Ap |void |gv_fullname |SV* sv|GV* gv
Ap |void |gv_fullname3 |SV* sv|GV* gv|const char* prefix
+Ap |void |gv_fullname4 |SV* sv|GV* gv|const char* prefix|bool keepmain
Ap |void |gv_init |GV* gv|HV* stash|const char* name \
|STRLEN len|int multi
Apd |HV* |gv_stashpv |const char* name|I32 create
Ap |U32 |to_uni_title_lc|U32 c
Ap |U32 |to_uni_lower_lc|U32 c
Ap |int |is_utf8_char |U8 *p
+Ap |bool |is_utf8_string |U8 *s|STRLEN len
Ap |bool |is_utf8_alnum |U8 *p
Ap |bool |is_utf8_alnumc |U8 *p
Ap |bool |is_utf8_idfirst|U8 *p
p |int |magic_nextpack |SV* sv|MAGIC* mg|SV* key
p |U32 |magic_regdata_cnt|SV* sv|MAGIC* mg
p |int |magic_regdatum_get|SV* sv|MAGIC* mg
+p |int |magic_regdatum_set|SV* sv|MAGIC* mg
p |int |magic_set |SV* sv|MAGIC* mg
p |int |magic_setamagic|SV* sv|MAGIC* mg
p |int |magic_setarylen|SV* sv|MAGIC* mg
Apd |SV* |newSVnv |NV n
Apd |SV* |newSVpv |const char* s|STRLEN len
Apd |SV* |newSVpvn |const char* s|STRLEN len
+Apd |SV* |newSVpvn_share |const char* s|STRLEN len|U32 hash
Afpd |SV* |newSVpvf |const char* pat|...
Ap |SV* |vnewSVpvf |const char* pat|va_list* args
Apd |SV* |newSVrv |SV* rv|const char* classname
Ap |char* |sv_pvn |SV *sv|STRLEN *len
Ap |char* |sv_pvutf8n |SV *sv|STRLEN *len
Ap |char* |sv_pvbyten |SV *sv|STRLEN *len
-Ap |I32 |sv_true |SV *sv
+Apd |I32 |sv_true |SV *sv
p |void |sv_add_arena |char* ptr|U32 size|U32 flags
Ap |int |sv_backoff |SV* sv
Apd |SV* |sv_bless |SV* sv|HV* stash
Apd |void |sv_chop |SV* sv|char* ptr
p |void |sv_clean_all
p |void |sv_clean_objs
-Ap |void |sv_clear |SV* sv
+Apd |void |sv_clear |SV* sv
Apd |I32 |sv_cmp |SV* sv1|SV* sv2
-Ap |I32 |sv_cmp_locale |SV* sv1|SV* sv2
+Apd |I32 |sv_cmp_locale |SV* sv1|SV* sv2
#if defined(USE_LOCALE_COLLATE)
Ap |char* |sv_collxfrm |SV* sv|STRLEN* nxp
#endif
Ap |void |sv_dump |SV* sv
Apd |bool |sv_derived_from|SV* sv|const char* name
Apd |I32 |sv_eq |SV* sv1|SV* sv2
-Ap |void |sv_free |SV* sv
+Apd |void |sv_free |SV* sv
p |void |sv_free_arenas
-Ap |char* |sv_gets |SV* sv|PerlIO* fp|I32 append
+Apd |char* |sv_gets |SV* sv|PerlIO* fp|I32 append
Apd |char* |sv_grow |SV* sv|STRLEN newlen
Apd |void |sv_inc |SV* sv
Apd |void |sv_insert |SV* bigsv|STRLEN offset|STRLEN len \
Apd |int |sv_isa |SV* sv|const char* name
Apd |int |sv_isobject |SV* sv
Apd |STRLEN |sv_len |SV* sv
-Ap |STRLEN |sv_len_utf8 |SV* sv
+Apd |STRLEN |sv_len_utf8 |SV* sv
Apd |void |sv_magic |SV* sv|SV* obj|int how|const char* name \
|I32 namlen
Apd |SV* |sv_mortalcopy |SV* oldsv
Ap |char* |sv_peek |SV* sv
Ap |void |sv_pos_u2b |SV* sv|I32* offsetp|I32* lenp
Ap |void |sv_pos_b2u |SV* sv|I32* offsetp
-Ap |char* |sv_pvn_force |SV* sv|STRLEN* lp
-Ap |char* |sv_pvutf8n_force|SV* sv|STRLEN* lp
+Apd |char* |sv_pvn_force |SV* sv|STRLEN* lp
+Apd |char* |sv_pvutf8n_force|SV* sv|STRLEN* lp
Ap |char* |sv_pvbyten_force|SV* sv|STRLEN* lp
-Ap |char* |sv_reftype |SV* sv|int ob
-Ap |void |sv_replace |SV* sv|SV* nsv
+Apd |char* |sv_reftype |SV* sv|int ob
+Apd |void |sv_replace |SV* sv|SV* nsv
Ap |void |sv_report_used
Ap |void |sv_reset |char* s|HV* stash
Afpd |void |sv_setpvf |SV* sv|const char* pat|...
Apd |void |sv_setsv |SV* dsv|SV* ssv
Ap |void |sv_taint |SV* sv
Ap |bool |sv_tainted |SV* sv
-Ap |int |sv_unmagic |SV* sv|int type
+Apd |int |sv_unmagic |SV* sv|int type
Apd |void |sv_unref |SV* sv
Ap |void |sv_untaint |SV* sv
Apd |bool |sv_upgrade |SV* sv|U32 mt
Ap |void |unsharepvn |const char* sv|I32 len|U32 hash
p |void |unshare_hek |HEK* hek
p |void |utilize |int aver|I32 floor|OP* version|OP* id|OP* arg
-Ap |U8* |utf16_to_utf8 |U16* p|U8 *d|I32 bytelen
-Ap |U8* |utf16_to_utf8_reversed|U16* p|U8 *d|I32 bytelen
+Ap |U8* |utf16_to_utf8 |U8* p|U8 *d|I32 bytelen|I32 *newlen
+Ap |U8* |utf16_to_utf8_reversed|U8* p|U8 *d|I32 bytelen|I32 *newlen
Ap |I32 |utf8_distance |U8 *a|U8 *b
Ap |U8* |utf8_hop |U8 *s|I32 off
+ApM |U8* |utf8_to_bytes |U8 *s|STRLEN *len
+ApM |U8* |bytes_to_utf8 |U8 *s|STRLEN *len
Ap |UV |utf8_to_uv |U8 *s|I32* retlen
Ap |U8* |uv_to_utf8 |U8 *d|UV uv
p |void |vivify_defelem |SV* sv
p |void |vivify_ref |SV* sv|U32 to_what
p |I32 |wait4pid |Pid_t pid|int* statusp|int flags
-p |void |report_closed_fh|GV *gv|IO *io|const char *func|const char *obj
+p |void |report_evil_fh |GV *gv|IO *io|I32 op
p |void |report_uninit
Afpd |void |warn |const char* pat|...
Ap |void |vwarn |const char* pat|va_list* args
#endif
Ap |int |runops_standard
Ap |int |runops_debug
+#if defined(USE_THREADS)
+Ap |SV* |sv_lock |SV *sv
+#endif
Afpd |void |sv_catpvf_mg |SV *sv|const char* pat|...
Ap |void |sv_vcatpvf_mg |SV* sv|const char* pat|va_list* args
Apd |void |sv_catpv_mg |SV *sv|const char *ptr
Ap |char* |sv_pv |SV *sv
Ap |char* |sv_pvutf8 |SV *sv
Ap |char* |sv_pvbyte |SV *sv
-Ap |void |sv_utf8_upgrade|SV *sv
-Ap |bool |sv_utf8_downgrade|SV *sv|bool fail_ok
-Ap |void |sv_utf8_encode |SV *sv
+Apd |void |sv_utf8_upgrade|SV *sv
+ApdM |bool |sv_utf8_downgrade|SV *sv|bool fail_ok
+ApdM |void |sv_utf8_encode |SV *sv
Ap |bool |sv_utf8_decode |SV *sv
Ap |void |sv_force_normal|SV *sv
Ap |void |tmps_grow |I32 n
-Ap |SV* |sv_rvweaken |SV *sv
+Apd |SV* |sv_rvweaken |SV *sv
p |int |magic_killbackrefs|SV *sv|MAGIC *mg
Ap |OP* |newANONATTRSUB |I32 floor|OP *proto|OP *attrs|OP *block
Ap |CV* |newATTRSUB |I32 floor|OP *o|OP *proto|OP *attrs|OP *block
#endif
#if defined(PERL_IN_DOOP_C) || defined(PERL_DECL_PROT)
-s |I32 |do_trans_CC_simple |SV *sv
-s |I32 |do_trans_CC_count |SV *sv
-s |I32 |do_trans_CC_complex |SV *sv
-s |I32 |do_trans_UU_simple |SV *sv
-s |I32 |do_trans_UU_count |SV *sv
-s |I32 |do_trans_UU_complex |SV *sv
-s |I32 |do_trans_UC_simple |SV *sv
-s |I32 |do_trans_CU_simple |SV *sv
-s |I32 |do_trans_UC_trivial |SV *sv
-s |I32 |do_trans_CU_trivial |SV *sv
+s |I32 |do_trans_simple |SV *sv
+s |I32 |do_trans_count |SV *sv
+s |I32 |do_trans_complex |SV *sv
+s |I32 |do_trans_simple_utf8 |SV *sv
+s |I32 |do_trans_count_utf8 |SV *sv
+s |I32 |do_trans_complex_utf8 |SV *sv
#endif
#if defined(PERL_IN_GV_C) || defined(PERL_DECL_PROT)
s |char* |scan_word |char *s|char *dest|STRLEN destlen \
|int allow_package|STRLEN *slp
s |char* |skipspace |char *s
+s |char* |swallow_bom |U8 *s
s |void |checkcomma |char *s|char *name|char *what
s |void |force_ident |char *s|int kind
s |void |incline |char *s
s |I32 |sublex_push
s |I32 |sublex_start
s |char * |filter_gets |SV *sv|PerlIO *fp|STRLEN append
+s |HV * |find_in_my_stash|char *pkgname|I32 len
s |SV* |new_constant |char *s|STRLEN len|const char *key|SV *sv \
|SV *pv|const char *type
s |int |ao |int toketype
# endif
#endif
-Arp |SV* |lock |SV *sv
-
#if defined(PERL_OBJECT)
};
#endif