package RDA::Pod; # $Id: Pod.pm,v 1.25 2009/01/13 16:46:12 mschenke Exp $ # ARCS: $Header: /u02/webapps/workbench/cvs/RDA_4/src/scripting/lib/RDA/Pod.pm,v 1.25 2009/01/13 16:46:12 mschenke Exp $ # # Change History # 20090113 MSC Change the copyright notice. =head1 NAME RDA::Pod - Class Used for Objects to Display Manual Pages =head1 SYNOPSIS require RDA::Pod; =head1 DESCRIPTION The objects of the C class are used to display manual pages. The following methods are available: =cut use strict; BEGIN { use Exporter; use File::Spec; use IO::File; } # Define the global public variables use vars qw($VERSION); $VERSION = sprintf("%d.%02d", q$Revision: 1.25 $ =~ /(\d+)\.(\d+)/); # Define the global private variables # Report the module version number sub Version { $VERSION; } =head2 S<$h = RDA::Pod-Enew($dir,$agt)> The object constructor. It takes the module directory and the agent reference as arguments. C is represented by a blessed hash reference. The following special keys are used: =over 12 =item S< B<'_agt'> > Reference to the agent object =item S< B<'_blk'> > Block indicator (_pod2text) =item S< B<'_dir'> > Module directory =item S< B<'_flg'> > Internal documentation extraction indicator =item S< B<'_off'> > Text offset (_pod2text) =item S< B<'_pag'> > Pager program =item S< B<'_pre'> > Previous Tag text (_pod2text) =item S< B<'_tag'> > Tag text (_pod2text) =item S< B<'_wdt'> > Page width parameter =back Internal keys are prefixed by an underscore. =cut sub new { my $slf = shift; my $cls = ref($slf) || $slf; my $dir = shift; my $agt = shift; # Create the render object $slf = bless {}, $cls; # Get some setup information $slf->{'_agt'} = $agt; $slf->{'_dir'} = $dir; $slf->{'_flg'} = exists($ENV{'RDA_MAN'}); $slf->{'_wdt'} = $agt->get_setting('RDA_COLUMNS'); # Determine the pager $slf->{'_pag'} = exists($ENV{'PAGER'}) ? $ENV{'PAGER'} : $agt->is_vms ? 'TYPE/PAGE=SAVE SYS$INPUT' : 'more'; # Return the object reference $slf; } =head2 S<$h-Edisplay($nam)> This method converts the specified documentation in the POD format into formatted ASCII. It displays the documentation using the pager specified in the C environment variable. When the pager is not specified, it uses C (or C on VMS) by default. When the C environment variable is defined, Pod::Text is not used to extract and format the documentation. =cut sub display { my ($slf, $nam) = @_; my $fil = File::Spec->catfile($slf->{'_dir'}, $nam); die "RDA-00401: Missing or invalid manual file for '$nam'" unless _display($slf, "$fil.pod") || _display($slf, "$fil.def") || _display($slf, "$fil.ctl") || _display($slf, "$fil.pm"); } sub _display { my ($slf, $fil) = @_; return 0 unless -r $fil; # Convert and display it using Pod::Text unless ($slf->{'_flg'}) { # Convert and display it (perl 5.6 and above) eval { local $SIG{'__WARN__'} = sub {}; require Pod::Text; my $hpr = Pod::Text->new(sentence => 0, width => $slf->{'_wdt'}); my $ifh = IO::File->new; open($ifh, "<$fil") || die "RDA-00402: Cannot open the manual file:\n $!\n"; if (-t STDOUT) { my $ofh = IO::File->new; open($ofh, '| '.$slf->{'_pag'}) || die "RDA-00403: Cannot open pager:\n $!\n"; $hpr->parse_from_filehandle($ifh, $ofh); close($ofh); } else { $hpr->parse_from_filehandle($ifh); } close($ifh); wait(); }; return 1 unless $@; die $@ if $@ =~ m/^RDA-\d+:/; # Convert and display it (before perl 5.6) eval { local $SIG{'__WARN__'} = sub {}; require Pod::Text; import Pod::Text; if (-t STDOUT ) { open(OUT, '| '.$slf->{'_pag'}) || die "RDA-00403: Cannot open pager:\n $!\n"; Pod::Text::pod2text('-'.$slf->{'_wdt'}, $fil, *OUT); close(OUT); } else { Pod::Text::pod2text('-'.$slf->{'_wdt'}, $fil, *STDOUT); } wait(); }; return 1 unless $@; die $@ if $@ =~ m/^RDA-\d+:/; } # Convert and display it using own code eval { local $SIG{'__WARN__'} = sub {}; if (-t STDOUT ) { open(OUT, '| '.$slf->{'_pag'}) || die "RDA-00403: Cannot open pager:\n $!\n"; _pod2text($slf, $fil, *OUT); close(OUT); } else { _pod2text($slf, $fil, *STDOUT); } wait(); }; return 1 unless $@; die $@ if $@ =~ m/^RDA-\d+:/; # Indicate the page cannot be displayed die "RDA-00400: Cannot display manual pages:\n $@\n" if $@; # Try another file 0; } sub _pod2text { my $slf = shift; my $fil = shift; local *OUT = shift; local $/ = ""; # Treat multiple empty lines as a single empty line my ($cut, $dft, $flg, $hdr, $max, $reg, @off, %reg); $cut = 1; $dft = 4; $flg = 0; $hdr = ' '; $slf->{'_blk'} = 0; $slf->{'_off'} = $dft; # Identify applicable regions $reg{'text'} = 1; if (exists($ENV{'RDA_MAN'})) { foreach my $key (split(/,/, $ENV{'RDA_MAN'})) { $reg{$key} = 1 if $key; } } # Extract the documentation and format it open(IN, $fil) || die "RDA-00402: Cannot open the manual file:\n $!\n"; while () { # Extract the documentation if ($cut) { next unless m/^=/; $cut = 0; } if ($reg) { next unless m/^=end\s+$reg[\n\r\s]*$/; $reg = undef; } # Resolve attributes $max = 10; s#E<(\w+)>#\&$1;#g; while ($max-- && /[A-Z]]+)\|[^>]+>#$1#g; s#C<(.*?)>#"$1"#sg; s#I<(.*?)>#*$1*#sg; s#X<.*?>##sg; s#[A-Z]<(.*?)>#$1#sg; } s#\&#&#g; s#\<#<#g; s#\>#>#g; s#\|#|#g; s#\/#/#g; s#\&(0[0-7]{1,3}|0x[0-9A-Fa-f]{1,4});#chr(oct($1))#g; s#\&(\d+);#chr($1)#g; s/[\s\r\n]+$//; # Treat the pod directives if (s/^=(\S*)\s?//) { my $cmd = $1; if ($cmd eq 'cut') { $cut = 1; } elsif ($cmd eq 'pod') { $cut = 0; } elsif ($cmd eq 'head1') { _prt_buf($slf, $_, 0); } elsif ($cmd eq 'head2' || $cmd eq 'head3') { _prt_buf($slf, $hdr.$_, 0); } elsif ($cmd eq 'over') { $slf->{'_pre'} = $slf->{'_tag'} if exists($slf->{'_tag'}); unshift(@off, $slf->{'_off'}); $slf->{'_off'} += ($_ + 0) || $dft; $flg = 1; } elsif ($cmd eq 'back') { _prt_blk($slf, '', 1) if exists($slf->{'_tag'}); $slf->{'_off'} = shift(@off) || $dft; $flg = 0; } elsif ($cmd eq 'item') { my ($lgt, $off, $tag); _prt_blk($slf, '', 0) if exists($slf->{'_tag'}); $off = $slf->{'_off'}; $tag = exists($slf->{'_pre'}) ? delete($slf->{'_pre'}) : ' ' x ($off[0] || $dft); s/\n/ /g; $tag .= $_.' '; for ($lgt = length($tag) ; $lgt < $off ; ++$lgt) { $tag .= ' '; } $slf->{'_blk'} = 0 unless $flg; $slf->{'_tag'} = $tag; $flg = 0; } elsif ($cmd eq 'begin') { if (!exists($reg{$_})) { $reg = $_; } elsif ($_ eq 'credits') { _prt_buf($slf, 'CREDITS', 0); } } } elsif (m/^\s+/) { my ($pre); _prt_blk($slf, '', 0) if exists($slf->{'_tag'}); $pre = ' ' x $slf->{'_off'}; s/\n/\n$pre/g; _prt_buf($slf, "$pre$_", 1); } else { _prt_blk($slf, $_, 1); } } close(IN); } sub _prt_blk { my ($slf, $str, $nxt) = @_; my ($buf, $lgt, $off); $off = $slf->{'_off'}; if (exists($slf->{'_tag'})) { $lgt = length($buf = delete($slf->{'_tag'})); if ($lgt > $off) { $buf .= $str; ($buf, $str) = ($buf =~ m/^(\s*\S+\s)(.*)/); $lgt = length($buf); } } elsif (exists($slf->{'_pre'})) { $lgt = length($buf = delete($slf->{'_pre'})); } else { $buf = ' ' x ($lgt = $off); } foreach my $wrd (split(/\s/, $str)) { $lgt += length($wrd); if ($lgt > $slf->{'_wdt'}) { _prt_buf($slf, $buf, 0); $buf = ' ' x $off; $lgt = $off + length($wrd); } $buf .= $wrd; $buf .= ' '; ++$lgt; } if ($lgt) { _prt_buf($slf, $buf, $nxt); } else { $slf->{'_blk'} = $nxt; } } sub _prt_buf { my ($slf, $buf, $nxt) = @_; $buf =~ s/\s+$//; $buf .= "\n"; $buf = "\n$buf" if $slf->{'_blk'}; $slf->{'_blk'} = $nxt; print OUT $buf; } 1; __END__ =head1 SEE ALSO L, L, L, L, L, L, L, L, L, L, L, L, L, L, L, L, L =head1 COPYRIGHT NOTICE Copyright (c) 2002-2009, Oracle. All rights reserved. =head1 TRADEMARK NOTICE Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. =cut