File Coverage

blib/lib/Test/Inline/IO/File.pm

Criterion	Covered	Total	%
statement	55	57	96.4
branch	18	28	64.2
condition	4	6	66.6
subroutine	13	14	92.8
pod	7	9	77.7
total	97	114	85.0

package Test::Inline::IO::File;
# ABSTRACT: Test::Inline Local Filesystem IO Handler

#pod =pod
#pod
#pod =head1 DESCRIPTION
#pod
#pod B is the default IO handler for L.
#pod
#pod L 2.0 was conceived in an enterprise setting, and retains
#pod the flexibilty, power, and bulk that this created, although for most
#pod users the power and complexity that is available is largely hidden away
#pod under multiple layers of sensible defaults.
#pod
#pod The intent with the C and C parameters is to
#pod allow L to be able to pull source data from anywhere, and
#pod write the resulting test scripts to anywhere.
#pod
#pod Until a more powerful pure-OO file-system API comes along, this module
#pod serves as a minimalist implementation of the subset of functionality
#pod that L needs in order to work.
#pod
#pod An alternative IO Handler class need not subclass this one (although it
#pod is recommended), merely implement the same interface, taking whatever
#pod alternative arguments to the C constructor that it wishes.
#pod
#pod All methods in this class are provided with unix-style paths, and should do
#pod the translating to the underlying filesystem themselves if required.
#pod
#pod =head1 METHODS
#pod
#pod =cut

use strict;
use File::Spec   ();
use File::chmod  ();
use File::Remove ();

our $VERSION = '2.214';





#####################################################################
# Constructor and Accessors

#pod =pod
#pod
#pod =head2 new
#pod
#pod   # Simplified usage
#pod   $io_handler = Test::Inline::IO::File->new( $path );
#pod
#pod   # Full key/value usage
#pod   $io_handler = Test::Inline::IO::File->new(
#pod           path     => $path,
#pod           readonly => 1,
#pod   );
#pod
#pod The C constructor takes a root path on the local filesystem
#pod and returns a new C object to that
#pod location.
#pod
#pod =cut

sub new {
	my $class  = shift;
	my @params = @_;
	if ( @params < 2 ) {
		my $path  = defined $_[0] ? shift : File::Spec->curdir;
		@params = ( path => $path );
	}

	# Create the object
	my $self = bless { @params }, $class;

	# Apply defaults
	$self->{readonly} = !! $self->{readonly};

	return $self;
}

sub path {
	$_[0]->{path};
}

sub readonly {
	$_[0]->{readonly};
}

# Resolve the full path for any file
sub _path {
	my $self = shift;
	my $file = defined $_[0] ? shift : return undef;
	File::Spec->catfile( $self->{path}, $file );
}





#####################################################################
# Filesystem API

#pod =pod
#pod
#pod =head2 exists_file $file
#pod
#pod The C method checks to see if a particular file currently
#pod exists in the input handler.
#pod
#pod Returns true if it exists, or false if not.
#pod
#pod =cut

sub exists_file {
	my $self = shift;
	my $file = $self->_path(shift) or return undef;
	!! -f $file;
}

#pod =pod
#pod
#pod =head2 exists_dir $dir
#pod
#pod The C method checks to see if a particular directory currently
#pod exists in the input handler.
#pod
#pod Returns true if it exists, or false if not.
#pod
#pod =cut

sub exists_dir {
	my $self = shift;
	my $dir = $self->_path(shift) or return undef;
	!! -d $dir;
}

#pod =pod
#pod
#pod =head2 read $file
#pod
#pod The C method reads in the entire contents of a single file,
#pod returning it as a reference to a SCALAR. It also localises the
#pod newlines as it does this, so files from different operating
#pod systems should read as you expect.
#pod
#pod Returns a SCALAR reference, or C on error.
#pod
#pod =cut

sub read {
	my $self    = shift;
	my $file    = $self->_path(shift) or return undef;
	require File::Flat;
	my $content = File::Flat->slurp($file) or return undef;
	$$content =~ s/\015{1,2}\012|\015|\012/\n/g;
	$content;
}

#pod =pod
#pod
#pod =head2 write $file, $content
#pod
#pod The C method writes a string to a file in one hit, creating
#pod it and it's path if needed.
#pod
#pod =cut

sub write {
	my $self = shift;
	my $file = $self->_path(shift) or return undef;
	if ( -f $file and ! -w $file ) {
		File::Remove::remove($file) or return undef;

	}
	require File::Flat;
	my $rv = File::Flat->write( $file, @_ );
	if ( $rv and $self->readonly ) {
		File::chmod::symchmod('a-w', $file);
	}
	return $rv;
}

#pod =pod
#pod
#pod =head2 class_file $class
#pod
#pod Assuming your input FileHandler is pointing at the root directory
#pod of a lib path (meaning that My::Module will be located at My/Module.pm
#pod within it) the C method will take a class name, and check to see
#pod if the file for that class exists in the FileHandler.
#pod
#pod Returns a reference to an ARRAY containing the filename if it exists,
#pod or C on error.
#pod
#pod =cut

sub class_file {
	my $self   = shift;
	my $_class = defined $_[0] ? shift : return undef;
	my $file   = File::Spec->catfile( split /(?:::|')/, $_class ) . '.pm';
	$self->exists_file($file) and [ $file ];
}

#pod =pod
#pod
#pod =head2 find $class
#pod
#pod The C method takes as argument a directory root class, and then scans within
#pod the input FileHandler to find all files contained in that class or any
#pod other classes under it's namespace.
#pod
#pod Returns a reference to an ARRAY containing all the files within the class,
#pod or C on error.
#pod
#pod =cut

sub find {
	my $self  = shift;
	my $dir   = $self->exists_dir($_[0]) ? shift : return undef;

	# Search within the path
	require File::Find::Rule;
	my @files = File::Find::Rule->file
	                            ->name('*.pm')
	                            ->relative
	                            ->in( $self->_path($dir) );
	@files = map { File::Spec->catfile( $dir, $_ ) } sort @files;
	return \@files;
}

1;

__END__