NAME

App::Run - Create simple (command line) applications

VERSION

version 0.03

SYNOPSIS

THIS MODULE IS NOT MAINTAINED ANYMORE. Please just http://neilb.org/2013/07/24/adopt-a-module.html or have a look at App::Cmd instead!

    ### shortest form of a script
    use App::Run 'script'; # parses @ARGV and sets $OPTS
    
        ...; # your script

    =head1 SYNOPSIS
    
        ...your documentation...

    =cut


    ### put script into a sub
    use App::Run;

    sub main {
        my ($opts, @args) = @_;
        ...;
    }

    App::Run->new( \&main )->run_with_args(@ARGV);


    ### put script into a package
    use App::Run;

        { 
            package MyApp;
        
                our $VERSION = 1.0; # shown if called with -v

            sub init {          # called before first run
                        my ($opts) = @_;
                ...; 
            }

            sub run {           # main method
            my ($opts, @args) = @_;
                        ...;
            }
        }

        App::Run->new( MyApp->new )->run_with_args(@ARGV);

DESCRIPTION

App::Run provides a boilerplate to build applications that can (also) be run from command line. The module comes in a single package that facilitates:

• Setting configuration values (from file or from command line)

• Initialization

• Logging

App::Run combines Pod::Usage, Config::Any, and Log::Contextual.

METHODS

new( $app, [ %options ] )

Create a new application instance, possibly with options.

parse_options( @ARGV )

Parse command line options, set options from key-value pairs and return the remaining arguments. Nested option names are possible separated with a dot:

    myapp foo=bar doz.bar=2

results in the following options

    { foo => "bar", doz => { bar => 2 }

which could also be specified in a YAML configuration file as

    foo: bar
    doz:
      bar: 2

The options are persistently stored in the application object. You should only call this method once and only for command line applications.

The following arguments are always detected:

    --h, --help, -?           print help with POD::Usage and exit
    --v, --version            print version and exit
    -c FILE, --config FILE    sets option config=file
    --quiet                   sets loglevel=ERROR

The option config is set to the empty string by default.

The method returns remaining arguments as array.

load_config ( [ $from ] )

Load additional options from config file. The config file is automatically detected if not explicitly given. Configuration from config file will not override existing options. Does not initialize the application.

init

Initialized the app by enabling a logger and calling the wrapped application's init method (if defined).

run( [ { $options } ], [ @args ] )

Runs the application.

run_with_args ( @ARGV )

Shortcut to simply initialize and run a command line application. Equal to:

    $app->run( $app->parse_options( @ARGV ) );

This will also initialize the application before actually running it.

name

Returns the name of the application. The name is only determinded once, as return value from $app->name (if implemented) or from $0.

version

Returns the version of the application. The version is determined from the application's VERSION method or from its $VERSION variable, if it is an object, or from $VERSION of the package that imported App:Run. Use method VERSION instead of version to get the version of App:::Run.

app ( $app )

Get and/or set the wrapped application as object or code reference.

logger( [ $logger | [ { %config }, ... ] )

Configure a Log::Log4perl logger, either directly or by passing logger configuration. Logger configuration consists of an array reference with hashes that each contain configuration of Log::Log4perl::Appender. The default appender, as configured with logger(undef) is equal to setting:

    logger([{
        class     => 'Log::Log4perl::Appender::Screen',
        threshold => 'WARN'
    }])

To simply log to a file, one can use:

    logger([{
        class     => 'Log::Log4perl::Appender::File',
        filename  => '/var/log/picaedit/error.log',
        threshold => 'ERROR',
        syswrite  => 1,
    })

Without threshold, logging messages up to TRACE are catched. To actually enable logging, a default logging level is set, for instance

    logger->level('WARN');

Use logger([]) to disable all loggers.

You should not need to directory call this method but provide configuration values logger and loglevel, for instance in a YAML config file:

    loglevel: DEBUG
    logger:
      - class:     Log::Log4perl::Appender::File
        filename:  error.log
        threshold: ERROR
      - class:     Log::Log4perl::Appender::Screen
        layout:    "%d{yyyy-mm-ddTHH::mm} %p{1} %C: %m{chomp}%n"

enable_logger

Set logger and loging level from logging options logger and loglevel. Logging level is set to WARN by default. You should not need to directly call this method unless you have changed the logging options.

SEE ALSO

Configuration is read with Config::Any.

Use Log::Contextual for logging in your application. See Log::Log4perl for logging configuration.

See CLI::Framework for a more elaborated application framework.

App::Run requires at least Perl 5.10.

This package was somehow inspired by plackup.

AUTHOR

Jakob Voß <voss@gbv.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Jakob Voß.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm App::Run

perl -MCPAN -e shell
install App::Run