From 49655cb6e58802c0fc6f013741c03968c9ab6f06 Mon Sep 17 00:00:00 2001 From: Marius Gavrilescu Date: Fri, 17 Jul 2015 13:52:55 +0300 Subject: [PATCH] Move POD after __END__ --- lib/Pod/Constants.pm | 358 +++++++++++++++++++++---------------------- 1 file changed, 176 insertions(+), 182 deletions(-) diff --git a/lib/Pod/Constants.pm b/lib/Pod/Constants.pm index 33fed16..e3839fd 100644 --- a/lib/Pod/Constants.pm +++ b/lib/Pod/Constants.pm @@ -5,79 +5,6 @@ package Pod::Constants; -=head1 NAME - -Pod::Constants - Include constants from POD - -=head1 SYNOPSIS - - use vars qw($myvar $VERSION @myarray $html %myhash); - - use Pod::Constants -trim => 1, - 'Pod Section Name' => \$myvar, - 'Version' => sub { eval }, - 'Some list' => \@myarray, - html => \$html, - 'Some hash' => \%myhash; - - =head2 Pod Section Name - - This string will be loaded into $myvar - - =head2 Version - - # This is an example of using a closure. $_ is set to the - # contents of the paragraph. In this example, "eval" is - # used to execute this code at run time. - $VERSION = 0.17; - - =head2 Some list - - Each line from this section of the file - will be placed into a separate array element. - For example, this is $myarray[2]. - - =head2 Some hash - - This text will not go into the hash, because - it doesn't look like a definition list. - key1 => Some value (this will go into the hash) - var2 => Some Other value (so will this) - wtf = This won't make it in. - - =head2 %myhash's value after the above: - - ( key1 => "Some value (this will go into the hash)", - var2 => "Some Other value (so will this)" ) - - =begin html

This text will be in $html

