[% setvar title Components in the Perl Core Should Have Well-Defined APIs and Behavior %]

This file is part of the Perl 6 Archive

Note: these documents may be out of date. Do not use as reference!

To see what is currently happening visit http://www.perl6.org/


Components in the Perl Core Should Have Well-Defined APIs and Behavior


  Maintainer: Bradley M. Kuhn <bkuhn@ebb.org>
  Date: 17 Aug 2000
  Last Modified: 28 Sep 2000
  Mailing List: perl6-internals@perl.org 
  Number: 125
  Version: 2
  Status: Frozen


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.



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 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 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 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.

Primary Advantages

An internals API that is separate from the implementation will provide the following advantages:


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 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.

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.


RFC 35: A proposed internal base format for perl variables

Aas, Gisle. "Perl Guts Illustrated, Version 0.09". [Online] Available at gisle.aas.no. November 1999.