The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
OpenInteract-1.99_00
River stage zero No dependents
/ OpenInteract2::Config::TransferSample

NAME

OpenInteract2::Config::TransferSample - On website install or package creation, transfer and modify sample files

SYNOPSIS

 use OpenInteract2::Config::TransferSample;
 ...
 # $source_dir has a 'FILES' document along with the files to copy
 # (they may be in subdirs of $source_dir also)
 
 my $transfer = OpenInteract2::Config::TransferSample->new( $source_dir );
 
 # Read in the 'FILES' document, replacing all instances of
 $ [% sample %] with 'YourSite' and parsing the file source
 # and destination into arrayrefs.
 
 my %filename_vars = ( sample => 'YourSite' );
 $transfer->read_file_spec( \%filename_vars );
 
 # Copy all files in 'FILES' (as translated by read_file_spec()) from
 # a relative directory in C<$source_dir> to a relative directory
 # C<$dest_dir>, replacing instances of [% sample %] and [% config %]
 # as specified in C<%content_vars>.
 
 my %content_vars => ( sample => 'YourSite',
                       config => 'YourSiteConfig' );
 my $copies = $transfer->transfer( \%content_files, $dest_dir );
 print "The following files were copied:\n  ",
       join( "\n  ", @{ $copies } ), "\n";
 
 # If our filename and content vars don't overlap we can take the
 # shortcut:
 
 my $copies = OpenInteract2::Config::TransferSample
                         ->new( $source_dir )
                         ->run( $dest_dir, \%template_vars );

DESCRIPTION

This class simplifies copying around files when we're creating a new package or website. As a result the non-OI2 developer will probably never use it, or even know it exists.

For the rest of you, this class:

  • Reads in a listing of files (always called 'FILES') to copy. This listing specifies the relative source and destination paths, and can be modified using Template Toolkit keys.

  • Copies files from a source directory tree to a destination directory tree. They do not need to be copied to the same levels of the tree, or even have the same resulting filename.

Format of FILES document

  • Blank lines are skipped

  • Comments are skipped

  • Source path and destination path are separated by a '-->' sequence, with all whitespace on either side being eaten up by the separation.

  • Entries in source and destination paths (directories and filenames) are separated by a single space.

  • If a filename in the source path is preceded by a '*', it is copied as-is and NOT run through the template processor.

Example

(note that this is modified for the example -- there is no website 'widget' directory)

 conf base.conf                 --> conf base.conf
 conf override_spops.ini        --> conf sample-override_spops.ini
 conf server.ini                --> conf server.ini
 
 template *base_main            --> widget global base_main
 template *base_simple          --> widget global base_simple

Given the source directory '/opt/OpenInteract-2.00/sample/website' and the destination directory '/home/httpd/mysite', the following actions will be performed:

  • Copy /opt/OpenInteract-2.00/sample/website/conf/base.conf --> /home/httpd/mysite/conf/base.conf

  • Copy /opt/OpenInteract-2.00/sample/website/conf/override_spops.ini --> /home/httpd/mysite/conf/sample-override_spops.ini

  • Copy /opt/OpenInteract-2.00/sample/website/conf/server.ini --> /home/httpd/mysite/conf/server.ini

  • Copy /opt/OpenInteract-2.00/sample/website/template/base_main --> /home/httpd/mysite/widget/global/base_main, and do not run it through the template processor.

  • Copy /opt/OpenInteract-2.00/sample/website/template/base_simple --> /home/httpd/mysite/widget/global/base_simple, and do not run it through the template processor.

METHODS

new( $source_dir )

Creates a new object. The $source_dir is mandatory, and if it is invalid we throw an exception. We set the source_dir property with it.

run( $dest_dir, [ \%template_vars ] )

Shortcut for read_file_spec() and transfer(). The same set of \%template_vars are applied to each, so be sure you do not use the same key for different purposes in the file listing and file(s) to be copied.

read_file_spec( [ \%template_vars ] )

Reads in the 'FILES' document from $source_dir and stores them in the file_spec property as an arrayref of arrayrefs. Each top-level arrayref holds two arrayrefs. The first is the source file specification, the second is the destination file specification. And each will be an arrayref even if you specify a filename with no path.

Returns: the new contents of the file_spec property.

transfer( $dest_dir, [ \%template_vars ] )

Transfers the files given the specification read from read_file_spec(). (If that hasn't been run prior to this, an exception is thrown.)

Files marked with a '*' in the source specification are not run through the template processor, everything else is. Generally you need to do this if the files you're copying are themselves Template Toolkit templates.

PROPERTIES

source_dir

Source directory of the files to copy, where the FILES specification is located.

file_spec

Results of read_file_spec() operation, also filled after run().

files_copied

Results of transfer() operation, also filled after run().

TO DO

Copy only new files

For files that are marked as copy-only, compare the file size and date. If both are equal, don't do the copy. (Makes it easy for people to see what's new.)

COPYRIGHT

Copyright (c) 2002-2003 Chris Winters. All rights reserved.

AUTHORS

Chris Winters <chris@cwinters.com>