Commit 5d3dbe0c73ade5271ef48ef61a1cca59e70802e0 - libcgi-application-plugin-config-simple-perl

Imported Upstream version 1.01 Nicholas Bamber 12 years ago

11 changed file(s) with 594 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all

+16

-0

Build.PL less more

	0	#!/usr/bin/perl -w
	1
	2	use Module::Build;
	3	my $build = Module::Build->new(
	4	module_name => 'CGI::Application::Plugin::Config::Simple',
	5	license => 'perl',
	6	requires => {
	7	'CGI::Application' => 3.21,
	8	'Exporter' => 0,
	9	'Config::Simple' => 0,
	10	'Test::More' => 0,
	11	},
	12	create_makefile_pl => 'traditional',
	13	create_readme => 1,
	14	);
	15	$build->create_build_script();

+22

-0

Changes less more

	0	Revision history for Perl extension CGI::Application::MailPage.
	1
	2	1.01 (Dec, 19 2005)
	3	- fixed failing permission tests if running as root
	4
	5	1.00 (Mar, 08 2005)
	6	- 100% test coverage
	7
	8	0.04 (Oct, 19 2004)
	9	- Removed CGI::Application::Plugin dependancy in tests
	10	- Fixed minor POD discrepancy
	11
	12	0.03 (Sep. 13 2004)
	13	- Changed from using CGI::Application::Plugin to Exporter
	14	- Changed name of internal store from {_PLUGINS}->{'Config::Simple'} to just {__CONFIG_SIMPLE}
	15
	16	0.02 (Aug. 16 2004)
	17	- Changed to support new CGI::Application::Plugin
	18
	19	0.01
	20	- First version.
	21

+11

-0

MANIFEST less more

	0	Build.PL
	1	Changes
	2	lib/CGI/Application/Plugin/Config/Simple.pm
	3	Makefile.PL
	4	MANIFEST This list of files
	5	META.yml
	6	README
	7	t/main.t
	8	t/test.conf
	9	t/test.ini
	10	t/test_unwriteable.ini

+19

-0

META.yml less more

	0	---
	1	name: CGI-Application-Plugin-Config-Simple
	2	version: 1.01
	3	author:
	4	- Michael Peters <mpeters@plusthree.com>
	5	abstract: Add Config::Simple support to CGI::Application
	6	license: perl
	7	resources:
	8	license: http://dev.perl.org/licenses/
	9	requires:
	10	CGI::Application: 3.21
	11	Config::Simple: 0
	12	Exporter: 0
	13	Test::More: 0
	14	provides:
	15	CGI::Application::Plugin::Config::Simple:
	16	file: lib/CGI/Application/Plugin/Config/Simple.pm
	17	version: 1.01
	18	generated_by: Module::Build version 0.2703

+18

-0

Makefile.PL less more

	0	# Note: this file was auto-generated by Module::Build::Compat version 0.03
	1	use ExtUtils::MakeMaker;
	2	WriteMakefile
	3	(
	4	'PL_FILES' => {},
	5	'INSTALLDIRS' => 'site',
	6	'NAME' => 'CGI::Application::Plugin::Config::Simple',
	7	'EXE_FILES' => [],
	8	'VERSION_FROM' => 'lib/CGI/Application/Plugin/Config/Simple.pm',
	9	'PM' => undef,
	10	'PREREQ_PM' => {
	11	'Test::More' => 0,
	12	'Config::Simple' => 0,
	13	'CGI::Application' => '3.21',
	14	'Exporter' => 0
	15	}
	16	)
	17	;

+145

-0

