Mixing documentation and data

coolmichael has asked for the wisdom of the Perl Monks concerning the following question:

Replies are listed 'Best First'.
Re: Mixing documentation and data by tobyink (Canon) 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... Define your messages in your pod, and then make your module parse its own documentation at run-time to extract those messages. Define your messages in your code, and then generate your documentation from that at install time, using something like Pod Weaver. 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;` [download] 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`	[reply] [d/l]
Re^2: Mixing documentation and data by coolmichael (Deacon) on Feb 01, 2013 at 18:15 UTC
This is exactly the idea I was looking for. Thanks!	[reply]
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` [download] 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; $` [download] 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	[reply] [d/l] [select]
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.` [download]	[reply] [d/l]
Re^2: Mixing documentation and data by Anonymous Monk on Feb 01, 2013 at 07:26 UTC
So you want to duplicate the data?	[reply]
Re^3: Mixing documentation and data by tmharish (Friar) on Feb 01, 2013 at 07:30 UTC
Well you cant Interpolate Perl variables in POD	[reply]
Re^4: Mixing documentation and data by Anonymous Monk on Feb 01, 2013 at 10:13 UTC
Re^5: Mixing documentation and data by tmharish (Friar) on Feb 01, 2013 at 10:24 UTC
Some notes below your chosen depth have not been shown here
Re^2: Mixing documentation and data by KurtZ (Friar) on Feb 02, 2013 at 10:00 UTC
Don't_repeat_yourself In software engineering, Don't Repeat Yourself (DRY) is a principle of software development aimed at reducing repetition of information of all kinds!	[reply]
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. perlpod	[reply]