- - =cut - -=head1 DESCRIPTION - -This module allows you to specify those constants that should be -documented in your POD, and pull them out a run time in a fairly -arbitrary fashion. - -Pod::Constants uses Pod::Parser to do the parsing of the source file. -It has to open the source file it is called from, and does so directly -either by lookup in %INC or by assuming it is $0 if the caller is -"main" (or it can't find %INC{caller()}) - -=head2 ARBITARY DECISIONS - -I have made this code only allow the "Pod Section Name" to match -`headN', `item', `for' and `begin' POD sections. If you have a good -reason why you think it should match other POD sections, drop me a -line and if I'm convinced I'll put it in the standard version. - -For `for' and `begin' sections, only the first word is counted as -being a part of the specifier, as opposed to `headN' and `item', where -the entire rest of the line counts. - -=cut - use 5.004; use strict; @@ -201,80 +128,6 @@ sub verbatim { # Pod::Parser overloaded textblock sub textblock { goto \&verbatim } -=head1 FUNCTIONS - -=head2 import(@args) - -This function is called when we are "use"'d. It determines the source -file by inspecting the value of caller() or $0. - -The form of @args is HOOK => $where. - -$where may be a scalar reference, in which case the contents of the -POD section called "HOOK" will be loaded into $where. - -$where may be an array reference, in which case the contents of the -array will be the contents of the POD section called "HOOK", split -into lines. - -$where may be a hash reference, in which case any lines with a "=>" -symbol present will have everything on the left have side of the => -operator as keys and everything on the right as values. You do not -need to quote either, nor have trailing commas at the end of the -lines. - -$where may be a code reference (sub { }), in which case the sub is -called when the hook is encountered. $_ is set to the value of the -POD paragraph. - -You may also specify the behaviour of whitespace trimming; by default, -no trimming is done except on the HOOK names. Setting "-trim => 1" -turns on a package "global" (until the next time import is called) -that will trim the $_ sent for processing by the hook processing -function (be it a given function, or the built-in array/hash -splitters) for leading and trailing whitespace. - -The name of HOOK is matched against any "=head1", "=head2", "=item", -"=for", "=begin" value. If you specify the special hooknames "*item", -"*head1", etc, then you will get a function that is run for every - -Note that the supplied functions for array and hash splitting are -exactly equivalent to fairly simple Perl blocks: - -Array: - - HOOK => sub { @array = split /\n/, $_ } - -Hash: - - HOOK => sub { - %hash = - (map { map { s/^\s+|\s+$//g; $_ } split /=>/, $_ } - (grep m/^ - ( (?:[^=]|=[^>])+ ) # scan up to "=>" - => - ( (?:[^=]|=[^>])+ =? )# don't allow more "=>"'s - $/x, split /\n/, $_)); - } - -Well, they're simple if you can grok map, a regular expression like -that and a functional programming style. If you can't I'm sure it is -probably voodoo to you. - -Here's the procedural equivalent: - - HOOK => sub { - for my $line (split /\n/, $_) { - my ($key, $value, $junk) = split /=>/, $line; - next if $junk; - $key =~ s/^\s+|\s+$//g - $value =~ s/^\s+|\s+$//g - $hash{$key} = $value; - } - }, - -=cut - sub import { my $class = shift; @@ -299,13 +152,6 @@ sub import { goto \&import_from_file; } -=head2 import_from_file($filename, @args) - -Very similar to straight "import", but you specify the source filename -explicitly. - -=cut - use IO::Handle; sub import_from_file { @@ -333,17 +179,6 @@ sub import_from_file { close $fh; } -=head2 add_hook(NAME => value) - -This function adds another hook, it is useful for dynamic updating of -parsing through the document. - -For an example, please see t/01-constants.t in the source -distribution. More detailed examples will be added in a later -release. - -=cut - sub add_hook { my $parser; if ( UNIVERSAL::isa($_[0], __PACKAGE__) ) { @@ -378,12 +213,6 @@ sub add_hook { } } -=head2 delete_hook(@list) - -Deletes the named hooks. Companion function to add_hook - -=cut - sub delete_hook { my $parser; if ( UNIVERSAL::isa($_[0], __PACKAGE__) ) { @@ -399,6 +228,181 @@ sub delete_hook { } } +BEGIN { + Pod::Constants->import + ( + SYNOPSIS => sub { + eval pop @{[ grep /^\s*\$VERSION/, split /\n/, $_ ]} + } + ) +}; + +1.4142; +__END__ + +=encoding utf-8 + +=head1 NAME + +Pod::Constants - Include constants from POD + +=head1 SYNOPSIS + + use vars qw($myvar $VERSION @myarray $html %myhash); + + use Pod::Constants -trim => 1, + 'Pod Section Name' => \$myvar, + 'Version' => sub { eval }, + 'Some list' => \@myarray, + html => \$html, + 'Some hash' => \%myhash; + + =head2 Pod Section Name + + This string will be loaded into $myvar + + =head2 Version + + # This is an example of using a closure. $_ is set to the + # contents of the paragraph. In this example, "eval" is + # used to execute this code at run time. + $VERSION = 0.17; + + =head2 Some list + + Each line from this section of the file + will be placed into a separate array element. + For example, this is $myarray[2]. + + =head2 Some hash + + This text will not go into the hash, because + it doesn't look like a definition list. + key1 => Some value (this will go into the hash) + var2 => Some Other value (so will this) + wtf = This won't make it in. + + =head2 %myhash's value after the above: + + ( key1 => "Some value (this will go into the hash)", + var2 => "Some Other value (so will this)" ) + + =begin html

This text will be in $html

+ + =cut + +=head1 DESCRIPTION + +This module allows you to specify those constants that should be +documented in your POD, and pull them out a run time in a fairly +arbitrary fashion. + +Pod::Constants uses Pod::Parser to do the parsing of the source file. +It has to open the source file it is called from, and does so directly +either by lookup in %INC or by assuming it is $0 if the caller is +"main" (or it can't find %INC{caller()}) + +=head2 ARBITARY DECISIONS + +I have made this code only allow the "Pod Section Name" to match +`headN', `item', `for' and `begin' POD sections. If you have a good +reason why you think it should match other POD sections, drop me a +line and if I'm convinced I'll put it in the standard version. + +For `for' and `begin' sections, only the first word is counted as +being a part of the specifier, as opposed to `headN' and `item', where +the entire rest of the line counts. + +=head1 FUNCTIONS + +=head2 import(@args) + +This function is called when we are "use"'d. It determines the source +file by inspecting the value of caller() or $0. + +The form of @args is HOOK => $where. + +$where may be a scalar reference, in which case the contents of the +POD section called "HOOK" will be loaded into $where. + +$where may be an array reference, in which case the contents of the +array will be the contents of the POD section called "HOOK", split +into lines. + +$where may be a hash reference, in which case any lines with a "=>" +symbol present will have everything on the left have side of the => +operator as keys and everything on the right as values. You do not +need to quote either, nor have trailing commas at the end of the +lines. + +$where may be a code reference (sub { }), in which case the sub is +called when the hook is encountered. $_ is set to the value of the +POD paragraph. + +You may also specify the behaviour of whitespace trimming; by default, +no trimming is done except on the HOOK names. Setting "-trim => 1" +turns on a package "global" (until the next time import is called) +that will trim the $_ sent for processing by the hook processing +function (be it a given function, or the built-in array/hash +splitters) for leading and trailing whitespace. + +The name of HOOK is matched against any "=head1", "=head2", "=item", +"=for", "=begin" value. If you specify the special hooknames "*item", +"*head1", etc, then you will get a function that is run for every + +Note that the supplied functions for array and hash splitting are +exactly equivalent to fairly simple Perl blocks: + +Array: + + HOOK => sub { @array = split /\n/, $_ } + +Hash: + + HOOK => sub { + %hash = + (map { map { s/^\s+|\s+$//g; $_ } split /=>/, $_ } + (grep m/^ + ( (?:[^=]|=[^>])+ ) # scan up to "=>" + => + ( (?:[^=]|=[^>])+ =? )# don't allow more "=>"'s + $/x, split /\n/, $_)); + } + +Well, they're simple if you can grok map, a regular expression like +that and a functional programming style. If you can't I'm sure it is +probably voodoo to you. + +Here's the procedural equivalent: + + HOOK => sub { + for my $line (split /\n/, $_) { + my ($key, $value, $junk) = split /=>/, $line; + next if $junk; + $key =~ s/^\s+|\s+$//g + $value =~ s/^\s+|\s+$//g + $hash{$key} = $value; + } + }, + +=head2 import_from_file($filename, @args) + +Very similar to straight "import", but you specify the source filename +explicitly. + +=head2 add_hook(NAME => value) + +This function adds another hook, it is useful for dynamic updating of +parsing through the document. + +For an example, please see t/01-constants.t in the source +distribution. More detailed examples will be added in a later +release. + +=head2 delete_hook(@list) + +Deletes the named hooks. Companion function to add_hook + =head2 CLOSURES AS DESTINATIONS If the given value is a ref CODE, then that function is called, with @@ -504,15 +508,5 @@ Source is kept at git://utsl.gen.nz/Pod-Constants -=cut - -BEGIN { - Pod::Constants->import - ( - SYNOPSIS => sub { - eval pop @{[ grep /^\s*\$VERSION/, split /\n/, $_ ]} - } - ) -}; -1.4142; +=cut -- 2.30.2