On 03/02/01 Dan Sugalski wrote:
> >[gazing into crystal ball . . . ] I predict some header somewhere is going
> >to already #define "INT". Perhaps PERL_INT and PERL_NUM ?
>
> Good point. We should probably prefix all perl 6's data types and functions
> like we do in perl 5. Perl_ for functionish things, PL_ for dataish things.
It's awhile I wanted to spark some discussion in this area and this
comment made me want to write a PDD on API conventions. The result
follows. Comments welcome.
=head1 TITLE
Perl API conventions
=head1 VERSION
1
=head2 CURRENT
Maintainer: Paolo Molaro <[EMAIL PROTECTED]>
Class: Internals
PDD Number: Unassigned
Version: 1
Status: Developing
Last Modified: 3 March 2001
PDD Format: 1
Language: English
=head2 HISTORY
=over 4
=item Version 1
First version
=back
=head1 ABSTRACT
This PDD describes perl API conventions on function, type and macro names
as well as conventions for the order of the parameters and other general
guidelines to provide a clean and consistent API.
=head1 DESCRIPTION
The perl5 core uses a number of different prefixes (or none at all) for
function, macro and type names. This leads to all sorts of problems,
from namespace pollution (think embedding perl) to poor consistency
(think learning the perl internals).
This PDD proposes a set of conventions perl6 implementors must follow
when contributing to the core functions, macros and types that are
exported in a header file for use in the core or in extensions.
A C implementation is assumed in the examples: implementations in OO
languages mostly will drop the prefix in the function names.
The core as well as the extensions will use the same API (no more C<embed.c>).
=head1 IMPLEMENTATION
=head2 Interpreter contexts
The API should remain the same when perl is compiled to support threads or not
(or other similar features that require an interpreter context): this means that
an interpreter context is always passed as an argument to the functions that may
require it. This can be avoided in some cases if the interpreter context is stored
in the objects (this scenario is assumed in the examples below where a PerlSV
knows it has been created in a specific interpreter: this probably only matters
for references, a plain PerlSV should not need a context).
=head2 Type names
Type names shall begin with the C<Perl> prefix (note there is no underscore).
Examples could be:
PerlIV integer;
PerlSV *scalar;
PerlAV *array;
=head2 Function names
All the function names shall begin with the C<perl_> prefix. The only exception
is function names that may be used only in the perl core: these names shall
begin with the C<_perl_> prefix. This will make it possible to export only
the perl_* functions from the libperl library on the platforms that support that.
When a function applies to a well defined internal type, the function name will
be composed of three parts:
=over 4
=item * the C<perl_> prefix
=item * the type tag
=item * the action
=back
The type tag is usually derived from the lowercased type name and removing the C<perl>
prefix, Examples could be:
PerlSV *perl_interp_sv_new (PerlInterp *interpreter);
void perl_sv_set_nv (PerlSV *scalar, PerlNV value);
PerlSV *perl_av_fetch (PerlAV *array, PerlIV index, PerlIV lval);
When a function applies to an object such as a PerlSV, the object shall be the first
argument of the function.
=head2 Macro names and enumerations
Macro names and enumeration values shall follow the conventions for function names
with the only difference of using uppercase instead of lowercase.
=head2 Global variable names
Global variables? What global variables?
=head2 Interfacing with extensions
Note: this will need to be expanded.
Extension will install C functions that have the following signature:
int extension_func (PerlContext *context, PerlAV *args, PerlAV *result);
PerlContext will contain the necessary info about the context the function is run
in, such as a PerlInterp*, the info to support want() and so on.
The C<args> array will contain the arguments passed to the function.
Any result will be pushed to the C<result> array. This means that there is no
need to learn a different API to push values on a stack opposed to push
values into an array.
The meaning of the integer return value will depend on other aspects of the
internals (exception handling for example).
=head1 REFERENCES
perlguts.pod
The conventions used in other successful free software projects like The Gimp,
GLib and Gtk+.
--
-----------------------------------------------------------------
[EMAIL PROTECTED] debian/rules
[EMAIL PROTECTED] Monkeys do it better
