This and other RFCs are available on the web at
http://dev.perl.org/rfc/
=head1 TITLE
Components in the Perl Core Should Have Well-Defined APIs and Behavior
=head1 VERSION
Maintainer: Bradley M. Kuhn <[EMAIL PROTECTED]>
Date: 17 Aug 2000
Last Modified: 28 Sep 2000
Mailing List: [EMAIL PROTECTED]
Number: 125
Version: 2
Status: Frozen
=head1 ABSTRACT
Perl has a number of native data structures, as well as standard core
libraries that operate on those data structures. All components that are
needed to make perl, "Perl", should have well-defined APIs and behavior.
These APIs should be documented separately from the implementation, in a
language-independent and an object-oriented way.
=head1 DESCRIPTION
=head2 Introduction
L<RFC35> has already begun to discuss some of the ways perl might keep track
of its internal data. This RFC, by contrast, looks at the problem of Perl's
internal data (and core libraries) from a much higher level.
Perl has a number of native data structures (e.g., scalar, array, hash,
sub), as well as standard core libraries (e.g., print, substr, keys) that
operate on these data structures. Each of these components has some sort of
interface. For F<perl5>, these interfaces were loosely documented in the
source, occasionally in the POD documentation files, and sometimes in
additional documents such as the Perl Guts Illustrated.
However, the documentation of the APIs in F<perl5> was not really designed
to help new implementers. It was designed either as user documentation or
as work-in-progress attempts to keep track of the increasingly changing code
of F<perl5>.
With this new implementation, we should work towards a development
environment where the code is secondary to the API. We have shown that the
model of "the reference is the implementation" can no longer work for a
complex language such as Perl. We do not want ANSI-style bureaucracy, but
we should still seek a way to provide documentation of the Perl internals
separate from the implementation.
=head2 Primary Advantages
An internals API that is separate from the implementation will provide the
following advantages:
=over
=item *
Reimplementation of a component can be done independently and more easily
when necessary, since the behavior of each component is well-defined.
=item *
Parallel implementations can easily be developed. This is an important
feature for porting Perl to architectures for which reasonable C compilers
are not available, such as the Java Virtual Machine. In addition,
developing parallel implementations allows for experimentation, and
radically different implementation ideas can be easily compared.
=item *
Perl is special in part because its internal data structures provide amazing
external features. Well-defined APIs will perhaps make it possible for
Perl's data structures to be used in ways above and beyond perl itself.
=item *
The learning curve for new core developers to learn the perl internals will
be greatly reduced. Any good programmer can read and understand API
documentation. That API documentation will provide a roadmap for
understanding why the core is laid out in a particular way. Since the API
documentation will come first, it will rarely be incomplete.
=back
=head1 IMPLEMENTATION
=head2 An Object-Oriented and Language-Independent Approach
An object-oriented approach to an API is not perfect. However, in this
case, nearly all the behaviors of Perl's internal objects are well
understood. In addition, in F<perl5>, the internals are already roughly
object-oriented. Thus, an object-oriented approach is reasonable in this
case.
We should not tie this API documentation to any particular language, lest we
be influenced by the object-oriented features supported by that language.
Instead, we should document the API using terminology borrowed from any
object-oriented language or design methodology that seems appropriate. Such
a mix should not be problematic, as long as we are internally consistent in
our use of the terminology. Of course, some overriding methodology might be
chosen as a guiding force.
Building this object-oriented interface does not necessarily demand an
object-oriented implementation. The API should be general, and should not
demand any particular implementation strategy. Thus, choosing a simple
object-oriented approach for the API document does not limit future
implementation choices; it only defines the behavior that the internals must
provide.
=head2 Format of the API Documentation
This will be addressed in future RFCs after the langauge design process has
completed and the Internals Working Group no longer faces a moving target.
=head1 REFERENCES
RFC 35: A proposed internal base format for perl variables
Aas, Gisle. "Perl Guts Illustrated, Version 0.09". [Online] Available at
F<http://gisle.aas.no/perl/illguts/>. November 1999.
