TITLE

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

VERSION

  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

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.

DESCRIPTION

Introduction

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:

Reimplementation of a component can be done independently and more easily when necessary, since the behavior of each component is well-defined.
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.
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.
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.

IMPLEMENTATION

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.

REFERENCES

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.

This file is part of the Perl 6 Archive