add --output option; expand docs; fix perlcritic

Changes

@@ -7,9 +7,11 @@
 
 Revision history for App-CPAN-Mini-Visit
 
-0.004
+0.004 Mon Feb 23 08:48:49 EST 2009
   Added:
     - "-e" option to act like "perl -e"
+    - "--output" option to capture output in a file
+    - examples in visitcpan POD
 
   Changed:
     - returned to old-style version numbers

README

@@ -37,7 +37,7 @@ AUTHOR
     David A. Golden (DAGOLDEN)
 
 COPYRIGHT AND LICENSE
-    Copyright (c) 2008 by David A. Golden. All rights reserved.
+    Copyright (c) 2008-2009 by David A. Golden. All rights reserved.
 
     Licensed under Apache License, Version 2.0 (the "License"). You may not
     use this file except in compliance with the License. A copy of the

bin/visitcpan

@@ -60,12 +60,25 @@ in a .minicpanrc file.
  --minicpan|-m      directory of a minicpan (defaults to local minicpan 
                     from CPAN::Mini config file)
 
+ --output|-o        file to save output instead of sending to terminal
+
  --quiet|-q         silence warnings and suppress STDERR from tar
 
  --version|-V       visitcpan program version
 
  --                 indicates the end of options for visitcpan
 
+= EXAMPLES
+
+  # count number of distributiosn in the minicpan
+  $ visitcpan | wc -l
+
+  # get a listing of all distributions using Build.PL
+  $ visitcpan -q -a dist -o listing.txt -e 'say shift if -f "Build.PL"'
+
+  # run a program against each distribution
+  $ visitcpan -q -- ack -a 'use version;'
+
 = BUGS
 
 Please report any bugs or feature using the CPAN Request Tracker.  
@@ -87,7 +100,7 @@ David A. Golden (DAGOLDEN)
 
 = COPYRIGHT AND LICENSE
 
-Copyright (c) 2008 by David A. Golden
+Copyright (c) 2008-2009 by David A. Golden
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -184,12 +197,25 @@ in a .minicpanrc file.
   --minicpan|-m      directory of a minicpan (defaults to local minicpan 
                      from CPAN::Mini config file)
  
+  --output|-o        file to save output instead of sending to terminal
+ 
   --quiet|-q         silence warnings and suppress STDERR from tar
  
   --version|-V       visitcpan program version
  
   --                 indicates the end of options for visitcpan
 
+=head1 EXAMPLES
+
+   # count number of distributiosn in the minicpan
+   $ visitcpan | wc -l
+ 
+   # get a listing of all distributions using Build.PL
+   $ visitcpan -q -a dist -o listing.txt -e 'say shift if -f "Build.PL"'
+ 
+   # run a program against each distribution
+   $ visitcpan -q -- ack -a 'use version;'
+
 =head1 BUGS
 
 Please report any bugs or feature using the CPAN Request Tracker.  
@@ -211,7 +237,7 @@ David A. Golden (DAGOLDEN)
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright (c) 2008 by David A. Golden
+Copyright (c) 2008-2009 by David A. Golden
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

lib/App/CPAN/Mini/Visit.pm

@@ -1,4 +1,4 @@
-# Copyright (c) 2008 by David Golden. All rights reserved.
+# Copyright (c) 2008-2009 by David Golden. All rights reserved.
 # Licensed under Apache License, Version 2.0 (the "License").
 # You may not use this file except in compliance with the License.
 # A copy of the License was distributed with this file or you may obtain a 
@@ -13,6 +13,7 @@ our $VERSION = '0.004';
 $VERSION = eval $VERSION; ## no critic
 
 use CPAN::Mini ();
+use Capture::Tiny qw/capture/;
 use Exception::Class::TryCatch qw/ try catch /;
 use File::Basename qw/ basename /;
 use File::Find qw/ find /;
