/ 
App-Framework-1.02
River stage one • 1 direct dependent • 1 total dependent
/ App::Framework::Feature::Data

NAME

App::Framework::Feature::Data - Handle application setup data

SYNOPSIS

# Data feature is loaded by default as if the script contained:
use App::Framework '+Data' ;

DESCRIPTION

System feature that provides the application core with access to the setup information stored in the __DATA__ section.

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.

FIELDS

No public fields

ADDITIONAL COMMAND LINE OPTIONS

This feature adds the following additional command line options to any application:

-dbg-data - show __DATA__

Display the __DATA__ definition text then exit

-dbg-data-array - show all __DATA__ items

Show all of the processed __DATA__ items then exit

CONSTRUCTOR

new([%args])

Create a new Data.

The %args are specified as they would be in the set method (see "Fields").

CLASS METHODS

init_class([%args])

Initialises the Data object class variables.

OBJECT METHODS

app_start_exit()

Called at the end of app_start. Used to expand the variables in the data

application_entry()

Called at start of application

data([$name])

Returns the lines for the named __DATA__ section. If no name is specified returns the first section. If an ARRAY is required, returns the array; otherwise concatenates the lines with "\n".

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

Data([$name])

Alias to "data"

process()

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

append_user_options()

Adds any user-defined options to the end of the options list

DIAGNOSTICS

Setting the debug flag to level 1 prints out (to STDOUT) some debug messages, setting it to level 2 prints out more verbose messages.

AUTHOR

Steve Price <sdprice at cpan.org>

BUGS

None that I know of!