develooper Front page | perl.perl5.porters | Postings from September 2003

Perl_foo vs. foo perl API in documentation

Thread Next
From:
Stas Bekman
Date:
September 29, 2003 16:39
Subject:
Perl_foo vs. foo perl API in documentation
Message ID:
3F78C2BA.2050602@stason.org
Finally I had a chance to read the whole new perldelta for 5.8.1. This para is 
not so clear to me:

<perldelta>
Certain Perl core C APIs like C<Perl_list> are no longer available
without their C<Perl_> prefix.  If your XS module stops working
because some functions cannot be found, in many cases a simple fix is
to add the C<Perl_> prefix to the function and the thread context
C<aTHX_> as the first argument of the function call.  This is also how
it should always have been done: letting the Perl_-less forms to leak
from the core was an accident.  For cleaner embedding you can also
force this for all APIs by defining at compile time the cpp define
PERL_NO_SHORT_NAMES.
</perldelta>

But anybody who wants to use perl API has to read perlapi.pod, which doesn't 
use the Perl_ prefix in most cases. And sometimes it's inconsistent, e.g. for 
Perl_form the entry mixes the two:

       form    Takes a sprintf-style format pattern and conventional (non-SV)
                arguments and returns the formatted string.

                    (char *) Perl_form(pTHX_ const char* pat, ...)

I'm sure that other pods use a lot of short forms as well.

So it's not surprising that non-core developers are using the short form in 
their XS/embedding code. IMHO, it's not not leaked from the core, it's 
"endorsed" by perl's own documentation. Unless I miss something obvious here.


__________________________________________________________________
Stas Bekman            JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/     mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org   http://ticketmaster.com


Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About