@@ -30,6 +31,7 @@ my @option_spec = (
   Param("append|a", qr/(?:^$|(?:^path|dist$))/ )->default(''),
   Param("e|E"),
   Param("minicpan|m"),
+  Param("output|o"),
 );
 
 sub run {
@@ -51,11 +53,15 @@ sub run {
   return _exit_version() if $opt->get_version;
 
   # Set Archive::Extract globals
+  # if quiet suppress warnings from Archive::Tar, etc.
   local $Archive::Extract::DEBUG = 0;
   local $Archive::Extract::PREFER_BIN = 1;
   local $Archive::Extract::WARN = $opt->get_quiet ? 0 : 1;
 
-  # if quiet suppress warnings from Archive::Tar, etc.
+  # if -e/-E, then prepend to command
+  if ( $opt->get_e ) {
+    unshift @args, $^X, '-E', $opt->get_e;
+  }
 
   # locate minicpan directory
   if ( ! $opt->get_minicpan ) {
@@ -77,17 +83,22 @@ sub run {
 
   my $minicpan = dir( $opt->get_minicpan )->absolute;
 
+  # save output by redirecting STDOUT if requested
+  my ($out_fh, $orig_stdout );
+  if ( $opt->get_output ) {
+    open $out_fh, ">", $opt->get_output;
+    open $orig_stdout, "<&=STDOUT";
+    open STDOUT, ">&=" . fileno $out_fh;
+  }
+
   find( 
     {
       no_chdir => 1,
       follow => 0,
-      preprocess => sub { return sort @_ },
+      preprocess => sub { my @files = sort @_; return @files },
       wanted => sub {
         return unless /$archive_re/;
         # run code if program/args given otherwise print name
-        if ( $opt->get_e ) {
-          unshift @args, $^X, '-E', $opt->get_e;
-        }
         if ( @args ) {
           return if $_ =~ /pm\.gz$/io; # not an archive, just a file
           my @cmd = @args;
@@ -112,6 +123,12 @@ sub run {
     $minicpan
   );
 
+  # restore STDOUT and close output file
+  if ( $opt->get_output ) {
+    open STDOUT, ">&=" . fileno $orig_stdout;
+    close $out_fh;
+  }
+
   return 0; # exit code
 }
 
@@ -151,6 +168,8 @@ Options:
  --minicpan|-m      directory of a minicpan (defaults to local minicpan 
                     from CPAN::Mini config file)
 
+ --output|-o        file to save output instead of sending to terminal
+
  --quiet|-q         silence warnings and suppress STDERR from tar
 
  --version|-V       $exe program version
@@ -263,7 +282,7 @@ David A. Golden (DAGOLDEN)
 
 = COPYRIGHT AND LICENSE
 
-Copyright (c) 2008 by David A. Golden. All rights reserved.
+Copyright (c) 2008-2009 by David A. Golden. All rights reserved.
 
 Licensed under Apache License, Version 2.0 (the "License").
 You may not use this file except in compliance with the License.

lib/App/CPAN/Mini/Visit.pod

@@ -55,7 +55,7 @@ David A. Golden (DAGOLDEN)
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright (c) 2008 by David A. Golden. All rights reserved.
+Copyright (c) 2008-2009 by David A. Golden. All rights reserved.
 
 Licensed under Apache License, Version 2.0 (the "License").
 You may not use this file except in compliance with the License.

t/01-App-CPAN-Mini-Visit.t

@@ -13,10 +13,10 @@ use File::Find qw/find/;
 use IO::CaptureOutput qw/capture/;
 use IO::File;
 use Path::Class;
-use File::Temp qw/tempdir/;
+use File::Temp qw/tempdir tmpnam/;
 use Test::More;
 
-plan tests => 27;
+plan tests => 30;
 
 require_ok( 'App::CPAN::Mini::Visit' );
 
@@ -303,9 +303,32 @@ _create_minicpanrc("local: $minicpan");
     catch my $err;
     my @found = split /\n/, $stdout;
     my $prefix = dir( $minicpan, qw/ authors id / )->absolute;
-    my @expect = map{ s{$prefix[/\\].[/\\]..[/\\]}{}; $_ } @files;
+    my @expect = map{ 
+      (my $file = $_ ) =~ s{$prefix[/\\].[/\\]..[/\\]}{}; 
+      $file; 
+    } @files;
     ok( length $stdout, "[$label] ($opt) got stdout" ) or diag $err;
     is_deeply( \@found, \@expect, "[$label] ($opt) listing correct" ) 
       or diag "STDOUT:\n$stdout\nSTDERR:\n$stderr\n";
   }
 }
+
+#--------------------------------------------------------------------------#
+# --output file
+#--------------------------------------------------------------------------#
+
+{
+  my $label = "output";
+  my $tempfile = tmpnam();
+  try eval { 
+    capture sub {
+      App::CPAN::Mini::Visit->run( "--output=$tempfile" )
+    } => \$stdout, \$stderr;
+  };
+  catch my $err;
+  ok( -f $tempfile, "[$label] output file created" );
+  my @found = map { chomp; $_ } do { local @ARGV = ($tempfile); <> };
+  is( $stdout, '', "[$label] saw no output on terminal" );
+  is_deeply( \@found, \@files, "[$label] listing correct" );
+}
+