home *** CD-ROM | disk | FTP | other *** search
/ CD Actual Thematic 7: Programming / CDAT7.iso / Share / Editores / Perl5 / perl / bin / perldoc.bat < prev    next >
Encoding:
DOS Batch File  |  1997-08-10  |  11.6 KB  |  457 lines
  1. @rem = '--*-Perl-*--
  2. @echo off
  3. perl -x -S %0 %1 %2 %3 %4 %5 %6 %7 %8 %9
  4. goto endofperl
  5. @rem ';
  6. #!perl
  7. #line 8
  8. #perl
  9.     eval 'exec c:\perl\bin\perl.exe -S $0 ${1+"$@"}'
  10.     if $running_under_some_shell;
  11.  
  12. @pagers = ();
  13. push @pagers, "more /e" if -x "more /e";
  14.  
  15. #
  16. # Perldoc revision #1 -- look up a piece of documentation in .pod format that
  17. # is embedded in the perl installation tree.
  18. #
  19. # This is not to be confused with Tom Christianson's perlman, which is a
  20. # man replacement, written in perl. This perldoc is strictly for reading
  21. # the perl manuals, though it too is written in perl.
  22.  
  23. if(@ARGV<1) {
  24.         $0 =~ s,.*/,,;
  25.     die <<EOF;
  26. Usage: $0 [-h] [-v] [-t] [-u] [-m] [-l] PageName|ModuleName|ProgramName
  27.        $0 -f PerlFunc
  28.  
  29. We suggest you use "perldoc perldoc" to get aquainted 
  30. with the system.
  31. EOF
  32. }
  33.  
  34. use Getopt::Std;
  35. use Config '%Config';
  36.  
  37. $Is_VMS = $^O eq 'VMS';
  38. $Is_MSWin32 = $^O eq 'MSWin32';
  39.  
  40. sub usage{
  41.     warn "@_\n" if @_;
  42.     # Erase evidence of previous errors (if any), so exit status is simple.
  43.     $! = 0;
  44.     die <<EOF;
  45. perldoc [options] PageName|ModuleName|ProgramName...
  46. perldoc [options] -f BuiltinFunction
  47.  
  48. Options:
  49.     -h   Display this help message
  50.     -t   Display pod using pod2text instead of pod2man and nroff
  51.              (-t is the default on win32)
  52.     -u     Display unformatted pod text
  53.     -m   Display modules file in its entirety
  54.     -l   Display the modules file name
  55.     -v     Verbosely describe what's going on
  56.  
  57. PageName|ModuleName...
  58.          is the name of a piece of documentation that you want to look at. You 
  59.          may either give a descriptive name of the page (as in the case of
  60.          `perlfunc') the name of a module, either like `Term::Info', 
  61.          `Term/Info', the partial name of a module, like `info', or 
  62.          `makemaker', or the name of a program, like `perldoc'.
  63.  
  64. BuiltinFunction
  65.          is the name of a perl function.  Will extract documentation from
  66.          `perlfunc'.
  67.          
  68. Any switches in the PERLDOC environment variable will be used before the 
  69. command line arguments.
  70.  
  71. EOF
  72. }
  73.  
  74. use Text::ParseWords;
  75.  
  76.  
  77. unshift(@ARGV,shellwords($ENV{"PERLDOC"}));
  78.  
  79. getopts("mhtluvf:") || usage;
  80.  
  81. usage if $opt_h || $opt_h; # avoid -w warning
  82.  
  83. if ($opt_t + $opt_u + $opt_m + $opt_l > 1) {
  84.     usage("only one of -t, -u, -m or -l")
  85. } elsif ($Is_MSWin32) {
  86.     $opt_t = 1 unless $opt_t + $opt_u + $opt_m + $opt_l;
  87. }
  88.  
  89. if ($opt_t) { require Pod::Text; import Pod::Text; }
  90.  
  91. if ($opt_f) {
  92.    @pages = ("perlfunc");
  93. } else {
  94.    @pages = @ARGV;
  95. }
  96.  
  97.  
  98.  
  99. sub containspod {
  100.     my($file) = @_;
  101.     local($_);
  102.     open(TEST,"<$file");
  103.     while(<TEST>) {
  104.         if(/^=head/) {
  105.             close(TEST);
  106.             return 1;
  107.         }
  108.     }
  109.     close(TEST);
  110.     return 0;
  111. }
  112.  
  113. sub minus_f_nocase {
  114.      my($file) = @_;
  115.      # on a case-forgiving file system we can simply use -f $file
  116.      if ($Is_VMS or $Is_MSWin32 or $^O eq 'os2') {
  117.         return ( -f $file ) ? $file : '';
  118.      }
  119.      local *DIR;
  120.      local($")="/";
  121.      my(@p,$p,$cip);
  122.      foreach $p (split(/\//, $file)){
  123.      if (-d ("@p/$p")){
  124.          push @p, $p;
  125.      } elsif (-f ("@p/$p")) {
  126.          return "@p/$p";
  127.      } else {
  128.          my $found=0;
  129.          my $lcp = lc $p;
  130.          opendir DIR, "@p";
  131.          while ($cip=readdir(DIR)) {
  132.          if (lc $cip eq $lcp){
  133.              $found++;
  134.              last;
  135.          }
  136.          }
  137.          closedir DIR;
  138.          return "" unless $found;
  139.          push @p, $cip;
  140.          return "@p" if -f "@p";
  141.      }
  142.      }
  143.      return; # is not a file
  144.  }
  145.  
  146.   sub searchfor {
  147.       my($recurse,$s,@dirs) = @_;
  148.       $s =~ s!::!/!g;
  149.       $s = VMS::Filespec::unixify($s) if $Is_VMS;
  150.     return $s if -f $s && containspod($s);
  151.       printf STDERR "looking for $s in @dirs\n" if $opt_v;
  152.      my $ret;
  153.      my $i;
  154.      my $dir;
  155.       for ($i=0;$i<@dirs;$i++) {
  156.           $dir = $dirs[$i];
  157.           ($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
  158.          if ((    $ret = minus_f_nocase "$dir/$s.pod")
  159.          or ( $ret = minus_f_nocase "$dir/$s.pm"  and containspod($ret))
  160.          or ( $ret = minus_f_nocase "$dir/$s"     and containspod($ret))
  161.           or ( $Is_VMS and 
  162.               $ret = minus_f_nocase "$dir/$s.com" and containspod($ret))
  163.         or ( $^O eq 'os2' and 
  164.               $ret = minus_f_nocase "$dir/$s.cmd" and containspod($ret))
  165.         or ( ($Is_MSWin32 or $^O eq 'os2') and 
  166.               $ret = minus_f_nocase "$dir/$s.bat" and containspod($ret))
  167.          or ( $ret = minus_f_nocase "$dir/pod/$s.pod")
  168.          or ( $ret = minus_f_nocase "$dir/pod/$s" and containspod($ret)))
  169.          { return $ret; }
  170.          
  171.          if($recurse) {
  172.             opendir(D,$dir);
  173.             my(@newdirs) = grep(-d,map("$dir/$_",grep(!/^\.\.?$/,readdir(D))));
  174.             closedir(D);
  175.             @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
  176.             next unless @newdirs;
  177.             print STDERR "Also looking in @newdirs\n" if $opt_v;
  178.             push(@dirs,@newdirs);
  179.          }
  180.      }
  181.       return ();
  182.   }
  183.  
  184.  
  185. foreach (@pages) {
  186.     print STDERR "Searching for $_\n" if $opt_v;
  187.     # We must look both in @INC for library modules and in PATH
  188.     # for executables, like h2xs or perldoc itself.
  189.     @searchdirs = @INC;
  190.     unless ($opt_m) { 
  191.         if ($Is_VMS) {
  192.         my($i,$trn);
  193.         for ($i = 0; $trn = $ENV{'DCL$PATH'.$i}; $i++) {
  194.             push(@searchdirs,$trn);
  195.         }
  196.         } else {
  197.             push(@searchdirs, grep(-d, split($Config{path_sep}, 
  198.                          $ENV{'PATH'})));
  199.         }
  200.         @files= searchfor(0,$_,@searchdirs);
  201.     }
  202.     if( @files ) {
  203.         print STDERR "Found as @files\n" if $opt_v;
  204.     } else {
  205.         # no match, try recursive search
  206.         
  207.         @searchdirs = grep(!/^\.$/,@INC);
  208.         
  209.         
  210.         @files= searchfor(1,$_,@searchdirs);
  211.         if( @files ) {
  212.             print STDERR "Loosely found as @files\n" if $opt_v;
  213.         } else {
  214.             print STDERR "No documentation found for '$_'\n";
  215.         }
  216.     }
  217.     push(@found,@files);
  218. }
  219.  
  220. if(!@found) {
  221.     exit ($Is_VMS ? 98962 : 1);
  222. }
  223.  
  224. if ($opt_l) {
  225.     print join("\n", @found), "\n";
  226.     exit;
  227. }
  228.  
  229. if( ! -t STDOUT ) { $no_tty = 1 }
  230.  
  231. if ($Is_MSWin32) {
  232.     $tmp = "$ENV{TEMP}\\perldoc1.$$";
  233.     push @pagers, qw( more< less notepad );
  234.     unshift @pagers, $ENV{PAGER}  if $ENV{PAGER};
  235. } elsif ($Is_VMS) {
  236.     $tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
  237.     push @pagers, qw( most more less type/page );
  238. } else {
  239.     if ($^O eq 'os2') {
  240.       require POSIX;
  241.       $tmp = POSIX::tmpnam();
  242.     } else {
  243.       $tmp = "/tmp/perldoc1.$$";      
  244.     }
  245.     push @pagers, qw( more less pg view cat );
  246.     unshift @pagers, $ENV{PAGER}  if $ENV{PAGER};
  247. }
  248. unshift @pagers, $ENV{PERLDOC_PAGER} if $ENV{PERLDOC_PAGER};
  249.  
  250. if ($opt_m) {
  251.     foreach $pager (@pagers) {
  252.         system("$pager @found") or exit;
  253.     }
  254.     if ($Is_VMS) { eval 'use vmsish qw(status exit); exit $?' }
  255.     exit 1;
  256. } 
  257.  
  258. if ($opt_f) {
  259.    my $perlfunc = shift @found;
  260.    open(PFUNC, $perlfunc) or die "Can't open $perlfunc: $!";
  261.  
  262.    # Skip introduction
  263.    while (<PFUNC>) {
  264.        last if /^=head2 Alphabetical Listing of Perl Functions/;
  265.    }
  266.  
  267.    # Look for our function
  268.    my $found = 0;
  269.    while (<PFUNC>) {
  270.        if (/^=item\s+\Q$opt_f\E\b/o)  {
  271.        $found++;
  272.        } elsif (/^=item/) {
  273.        last if $found;
  274.        }
  275.        push(@pod, $_) if $found;
  276.    }
  277.    if (@pod) {
  278.        if ($opt_t) {
  279.        open(FORMATTER, "| pod2text") || die "Can't start filter";
  280.        print FORMATTER "=over 8\n\n";
  281.        print FORMATTER @pod;
  282.        print FORMATTER "=back\n";
  283.        close(FORMATTER);
  284.        } else {
  285.        print @pod;
  286.        }
  287.    } else {
  288.        die "No documentation for perl function `$opt_f' found\n";
  289.    }
  290.    exit;
  291. }
  292.  
  293. foreach (@found) {
  294.  
  295.     if($opt_t) {
  296.         open(TMP,">>$tmp");
  297.         Pod::Text::pod2text($_,*TMP);
  298.         close(TMP);
  299.     } elsif(not $opt_u) {
  300.         my $cmd = "pod2man --lax $_ | nroff -man";
  301.         $cmd .= " | col -x" if $^O =~ /hpux/;
  302.         $rslt = `$cmd`;
  303.         unless(($err = $?)) {
  304.             open(TMP,">>$tmp");
  305.             print TMP $rslt;
  306.             close TMP;
  307.         }
  308.     }
  309.                                                     
  310.     if( $opt_u or $err or -z $tmp) {
  311.         open(OUT,">>$tmp");
  312.         open(IN,"<$_");
  313.         $cut = 1;
  314.         while (<IN>) {
  315.             $cut = $1 eq 'cut' if /^=(\w+)/;
  316.             next if $cut;
  317.             print OUT;
  318.         }
  319.         close(IN);
  320.         close(OUT);
  321.     }
  322. }
  323.  
  324. if( $no_tty ) {
  325.     open(TMP,"<$tmp");
  326.     print while <TMP>;
  327.     close(TMP);
  328. } else {
  329.     foreach $pager (@pagers) {
  330.         system("$pager $tmp") or last;
  331.     }
  332. }
  333.  
  334. 1 while unlink($tmp); #Possibly pointless VMSism
  335.  
  336. exit 0;
  337.  
  338. __END__
  339.  
  340. =head1 NAME
  341.  
  342. perldoc - Look up Perl documentation in pod format.
  343.  
  344. =head1 SYNOPSIS
  345.  
  346. B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] PageName|ModuleName|ProgramName
  347.  
  348. B<perldoc> B<-f> BuiltinFunction
  349.  
  350. =head1 DESCRIPTION
  351.  
  352. I<perldoc> looks up a piece of documentation in .pod format that is embedded
  353. in the perl installation tree or in a perl script, and displays it via
  354. C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
  355. C<col -x> will be used.) This is primarily used for the documentation for
  356. the perl library modules.
  357.  
  358. Your system may also have man pages installed for those modules, in
  359. which case you can probably just use the man(1) command.
  360.  
  361. =head1 OPTIONS
  362.  
  363. =over 5
  364.  
  365. =item B<-h> help
  366.  
  367. Prints out a brief help message.
  368.  
  369. =item B<-v> verbose
  370.  
  371. Describes search for the item in detail.
  372.  
  373. =item B<-t> text output
  374.  
  375. Display docs using plain text converter, instead of nroff. This may be faster,
  376. but it won't look as nice.
  377.  
  378. =item B<-u> unformatted
  379.  
  380. Find docs only; skip reformatting by pod2*
  381.  
  382. =item B<-m> module
  383.  
  384. Display the entire module: both code and unformatted pod documentation.
  385. This may be useful if the docs don't explain a function in the detail
  386. you need, and you'd like to inspect the code directly; perldoc will find
  387. the file for you and simply hand it off for display.
  388.  
  389. =item B<-l> file name only
  390.  
  391. Display the file name of the module found.
  392.  
  393. =item B<-f> perlfunc
  394.  
  395. The B<-f> option followed by the name of a perl built in function will
  396. extract the documentation of this function from L<perlfunc>.
  397.  
  398. =item B<PageName|ModuleName|ProgramName>
  399.  
  400. The item you want to look up.  Nested modules (such as C<File::Basename>)
  401. are specified either as C<File::Basename> or C<File/Basename>.  You may also
  402. give a descriptive name of a page, such as C<perlfunc>. You make also give a
  403. partial or wrong-case name, such as "basename" for "File::Basename", but
  404. this will be slower, if there is more then one page with the same partial
  405. name, you will only get the first one.
  406.  
  407. =back
  408.  
  409. =head1 ENVIRONMENT
  410.  
  411. Any switches in the C<PERLDOC> environment variable will be used before the 
  412. command line arguments.  C<perldoc> also searches directories
  413. specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
  414. defined) and C<PATH> environment variables.
  415. (The latter is so that embedded pods for executables, such as
  416. C<perldoc> itself, are available.)
  417.  
  418. =head1 AUTHOR
  419.  
  420. Kenneth Albanowski <kjahds@kjahds.com>
  421.  
  422. Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>
  423.  
  424. =cut
  425.  
  426. #
  427. # Version 1.12: Sat Apr 12 22:41:09 EST 1997
  428. #       Gurusamy Sarathy <gsar@umich.edu>
  429. #    -various fixes for win32
  430. # Version 1.11: Tue Dec 26 09:54:33 EST 1995
  431. #       Kenneth Albanowski <kjahds@kjahds.com>
  432. #   -added Charles Bailey's further VMS patches, and -u switch
  433. #   -added -t switch, with pod2text support
  434. # 
  435. # Version 1.10: Thu Nov  9 07:23:47 EST 1995
  436. #        Kenneth Albanowski <kjahds@kjahds.com>
  437. #    -added VMS support
  438. #    -added better error recognition (on no found pages, just exit. On
  439. #     missing nroff/pod2man, just display raw pod.)
  440. #    -added recursive/case-insensitive matching (thanks, Andreas). This
  441. #     slows things down a bit, unfortunately. Give a precise name, and
  442. #     it'll run faster.
  443. #
  444. # Version 1.01:    Tue May 30 14:47:34 EDT 1995
  445. #        Andy Dougherty  <doughera@lafcol.lafayette.edu>
  446. #   -added pod documentation.
  447. #   -added PATH searching.
  448. #   -added searching pod/ subdirectory (mainly to pick up perlfunc.pod
  449. #    and friends.
  450. #
  451. #
  452. # TODO:
  453. #
  454. #    Cache directories read during sloppy match
  455. __END__
  456. :endofperl
  457.