NAME

OpenInteract2::Config::Readonly - Simple read/write for readonly files

SYNOPSIS

 use OpenInteract2::Config::Readonly;
 
 # See if some files are writeable in $dir
 
 my @files_to_write = ( 'blah.html', 'bleh.txt' );
 my $read_only = OpenInteract2::Config::Readonly->new( $dir );
 foreach my $file ( @files_to_write ) {
     print "Writeable? ", $read_only->is_writeable( $file );
 }
 
 # See if a single file is writeable
 
 my $original_path = '/path/to/distribution/foo.html';
 my $can_write = OpenInteract2::Config::Readonly
    ->new( $dir )
    ->is_writeable( $original_path );
 if ( $can_write ) {
     cp( $original_path,
         File::Spec->catfile( $dir, basename( $original_path ) ) );
 }
 

 # Write a set of readonly files...
 
 OpenInteract2::Config::Readonly
     ->new( $dir )
     ->write_config( [ 'file1', 'file2' ] );
 
 # Write a set of readonly files with a comment...
 
 OpenInteract2::Config::Readonly
     ->new( $dir )
     ->write_config( [ 'file1', 'file2' ],
                     'OI will not overwrite these files' );

DESCRIPTION

Simple module to read/write configuration that determines which files in a directory OpenInteract2 should not overwrite.

METHODS

Note: We only read, store and check against bare filenames from the readonly config -- that is, the result of a File::Basename basename call.

new( $directory )

Constructor. Throws exception if $directory is invalid.

get_readonly_files()

Returns: arrayref of readonly files in the configured directory.

is_writeable( $file )

Returns: true if $file is writeable in the configured directory, false if not.

get_all_writeable_files()

Returns: arrayref of all writeable files in the configured directory.

write_readonly_files( \@files, [ $comment ] )

Write a new readonly configuration file (typically .no_overwrite) to the configured directory. All filenames in \@files will be written to the file, as with the $comment if given.

Returns: full path to file written.

is_writeable_file( \@readonly_filenames | $directory, $filename )

Returns true if file $filename is writeable in $directory or if it is not found among \@readonly_filenames. We do a basename() against $filename before doing the check.

Examples:

 # These all return true
 OpenInteract2::Config::Readonly->is_writeable_file(
                    [ 'index.html' ], 'foo.html' );
 OpenInteract2::Config::Readonly->is_writeable_file(
                    [ 'index.html' ], 'INDEX.HTML' );
 OpenInteract2::Config::Readonly->is_writeable_file(
                    [ 'index.html' ], '/path/to/index.htm' );

 # These all return false
 OpenInteract2::Config::Readonly->is_writeable_file(
                    [ 'index.html' ], 'index.html' );
 OpenInteract2::Config::Readonly->is_writeable_file(
                    [ 'index.html' ], '/path/to/my/index.html' );

get_writeable_files( \@readonly_filenames | $directory, \@filenames )

Returns an arrayref of all writeable files from \@filenames as compared against the config in $directory or the readonly filenames in \@readonly_filenames. The filenames returned are whatever was stored in \@filenames rather than the basename.

Examples:

 my $files = OpenInteract2::Config::Readonly->get_writeable_files(
                    [ 'index.html' ], [ '/path/to/foo.html' ] );
 # $files = [ '/path/to/foo.html' ]
 
 my $files = OpenInteract2::Config::Readonly->get_writeable_files(
                    [ 'index.html' ], [ 'INDEX.HTML', '/path/to/README.txt' ] );
 # $files = [ 'INDEX.HTML', '/path/to/README.txt' ]
 
 my $files = OpenInteract2::Config::Readonly->get_writeable_files(
                    [ 'index.html' ], [ '/path/to/index.htm', '/path/to/index.html' ] );
 # $files = [ '/path/to/index.htm' ]

read_config( $dir )

Reads the file in $dir for files not to overwrite. This method should never die or throw an exception -- if there is an error reading the file or if the file does not exist, it simply returns an empty arrayref.

Returns: arrayref of filenames relative to $dir.

write_config( $dir, \@files_to_write | \%write_info )

Writes filenames to a file in $dir. The \%write_info parameters can be either an arrayref of filenames to write or a hashref with the following keys:

file: Arrayref of filenames to write
comment: Message to write as a comment.

No path information is written to the file, only the base filename.

Returns: full path to file written. If the file cannot be written, it will throw an exception. If there are no files passed in to write, it returns nothing.

BUGS

None known.

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>

CPAN RT