The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
OpenInteract-1.99_06
River stage zero No dependents
1 ++
/ 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>