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               MyPackage

multiple 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::MyWiki

Additionally, 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 commodo

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.conf located 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

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
 spops_file  conf/action_one.ini
 spops_file  conf/action_two.ini
 ...
 $config->package_dir( '/home/me/pkg' )
 my $files = $config->get_spops_files();
 # [ 'conf/action_one.ini', 'conf/action_two.ini' ]

Returns: Arrayref of filenames

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.perl. Both perl- and INI-formatted configurations are acceptable.

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.perl. Both perl- and INI-formatted configurations are acceptable.

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.

filter (\%)

Filters defined by this package. It should be in a 'name class' format simiilar to template_plugin.

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

OpenInteract2::Package

Class::Accessor

COPYRIGHT

Copyright (c) 2002-2003 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>

Generated from the OpenInteract 1.99_03 source.