use vars qw($VERSION @Pagers $Bindir $Pod2man
$Temp_Files_Created $Temp_File_Lifetime
);
-$VERSION = '3.14_04';
+$VERSION = '3.14_07';
#..........................................................................
BEGIN { # Make a DEBUG constant very first thing...
sub TRUE () {1}
sub FALSE () {return}
+sub BE_LENIENT () {1}
BEGIN {
*IS_VMS = $^O eq 'VMS' ? \&TRUE : \&FALSE unless defined &IS_VMS;
#
# Option accessors...
-foreach my $subname (map "opt_$_", split '', q{mhlvriFfXqnTdUL}) {
+foreach my $subname (map "opt_$_", split '', q{mhlDriFfXqnTdULv}) {
no strict 'refs';
*$subname = do{ use strict 'refs'; sub () { shift->_elem($subname, @_) } };
}
sub opt_q_with { shift->_elem('opt_q', @_) }
sub opt_d_with { shift->_elem('opt_d', @_) }
sub opt_L_with { shift->_elem('opt_L', @_) }
+sub opt_v_with { shift->_elem('opt_v', @_) }
sub opt_w_with { # Specify an option for the formatter subclass
my($self, $value) = @_;
#..........................................................................
-sub aside { # If we're in -v or DEBUG mode, say this.
+sub aside { # If we're in -D or DEBUG mode, say this.
my $self = shift;
- if( DEBUG or $self->opt_v ) {
+ if( DEBUG or $self->opt_D ) {
my $out = join( '',
DEBUG ? do {
my $callsub = (caller(1))[3];
perldoc [options] PageName|ModuleName|ProgramName...
perldoc [options] -f BuiltinFunction
perldoc [options] -q FAQRegex
+perldoc [options] -v PerlVariable
Options:
-h Display this help message
-n Specify replacement for nroff
-l Display the module's file name
-F Arguments are file names, not modules
- -v Verbosely describe what's going on
+ -D Verbosely describe what's going on
-T Send output to STDOUT without any pager
-d output_filename_to_send_to
-o output_format_name
-L translation_code Choose doc translation (if any)
-X use index if present (looks for pod.idx at $Config{archlib})
-q Search the text of questions (not answers) in perlfaq[1-9]
+ -f Search Perl built-in functions
+ -v Search predefined Perl variables
PageName|ModuleName...
is the name of a piece of documentation that you want to look at. You
$me =~ s,.*[/\\],,; # get basename
die <<"EOUSAGE";
-Usage: $me [-h] [-V] [-r] [-i] [-v] [-t] [-u] [-m] [-n nroffer_program] [-l] [-T] [-d output_filename] [-o output_format] [-M FormatterModuleNameToUse] [-w formatter_option:option_value] [-L translation_code] [-F] [-X] PageName|ModuleName|ProgramName
+Usage: $me [-h] [-V] [-r] [-i] [-D] [-t] [-u] [-m] [-n nroffer_program] [-l] [-T] [-d output_filename] [-o output_format] [-M FormatterModuleNameToUse] [-w formatter_option:option_value] [-L translation_code] [-F] [-X] PageName|ModuleName|ProgramName
$me -f PerlFunc
$me -q FAQKeywords
+ $me -A PerlVar
The -h option prints more help. Also try "perldoc perldoc" to get
acquainted with the system. [Perldoc v$VERSION]
$self->{'pages'} = \@pages;
if( $self->opt_f) { @pages = ("perlfunc") }
elsif( $self->opt_q) { @pages = ("perlfaq1" .. "perlfaq9") }
+ elsif( $self->opt_v) { @pages = ("perlvar") }
else { @pages = @{$self->{'args'}};
# @pages = __FILE__
# if @pages == 1 and $pages[0] eq 'perldoc';
DEBUG > 4 and print "Trying to eval 'require $c'...\n";
local $^W = $^W;
- if(DEBUG() or $self->opt_v) {
+ if(DEBUG() or $self->opt_D) {
# feh, let 'em see it
} else {
$^W = 0;
if (@files) {
$self->aside( "Found as @files\n" );
}
+ # add "perl" prefix, so "perldoc foo" may find perlfoo.pod
+ elsif (BE_LENIENT and !/\W/ and @files = $self->searchfor(0, "perl$_", @searchdirs)) {
+ $self->aside( "Loosely found as @files\n" );
+ }
else {
# no match, try recursive search
@searchdirs = grep(!/^\.\z/s,@INC);
my @dynamic_pod;
$self->search_perlfunc($found_things, \@dynamic_pod) if $self->opt_f;
+
+ $self->search_perlvar($found_things, \@dynamic_pod) if $self->opt_v;
$self->search_perlfaqs($found_things, \@dynamic_pod) if $self->opt_q;
- if( ! $self->opt_f and ! $self->opt_q ) {
+ if( ! $self->opt_f and ! $self->opt_q and ! $self->opt_v ) {
DEBUG > 4 and print "That's a non-dynamic pod search.\n";
} elsif ( @dynamic_pod ) {
$self->aside("Hm, I found some Pod from that search!\n");
push @{ $self->{'temp_file_list'} }, $buffer;
# I.e., it MIGHT be deleted at the end.
- my $in_list = $self->opt_f;
+ my $in_list = $self->opt_f || $self->opt_v;
print $buffd "=over 8\n\n" if $in_list;
print $buffd @dynamic_pod or die "Can't print $buffer: $!";
#..........................................................................
+sub search_perlvar {
+ my($self, $found_things, $pod) = @_;
+
+ my $opt = $self->opt_v;
+
+ if ( $opt !~ /^ (?: [\@\%\$]\S+ | [A-Z]\w* ) $/x ) {
+ die "'$opt' does not look like a Perl variable\n";
+ }
+
+ DEBUG > 2 and print "Search: @$found_things\n";
+
+ my $perlvar = shift @$found_things;
+ open(PVAR, "<", $perlvar) # "Funk is its own reward"
+ or die("Can't open $perlvar: $!");
+
+ if ( $opt =~ /^\$\d+$/ ) { # handle $1, $2, ..., $9
+ $opt = '$<I<digits>>';
+ }
+ my $search_re = quotemeta($opt);
+
+ DEBUG > 2 and
+ print "Going to perlvar-scan for $search_re in $perlvar\n";
+
+ # Skip introduction
+ local $_;
+ while (<PVAR>) {
+ last if /^=over 8/;
+ }
+
+ # Look for our variable
+ my $found = 0;
+ my $inheader = 1;
+ my $inlist = 0;
+ while (<PVAR>) { # "The Mothership Connection is here!"
+ last if /^=head2 Error Indicators/;
+ # \b at the end of $` and friends borks things!
+ if ( m/^=item\s+$search_re\s/ ) {
+ $found = 1;
+ }
+ elsif (/^=item/) {
+ last if $found && !$inheader && !$inlist;
+ }
+ elsif (!/^\s+$/) { # not a blank line
+ if ( $found ) {
+ $inheader = 0; # don't accept more =item (unless inlist)
+ }
+ else {
+ @$pod = (); # reset
+ $inheader = 1; # start over
+ next;
+ }
+ }
+
+ if (/^=over/) {
+ ++$inlist;
+ }
+ elsif (/^=back/) {
+ --$inlist;
+ }
+ push @$pod, $_;
+# ++$found if /^\w/; # found descriptive text
+ }
+ @$pod = () unless $found;
+ if (!@$pod) {
+ die "No documentation for perl variable '$opt' found\n";
+ }
+ close PVAR or die "Can't open $perlvar: $!";
+
+ return;
+}
+
+#..........................................................................
+
sub search_perlfunc {
my($self, $found_things, $pod) = @_;
# Now, finally, do the formatting!
{
local $^W = $^W;
- if(DEBUG() or $self->opt_v) {
+ if(DEBUG() or $self->opt_D) {
# feh, let 'em see it
} else {
$^W = 0;
if ( IS_Cygwin and -x $file and -f "$file.exe" )
{
- warn "Cygwin $file.exe search skipped\n" if DEBUG or $self->opt_v;
+ warn "Cygwin $file.exe search skipped\n" if DEBUG or $self->opt_D;
return 0;
}
# don't add if superuser
if ($< && $> && -d "blib") { # don't be looking too hard now!
eval q{ use blib; 1 };
- warn $@ if $@ && $self->opt_v;
+ warn $@ if $@ && $self->opt_D;
}
}
__END__
-# See "perldoc perldoc" for basic details.
+=head1 NAME
+
+Pod::Perldoc - Look up Perl documentation in Pod format.
+
+=head1 SYNOPSIS
+
+ use Pod::Perldoc ();
+
+ Pod::Perldoc->run();
+
+=head1 DESCRIPTION
+
+The guts of L<perldoc> utility.
+
+=head1 SEE ALSO
+
+L<perldoc>
+
+=head1 COPYRIGHT AND DISCLAIMERS
+
+Copyright (c) 2002-2007 Sean M. Burke.
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+This program is distributed in the hope that it will be useful, but
+without any warranty; without even the implied warranty of
+merchantability or fitness for a particular purpose.
+
+=head1 AUTHOR
+
+Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
+
+Past contributions from:
+Sean M. Burke <sburke@cpan.org>
+
+=cut
+
+#
#
# Perldoc -- look up a piece of documentation in .pod format that
# is embedded in the perl installation tree.
=head1 SYNOPSIS
-B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>]
+B<perldoc> [B<-h>] [B<-D>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>]
[B<-i>] [B<-V>] [B<-T>] [B<-r>]
[B<-dI<destination_file>>]
[B<-oI<formatname>>]
B<perldoc> B<-L> fr B<-q> FAQ Keyword
+B<perldoc> B<-v> PerlVariable
+
See below for more description of the switches.
=head1 DESCRIPTION
Prints out a brief B<h>elp message.
-=item B<-v>
+=item B<-D>
-Describes search for the item in detail (B<v>erbosely).
+B<D>escribes search for the item in B<d>etail.
=item B<-t>
perldoc -f sprintf
+
=item B<-q> I<perlfaq-search-regexp>
The B<-q> option takes a regular expression as an argument. It will search
the B<q>uestion headings in perlfaq[1-9] and print the entries matching
-the regular expression. Example: C<perldoc -q shuffle>
+the regular expression.
+
+Example:
+
+ perldoc -q shuffle
+
+
+=item B<-v> I<perlvar>
+
+The B<-v> option followed by the name of a Perl predefined variable will
+extract the documentation of this variable from L<perlvar>.
+
+Examples:
+
+ perldoc -v '$"'
+ perldoc -v @+
+ perldoc -v DATA
+
=item B<-T>
are specified either as C<File::Basename> or C<File/Basename>. You may also
give a descriptive name of a page, such as C<perlfunc>.
+For simple names like 'foo', when the normal search fails to find
+a matching page, a search with the "perl" prefix is tried as well.
+So "perldoc intro" is enough to find/render "perlintro.pod".
+
=item B<-n> I<some-formatter>
Specify replacement for nroff
even more descriptive output than the C<-v> switch does -- the higher the
number, the more it emits.
+
+=head1 CHANGES
+
+Up to 3.14_05, the switch B<-v> was used to produce verbose
+messages of B<perldoc> operation, which is now enabled by B<-D>.
+
+
=head1 AUTHOR
-Current maintainer: Sean M. Burke, <sburke@cpan.org>
+Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
Past contributors are:
+Sean M. Burke <sburke@cpan.org>,
Kenneth Albanowski <kjahds@kjahds.com>,
Andy Dougherty <doughera@lafcol.lafayette.edu>,
and many others.
projects / platform / upstream / perl.git / commitdiff