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 Version: 1 Mailing List: [EMAIL PROTECTED] Number: 125 =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 STATUS In-Discussion =head1 DESCRIPTION =head2 Introduction L<RFC 35|perl6-RFCs/"35"> 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 either be addressed in future versions of this RFC, or in a separate RFC. =head1 REFERENCES RFC 35: A proposed internal base format for perl Aas, Gisle. "Perl Guts Illustrated, Version 0.09". [Online] Available at F<http://gisle.aas.no/perl/illguts/>. November 1999.