README less more

	0	NAME
	1	CGI::Application::Plugin::Config::Simple - Add Config::Simple support to
	2	CGI::Application
	3
	4	SYNOPSIS
	5	in your CGI::Application based module
	6
	7	use CGI::Application::Plugin::Config::Simple;
	8
	9	sub cgiapp_init {
	10	my $self = shift;
	11	#set my config file
	12	$self->config_file('myapp.conf');
	13
	14	#
	15	#do other stuff
	16	#
	17	}
	18
	19	#later on in a run mode
	20	sub run_mode1 {
	21	my $self = shift;
	22
	23	#just get a single parameter from my config file
	24	my $value = $self->config_param('my_param');
	25
	26	#get a parameter in a block (if using ini style files)
	27	$value = $self->config_param('my_block.my_param');
	28
	29	#the entire config hash reference
	30	my $config_vars = $self->config_param();
	31
	32	#get my Config::Simple object for direct access
	33	my $config = $self->config;
	34	}
	35
	36	DESCRIPTION
	37	This module acts as a plugin for Config::Simple to be easily used inside
	38	of a CGI::Application module. It does not provide every method available
	39	from Config::Simple but rather easy access to your configuration
	40	variables. It does however provide direct access to the underlying
	41	Config::General object created if you want to use it's full power.
	42
	43	The module tries to make the getting and setting of configuration
	44	variables as easy as possible. Only three methods are exported into your
	45	CGI::Application module and they are described below.
	46
	47	Before I wrote this module sometimes I would put my code that read in
	48	the configuration file into the cgiapp_init() or cgiapp_prerun() methods
	49	but then if I had a run mode that didn't need those config variables it
	50	was run anyway. This module helps to solve this is. The Config::Simple
	51	object is not created (and the config file is not read and parsed) until
	52	after your first call to config() or config_param() to either
	53	retrieve/set values, or get the Config::Simple object. This lazy loading
	54	idea came from Cees Hek's CGI::Application::Plugin::Session module.
	55
	56	METHODS
	57	config_param()
	58
	59	This method acts as an accessor/mutator for configuration variables
	60	coming from the configuration file.
	61
	62	This method will behave in three different ways depending on how many
	63	parameters it is passed. If 0 parameters are passed then the entire
	64	config structure will be returned as a hash ref. If 1 parameters is
	65	passed then the value of that parameter in the config file will be
	66	returned. If more than 1 parameter is passed then it will treat them as
	67	name value pairs and will set the parameters in the config file
	68	accordingly. In this case, if we successfully set the parameters then a
	69	true value will be returned.
	70
	71	#get the complete config hash
	72	my $config_hash = $self->config_param();
	73	#just get one config value
	74	my $value = $self->config_param($parameter);
	75	#set multiple config values
	76	my $success = $self->config_param(param1 => $value1, param2 => $value2);
	77
	78	This method uses Config::Simple so if you are using ini-files then you
	79	can set the values of variables inside blocks as well using the '.'
	80	notation. See Config::Simple;
	81
	82	You must set the name of the configuration file either using the
	83	config_file() method or the CGIAPP_CONFIG_FILE environment variable
	84	before calling this method or it will 'die'.
	85
	86	config()
	87
	88	This method will return the underlying Config::Simple object for more
	89	direct use by your application. You must set the name of the
	90	configuration file either using the config_file() method or the
	91	CGIAPP_CONFIG_FILE environment variable before calling this method or it
	92	will 'die'.
	93
	94	my $conf = $self->config();
	95
	96	config_file([$file_name])
	97
	98	This method acts as an accessor/mutator to either get the name of the
	99	current config file or to change/initialize it. This method must be
	100	called to initialize the name of the config file before any call can be
	101	made to either config() or config_param() unless the
	102	'CGIAPP_CONFIG_FILE' environment variable has been set. If this
	103	environment variable is set it will be used as the initial value of the
	104	config file. This is useful if we are running in a mod_perl environment
	105	when can use a statement like this in your httpd.conf file:
	106
	107	PerlSetEnv CGIAPP_CONFIG_FILE /path/to/my/conf
	108
	109	It is typical to set the name of the config file in the cgiapp_init()
	110	phase of your application.
	111
	112	If a value is passed as a parameter then the config file with that name
	113	is used. It will always return the name of the current config file.
	114
	115	#get the value of the CGIAPP_CONFIG_FILE environment variable (if there is one)
	116	#since we haven't set the config file's name with config_file() yet.
	117	my $file_name = $self->config_file();
	118
	119	#set the config file's name
	120	$self->config_file('myapp.conf');
	121
	122	#get the name of the config file
	123	$file_name = $self->config_file();
	124
	125	CAVEATS
	126	The CGI::Application object is implemented as a hash and we store the
	127	variables used by this module's methods inside of it as a hash named
	128	__CONFIG_SIMPLE. If you use any other CGI::Application plugins there
	129	would be problems if they also used $self->{__CONFIG_SIMPLE} but in
	130	practice this should never actually happen.
	131
	132	AUTHOR
	133	Michael Peters <mpeters@plusthree.com>
	134
	135	Thanks to Plus Three, LP (http://www.plusthree.com) for sponsoring my
	136	work on this module
	137
	138	SEE ALSO
	139	* CGI::Application
	140	* Config::Simple
	141	LICENSE
	142	This library is free software; you can redistribute it and/or modify it
	143	under the same terms as Perl itself.
	144

+235

-0

lib/CGI/Application/Plugin/Config/Simple.pm less more

	0	package CGI::Application::Plugin::Config::Simple;
	1	use strict;
	2	use warnings;
	3	use base 'Exporter';
	4	use CGI::Application;
	5	use Config::Simple;
	6
	7	$CGI::Application::Plugin::Config::Simple::VERSION = '1.01';
	8	use vars '@EXPORT';
	9	@EXPORT = qw(config_file config_param config);
	10
	11	=pod
	12
	13	=head1 NAME
	14
	15	CGI::Application::Plugin::Config::Simple - Add Config::Simple support to CGI::Application
	16
	17	=head1 SYNOPSIS
	18
	19	in your CGI::Application based module
	20
	21	use CGI::Application::Plugin::Config::Simple;
	22
	23	sub cgiapp_init {
	24	my $self = shift;
	25	#set my config file
	26	$self->config_file('myapp.conf');
	27
	28	#
	29	#do other stuff
	30	#
	31	}
	32
	33	#later on in a run mode
	34	sub run_mode1 {
	35	my $self = shift;
	36
	37	#just get a single parameter from my config file
	38	my $value = $self->config_param('my_param');
	39
	40	#get a parameter in a block (if using ini style files)
	41	$value = $self->config_param('my_block.my_param');
	42
	43	#the entire config hash reference
	44	my $config_vars = $self->config_param();
	45
	46	#get my Config::Simple object for direct access
	47	my $config = $self->config;
	48	}
	49
	50
	51	=head1 DESCRIPTION
	52
	53	This module acts as a plugin for L<Config::Simple> to be easily used inside of a
	54	L<CGI::Application> module. It does not provide every method available from L<Config::Simple>
	55	but rather easy access to your configuration variables. It does however provide direct
	56	access to the underlying L<Config::General> object created if you want to use it's full
	57	power.
	58
	59	The module tries to make the getting and setting of configuration variables as easy as
	60	possible. Only three methods are exported into your L<CGI::Application> module and they
	61	are described below.
	62
	63	Before I wrote this module sometimes I would put my code that read in the configuration file
	64	into the cgiapp_init() or cgiapp_prerun() methods but then if I had a run mode that didn't need
	65	those config variables it was run anyway. This module helps to solve this is. The L<Config::Simple>
	66	object is not created (and the config file is not read and parsed) until after your first call
	67	to L<config()> or L<config_param()> to either retrieve/set values, or get the L<Config::Simple>
	68	object. This lazy loading idea came from Cees Hek's L<CGI::Application::Plugin::Session> module.
	69
	70	=head1 METHODS
	71
	72	=head2 config_param()
	73
	74	This method acts as an accessor/mutator for configuration variables coming from the
	75	configuration file.
	76
	77	This method will behave in three different ways depending on how many parameters it
	78	is passed. If 0 parameters are passed then the entire config structure will be returned
	79	as a hash ref. If 1 parameters is passed then the value of that parameter in the config
	80	file will be returned. If more than 1 parameter is passed then it will treat them as name
	81	value pairs and will set the parameters in the config file accordingly. In this case, if
	82	we successfully set the parameters then a true value will be returned.
	83
	84	#get the complete config hash
	85	my $config_hash = $self->config_param();
	86	#just get one config value
	87	my $value = $self->config_param($parameter);
	88	#set multiple config values
	89	my $success = $self->config_param(param1 => $value1, param2 => $value2);
	90
	91	This method uses Config::Simple so if you are using ini-files then you can set
	92	the values of variables inside blocks as well using the '.' notation. See L<Config::Simple>;
	93
	94	You must set the name of the configuration file either using the L<config_file()> method
	95	or the CGIAPP_CONFIG_FILE environment variable before calling this method or it will 'die'.
	96
	97	=cut
	98
	99	sub config_param {
	100	my $self = shift;
	101	my @params = @_;
	102	my $conf = $self->config();
	103
	104	#if there aren't any params then we want the entire config structure as a hash ref
	105	if(scalar(@params) == 0) {
	106	return scalar($conf->vars)
	107	} elsif(scalar(@params) == 1) {
	108	#if there is just one then we want just that value
	109	return $conf->param($params[0])
	110	}
	111	#else we might be setting some values
	112	else {
	113	my %params = (@params);
	114	$conf->param($_ => $params{$_}) foreach (keys %params);
	115	if($conf->write) {
	116	return 1
	117	} else {
	118	die "Config-Plugin: Could not write to config file (" . $self->config_file . ")! " . $conf->error()
	119	}
	120	}
	121	}
	122
	123
	124	=pod
	125
	126	=head2 config()
	127
	128	This method will return the underlying Config::Simple object for more direct use by your
	129	application. You must set the name of the configuration file either using the L<config_file()> method
	130	or the CGIAPP_CONFIG_FILE environment variable before calling this method or it will 'die'.
	131
	132	my $conf = $self->config();
	133
	134	=cut
	135
	136	sub config {
	137	my $self = shift;
	138	#if we don't already have a config object or if the file name has changed on us then create it
	139	my $create = !$self->{__CONFIG_SIMPLE}->{__CONFIG_OBJ}
	140	\|\| $self->{__CONFIG_SIMPLE}->{__FILE_CHANGED};
	141	if($create) {
	142	#get the file name from config_file()
	143	my $file_name = $self->config_file or die "No config file specified!";
	144	my $conf = Config::Simple->new($file_name) or die "Could not create Config::Simple object for file $file_name! $!";
	145	$self->{__CONFIG_SIMPLE}->{__CONFIG_OBJ} = $conf;
	146	$self->{__CONFIG_SIMPLE}->{__FILE_CHANGED} = 0;
	147	}
	148	return $self->{__CONFIG_SIMPLE}->{__CONFIG_OBJ};
	149	}
	150
	151	=pod
	152
	153	=head2 config_file([$file_name])
	154
	155	This method acts as an accessor/mutator to either get the name of the current config file
	156	or to change/initialize it. This method must be called to initialize the name of the config
	157	file before any call can be made to either L<config()> or L<config_param()> unless the
	158	'CGIAPP_CONFIG_FILE' environment variable has been set. If this environment variable is set
	159	it will be used as the initial value of the config file. This is useful if we are running in
	160	a mod_perl environment when can use a statement like this in your httpd.conf file:
	161
	162	PerlSetEnv CGIAPP_CONFIG_FILE /path/to/my/conf
	163
	164	It is typical to set the name of the config file in the cgiapp_init() phase of your application.
	165
	166	If a value is passed as a parameter then the config file with that name is used. It will always
	167	return the name of the current config file.
	168
	169	#get the value of the CGIAPP_CONFIG_FILE environment variable (if there is one)
	170	#since we haven't set the config file's name with config_file() yet.
	171	my $file_name = $self->config_file();
	172
	173	#set the config file's name
	174	$self->config_file('myapp.conf');
	175
	176	#get the name of the config file
	177	$file_name = $self->config_file();
	178
	179	=cut
	180
	181	sub config_file {
	182	my ($self, $file_name) = @_;
	183	#if we have a file name to set
	184	if(defined $file_name) {
	185	$self->{__CONFIG_SIMPLE}->{__FILE_NAME} = $file_name;
	186	$self->{__CONFIG_SIMPLE}->{__FILE_CHANGED} = 1;
	187	} else {
	188	#else we are getting the filename
	189	$file_name = $self->{__CONFIG_SIMPLE}->{__FILE_NAME}
	190	}
	191	#if we don't have the file_name then get it from %ENV, but untaint it
	192	if(!$file_name) {
	193	$ENV{CGIAPP_CONFIG_FILE} =~ /(.*)/;
	194	$file_name = $1;
	195	}
	196	return $file_name;
	197	}
	198
	199	1;
	200
	201	__END__
	202
	203	=pod
	204
	205	=head1 CAVEATS
	206
	207	The CGI::Application object is implemented as a hash and we store the variables used by this
	208	module's methods inside of it as a hash named __CONFIG_SIMPLE. If you use any other CGI::Application
	209	plugins there would be problems if they also used $self->{__CONFIG_SIMPLE} but in practice this should
	210	never actually happen.
	211
	212	=head1 AUTHOR
	213
	214	Michael Peters <mpeters@plusthree.com>
	215
	216	Thanks to Plus Three, LP (http://www.plusthree.com) for sponsoring my work on this module
	217
	218	=head1 SEE ALSO
	219
	220	=over 8
	221
	222	=item * L<CGI::Application>
	223
	224	=item * L<Config::Simple>
	225
	226	=back
	227
	228	=head1 LICENSE
	229
	230	This library is free software; you can redistribute it and/or modify
	231	it under the same terms as Perl itself.
	232
	233	=cut
	234

+97

-0

t/main.t less more

	0	#!/usr/bin/perl
	1	use Test::More;
	2	plan(tests => 20);
	3	use strict;
	4
	5
	6	# 1
	7	# test that we have the modules we need
	8	require_ok('CGI::Application::Plugin::Config::Simple');
	9	#create an empty hash to represent a C::A::P::C::S object
	10	my $self = bless {}, 'CGI::Application::Plugin::Config::Simple';
	11
	12	# 2..11
	13	# ok, set the environment variable to make sure we can get that
	14	{
	15	$ENV{CGIAPP_CONFIG_FILE} = 't/test.ini';
	16	my $value = $self->config_file();
	17	is($value, 't/test.ini', 'Config file name from %ENV');
	18
	19	# now let's get a few parameters
	20	$value = $self->config_param('block1.param11');
	21	is($value, 'value11', 'Simple ini-file param 1');
	22	$value = $self->config_param('block2.param22');
	23	is($value, 'value22', 'Simple ini-file param 2');
	24
	25	# now let's set some parameters
	26	$value = $self->config_param('block1.param11' => 'testing11', 'block2.param22' => 'testing22');
	27	ok($value, 'Set ini-file params 1');
	28	# and test their values
	29	$value = $self->config_param('block1.param11');
	30	is($value, 'testing11', 'Simple ini-file param 1');
	31	$value = $self->config_param('block2.param22');
	32	is($value, 'testing22', 'Simple ini-file param 2');
	33	# now let's set them back
	34	$value = $self->config_param('block1.param11' => 'value11', 'block2.param22' => 'value22');
	35	ok($value, 'Set ini-file params 2');
	36
	37	# now let's get all of the values in a hash
	38	$value = $self->config_param();
	39	is(ref($value), 'HASH', 'Get all ini-file params');
	40
	41	# now let's test this hash's values
	42	is($value->{'block1.param11'}, 'value11', 'Testing individual elements of entire config hash 1');
	43	is($value->{'block2.param22'}, 'value22', 'Testing individual elements of entire config hash 2');
	44	}
	45
	46	# 12..16
	47	# now let's change config files
	48	{
	49	my $value = $self->config_file('t/test.conf');
	50	is($value, 't/test.conf', 'Change config file');
	51
	52	# now let's test these values
	53	$value = $self->config_param('param1');
	54	is($value, 'value1', 'Simple config param 1');
	55	$value = $self->config_param('param2');
	56	is($value, 'value2', 'Simple config param 2');
	57	$value = $self->config_param('param3');
	58	is($value, 'value3', 'Simple config param 3');
	59
	60	# now let's test the config() method to see if we get a Config::Simple object
	61	$value = $self->config();
	62	is(ref($value), 'Config::Simple', 'config() returned object');
	63	}
	64
	65	# 17..20
	66	# lets cause some errors
	67	SKIP: {
	68	# try to change it's permissions
	69	my $new_file = 't/test_unwriteable.ini';
	70	chmod(0000, $new_file) \|\| die "Could not chmod $new_file! $!";
	71	# skip these tests if we can still read the file
	72	# cause we're probably running as root
	73	skip('user wont have permission issues', 4) if( -r $new_file );
	74
	75	# un readable file
	76	$self->config_file($new_file);
	77	eval { $self->config_param('param1') };
	78	like($@, qr/Permission denied/i, 'un readable file');
	79
	80	# un writeable file
	81	chmod(0400, $new_file)
	82	\|\| die "Could not chmod $new_file! $!";
	83	my $value = $self->config_file($new_file);
	84	is($value, $new_file, 'new unwriteable file');
	85	eval { $self->config_param(param1 => 'xyz') };
	86	like($@, qr/Could not write/i, 'could not write');
	87
	88	# don't specify a config file
	89	$ENV{CGIAPP_CONFIG_FILE} = '';
	90	$self->config_file('');
	91	eval { $self->config_param('param1') };
	92	like($@, qr/No config file/i, 'no file given');
	93	}
	94
	95
	96

-0

t/test.conf less more

	0	param1 value1
	1	param2 value2
	2	param3 value3
	3

+12

-0

t/test.ini less more

	0	; Config::Simple 4.57
	1	; Mon Dec 19 10:35:02 2005
	2
	3	[block2]
	4	param22=value22
	5	param21=value21
	6
	7	[block1]
	8	param12=value12
	9	param11=value11
	10
	11

+15

-0

t/test_unwriteable.ini less more

	0	; Config::Simple 4.57
	1	; Mon Dec 19 10:34:23 2005
	2
	3	[block1]
	4	param12=value12
	5	param11=value11
	6
	7	[block2]
	8	param22=value22
	9	param21=value21
	10
	11	[default]
	12	param1=xyz
	13
	14