To see what is currently happening visit http://www.perl6.org/
The Predefined POD Streams are perl, data, and doc
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
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.
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.
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.
The user code in the current module may read any of the streams.
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> ) { ...
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.
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'}.
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.
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.
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.
"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.