/ 
OpenInteract-1.99_06
River stage zero No dependents
/ OpenInteract2::Config::Package

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 file

  • directory: Read the configuration from the file package.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

OpenInteract2::Package

Class::Accessor

OpenInteract2::Config::Ini

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>