NAME

LEOCHARRE::CLI - useful subs for coding cli scripts

DESCRIPTION

I use this module as base for my CLI scripts. It standardizes some things.

PROMPT

yn()

prompt user for y/n confirmation will loop until it returs true or false argument is the question for the user

        yn('are you sure you want to destroy something?') or exit;

FEEDBACK DEBUG ETC

DEBUG()

returns boolean if script has -d flag, this is on.

debug()

Use to print to STDERR if DEBUG is on.

   debug('reached that part in our program..');

say()

Prints to stderr returns true, similar to warn.

dye()

Similar to dye, implies there is no error with script, but with a param, etc.

SYSTEM AND ENVIRONMENT

All my scripts are meant to be run on POSIX systems. Specifically gnu linux.

_scriptname()

Returns name of script, just the name.

os_is_win()

attempts to match $^O to a windows type os

force_root()

Will force program to exit if whoami() is not root.

running_as_root()

Returns boolean, checks if we are running as root.

whoami()

Returns who you are running as, name. If which('whoami') does not return, returns undef

get_uid()

Argument is username. Returns user id number. Returns nothing if not a user on this system. This is a way to test if user exists on system.

get_gid()

Argument is group name. Returns gid of group. If the argument is not a group on the system, returns undef. With this you can test for the user on system.

user_exists()

Argument is username. Returns boolean.

witch()

Arg is binary name (like find, man, etc), returns abs path to binary or dies with error.

   my $bin = witch('tesseract');

Will exit and say that tesseract is not installed etc.

FILE SUBS

get_mode()

argument is path to file on disk returns mode in the form 755 if not on disk returns undef

COMMAND LINE ARGUMENTS

Arguments to command line interface.

CLI options:

        -d is always debug
        -h is always print help and exit
        -v is always print version and exit
        

PATH ARGUMENTS

You MUST call gopts() BEFORE you call these, if you expect both filename arguments AND command arguments. Otherwise you will get garble- because you'll interpret things like -f and -d as file instead of options.

argv_aspaths()

returns array ref of argument variables treated as paths, they are resolved with Cwd::abs_path() Any arguments that do not resolve, are skipped with a warning. if no abs paths are present after checking, returns undef files are checked for existence returns undef if no @ARGVS or none of the args are on disk skips over files not on disk with warnings

argv_aspaths_strict()

Same as argv_aspaths(), but returns false if any of the file arguments are no longer on disk

argv_aspaths_loose()

Same as argv_aspaths(), but does not check for existence, only resolved to abs paths

OPTIONS AND PARAMETERS

gopts()

returns hash of options uses Getopt::Std, forces v for version, h for help d for debug

To get standard with v and h:

        my $o = gopts(); 

To add options

        my $o = gopts('af:');

Adds a (bool) and f(value), v and h are still enforced.

See Getopt::Std

config()

argument is abs paht to YAML conf file returns conf hash warns and returns undef if file is not there

If no argument if provided, will attempt to use heuristics to guess. Will use HOME environment variable.

suggest_abs_conf()

suggest_abs_log()

HELP

Whenever a script is calledwith -h it should output help.

Example script:

   use base 'LEOCHARRE::CLI';

   sub usage {
      return qq{
      $0

      OPTIONS

         -h help
      };
   }

And then..

   script -h

usage()

You should define this sub in your script. It should return OPTION and PARAMETER flags etc.

man()

will print manual and exit.

This first seeks your script for a global variable $usage, then a subroutine named usage() prints to screen and exits. otherwise it calls man ./pathtoscript

when you invoke -h via the commandline, this is called automatically.

mktmpdir()

will make a temp dir in /tmp/tmp_$rand returns abs path to dir returns undef and warns if it cant will not overrite an existing dir, returns undef if already exists (unlikely).

SEE ALSO

File::Which Linux::usermod Cwd Getopt::Std

CAVEATS

This module is for gnu linux. It will not even install on non POSIX systems. Don't even try it, the installer checks for that.

There are no plans to port any of my code to other "systems".

AUTHOR

Leo Charre leocharre at cpan dot org

BUGS

I make fixes and updates as quickly as I can. Please contact me for any suggestions, etc.

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".

COPYRIGHT

Copyright (c) 2008 Leo Charre. All rights reserved.

cpanm LEOCHARRE::CLI

perl -MCPAN -e shell
install LEOCHARRE::CLI