NAME

App::Framework::Lite - A lightweight framework for creating applications

SYNOPSIS

  use App::Framework::Lite ;
  
  go() ;
  
  sub app
  {
        my ($app, $opts_href, $args_href) = @_ ;
        
        # options
        my %opts = $app->options() ;
    
        # aplication code here....      
  }

DESCRIPTION

App::Framework::Lite is a framework for quickly developing application scripts, where the majority of the mundane script setup, documentation jobs are performed by the framework (under direction from simple text definitions stored in the script). This leaves the developer to concentrate on the main job of implementing the application.

The module also provides the facility of embedding itself into a copy of the original script, creating a self-contained stand-alone script (for further details see "EMBEDDING").

Note that this module provides a subset of the the facilities provided by App::Framework, In particular, it provides the App::Framework::Features:Args, App::Framework::Features:Options, and App::Framework::Features:Data features.

To jump straight in to developing applications, please see App::Framework::Lite::GetStarted.

Capabilities

The application framework provides the following capabilities:

Options definition

Text definition of options in application, providing command line options, help pages, options checking.

Also supports variables in options definition, the variables being replaced by other option values, application field values, or environment variables.

Arguments definition

Text definition of arguments in application, providing command line arguments, help pages, arguments checking, file/directory creation, file/directory existence, file opening

Also supports variables in arguments definition, the variables being replaced by other argument values, option values, application field values, or environment variables.

Named data sections

Multiple named __DATA__ sections, the data being readily accessible by name from the application.

Variables can be used in the data definitions, the variables being replaced by command line option values, application field values, or environment variables.

Application directories

The framework automatically adds the location of the script (following any links) to the Perl search path. This means that perl modules can be created in subdirectories under the application's script making the application self-contained.

The directories used for loading personalities/extensions/features also include the script install directory, meaning that new personalities/extensions/features can also be provided with a script.

Using This Module

The minimum you need is:

    use App::Framework::Lite ;

Optionally, you can specify arguments to the underlying features by appending a string to the 'use' pragma. For exanmple:

    use App::Framework::Lite '+Args(open=none)' ;

Creating Application Object

There are two ways of creating an application object and running it. The normal way is:

    # Create application and run it
    App::Framework::Lite->new()->go() ;

As an alternative, the framework creates a subroutine in the calling namespace called go() which does the same thing:

    # Create application and run it
    go() ;

You can use whatever takes your fancy. Either way, the application object will end up calling the user-defined application subroutines

Application Subroutines

Once the application object has been created it can then be run by calling the 'go()' method. go() calls the application's registered functions in turn:

app_start()

Called at the start of the application. You can use this for any additional set up (usually of more use to extension developers)
app()

Called once all of the arguments and options have been processed
app_end()

Called when app() terminates or returns (usually of more use to extension developers)

The framework looks for these 3 functions to be defined in the script file. The functions app_start and app_end are optional, but it is expected that app will be defined (otherwise nothing happens!).

Setup

The application settings are entered into the __DATA__ section at the end of the file. All program settings are grouped under sections which are introduced by '[section]' style headings. There are many different settings that can be set using this mechanism, but the framework sets most of them to useful defaults.

For more details see "Options" and "Args".

Summary

This should be a single line, concise summary of what the script does. It's used in the terse man page created by pod2man.

Description

As you'd expect, this should be a full description, user-guide etc. on what the script does and how to do it. Notice that this example has used one (of many) of the variables available: $name (which expands to the script name, without any path or extension).

Example

An example script setup is:

    __DATA__
    
    [SUMMARY]
    
    An example of using the application framework
    
    [ARGS]
    
    * infile=f        Input file
    
    Should be set to the input file
    
    * indir=d        Input dir
    
    Should be set to the input dir
    
    [OPTIONS]
    
    -table=s        Table [default=listings2]
    
    Sql table name
    
    -database=s        Database [default=tvguide]
    
    Sql database name
    
    
    [DESCRIPTION]
    
    B<$name> is an example script.

Args

Args feature that provides command line arguments handling.

Command line arguments are defined once in a text format and this text format generates both the command line arguments data, but also the man pages, help text etc. Defining the expected arguments and their types allows the module to check for the existence of the program arguments and their correctness.

Argument Definition

