gitpan / leocharre-cli2 Goto Github PK

================================================================================

LEOCHARRE::CLI2 - Some quick help for writing cli scripts.

SYNOPSIS
    In script.pl:

       use LEOCHARRE::CLI2 
          'ko:', # options
          ':all', # subs to import
          'This program shows example usage.', # description of what script does
          '(manpage suggested)', # where to look for more info in man pages
          '[parent package name], # parent package name
          'argv_cwd', # explicit sub import name
          ;
   
       our $VERSION = 1;
   
       $opt_o or die("Missing -o opt");
   
       my @files_selected = argv_files();
   
       my @base_dir_selected = argv_cwd();
   
       my @all_dirs_selected = argv_dirs();
   
       my ($countfiles, $countdirs) = ( argv_dirs_count(), argv_files_count() );
   
       debug("You chose $countfiles files and $countdirs dirs.");

    Then to get help: $ script.pl -h

    To get version: $ script.pl -v

    To see debug: $ script.pl -d -o "my value" ./files* ./dirs*

DESCRIPTION
    Some quick help for writing cli scripts. Forces by default that -h
    triggers help, that -d triggers debug, and -v version.. Automates help,
    debug, version etc. If you use LEOCHARRE::CLI2, we alter the OPTIONS
    automatically. Also we automatically generate HELP.

Environment Variables
    New environment variables are set. They are..

  $ENV{SCRIPT_FILENAME}
    Holds name of your script, no leading path. Is accessible to main.

SCRIPT_DESCRIPTION
    If you define this, and you don't define usage(), the usage help output
    generated will contain this string.

       use LEOCHARRE::CLI2 'This is a script description because it has spaces.';

    When -h is called, if there is not usage() defined, this would spit out:

       /bin/file [OPTION]..
       This is a script description because it has spaces.
   
          -d    debug
          -h    help
          -v    version

SCRIPT PARENT PACKAGE
       use LEOCHARRE::CLI2 '[MyPkg]';

SCRIPT MAN PAGE
       use LEOCHARRE::CLI2 '(manpagename)';

Argument Variables
    For path arguments on disk specified via @ARGV.

    You can optionally use these to see any files, dirs, etc that a user
    defined in the cli. These must all be paths that resolve to disk. They
    all return abs path.

    Files and dirs, holds absolute paths on disk. Count holds number, 0 if
    none.

    To make these accessible, import.

       use LEOCHARRE::CLI2 ':argv'; # for all
       use LEOCHARRE::CLI2  qw/argv_files argv_files_count argv_dirs argv_dirs_count argv_cwd/; # same

    Usage: script ./pathtodir ./path2dir2 ./path2file.txt Then in our
    script:

       my @dirs = argv_dirs(); # holds abs path to dirs
       my $dirs_count = argv_dirs_count();
   
       argv_files_count() 
          or die("you forgot to specidy files on disk.");

    Note that this alters @ARGV.

    If you wish to import these.. Either use export tag ':all' or ':argv'.

  argv_cwd()
    Sometimes you want a destination dir to do something to. You want the
    option for the user to say; script ./path_to/

    But if none is provided, you want to assume './'. my $base_dir =
    argv_cwd();

  argv_files()
    Returns array of files abs paths. Undef if none.

  argv_files_count()
    Returns count of files, 0 if none.

  argv_dirs()
    Returns array of dirs abs paths. Undef if none.

  argv_dirs_count()
    Returns count of dirs abs paths, 0 if none.

  argv_cwd()
    Returns dirs chosen by user, or './' abs path.

  MODULES LOADED AND AVAILABLE
    YAML, Carp, Cwd

  abs_path(), cwd()
    Available and exported if you choose :all

  slurp()
    Arg is file on disk. If not there, warns and returns undef. If can't do
    it, warns and returns undef. Returns content. If no content, warns and
    returns whatever was inside.

       my $txt = slurp('./this.txt') or die;

    In scalar context returns all text. In array context returns all lines,
    as list.

  burp()
    Arg is path on disk, and content. Dumps to path. Warns and returns undef
    on failure.

       burp('./this.out','content') or die;

  yn()
    Argument is what to ask the user, they select y or n. Returns bool.
    Prompts user.

       if (yn('please say y to continue..')){
          warn " # continuing.. \n";
       }

  user_exists()
    Argument is user name, uses system id command. Returns boolean.

       user_exists('leo');

  sq()
    Argument is thing to quote for shell use. Shortcut to
    String::ShellQuote::shell_quote().

       my $weird = '/home/myself/path to funny*named, file';
       my $quoted = sq($weird);
       my $quoted = sq $weird;

OPTIONS
    This uses Getopt::Std, it works very similar to Getopt::Std::Strict. By
    default unless it is already there, -d -h and -v flags are set to
    trigger

       -h will trigger help, if no usage() sub is defined, one is generated.
       -d will enable debug
       -v will print version and exit

    Each option is accessible viat $opt_* So that if you say..

       use LEOCHARRE::CLI2 'ji:';

    You have available the variables $opt_i and $opt_j in your namespace.

  %OPT
    Holds hash of options.

    To access..

       for ( keys %LEOCHARRE::CLI2::OPT){ ...

  opt_selected()
    Returns list of what option keys were chosen, returns undef on none.
    Returns array on list context, array ref on scalar context.

       opts_selected() or die('no options selected');

    Optional argument is list of options. If you pass arguments, returns
    true or false if the options selected match exactly.

    Therefore.. If you say:

       opt_selected(qw/a b/);

    And $opt_a and $opt_b are defined and nothing else is set, it returns
    true.

HELP
    If you want to write your own help, define a usage() sub. If you don't
    defined one, and the user says -h, a help is automatically generated. It
    will contain all your flags, name of script, etc.

    In this example, we generate our own help, and a manual. Usage simply
    returns a string.

       use LEOCHARRE::CLI2;
   
       sub usage {
          q{script [OPTION]...
          -h    help
          -d    debug
          -v    version
      
          Try 'man script' for more info.
          }
       }
   
       __END__
   
       =pod
   
       =head1 NAME
   
       script
   
       =head1 DESCRIPTION
   
       Hi.. I do x y z.

    All cli should have a minimal help that triggers when the user says -h.
    If you define a SCRIPT_DESCRIPTION, it will be placed in the usage
    generated.

CAVEATS
    Alpha software.

SEE ALSO
    Getopt::Std::Strict String::ShellQuote YAML :<Carp> Cwd

AUTHOR
    Leo Charre leocharre at cpan dot org

LICENSE
    This package is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, i.e., under the terms of the
    "Artistic License" or the "GNU General Public License".

DISCLAIMER
    This package 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.

    See the "GNU General Public License" for more details.


--------------------------------------------------------------------------------



REQUIRES

Carp: 1
Cwd: 3
Devel::Symdump: 2.07
Exporter: 5
Getopt::Std: 1.05
Getopt::Std::Strict: 1.01
LEOCHARRE::Dir: 1.06
Smart::Comments: 1
String::ShellQuote: 1.03
Test::Simple: 0
YAML: 0.66


INSTALL

   perl Makefile.PL
   make install