NAME
OpenInteract2::Config::Package - Read, write and check package config files
SYNOPSIS
# Sample package file
[package]
name = MyPackage
version = 1.53
author = Steve <steve@dude.com>
author = Chuck <chuck@guy.com>
url = http://www.oirox.com/
description = This package rocks!
[package template_plugin]
TestPlugin = OpenInteract2::Plugin::Test
[package observer]
mywiki = OpenInteract2::Filter::MyWiki
# 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->observer({ mywiki => 'OpenInteract2::Filter::MyWiki' });
$c->description( 'This package rocks!' );
# Set the filename to save the config to and save it
$c->filename( 'mydir/pkg/MyPackage/package.ini' );
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.ini'
});
# Read the content yourself and pass it in
my $ini_text = _read_ini_file( '...' );
my $c = OpenInteract2::Config::Package->new({
content => $ini_text
});
DESCRIPTION
This class implements read/write access to a package configuration file. As all other configurations in OI2 this uses the modified INI format.
METHODS
Class Methods
new( \%params )
Creates a new configuration object from \%params
:
filename
: Read the configuration from this filedirectory
: Read the configuration from the filepackage.ini
located in this directory. (Also:package_dir
)content
: Use the text in this value as the package configuration.
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.ini
.
Examples:
my $filename = OpenInteract2::Config::Package->create_filename( '/home/httpd/mysite/pkg/foo' );
# $filename: '/home/httpd/mysite/pkg/foo/package.ini'
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
author_names()
Returns a list of all author names pulled out of the 'author' property.
author_emails()
Returns a list of all author emails pulled out of the 'author' property.
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(s) with SPOPS objects defined in this package.
action_file (\@)
File(s) with the actions defined in this package.
message_file (\@)
File(s) 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.
observers (\%)
Observers (commonly in the guise of filters) defined by this package. It should be in a space-separated key/value pair simiilar to template_plugin
, where the key defines the observer name and the value defines the observer 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 may be a little abstract: see OpenInteract2::Config::Initializer for examples.
description
($*)
Description of this package.
SEE ALSO
COPYRIGHT
Copyright (c) 2002-2005 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>