Arguments are specified in the application __DATA__ section in the format:

    * <name>=<specification>    <Summary>    <optional default setting>
    
    <Description>

The parts of the specification are defined below.

name

The name defines the name of the key to use to access the argument value in the arguments hash. The application framework passes a reference to the argument hash as the third parameter to the application subroutine app (see "Script Usage")

specification

The specification is in the format:

   [ <direction> ] [ <binary> ] <type> [ <multiple> ]

The optional direction is only valid for file or directory types. For a file or directory types, if no direction is specified then it is assumed to be input. Direction can be one of:

<: An input file or directory
>: An output file or directory
>>: An output appended file

An optional 'b' after the direction specifies that the file is binary mode (only used when the type is file).

The type must be specified and may be one of:

f: A file
d: A directory
s: Any string

Additionally, an optional multiple can be specified. If used, this can only be specified on the last argument. When it is used, this tells the application framework to use the last argument as an ARRAY, pushing all subsequent specified arguments onto this. Accessing the argument in the script returns the ARRAY ref containing all of the command line argument values.

Multiple can be:

'@': One or more items
'*': Zero or more items. There is also a special case (the real reason for *) where the argument specification is of the form '<f*' (input file multiple). Here, if the script user does not specify any arguments on the command line for this argument then the framework opens STDIN and provides it as a file handle.

summary

The summary is a simple line of text used to summarise the argument. It is used in the man pages in 'usage' mode.

default

Defaults values are optional. If they are defined, they are in the format:

    [default=<value>]

When a default is defined, if the user does not specify a value for an argument then that argument takes on the defualt value.

Also, all subsequent arguments must also be defined as optional.

description

The summary is multiple lines of text used to fully describe the option. It is used in the man pages in 'man' mode.

Feature Options

The Args feature allows control over how it opens files. By default, any input or output file definitions also create equivalent file handles (the files being opened for read/write automatically). These file handles are made available only in the arguments HASH. The key name for the handle being the name of the argument with the suffix '_fh'.

For example, the following definition:

    [ARGS]
    
    * file=f            Input file
    
    A simple input directory name (directory must exist)
    
    * out=>f            Output file (file will be created)
    
    An output filename

And the command line arguments:

    infile.txt outfile.txt

Results in the arguments HASH:

    'file'    => 'infile.txt'
    'out'     => 'outfile.txt'
    'file_fh' => <file handle of 'infile.txt'>
    'out_fh'  => <file handle of 'outfile.txt'>

If this behaviour is not required, then you can get the framework to open just input files, output files, or none by using the 'open' option.

Specify this in the App::Framework 'use' line as an argument to the Args feature:

    # Open no file handles 
    use App::Framework '+Args(open=none)' ;
    
    # Open only input file handles 
    use App::Framework '+Args(open=in)' ;
    
    # Open only output file handles 
    use App::Framework '+Args(open=out)' ;
    
    # Open all file handles (the default)
    use App::Framework '+Args(open=all)' ;

Variable Expansion

Argument values can contain variables, defined using the standard Perl format:

        $<name>
        ${<name>}

When the argument is used, the variable is expanded and replaced with a suitable value. The value will be looked up from a variety of possible sources: object fields (where the variable name matches the field name) or environment variables.

The variable name is looked up in the following order, the first value found with a matching name is used:

Argument names - the values of any other arguments may be used as variables in arguments
Option names - the values of any command line options may be used as variables in arguments
Application fields - any fields of the $app object may be used as variables
Environment variables - if no application fields match the variable name, then the environment variables are used

Script Usage

The application framework passes a reference to the argument HASH as the third parameter to the application subroutine app. Alternatively, the script can call the app object's alias to the args accessor, i.e. the args method which returns the arguments value list. Yet another alternative is to call the args accessor method directly. These alternatives are shown below:

    sub app
    {
        my ($app, $opts_href, $args_href) = @_ ;
        
        # use parameter
        my $infile = $args_href->{infile}
        
        # access alias
        my @args = $app->args() ;
        $infile = $args[0] ;
        
        # access alias
        @args = $app->Args() ;
        $infile = $args[0] ;

        ($infile) = $app->args('infile') ;
        
        # feature object
        @args = $app->feature('Args')->args() ;
        $infile = $args[0] ;
    }

Examples

