develooper Front page | perl.perl6.stdlib | Postings from September 2000

RFC 286 (v2) Add a "emit pod" runtime option to Perl

From:
Perl6 RFC Librarian
Date:
September 27, 2000 00:36
Subject:
RFC 286 (v2) Add a "emit pod" runtime option to Perl
Message ID:
20000927073611.7777.qmail@tmtowtdi.perl.org
This and other RFCs are available on the web at
  http://dev.perl.org/rfc/

=head1 TITLE

Add a "emit pod" runtime option to Perl

=head1 VERSION

  Maintainer: Adam Turoff <ziggy@panix.com>
  Date: 24 Sep 2000
  Last Modified: 26 Sep 2000
  Mailing List: perl6-stdlib@perl.org
  Number: 286
  Version: 2
  Status: Frozen

=head1 ABSTRACT

It would be really handy if there were a core mechanism to emit the
documentation embedded in a Perl program/module.

=head1 NOTES

Not much discussion came out of this proposal.  John Porter mentioned
that this would be trivial to implement, if RFC 79 is implemented.

=head1 DESCRIPTION

Tom Christiansen proposed this in his perl6storm message:

	=item perl6storm #0004

	Need perl to spit out pod/non-pod, like cc -E.  Pod is too hard to parse.
	This would make catpod trivially implemented as a compiler filter.

This feature would be quite useful, aside from just Tom's example of 'catpod'.

While RFC 79 proposes a much broader mechanism, this RFC proposes
that Perl simply have three modes - one where POD is ignored and 
Perl code is analyzed and interpreted, one mode where Perl code
is ignored and POD is emitted, and one mode where POD is ignored
and Perl code is emitted without any parsing or interpretation.

This RFC does not require RFC 79-style interleaved POD streams to
be implemented.

=head1 IMPLEMENTATION

Many options exist, including mucking around with the core to have a simple
commandline flag (e.g. C<perl -E>)

The most sensible implementation would be to write a standard module
that was a compiler backend, and invoked easliy, as in:

	perl -MPOD -e "emit()" *.pl *.pm t/*.t

Another option would be to tweak the parser to ignore Perl code and
simply emit any POD it would otherwise ignore, as well as emit
the Perl code it would otherwise process after ignoring POD as usual.

=head1 REFERENCES

RFC 79:

perl6storm




nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About