Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change

Mixing documentation and data

by coolmichael (Deacon)
on Feb 01, 2013 at 05:34 UTC ( #1016446=perlquestion: print w/replies, xml ) Need Help??
coolmichael has asked for the wisdom of the Perl Monks concerning the following question:

Suppose I have an error message package which associates error messages with error codes. I've got all the error codes and messages stored in the DATA section of the package, and it's working out very nicely.

But now I want to include the list of error codes and messages in the POD for the module somehow. I'm not sure how to do that.

Any suggestions are welcome, I'm open to rewriting and redesigning the package.

package FOO::Messages; ... __DATA__ eof:Unexpected end of file bad_tag:Syntax error in tag ...

Replies are listed 'Best First'.
Re: Mixing documentation and data
by tobyink (Abbot) on Feb 01, 2013 at 10:20 UTC

    I'm assuming you mean that you have a list of error codes and want this list to be included in the running source code for the program (as a hash or array or whatever), and also in the program's documentation, but without duplicating the list of error codes.

    There are three real options...

    1. Define your messages in your pod, and then make your module parse its own documentation at run-time to extract those messages.

    2. Define your messages in your code, and then generate your documentation from that at install time, using something like Pod Weaver.

    3. Perl and Pod are two different syntaxes. It is possible (usually using heredocs) to write text which can be executed as Perl and is also seen as Pod. Here's an example:

      use 5.010; use strict; use warnings; use Data::Dumper; our %messages = map /^\s+(.+?):(.+)$/?($1=>$2):(), split "\n", <<'=cut +'; =head1 MESSAGES The following messages are defined... eof:Unexpected end of file bad_tag:Syntax error in tag =cut print Dumper \%messages;

      View that file with perldoc and you'll see the list of messages. Execute it, and you'll see they get dumped.

    package Cow { use Moo; has name => (is => 'lazy', default => sub { 'Mooington' }) } say Cow->new->name
      This is exactly the idea I was looking for. Thanks!
Re: Mixing documentation and data (hash, i18n/ gettext/.po/.mo)
by Anonymous Monk on Feb 01, 2013 at 08:04 UTC

    Well, if you want to stick with perl, and don't want to duplicate the data, two ways

    __DATA__ =head1 ERROR MESSAGES =item * eof Unexpected end of file =cut

    Then when you're reading from *DATA, adjust your regex

    Or better idea, make it what it is, a hash

    $ podchecker junk junk pod syntax OK. $ perldoc junk ERROR MESSAGES %E2S = ( eof => 'Unexpected end of file', ); $ perl -Mstrict -Mwarnings junk { eof => "Unexpected end of file" } $ cat junk BEGIN { use vars qw' %E2S '; my $pod = <<'=head1 ERROR MESSAGES'; =head1 ERROR MESSAGES %E2S = ( eof => 'Unexpected end of file', ); =for no_pod_formatter =cut } use Data::Dump; dd\%E2S; $

    and even better idea is to use gettext, and generate the pod from your .po/.mo database, using whatever means,
    a utils/gettexttopod.PL (or utils/gettexttopod ) you wrote, or whatever

Re: Mixing documentation and data
by tmharish (Friar) on Feb 01, 2013 at 07:07 UTC

    Everything after __DATA__ is considered data.

    Have you tried this:
    package FOO::Messages; sub foo{} =head1 __DATA__ This is the data stuff here. =cut 1; __DATA__ data stuff here.
      So you want to duplicate the data?

      In software engineering, Don't Repeat Yourself (DRY) is a principle of software development aimed at reducing repetition of information of all kinds!

Re: Mixing documentation and data
by vinoth.ree (Monsignor) on Feb 01, 2013 at 05:56 UTC

    I guess you wanted to include your error codes into your perl module's POD document, So go through this link to get an idea.


Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://1016446]
Approved by vinoth.ree
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others cooling their heels in the Monastery: (11)
As of 2017-02-20 20:29 GMT
Find Nodes?
    Voting Booth?
    Before electricity was invented, what was the Electric Eel called?

    Results (302 votes). Check out past polls.