With the following script definition:

    [ARGS]
    
    * file=f            Input file
    
    A simple input file name (file must exist)
    
    * dir=d                     Input directory
    
    A simple input directory name (directory must exist)
    
    * out=>f            Output file (file will be created)
    
    An output filename
    
    * outdir=>d         Output directory
    
    An output directory name (path will be created) 
    
    * append=>>f        Output file append
    
    An output filename (an existing file will be appended; otherwise file will be created)
    
    * array=<f*         All other args are input files
    
    Any other command line arguments will be pushced on to this array.

The following command line arguments:

    infile.txt indir outfile.txt odir append.txt file1.txt file2.txt file3.txt

Give the arguments HASH values:

    'file'     => 'infile.txt'
    'file_fh'  => <infile.txt file handle>
    'dir'      => 'indir'
    'out'      => 'outfile.txt'
    'out_fh'   => <outfile.txt file handle>
    'outdir'   => 'odir'
    'append'   => 'append.txt'
    'append_fh'=> <append.txt file handle>
    'array'    => [
        'file1.txt'
        'file2.txt'
        'file3.txt'
    ]
    'array_fh' => [
        <file1.txt file handle>
        <file2.txt file handle>
        <file3.txt file handle>
    ]

An example script that uses the multiple arguments, along with the default 'open' behaviour is:

    sub app
    {
        my ($app, $opts_href, $args_href) = @_ ;
        
        foreach my $fh (@{$args_href->{array_fh}})
        {
            while (my $data = <$fh>)
            {
                # do something ... 
            }
        }
    }    
    
    __DATA__
    [ARGS]
    * array=f@    Input file

This script can then be called with one or more filenames and each file will be processed. Or it can be called with no filenames and STDIN will then be used.

Options

Options feature that provides command line options handling.

Options are defined once in a text format and this text format generates both the command line options data, but also the man pages, help text etc.

Option Definition

Options are specified in the application __DATA__ section in the format:

    -<name><specification>    <Summary>    <optional default setting>
    
    <Description>

These user-specified options are added to the application framework options (defined dependent on whatever core/features/extensions are installed). Also, the user may over ride default settings and descriptions on any application framework options by re-defining them in the script.

The parts of the specification are defined below.

name

The name defines the option name to be used at the command line, along with any command line option aliases (e.g. -log or -l, -logfile etc). Using the option in the script is via a HASH where the key is the 'main' option name.

Where an option has one or more aliases, this list of names is separated by '|'. By default, the first name defined is the 'main' option name used as the option HASH key. This may be overridden by quoting the name that is required to be the main name.

For example, the following name definitions:

    -log|logfile|l
    -l|'log'|logfile
    -log

Are all access by the key 'log'

specification

(Note: This is a subset of the specification supported by Getopt::Long).

The specification is optional. If not defined, then the option is a boolean value - is the user specifies the option on the command line then the option value is set to 1; otherwise the option value is set to 0.

When the specification is defined, it is in the format:

   [ <flag> ] <type> [ <desttype> ]

The option requires an argument of the given type. Supported types are:

s: String. An arbitrary sequence of characters. It is valid for the argument to start with - or --.
i: Integer. An optional leading plus or minus sign, followed by a sequence of digits.
o: Extended integer, Perl style. This can be either an optional leading plus or minus sign, followed by a sequence of digits, or an octal string (a zero, optionally followed by '0', '1', .. '7'), or a hexadecimal string (0x followed by '0' .. '9', 'a' .. 'f', case insensitive), or a binary string (0b followed by a series of '0' and '1').
f: Real number. For example 3.14, -6.23E24 and so on.

The desttype can be @ or % to specify that the option is list or a hash valued. This is only needed when the destination for the option value is not otherwise specified. It should be omitted when not needed.

The flag, if used, can be dev: to specify that the option is meant for application developer use only. In this case, the option will not be shown in the normal help and man pages, but will only be shown when the -man-dev option is used.

summary

The summary is a simple line of text used to summarise the option. It is used in the man pages in 'usage' mode.

default

Defaults values are optional. If they are defined, they are in the format:

    [default=<value>]

When a default is defined, if the user does not specify a value for an option then that option takes on the defualt value.

description

The summary is multiple lines of text used to fully describe the option. It is used in the man pages in 'man' mode.

