[% setvar title The Predefined POD Streams are C, C, and C %]

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/

TITLE

The Predefined POD Streams are perl, data, and doc

VERSION

  Maintainer: John Porter <jdporter@min.net>
  Date: 9 Aug 2000
  Last Modified: 7 Sep 2000
  Mailing List: perl6-language@perl.org
  Number: 79
  Version: 3
  Status: Developing

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 =perl, =doc, and =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 __DATA__ with POD, and allows any text to be both code and documentation.

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 =begin/=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.

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, =begin and =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, all, refers to all known streams.

	=end all, begin doc

	This here is documentation, and nothin' else.

	=end

Note that an =end directive with no arguments causes the effects of the most recent =begin to be reversed -- in this example, the 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 code stream is always implicitly in effect at the beginning of each file/module.

How the Streams are Used

The user code in the current module may read any of the streams.

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

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 "IMPLEMENTATION"), and then it uses the $pod{'doc'} filehandle, or something like it.

Perl Source Code Stream

The perl compiler sees only the stream of text from the perl stream, which is also available to the user code via a special filehandle, something like $pod{'perl'}.

Affect on Special POD Formatters

This RFC usurps the =begin and =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 =for.

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.

IMPLEMENTATION

The POD specification is modified from its perl5 form, to allow "streams" of input paragraphs not only of pod, but also data, and, for uniformity, perl. All of them are readable via special filehandles, localized in a special (global?) hash of filehandles. =pod, etc., are implemented as shorthands for directives built on =begin. Furthermore, a special pseudo-stream name, all, is an alias for all known stream names, i.e. perl, data, and doc.

The perl compiler reads input from the perl stream.

The =cut POD directive is disused.

The mechanism which parses the file, looking for =begin/=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 =end reverts to the set of streams in effect before the nearest preceding =begin.

REFERENCES

"access to pod/doc text by code", mail thread rooted at www.mail-archive.com

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.