view release on metacpan or  search on metacpan

lib/App/Basis.pm  view on Meta::CPAN

# ----------------------------------------------------------------------------

1 ;

__END__

=pod

=encoding UTF-8

=head1 NAME

App::Basis - Simple way to create applications

=head1 VERSION

version 1.2

=head1 SYNOPSIS

    use 5.10.0 ;
    use strict ;
    use warnings ;
    use POSIX qw(strftime) ;
    use App::Basis

    sub ctrlc_func {
        # code to decide what to do when CTRL-C is pressed
    }

    sub cleanup_func {
        # optionally clean up things when the script ends
    }

    sub debug_func {
        my ($lvl, $debug) = @_;
        if(!$debug) {
            $debug = $lvl ;
            # set a default level
            $lvl = 'INFO' ;
        }

        say STDERR strftime( '%Y-%m-%d %H:%M:%S', gmtime( time() ) ) . " [$lvl] " . get_program() . " " . $debug;
    }

    # main
    my %opt = App::Basis::init_app(
    help_text   => 'Sample program description'
    , help_cmdline => 'extra stuff to print about command line use'
    , options   =>  {
        'file|f=s'  => {
            desc => 'local system location of xml data'
            , required => 1
        }
        , 'url|u=s' => {
            desc => 'where to find xml data on the internet'
            , validate => sub { my $url = shift ; return $url =~ m{^(http|file|ftp)://} ; }
        }
        , 'keep|k'  => {
            # no point in having this if there is no file option
            desc => 'keep the local file, do not rename it'
            , depends => 'file'
        }
        , 'counter|c=i' => {
            desc => 'check a counter'
            , default   => 5
        }
        , 'basic'   => 'basic argument, needs no hashref data'
    }
    , ctrl_c   => \&ctrl_c_handler  # override built in ctrl-c handler
    , cleanup  => \&cleanup_func    # optional func to call to clean up
    , debug    => \&debug_func      # optional func to call with debugging data
    , 'verbose|v' => 'be verbose about things',
    , log_file => "~/log/fred.log"  # alternative place to store default log messages
    ) ;

    show_usage("need keep option") if( !$opt{keep}) ;

    msg_exit( "spurious reason to exit with error code 3", 3) ;

=head1 DESCRIPTION

There are a number of ways to help script development and to encorage people to do the right thing.
One of thses is to make it easy to get parameters from the command line. Obviously you can play with Getopt::Long and
continuously write the same code and add in your own handlers for help etc, but then your co-workers and friends
make not be so consistent, leading to scripts that have no help and take lots of cryptic parameters.

So I created this module to help with command line arguments and displaying help, then I added L<App::Basis::Config> because
everyone needs config files and does not want to constantly repeat themselves there either.

So how is better than other similar modules? I can't say that it is, but it meets my needs.

There is app help available, there is basic debug functionality, which you can extend using your own function,
you can daemonise your script or run a shell command and get the output/stderr/return code.

If you choose to use App::Basis::Config then you will find easy methods to manage reading/saving YAML based config data.

There are (or will be) other App::Basis modules available to help you write scripts without you having to do complex things
or write lots of code.

There is a helper script to create the boilerplate for an appbasis script, see L<appbasis>

=head1 NAME

 App::Basis

=head1 Public Functions

=over 4

=item set_log_file

Set the name of the log file for the debug function

    set_log_file( "/tmp/lof_file_name") ;
    debug( "INFO", "adding to the debug log") ;

=item debug

Write some debug data. If a debug function was passed to init_app that will be
used, otherwise we will write to STDERR.