NAME
OpenInteract2::Config::Package - Read, write and check package config files
SYNOPSIS
# Sample package file
name MyPackage
version 1.53
author Steve <steve@dude.com>
author Chuck <chuck@guy.com>
url http://www.oirox.com/
template_plugin TestPlugin OpenInteract2::Plugin::Test
filter mywiki OpenInteract2::Filter::MyWiki
description
This package rocks!
# Create a new package file from scratch
use OpenInteract2::Config::Package;
my $c = OpenInteract2::Config::Package->new();
$c->name( 'MyPackage' );
$c->version( 1.53 );
$c-> url( 'http://www.oirox.com/' );
$c->author( [ 'Steve <steve@dude.com>', 'Chuck <chuck@guy.com>' ] );
$c->template_plugin({ TestPlugin => 'OpenInteract2::Plugin::Test' });
$c->description( 'This package rocks!' );
# Set the filename to save the config to and save it
$c->filename( 'mydir/pkg/MyPackage/package.conf' );
eval { $c->save_config };
# Specify a directory for an existing config
my $c = OpenInteract2::Config::Package->new(
{ directory => '/path/to/mypackage' } );
# Specify a filename for an existing config
my $c = OpenInteract2::Config::Package->new(
{ filename => 'work/pkg/mypackage/package-alt.conf' } );DESCRIPTION
This class implements read/write access to a package configuration file. This is a very simple line-based format. There are three types of values:
single value
Example:
name MyPackagemultiple value
Example:
author Chris Winters E<lt>chris@cwinters.comE<gt>
author Mario Lemiux <mario@pghpenguins.com>multiple keyed value
Example:
template_plugin MyPlugin OpenInteract2::Template::Plugin::MyPlugin
template_plugin MyPluginNew OpenInteract2::Template::Plugin::MyPluginNew
filter mywiki OpenInteract2::Filter::MyWikiAdditionally, all data below the last entry description is used as the description. Example:
description
Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam
nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat
volutpat. Ut wisi enim ad minim veniam, quis nostrud exercitation
ulliam corper suscipit lobortis nisl ut aliquip ex ea commodoMETHODS
Class Methods
new( \%params )
Creates a new configuration object from \%params:
filename: Read the configuration from this filedirectory: Read the configuration from the filepackage.conflocated in this directory. (Also:package_dir)
Other fields in \%params are used to set the values of the object. If you pass a filename/directory and parameters, the parameters will be overridden by whatever is read from the file.
Returns: new object
create_filename( $directory )
Create a filename for this configuration file given $directory. The default name for the package configuration file is package.conf.
Examples:
my $filename = OpenInteract2::Config::Package->create_filename( '/home/httpd/mysite/pkg/foo' );
# $filename: '/home/httpd/mysite/pkg/foo/package.conf'We do not check whether $directory exists or whether the resulting filename is valid.
Returns: filename
get_required_fields()
Returns: Arrayref of fields required for configuration object to be valid.
Object Methods
init( \%params )
Initialize the object with \%params. Only fields listed in PROPERTIES will be set, and only properties with a value will be set.
Returns: object
get_spops_files()
Returns all SPOPS files in this package as set in spops_file, relative to the package directory (set in package_dir). This module does not verify that the files exist and are coherent, it just reports what is configured. If no entries are in spops_file, it returns an empty arrayref.
Example:
name foo
version 1.51
spops_file conf/object_one.ini
spops_file conf/object_two.ini
...
$config->package_dir( '/home/me/pkg' )
my $files = $config->get_spops_files();
# [ 'conf/object_one.ini', 'conf/object_two.ini' ]Returns: Arrayref of filenames, not fully-qualified. If no files declared return an empty arrayref.
get_action_files()
Returns all action files in this package as set in action_file, relative to the package directory (set in package_dir). This module does not verify that the files exist and are coherent, it just reports what is configured. If no entries are in action_file, it returns an empty arrayref.
Example:
name foo
version 1.51
action_file conf/action_one.ini
action_file conf/action_two.ini
...
$config->package_dir( '/home/me/pkg' )
my $files = $config->get_action_files();
# [ 'conf/action_one.ini', 'conf/action_two.ini' ]Returns: Arrayref of filenames, not fully-qualified. If no files declared returns an empty arrayref.
get_message_files()
Returns all message files in this package as set in message_file, relative to the package directory (set in package_dir). This module does not verify that the files exist and are coherent, it just reports what is configured. If no entries are in message_file, it returns an empty arrayref.
Example:
name foo
version 1.51
message_file data/foo-en.msg
message_file data/foo-en_us.msg
message_file data/foo-en_uk.msg
...
$config->package_dir( '/home/me/pkg' )
my $files = $config->get_message_files();
# [ 'data/foo-en.msg', 'data/foo-en_us.msg', 'data/foo-en_uk.msg' ]Returns: Arrayref of filenames, not fully-qualified. If no files declared returns an empty arrayref.
check_required_fields( [ @check_fields ] )
Check whether the required fields are set in the object. Required fields are those returned by get_required_fields(); you can also add your own to check using @check_fields.
Returns: true if all required fields are defined, throws exception if not.
save_config()
Saves the configuration information to a file. The property filename must be set, otherwise an exception is thrown. An exception is also thrown if filename cannot be opened for writing.
Returns: Filename where the configuration was written.
PROPERTIES
Filesystem Properties
Both of these will be set automatically if you pass in either filename or directory to new()
filename: File where the configuration is written.
package_dir: Directory in which the configuration is written.
Configuration Properties
These are all read from and written to the configuration file.
name ($) (mandatory)
Name of the package
version ($) (mandatory)
Package version
author (\@)
Author(s) of the package
url ($)
URL where you can find out more information
spops_file (\@)
File with SPOPS objects defined in this package. If you do not specify these you must store all object configuration information in a single file conf/spops.ini. Both perl- and INI-formatted configurations are acceptable. (TODO: true?)
action_file (\@)
File with the actions defined in this package. If you do not specify these you must store all action information in a single file conf/action.ini. Both perl- and INI-formatted configurations are acceptable. (TODO: true?)
message_file (\@)
File with the localized messages used in your application. If you do not specify these you must store your message files in a subdirectory msg/ and in files ending with .msg. The format of these files is discussed in OpenInteract2::I18N and OpenInteract2::Manual::I18N.
module (\@)
Module(s) required by this package.
sql_installer ($)
SQL installer class to use for this package.
template_plugin (\%)
Template Toolkit plugins defined by this package. Each plugin is defined by a space-separated key/value pair. The template users access the plugin by the key, the value is used to instantiate the plugin.
filter (\%)
Filters defined by this package. It should be in a space-separated key/value pair simiilar to template_plugin, where the key defines the filter name and the value defines the filter class.
config_watcher (\@)
Classes defined by this package that will observe OpenInteract2::Config::Initializer events at server startup. You can use this to create custom, concise directives for your SPOPS and/or Action configurations that get expanded into either more meaningful information or into data that can only be found at runtime. That's a little abstract: see OpenInteract2::Config::Initializer for examples.
description ($*)
Description of this package. Instead of reading a single line we read every line after the 'description' key to the end of the file. Do not put additional configuration keys under 'description', they will not be read.
BUGS
None known.
TO DO
Nothing known.
SEE ALSO
COPYRIGHT
Copyright (c) 2002-2004 Chris Winters. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
AUTHORS
Chris Winters <chris@cwinters.com>