detecting pod in a file?

[Mike]

I want to detect if pod is embedded into a file or not.
Is there an easier way to detect the embedded pod other
than the sample code below?

Mike


my $file = '/tmp/file';
open(IN, "<$file") or die "$0: cannot read file '$file': $!";
my $pod = 1 if scalar(grep(/^=pod/o, <IN>)) > 0;
close(IN);
pod2html($file) if $pod;

 

[Paul Lalli]

I want to detect if pod is embedded into a file or not.

perldoc podchecker

Is there an easier way to detect the embedded pod other
than the sample code below?

This sample code has a few problems...

my $file = '/tmp/file';
open(IN, "<$file") or die "$0: cannot read file '$file': $!";

die() automatically includes the filename in its output, so $0 is
probably redundant there.

my $pod = 1 if scalar(grep(/^=pod/o, <IN>)) > 0;

1) This is only checking for a very specific POD command: =pod
That specific command is not likely to appear in every Perl file which
contains POD.
2) You're reading the entire file into one large list. This is a bad
idea.
3) You're grepping through the entire list regardless of whether or not
the pattern is found on the first line. Also a bad idea.
4) The assignment to one if the expression is greater than 0 seems
pointless. Just assign to the return value. (If you were to continue
to use that expression - which you shouldn't, of course).

You may wish to read:
perldoc -q contains

close(IN);
pod2html($file) if $pod;

Hope this helps,
Paul Lalli

 

[Miroslav Suchy]

I want to detect if pod is embedded into a file or not.
Is there an easier way to detect the embedded pod other
than the sample code below?
Yes.

my $file = '/tmp/file';
open(IN, "<$file") or die "$0: cannot read file '$file': $!";

my $pod=1;
while (my $line=<IN> and $pod) {
$pod=0 if ($line =~ m/^=pod/o);
}

close(IN);
pod2html($file) if $pod;

You have not to read whole file.

Miroslav Suchy

 

[Mike]

perldoc podchecker


This sample code has a few problems...


die() automatically includes the filename in its output, so $0 is
probably redundant there.

$file is the file being checked for =pod
$0 is the running perl script

1) This is only checking for a very specific POD command: =pod
That specific command is not likely to appear in every Perl file which
contains POD.

all POD must start with =pod or it is not formatted, yes?

2) You're reading the entire file into one large list. This is a bad
idea.

agreed, that's why it was only an idea

3) You're grepping through the entire list regardless of whether or not
the pattern is found on the first line. Also a bad idea.

=pod is not required to be on the first line
the first line of a script should be '#!'
the =pod could also be embedded in *.[ch] files or other documents

4) The assignment to one if the expression is greater than 0 seems
pointless. Just assign to the return value. (If you were to continue
to use that expression - which you shouldn't, of course).

good point, thanks

You may wish to read:
perldoc -q contains

I'll check that, thanks.

 

[Paul Lalli]

$file is the file being checked for =pod
$0 is the running perl script

Yes, I know what those variables are. I'm telling you that $0 is
redundant - that you would be effectively printing it out twice. die()
already prints it out.

all POD must start with =pod or it is not formatted, yes?

No. =pod is only one of several ways to start POD. Any POD command
(=head1, =over, etc) starts POD formatting. Just look at any of the
modules available on CPAN for examples. (For instance:
http://search.cpan.org/src/NWCLARK/perl-5.8.7/lib/strict.pm )

You may wish to read up on POD syntax:
perldoc perlpod

3) You're grepping through the entire list regardless of whether or not
the pattern is found on the first line. Also a bad idea.

=pod is not required to be on the first line
the first line of a script should be '#!'
the =pod could also be embedded in *.[ch] files or other documents

You miss my point. The point is that if your file is 20,000 lines
long, and you find the pattern you're looking for on line X, you're
still going to search through the remaining 20,000 - X lines of the
file, even though you already know the flag should be set. That's
wasteful.

I'll check that, thanks.

You're welcome. Please do make sure you also read the other perldoc I
mentioned:
perldoc podchecker

Basically, there is no need for you to write a script to do this. The
program `podchecker` that comes in the standard distribution will
output a message like so:
$ podchecker clpm.pl
clpm.pl does not contain any pod commands.
$ podchecker haspod.pl
haspod.pl pod syntax OK.

Paul Lalli

 

[Paul Lalli]

1) This is only checking for a very specific POD command: =pod
That specific command is not likely to appear in every Perl file which
contains POD.
2) You're reading the entire file into one large list. This is a bad
idea.
3) You're grepping through the entire list regardless of whether or not
the pattern is found on the first line. Also a bad idea.
4) The assignment to one if the expression is greater than 0 seems
pointless. Just assign to the return value. (If you were to continue
to use that expression - which you shouldn't, of course).

5) the /o modifier is doing absolutely nothing in that regexp to begin
with.
perldoc -q "/o"
Found in /opt/perl/lib/5.6.1/pod/perlfaq6.pod
What is "/o" really for?

...

Use of "/o" is irrelevant unless variable interpolation is
used in the pattern, and if so, the regex engine will
neither know nor care whether the variables change after the
pattern is evaluated the very first time.

Paul Lalli

 

[Mike]

5) the /o modifier is doing absolutely nothing in that regexp to begin
with.
perldoc -q "/o"
Found in /opt/perl/lib/5.6.1/pod/perlfaq6.pod
What is "/o" really for?

...

Use of "/o" is irrelevant unless variable interpolation is
used in the pattern, and if so, the regex engine will
neither know nor care whether the variables change after the
pattern is evaluated the very first time.

Paul Lalli

old habits

 

[Tad McClellan]

You have not to read whole file.

He *has* read the whole file.

Have you read his code?

Do you know what the input operator does when used in a list context?

 

[Tad McClellan]

old habits

ITYM bad habits