view release on metacpan or  search on metacpan

lib/Shell/Tools.pm  view on Meta::CPAN

 use Pod::Usage 'pod2usage';
 use Getopt::Std 1.04 'getopts';
 sub main::HELP_MESSAGE { ... }            # calls pod2usage()
 sub main::VERSION_MESSAGE { ... }         # see documentation below
 $Getopt::Std::STANDARD_HELP_VERSION = 1;  # exit after --help or --version
 use Cwd qw/getcwd cwd abs_path/;
 use File::Spec::Functions qw/canonpath catdir catfile curdir rootdir updir
     no_upwards file_name_is_absolute splitdir abs2rel rel2abs/;
 use File::Basename qw/fileparse basename dirname/;
 use File::Temp qw/tempfile tempdir/;
 use File::Copy qw/move copy/;
 use File::Path 2.08 qw/make_path remove_tree/;
 use File::Find 'find';
 use Fcntl qw/LOCK_SH LOCK_EX LOCK_UN LOCK_NB SEEK_SET SEEK_CUR SEEK_END/;
 use FindBin ();
 use Data::Dumper 'Dumper';
 use Scalar::Util 'looks_like_number';
 use List::Util qw/first reduce/;

=head1 Description

This module exports a collection of functions from several core Perl modules
which can often be very useful when writing Perl shell scripts.

B<See also> L<Shell::Tools::Extra|Shell::Tools::Extra>, which exports
additional CPAN modules' functions and classes.

=head2 Warning

This module is intended to help write short, simple shell scripts.
Because of its many exports it is not recommended for large applications,
CGI scripts, object-oriented applications and the like.

=head1 Version

This document describes version 0.04 of Shell::Tools.

=head1 Exports

This module exports the following modules and functions.

Each module has an L<Exporter|Exporter> tag that is the same name as the module.
This is useful if you want to exclude some modules' functions from being exported,
for example C<< use Shell::Tools qw/ !:File::Copy /; >>.

=head2 L<warnings|warnings> and L<strict|strict>

These are enabled in the calling script.
(No Exporter tag.)

=cut

## no critic (ProhibitConstantPragma)

use base 'Exporter';
our @EXPORT = ();  ## no critic (ProhibitAutomaticExportation)
our %EXPORT_TAGS = ();

sub import {  ## no critic (RequireArgUnpacking)
	warnings->import;
	strict->import;
	__PACKAGE__->export_to_level(1, @_);
	return;
}


=head2 L<IO::File|IO::File> and L<IO::Handle|IO::Handle>

These modules are loaded, nothing is exported.
(No Exporter tag.)

Perl before v5.14 did not load these automatically.
Loading these modules allows you to do things like:

 open my $fh, ">", $file or die $!;
 $fh->autoflush(1);
 $fh->print("Hello");
 # Note: calling binmode this way may not work on older Perls
 $fh->binmode(":raw");

=cut

use IO::File ();    # core since Perl 5.00307
use IO::Handle ();  # core since Perl 5.00307


=head2 L<Carp|Carp>

L<Carp|Carp>'s C<carp>, C<croak> and C<confess>.

=cut

use constant _EXP_CARP => qw/carp croak confess/;
use Carp _EXP_CARP;  # core since Perl 5
push @EXPORT, _EXP_CARP;
$EXPORT_TAGS{"Carp"} = [_EXP_CARP];


=head2 L<Getopt::Std|Getopt::Std> and L<Pod::Usage|Pod::Usage>

 =head1 SYNOPSIS
 
  foo.pl [OPTIONS] FILENAME
  OPTIONS:
  -f       - foo
  -b BAR   - bar
 
 =cut
 
 getopts('fb:', \my %opts) or pod2usage;
 pod2usage("must specify a filename") unless @ARGV==1;

This module provides the functions C<main::HELP_MESSAGE> and C<main::VERSION_MESSAGE>.
C<HELP_MESSAGE> simply calls L<pod2usage|Pod::Usage>.
C<VERSION_MESSAGE> first checks for C<$main::VERSION_STRING> and prints that if available,
otherwise it will use C<$main::VERSION> to construct a message,
and if neither is available, it will use the "last modified" time of the script.
Also, C<$Getopt::Std::STANDARD_HELP_VERSION> is set, so the C<getopts> call
will exit the script if it sees C<--help> or C<--version>.

We require L<Getopt::Std|Getopt::Std> 1.04 or greater for the