NAME

CAF::Application - Common Application Framework core class

SYNOPSIS

package example;
use strict;
use warnings;
use LC::Exception qw (SUCCESS throw_error);
use parent qw(CAF::Application);

<extend/overwrite default methods here...>
### Main loop
package main;
use strict;
use warnings;
use LC::Exception qw (SUCCESS throw_error);

use vars ($this_app %SIG);

unless ($this_app = example->new($0,@ARGV)) {
  throw_error (...);
}

$this_app->report("Hello");
...

DESCRIPTION

CAF::Application is the core class which provides command line and configuration file parsing, and general application methods.

Applications can extend or overwrite the default methods.

Public methods

  • name(): string

    Return the application name (basename)

  • version(): string

    Returns the version number as defined in $self->{'VERSION'}, or <unknown> if not defined.

  • hostname(): string

    Returns the machine's hostname.

  • username(): string

    Returns the name of the user.

  • option($opt): scalar|undef

    Returns the option value coming from the command line and/or configuration file. Scalar can be a string, or a reference to a hash or an array containing the option's value. option() is a wrapper on top of AppConfig->get($opt).

  • show_usage(): boolean

    Prints the usage message of the command based on options and help text.

  • show_version(): boolean

    prints the version number of the Application.

  • app_options(): ref(array)

    to be overloaded by the application with application specific options.

    This function has to return a reference to an array. Every element in the array must be a reference to a hash with the following structure:

    NAME    => option name specification in the Getopt::Long(3pm) format
               "name|altname1|altname2|..[argument_type]"
    DEFAULT => [optional] default value (string). If not specified: undef
    HELP    => help text (string)
    

    example:

    push(@array, {NAME =>'M|myoption=s' ,
                  DEFAULT=>'defaultvalue',
                  HELP=>'do somewhat on something'});
    
    return \@array;
    

    see also _app_default_options()

Private methods

  • _initialize

    Initialize the Application.

    Arguments

    • $command

      Name of the script/command/... (typically $0).

    • Remaining arguments @argv

      Typically this is the perl builtin variable @ARGV, but can be any array of options/arguments, or a single arrayref (in which case all elements of the arrayref are handled as options/arguments).

      Any arguments that are not handled by the options, can be retrieved either via @ARGV or by passing an arrayref holding the options/arguments. In these 2 cases, the contents is modified, removing all handled options, leaving the non-option arguments in place. (In particular, using a regular array will leave the original array unmodified).

  • _app_default_options

    This method specifies a number of default options, with the same format as app_options. The options are:

    debug <debuglevel> : sets debug level (1 to 5)
    help               : prints out help message
    quiet              : no output
    verbose            : verbose output
    version            : print out version number & exit
    

    The 'noaction', 'cfgfile' and 'logfile' options are not enabled by default but recognized (they have to be added to the application specific code - see the 'example' file):

    noaction           : execute no operations
    cfgfile <string>  : use configuration file <string>
    logfile  <string>  : use log file <string>
    
  • _add_options

    add options coming from _app_default_options() and app_options()