NAME

OpenInteract2::Package - Perform actions on individual packages

SYNOPSIS

 # Programmatically install a package you've downloaded (for the real
 # world, see C<oi2_manage> and/or
 # L<OpenInteract2::Manage::Website::InstallPackage|OpenInteract2::Manage::Website::InstallPackage).
 # You get back a reference to the installed package.
  
 my $package = OpenInteract2::Package->install(
                         { package_file => '/home/perlguy/trivia-game-1.07.zip',
                           website_dir  => '/home/httpd/mysite' });
  
 # Create a new skeleton package for development (for the real world,
 # see C<oi2_manage>). You get back a reference to the newly created
 # package.
 
 my $package = OpenInteract2::Package->create_skeleton(
                         { name       => 'mynewpackage',
                           sample_dir => '/usr/local/src/OpenInteract-2.00/sample/package' });
 
 # Export package in the given directory for distribution
 
 my $package = OpenInteract2::Package->new({
                    directory => '/home/cwinters/pkg/mynewpackage' });
 my $export_filename = eval { $package->export };
 if ( $@ ) {
     print "Export failed: $@";
 }
 else {
     print "Exported successfully to file '$export_filename'";
 }
 
 # Read information about a package distribution
 
 my $package = OpenInteract2::Package->new({
                    package_file => '/home/cwinters/pkg/mynewpackage-1.02.zip' });
 my $config = $package->config;
 print "Package ", $package->name, " ", $package->version, "\n",
       "Author ", join( ", ", @{ $config->author } ), "\n";
 my $files = $package->get_files;
 foreach my $filename ( @{ $files } ) {
     print "   File - $filename\n";
 }
 
 # Check validity of a package
 
 my $package = OpenInteract2::Package->new({
                    directory => '/home/cwinters/pkg/mynewpackage' });
 my @status = $package->check;
 foreach my $status ( @status ) {
    print "Action: $status->{action}   OK? $status->{is_ok}\n";
 }
 
 # Remove package
 
 my $package = OpenInteract2::Package->new({
                    directory => '/home/cwinters/pkg/mynewpackage' });
 $package->remove;
 
 # Get an object representing the changelog of a package and print out
 # the last version, date and message
 
 my $changes = $package->get_changes;
 my ( $latest_change ) = $changes->latest(1);
 print "$latest_change->{version}  on  $latest_change->{date}\n",
       "$latest_change->{message}\n";

DESCRIPTION

This module defines actions to be performed on individual packages. The first argument for many of the methods that

METHODS

Class Methods

new( \%params )

Create a new package object. You can specify an archived package (using package_file) and be able to find out information about the package, or you can specify a directory (using directory) of an opened package.

If package_file, directory or a valid package_config are passed in we read the package information immediately.

Parameters:

package_file: Specify the package file to explore. An example is news-2.11.zip, although it's smart to specify the full path with the file.

If the specified file does not exist we throw an exception.
directory: A package directory to explore. It's smart to specify the full path with the directory.

If the specified directory does not exist we throw an exception.
package_config: A OpenInteract2::Config::Package object. We pull the package directory (package_dir property) from it.
repository: The OpenInteract2::Repository that this package belongs to.

install( \%params )

Installs the file specified in the parameter filename to the website specified in the parameter website_dir or retrieved from the OpenInteract2::Repository object specified in repository.

If the package already exists in the website repository we first remove its entry (leaving the old directory). We then unpack the given package file into the website, copy over any global files (those in html/ and widget/), and then create an entry in the website repository for the new package.

Paramters:

filename: A valid package file.
website_dir: Full path to a website we will install the package to.
repository: A OpenInteract2::Repository from which we can take the website directory.

Returns: package created from the new directory. Any failures throw an exception.

create_skeleton( \%params )

Creates a new package skeleton in the current directory. This is the recommended way to start developing a new OI2 package, similar to creating a new perl module using h2xs.

Parameters:

name: Name of your package. It should be all alphanumberic lower-case with no spaces. If not an exception is thrown.
sample_dir: The directory from where we pull our skeleton files from. This is normally in the OpenInteract source distribution directory, although you may elect to copy these files elsewhere so developers can have access.
source_dir: You can use this instead of sample_dir as long as the directory 'sample/package' exists underneath. (It should unless you have mucked with the source distribution.)

Returns: package created from the new directory. Any failures throw an exception.

generate_distribution_digest( $package_file )

Creates an MD5 digest of the contents in $package_file. (See Digest::MD5 for what this means.)

parse_full_name( $full_name )

Returns a two-item list of the package name and version found in $full_name.

Object Methods

full_name()

Returns a string with the package name and version:

 $package->name( 'foo' );
 $package->version( '1.52' );
 print "Name: ", $package->full_name;
 # Name: foo-1.52

get_files( [ $force_read ] )

Reads list of files from package MANIFEST file. These results are cached in the object -- if you want to force a read pass a true value for $force_read.