Variable Expansion

Option values and default values can contain variables, defined using the standard Perl format:

        $<name>
        ${<name>}

When the option is used, the variable is expanded and replaced with a suitable value. The value will be looked up from a variety of possible sources: object fields (where the variable name matches the field name) or environment variables.

The variable name is looked up in the following order, the first value found with a matching name is used:

Option names - the values of any other options may be used as variables in options
Application fields - any fields of the $app object may be used as variables
Environment variables - if no application fields match the variable name, then the environment variables are used

Script Usage

The application framework passes a reference to the options HASH as the second parameter to the application subroutine app. Alternatively, the script can call the app object's alias to the options accessor, i.e. the options method which returns the options hash. Yet another alternative is to call the options accessor method directly. These alternatives are shown below:

    sub app
    {
        my ($app, $opts_href, $args_href) = @_ ;
        
        # use parameter
        my $log = $opts_href->{log}
        
        # access alias
        my %options = $app->options() ;
        $log = $options{log} ;
        
        # access alias
        %options = $app->Options() ;
        $log = $options{log} ;
        
        # feature object
        %options = $app->feature('Options')->options() ;
        $log = $options{log} ;
    }

Examples

With the following script definition:

    [OPTIONS]
    
    -n|'name'=s        Test name [default=a name]
    
    String option, accessed as $opts_href->{name}. 
    
    -nomacro    Do not create test macro calls
    
    Boolean option, accessed as $opts_href->{nomacro}
    
    -log=s        Override default [default=another default]
    
    Over rides the default log option (specified by the framework)
    
    -int=i        An integer
    
    Example of integer option
    
    -float=f    An float
    
    Example of float option
    
    -array=s@    An array
    
    Example of an array option
    
    -hash=s%    A hash
    
    Example of a hash option

The following command line options are valid:

    -int 1234 -float 1.23 -array a -array b -array c -hash key1=val1 -hash key2=val2 -nomacro

Giving the options HASH values:

    'name' => 'a name'
    'nomacro' => 1
    'log' => 'another default'
    'int' => 1234
    'float' => 1.23
    'array' => [ 'a', 'b', 'c' ]
    'hash' => {
        'key1' => 'val1',
        'key2' => 'val2',
    }

Data

After the settings (described above), one or more extra data areas can be created by starting that area with a new __DATA__ line.

The __DATA__ section at the end of the script is used by the application framework to allow the script developer to define various settings for his/her script. This setup is split into "headed" sections of the form:

  [ <section name> ]
  
  <settings>

In general, the <section name> is the name of a field value in the application, and <settings> is some text that the field will be set to. Sections of this type are:

[SUMMARY] - Application summary text

A single line summary of the application. Used for man pages and usage summary.

