This and other RFCs are available on the web at http://dev.perl.org/rfc/ =head1 TITLE The Predefined POD Streams are C<perl>, C<data>, and C<doc> =head1 VERSION Maintainer: John Porter <[EMAIL PROTECTED]> Mailing List: [EMAIL PROTECTED] Date: 9 Aug 2000 Last Modified: 7 Sep 2000 Number: 79 Version: 3 =head1 ABSTRACT Source files are pre-processed through a filter which breaks the text into multiple "streams" of paragraphs, using POD directives. Perl code, documentation ("POD"), and data are three pre-defined such streams, introduced by C<=perl>, C<=doc>, and C<=data> directives, respectively. A special (global?) hash of filehandles is created, keyed as appropriate, enabling user code to read the streams of perl code, documentation, and data. This unifies perl5's C<__DATA__> with POD, and allows any text to be both code and documentation. =head1 CHANGES Version 2 of this RFC was entitled "Perl Compiler is Just Another Pod Processor". Versions 1 and 2 failed to distinguish between the input streams, and the special pod formatter diversions. This version makes the distinction clear, and furthermore asserts the use of C<=begin>/C<=end> for the former only. Version 1 of this RFC was entitled "Code which is both executable and POD". Version 1 of this RFC proposed a special "perl" POD processor type. Version 2 made the "perl" type non-special. This version calls "perl", "doc", and "data" streams, as distinct from POD processor types. Version 1 proposed a simple implementation which could theoretically work with the perl5 front end. Later versions presume that the perl6 front end is game for any implementation details necessary to support the proposal. =head1 DESCRIPTION Each file is treated as a set of (possibly entertwined) text streams, of which three are predefined: perl code, data, and documentation. Which stream a given paragraph belongs to is controlled by POD-style directives, C<=begin> and C<=end>, each of which take one or more optional arguments naming the affected stream. Multiple directives can be combined on a single line, separated by commas. A special alias, C<all>, refers to all known streams. =end all, begin doc This here is documentation, and nothin' else. =end Note that an C<=end> directive with no arguments causes the effects of the most recent C<=begin> to be reversed -- in this example, the C<doc> stream is ended and the previous streams resumed. As a convenience, some shorthand directives are defined: =perl =data =doc which are equivalent, respectively, to: =end all, begin perl =end all, begin data =end all, begin doc So the above example may be written as: =doc This here is documentation, and nothin' else. =end Note that the C<code> stream is always implicitly in effect at the beginning of each file/module. =head2 How the Streams are Used The user code in the current module may read any of the streams. =head3 DATA Section To read the data section, user code can do something like this: while ( $pod{'data'}->readline ) { ... which will be the direct replacement for older perls' while ( <DATA> ) { ... =head3 POD Processors When a POD processor goes to scan a file for documentation, it need only request that the POD streams be initialized (by whatever mechanism is created to do this -- see L</IMPLEMENTATION>), and then it uses the C<$pod{'doc'}> filehandle, or something like it. =head3 Perl Source Code Stream The perl compiler sees only the stream of text from the C<perl> stream, which is also available to the user code via a special filehandle, something like C<$pod{'perl'}>. =head2 Affect on Special POD Formatters This RFC usurps the C<=begin> and C<=end> directives, which are used in previous versions of Perl to designate sections for special POD formatters. Some replacement for these should be devised. It does not affect the existing semantics of C<=for>. =head2 Combining Code and Documentation One of the motivations for this RFC was to allow arbitrary text to be treated as both executable perl code and as documentation, thus allowing actual perl code to appear in POD-generated documentation. Example: =begin code doc sub foo($$$$) { my( $marg, $bar, $sheitane, $bozorg ) = @_; =end # non-doc code here... } This shows the declaration of a subroutine being both actual perl code and appearing in the doc stream. =head1 IMPLEMENTATION The POD specification is modified from its perl5 form, to allow "streams" of input paragraphs not only of C<pod>, but also C<data>, and, for uniformity, C<perl>. All of them are readable via special filehandles, localized in a special (global?) hash of filehandles. C<=pod>, etc., are implemented as shorthands for directives built on C<=begin>. Furthermore, a special pseudo-stream name, C<all>, is an alias for all known stream names, i.e. C<perl>, C<data>, and C<doc>. The perl compiler reads input from the C<perl> stream. The C<=cut> POD directive is disused. The mechanism which parses the file, looking for C<=begin>/C<=end> directives must be called implicitly whenever perl loads a source file, and set up a hash to contain the special filehandles by which the various pod streams can be read. Probably the best way to do this is to reserve a global hash variable to hold them, and localize the values of it for the scope of the file. In addition, the above-mentioned parsing mechanism should be callable explicitly from user code; it would take a hash (by reference), and a file name. This feature will be needed by POD processing systems. For example, a POD processor would do something like this: my $file_having_doco = shift; my %pod_streams; parse_pod_streams( %pod_streams, $file_having_doco ); local $/ = ""; while ( $pod_streams{'doc'}->readline ) { # process a paragraph. } The parsing mechanism will need to maintain a stack of "currently open streams", since a bare C<=end> reverts to the set of streams in effect before the nearest preceding C<=begin>. =head1 REFERENCES "access to pod/doc text by code", mail thread rooted at http://www.mail-archive.com/perl6-language@perl.org/msg01471.html RFC 5: Multiline Comments for Perl RFC 11: Examples encoded with =also for|begin|end POD commands RFC 44: Bring Documentation Closer To Whatever It Documents perlpod for discussion of POD.
