views:

68

answers:

1

When using keys %:: to get a list of the currently loaded root namespaces, the Internals:: package is loaded by default (along with UNIVERSAL:: and a few others). However, I haven't found any documentation for the functions in Internals::

keys %{Internals::} returns SvREFCNT hv_clear_placeholders hash_seed SvREADONLY HvREHASH rehash_seed

All of these can probably be looked up in Perl's C API docs, but is there any Perl level documentation for them? Is the package stable? It's used by several core modules (Hash::Util for one), so I imagine it is, but the lack of documentation is a bit troubling.

I didn't see Internals.pm in the Perl distribution (different name maybe?), and it is not the Internals module up on CPAN.

Note: I fully understand that the functions in Internals:: are potentially dangerous, and I do not have any particular use in mind. I was reading through Hash::Util's source and came across it.

+5  A: 

IIRC the code is not Internals.pm but libinternals.c. It looks like they used to be in universal.c in Perl 5.8 but got migrated out.

As per 03/2009 and Perl 5.10 they were not documented as per this perlmonks thread.

Also, in the same thread, ysth states:

Undocumented things in universal.c should not be depended on; they should only be used by core modules. They aren't documented on purpose, to allow them to be changed whenever and however necessary. For those purposes, the code is good enough documentation.

DVK
the comments in `universal.c` are great: `/* This is dangerous stuff. */` ... `/* I hope you really know what you are doing. */`
Eric Strom
"...the code is good enough documentation" -- that doesn't prevent people from writing code against the current implementation and seeing it break when changes are made.
Ether
The link you provided earlier - http://perlbin.sourceforge.net/perlcompiler/perl.internals.pdf - looks interesting, although it appears quite outdated.
Ether
@Ether - it does not seem to be centered on explaining internals:: module (which probably geled together after that was written?) and so, while interesting, i deemed it to be somewhat irrelevant to this Q.
DVK
@Eric - in an interesting timing, I'm releasing an initial version of Perl module today which has a comment: `# Now, for the voodoo. DON'T MESS WITH THIS CODE IF YOU DON'T KNOW WHAT YOU ARE DOING - deep Perl magic!`. In reality the magic is more David Copperfield than deep voodoo, but the target audience is pretty far from people likely to be reading libinternals.c :)
DVK
@DVK: suggestion: also explain your voodoo in comments, or you will be scratching your head in a few years wondering why on earth you did it the way you did and what you were thinking. Trust me. :)
Ether
@Ether - of course. I always do, voodoo or not. I'm a software developer, not a coder. Though in this case the voodoo is embarassingly easy as far as I'm concerned :)
DVK