(Stored in the application's summary field).

[DESCRIPTION] - Application description text

Multiple line description of the application. Used for man pages.

(Stored in the application's description field).

[SYNOPSIS] - Application synopsis [optional]

Multiple line synopsis of the application usage. By default the application framework creates this if it is not specified.

(Stored in the application's synopsis field).

[NAME] - Application name [optional]

Name of the application usage. By default the application framework creates this if it is not specified.

(Stored in the application's name field).

__DATA__ sections that have special meaning are:

[OPTIONS] - Application command line options

These are fully described in App::Framework::Features::Options.

If no options are specified, then only those created by the application framework will be defined.

[ARGS] - Application command line arguments [optional]

These are fully described in App::Framework::Features::Args.

Named Data

After the settings (described above), one or more extra data areas can be created by starting that area with a new __DATA__ line.

Each defined data area is named 'data1', 'data2' and so on. These data areas are user-defined multi line text that can be accessed by the object's accessor method "data", for example:

        my $data = $app->data('data1') ;

Alternatively, the user-defined data section can be arbitrarily named by appending a text name after __DATA__. For example, the definition:

        __DATA__
        
        [DESCRIPTION]
        An example
        
        __DATA__ test.txt
        
        some text
        
        __DATA__ a_bit_of_sql.sql
        
        DROP TABLE IF EXISTS `listings2`;

leads to the use of the defined data areas as:

        my $file = $app->data('text.txt') ;
        # or
        $file = $app->data('data1') ;

        my $sql = $app->data('a_bit_of_sql.sql') ;
        # or
        $file = $app->Data('data2') ;

Variable Expansion

The data text can contain variables, defined using the standard Perl format:

        $<name>
        ${<name>}

When the data is used, the variable is expanded and replaced with a suitable value. The value will be looked up from a variety of possible sources: object fields (where the variable name matches the field name) or environment variables.

The variable name is looked up in the following order, the first value found with a matching name is used:

Option names - the values of any command line options may be used as variables
Arguments names - the values of any command line arguments may be used as variables
Application fields - any fields of the $app object may be used as variables
Environment variables - if no application fields match the variable name, then the environment variables are used

Data Comments

Any lines starting with:

__#

are treated as comment lines and not included in the data.

Directories

The framework sets up various directory paths automatically, as described below.

@INC path

App::Framework automatically pushes some extra directories at the start of the Perl include library path. This allows you to 'use' application-specific modules without having to install them globally on a system. The path of the executing Perl application is found by following any links until an actually Perl file is found. The @INC array has the following added:

        * $progpath
        * $progpath/lib

i.e. The directory that the script resides in, and a sub-directory 'lib' will be searched for application-specific modules.

Note that this is the path also used when the framework loads in the core personality, and any optional extensions.

EMBEDDING

A script may be developed and debugged using the App::Framework::Lite module installed on a system, and then turned into a standalone Perl script by embedding the App::Framework::Lite module into the script file. Also, a developer may choose to also embed any user library modules related to this script (or may just deliver them in their dubdirectory along with the standalone script).

Embedding Procedure

When a script is using the App::Framework::Lite module, some developer command line options are automatically added to the script. The developer uses these options in the embedding process:

-alf-embed

Causes the script to create a standalone version of itself

-alf-embed-lib

By default, the script also embeds any user library modules (i.e. any 'use'd modules that are located under $progpath/ or $progpath/lib/).

Specifying this option set to 0 prevents these modules from being embedded.

-alf-compress

By default the embedded modules are stored in a compressed format (whitespace and comments removed).

Specifying this option set to 0 prevents these modules from being compressed. If you have any problems with the embedded modules not working, then try setting this option to 0 and check the resulting script.

Examples

If you have a script test.pl that uses App::Framework::Lite and a user module MyLib.pm (stored in the same directory as test.pl), then you would create a new, stand-alone script alf-test.pl by running any of the following:

Embded compressed App::Framework::Lite and user modules

        perl test.pl -alf-embed alf-test.pl

Results in alf-test.pl having the App::Framework::Lite module and MyLib.pm embedded in a compressed version. The script is then completely stand-alone.

Embded compressed App::Framework::Lite

        perl test.pl -alf-embed alf-test.pl -alf-embed-lib 0

Results in alf-test.pl having the App::Framework::Lite module embedded in a compressed version, but the user module MyLib.pm would need to be delivered along with the script for it to work.

Embded readable App::Framework::Lite and user modules

        perl test.pl -alf-embed alf-test.pl -alf-compress 0

Results in alf-test.pl having the App::Framework::Lite module and MyLib.pm embedded in a readable version. The script is completely stand-alone, but much larger than if the modules had been compressed. This is useful for debugging module problems (especially with a debugger!).

FIELDS

The following fields should be defined either in the call to 'new()' or as part of the application configuration in the __DATA__ section:

 * name = Program name (default is name of program)
 * summary = Program summary text
 * synopsis = Synopsis text (default is program name and usage)
 * description = Program description text
 * history = Release history information
 * version = Program version (default is value of 'our $VERSION')

 * app_start_fn = Function called before app() function (default is application-defined 'app_start' subroutine if available)
 * app_fn = Function called to execute program (default is application-defined 'app' subroutine if available)
 * app_end_fn = Function called after app() function (default is application-defined 'app_end' subroutine if available)
 * usage_fn = Function called to display usage information (default is application-defined 'usage' subroutine if available)

During program execution, the following values can be accessed:

 * package = Name of the application package (usually main::)
 * filename = Full filename path to the application (after following any links)
 * progname = Name of the program (without path or extension)
 * progpath = Pathname to program
 * progext = Extension of program

METHODS

new([%args])

Create a new object.

The %args passed down to the parent objects.

set(%args)

Set one or more settable parameter.

vars()

Return the current object variables

feature($name [, %args])

Dummy for compatibility with App::Framework

go()

Execute the application.

Calls the following methods in turn:

        * app_start
        * application
        * app_end
        * exit

getopts()

Convert the (already processed) options list into settings.

Returns result of calling GetOptions

app_start()

Set up before running the application.

Calls the following methods in turn:

* getopts * [internal _expand_vars method] * options

app_handle_opts()

Handles the default options (for example -man, -help etc)

application()

Execute the application.

Calls the following methods in turn:

* (Application registered 'app' function)

app_end()

Tidy up after the application.

Calls the following methods in turn:

* (Application registered 'app_end' function)

exit()

Exit the application.

usage($level)

Show usage.

$level is a string containg the level of usage to display

        'opt' is equivalent to pod2usage(2)

        'help' is equivalent to pod2usage(1)

        'man' is equivalent to pod2usage(-verbose => 2)

options()

Returns the hash of options/values

Options([%args])

Alias to "options"

get_options()

Use Getopt::Long to process the command line options. Returns 1 on success; 0 otherwise

option_entry($option_name)

Returns the HASH ref of option if name is found; undef otherwise.

The HASH ref contains:

        'field' => option 'main' name 
        'spec' => specification string
        'summary' => summary text 
        'description' => description text
        'default' => default value (if specified)
        'pod_spec' => specification string suitable for pod output
        'type' => option type (e.g. s, f etc)
        'dest_type' => destination type (e.g. @, %)
        'developer' => developer only option (flag set if option is to be used for developer use only)
        'entry' => reference to the ARRAY that defined the option (as per L</append_options>)

option_values_hash()

Returns the options values and defaults HASH references in an array, values HASH ref as the first element.

option_values_set($values_href, $defaults_href)

Sets the options values and defaults based on the HASH references passed in.

args([$name])

When called with no arguments, returns the full arguments list (same as call to method "arg_list").

When a name (or list of names) is specified: if the named arguments hash is available, returns the argument values as a list; otherwise just returns the complete args list.

Args([$name])

Alias to "args"

arg_list()

Returns the full arguments list. This is the list of arguments, as specified at the command line by the user.

arg_hash()

Returns the full arguments hash.

append_args($args_aref)

Append the options listed in the ARRAY ref $args_aref to the current args list

update()

Take the list of args (created by calls to "append_args") and process the list into the final args list.

Each entry in the ARRAY is an ARRAY ref containing:

 [ <arg spec>, <arg summary>, <arg description>, <arg default> ]

Returns the hash of args/values

check_args()

At start of application, check the arguments for valid files etc.

close_args()

If any arguements cause files/devices to be opened, this shuts them down

get_args()

Finish any args processing and return the arguments list

arg_entry($arg_name)

Returns the HASH ref of arg if name is found; undef otherwise

args_values_hash()

Returns the args values HASH reference.

args_values_set($values_href)

Sets the args values based on the values in the HASH reference $values_href.

data([$name])

Returns the lines for the named __DATA__ section as a string. If no name is specified returns the first section.

Returns undef if no data found, or no section with specified name

Data([%args])

Alias to "data"

process_data()

If caller package namespace has __DATA__ defined then use that information to set up object parameters.

pod([$developer])

Return full pod of application

If the optional $developer flag is set, returns application developer biased information

pod_head([$developer])

Return pod heading of application

If the optional $developer flag is set, returns application developer biased information

pod_options([$developer])

Return pod of options of application

If the optional $developer flag is set, returns application developer biased information

pod_description([$developer])

Return pod of description of application

If the optional $developer flag is set, returns application developer biased information

get_synopsis()

Check to ensure synopsis is set. If not, set based on application name and any Args settings

required([$required_href])

Get/set the required programs list. If specified, $required_href is a HASH ref where the keys are the names of the required programs (the values are unimportant).

This method returns the $required_href HASH ref having set the values associated with the program name keys to the path for that program. Where a program is not found then it's path is set to undef.

Also, if the "on_error" field is set to 'warning' or 'fatal' then this method throws a warning or fatal error if one or more required programs are not found. Sets the message string to indicate which programs were not found.

run( [args] )

Execute a command if args are specified. Whether args are specified or not, always returns the run object.

This method has reasonably flexible arguments which can be one of:

(%args)

The args HASH contains the information needed to set the "FIELDS" and then run teh command for example:

  ('cmd' => 'ping', 'args' => $host)

($cmd)

You can specify just the command string. This will be treated as if you had called the function with:

  ('cmd' => $cmd)

($cmd, $args)

You can specify the command string and the arguments string. This will be treated as if you had called the function with:

  ('cmd' => $cmd, 'args' => $args)

NOTE: Need to get run object from application to access this method. This can be done as one of:

  $app->run()->run(.....);
  
  or
  
  my $run = $app->run() ;
  $run->run(....) ;

Run([%args])

Alias to "run"

results()

Run: Retrieve the results output from the last run. Results are returned as an ARRAY ref to the lines of output

status()

Run: Retrieve the exit status of the last run.

on_error( [$on_error] )

Run: Set/get the on_error field.

progress( $progress_callback )

Run: Set the progress callback.

logging($arg1, [$arg2, ....])

Log the argument(s) to the log file iff a log file has been specified.

The list of arguments may be: SCALAR, ARRAY reference, HASH reference, SCALAR reference. SCALAR and SCALAR ref are printed as-is without any extra newlines. ARRAY ref is printed out one entry per line with a newline added. The HASH ref is printed out in the format produced by App::Framework::Base::Object::DumpObj.

echo_logging($arg1, [$arg2, ....])

Same as "logging" but echoes output to STDOUT.

Logging([%args])

Alias to "logging"

expand_keys($hash_ref, $vars_aref)

Processes all of the HASH values, replacing any variables with their contents. The variable values are taken from the ARRAY ref $vars_aref, which is an array of hashes. Each hash containing variable name / variable value pairs.

The HASH values being expanded can be either scalar, or an ARRAY ref. In the case of the ARRAY ref each ARRAY entry must be a scalar (e.g. an array of file lines).

throw_fatal($message)

Output error message then exit

throw_nonfatal($message, [$errorcode])

Add a new error (type=nonfatal) to this object instance, also adds the error to this Class list keeping track of all runtime errors

throw_warning($message, [$errorcode])

Add a new error (type=warning) to this object instance, also adds the error to this Class list keeping track of all runtime errors

throw_note($message, [$errorcode])

Add a new error (type=note) to this object instance, also adds the error to this Class list keeping track of all runtime errors

find_lib($module)

Looks for the named module in the @INC path. If found, checks the package name inside the file to ensure that it really matches the capitalisation.

(Mainly for Microsoft Windows use!)

embed($src, $dest, [$compress])

Embeds App::Framework::Lite into the script and writes the standalone script out

AUTHOR

Steve Price, <sdprice at cpan.org>

BUGS

Please report any bugs or feature requests to bug-app-framework-lite at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-Framework-Lite. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

TODO

This version actually contains support for the 'run' and 'logging' features (from App::Framework) as experimental add-ons. Feel free to use them, but don't expect any support yet!

The next release will have better documentation, feature support, testing etc.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc App::Framework::Lite

You can also look for information at:

RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-Framework-Lite
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/App-Framework-Lite
CPAN Ratings

http://cpanratings.perl.org/d/App-Framework-Lite
Search CPAN

http://search.cpan.org/dist/App-Framework-Lite/

COPYRIGHT & LICENSE

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

To install App::Framework::Lite, copy and paste the appropriate command in to your terminal.

cpanm

cpanm App::Framework::Lite

CPAN shell

perl -MCPAN -e shell
install App::Framework::Lite

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Capabilities

Using This Module

Creating Application Object

Application Subroutines

Setup

Summary

Description

Example

Args

Argument Definition

name

specification

summary

default

description

Feature Options

Variable Expansion

Script Usage

Examples

Options

Option Definition

name

specification

summary

default

description

Variable Expansion

Script Usage

Examples

Data

Named Data

Variable Expansion

Data Comments

Directories

@INC path

EMBEDDING

Embedding Procedure

Examples

Embded compressed App::Framework::Lite and user modules

Embded compressed App::Framework::Lite

Embded readable App::Framework::Lite and user modules

FIELDS

METHODS

AUTHOR

BUGS

TODO

SUPPORT

COPYRIGHT & LICENSE

Module Install Instructions