view release on metacpan or  search on metacpan

lib/App/Framework/Feature/Data.pm  view on Meta::CPAN

__DATA__ sections that have special meaning are:

=over 4

=item B<[OPTIONS]> - Application command line options

These are fully described in L<App::Framework::Features::Options>.

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

=item B<[ARGS]> - Application command line arguments [I<optional>]

These are fully described in L<App::Framework::Features::Args>.

=back


=head2 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 L</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') ;


=head2 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:

=over 4

=item *

Option names - the values of any command line options may be used as variables

=item *

Arguments names - the values of any command line arguments may be used as variables

=item *

Application fields - any fields of the $app object may be used as variables

=item *

Environment variables - if no application fields match the variable name, then the environment variables are used

=back 

=head2 Data Comments

Any lines starting with:

    __#

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

=cut

use strict ;
use Carp ;

our $VERSION = "1.003" ;


#============================================================================================
# USES
#============================================================================================
use App::Framework::Feature ;
use App::Framework::Base ;

#============================================================================================
# OBJECT HIERARCHY
#============================================================================================
our @ISA = qw(App::Framework::Feature) ; 

#============================================================================================
# GLOBALS
#============================================================================================


=head2 FIELDS

No public fields

lib/App/Framework/Feature/Data.pm  view on Meta::CPAN

	) ;

#$this->debug(2);

	
	return($this) ;
}



#============================================================================================

=back

=head2 CLASS METHODS

=over 4

=cut

#============================================================================================


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

=item B< init_class([%args]) >

Initialises the Data object class variables.

=cut

sub init_class
{
	my $class = shift ;
	my (%args) = @_ ;

	# Add extra fields
	$class->add_fields(\%FIELDS, \%args) ;

	# init class
	$class->SUPER::init_class(%args) ;

}

#============================================================================================

=back

=head2 OBJECT METHODS

=over 4

=cut

#============================================================================================

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

=item B<app_start_exit()>

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

=cut


sub app_start_exit
{
	my $this = shift ;

	## Handle special options
	my $app = $this->app ;
	my %app_vars = $app->vars ;

	my %opts = $app->options() ;
	my $args_values_href = $app->feature('Args')->args_values_hash() ;

	
	my $data_href = $this->_data_hash() ;

	$this->expand_keys($data_href, [\%opts, $args_values_href, \%app_vars, \%ENV]) ;
}


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

=item B<application_entry()>

Called at start of application 

=cut


sub application_entry
{
	my $this = shift ;

	## Handle special options
	my $app = $this->app ;
	my %opts = $app->options() ;
	## Debug
	if ($opts{'dbg-data'})
	{
		$this->_show_data() ;
		$app->exit(0) ;
	}
	if ($opts{'dbg-data-array'})
	{
		$this->_show_data_array() ;
		$app->exit(0) ;
	}

	
}

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

=item B< 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

=cut

sub data
{
	my $this = shift ;
	my ($name) = @_ ;
	
	my $data_ref ;
	$name ||= "" ;

$this->_dbg_prt(["Data: data($name)\n"]) ;
	
	if ($name)
	{
		my $data_href = $this->_data_hash() ;
$this->_dbg_prt(["Data HASH=", $data_href], 2) ;