Returns: arrayref of files in MANIFEST.

export( \%params )

Exports a package to a package distribution file. The name of the file is always:

 {package}-{version}.zip

If a file already exists with that name in the current directory, the process will throw an exception. Similarly, if a directory of the name:

 {package}-{version}/

already exists in the current directory an exception will be thrown.

Returns: the full path to the distribution file created.

check( \%params )

Checks the validity of a package. We perform the following checks:

Does the changelog exist? (This is not a fatal error, but you will get a virtual raspberry if you do not have one.)
Are all the files in MANIFEST in the package directory?
Are there any extra files in the package directory that are not in MANIFEST?
Are all the configuration INI files (action.ini, spops.ini) parseable?
Are all the perl modules includable? (A "perl module" includes any file ending in .pm.)
Are all the data files valid Perl data structures? (This includes all files in data/ ending in .dat.)
Are the Template Toolkit templates parseable? (This includes all files ending in .tmpl in template/ and all files in widget/.) The implementation of parseability can probably be improved, since we have to ignore certain errors caused by commonly available templates not being available since the template is not deployed in the full OI2 environment.

Returns a list of hashrefs indicating the status of the various package elements. Each hashref includes (at a minimum): 'is_ok', 'message' and 'action'. Some also include 'filename' where appropriate.

remove( [ $repository ] )

Removes a package from its repository. This may fail if you do not have a repository set in the package object or if you do not pass $repository into the method. It may also fail for reasons given in OpenInteract2::Repository.

Returns: array of status hashrefs, with a single member.

get_spops_files()

Retrieves SPOPS configuration files from the package. You can either specify the files yourself in the package configuration (see OpenInteract2::Config::Package), or this routine will pick up all files that match ^conf/spops.*\.ini$.

Returns: arrayref of relative SPOPS configuration files.

get_action_files()

Retrieves action configuration files from the package. You can either specify the files yourself in the package configuration (see OpenInteract2::Config::Package), or this routine will pick up all files that match ^conf/action.*\.ini$.

Returns: arrayref of relative action configuration files.

get_doc_files()

Retrieves all documentation from the package. This includes all files in doc/.

Returns: arrayref of relative documentation files.

get_message_files()

Retrieves message files from the package -- each one specifies i18n keys and values for use in templates and elsewhere. You can either specify the files yourself in the package configuration (see OpenInteract2::Config::Package), or this routine will pick up all files that match ^msg/*\.msg$.

Returns: arrayref of relative message files.

get_changes()

Returns the OpenInteract2::Config::PackageChanges object associated with this package.

find_file( @relative_files )

Finds the a file from the list @relative_files.

Returns: the full path to the first existing filename; if no file is found, undef.

read_file( $relative_file )

Slurps the contents of $relative_file into a variable and returns it. Finds full path to $relative_file using find_file().

Returns: contents of $relative_file; if $relative_file does not exist, returns undef. If there is an error reading $relative_file, throws exception.

PROPERTIES

name: Name of this package.

version: Version of this package.

package_file: The distribution (zip) file this package was read from.

directory: The directory this package was read from. Hopefully fully-qualified... (TODO: shouldn't it always be?)

repository: The OpenInteract2::Repository associated with this package.

installed_date: Date the package was installed. This is typically stored in the repository associated with the package.

config: The OpenInteract2::Config::Package object associated with this package.

TO DO

Automatically create objects for HTML pages

NEW WAY:

In the relevant OI2::Manage class, just run the page scanner after a package has been installed.

OLD WAY:

For each file copied over to the /html directory, create a 'page' object in the system for it. Note that we might have to hook this up with the system that ensures we do not overwrite certain files. So we might need to either remove it from the _copy_package_files() routine, or add an argument to that routine that lets us pass in a coderef to execute with every item copied over.

ACK -- here is the problem. We do not know if we can even create an $R yet, because (1) the base_page package might not have even been installed yet (when creating a website) and (2) the user has not yet configured the database (etc.)

We can get around this whenever we rewrite Package/PackageRepository/oi_manage, but until then we will tell people to include the relevant data inserts with packages that include HTML documents.

Until then, here is what this might look like :-)

 # Now do the HTML files, but also create records for each of the HTML
 # files in the 'page' table

   my $copied = $class->_copy_package_files( "$info->{website_dir}/html",
                                             'html',
                                             $pkg_file_list );
   my @html_locations = map { s/^html//; $_ } @{ $copied };
   foreach my $location ( @html_locations ) {
       my $page = $R->page->fetch( $location, { skip_security => 1 } );
       next if ( $page );
       eval {
           $R->page->new({ location => $location,
                                      ... })
                   ->save({ skip_security => 1 });
       };
   }

COPYRIGHT

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>

To install OpenInteract2::URL, copy and paste the appropriate command in to your terminal.

cpanm

cpanm OpenInteract2::URL

CPAN shell

perl -MCPAN -e shell
install OpenInteract2::URL

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)