CatalystX::Usul::File::IO - Better IO syntax

0.3.$Revision: 576 $

   use MyExceptionClass;
   use CatalystX::Usul::File::IO;

   sub io {
      my ($self, @rest) = @_;
      my $io = CatalystX::Usul::File::IO->new( @rest );

      $io->exception_class( q(MyExceptionClass) );
      return $io;
   }

   # Read the first line of a file and chomp the result
   my $line = $self->io( q(path_name) )->chomp->getline;

   # Write the line to file set permissions, atomic update and fcntl locking
   $self->io( q(path_name), q(w), q(0644) )->atomic->lock->print( $line );

This is a simplified re-write of IO::All with additional functionality from IO::AtomicFile. Provides the same minimalist API but without the heavy OO overloading. Only has methods for files and directories

If any errors occur the throw method in the exception_class is called. If that is not defined the module throws an Exception::Class of its own

Methods beginning with an _ (underscore) are deemed private and should not be called from outside this package

   my $io = CatalystX::Usul::File::IO->new( $pathname, [ $mode, $perms ] );

Called with either a single hash ref containing a list of key value pairs which are the object's attributes (where name is the pathname) or a list of values which are taken as the pathname, mode and permissions. Returns the value from the call to _init which it makes without any options

   my $io = $self->io( q(path_to_file) )->absolute;

Makes the pathname absolute

   my $lines = $self->io( q(path_to_file) )->all;

Read all the lines from the file. Returns them as a single scalar

   $self->io( q(path_to_file) )->append( $line1, $line2, ... );

Opens the file in append mode and calls print with the passed args

   $self->io( q(path_to_file) )->appendln( $line, $line2, ... );

Opens the file in append mode and calls println with the passed args

   my $io = $self->io( q(path_to_file) )->assert;

Sets the private attribute _assert to true. Causes the open methods to create the path to the directory before the file/directory is opened

   $self->io( q(path_to_file) )->assert_dirpath;

Create the given directory if it doesn't already exist

   $self->io( q(path_to_file) )->assert_filepath;

Calls assert_dirpath on the directory part of the full pathname

   my $io = $self->io( q(path_to_file) )->assert_open( $mode, $perms );

Calls file to default the type if its not already set and then calls open passing in the optional arguments

   my $io = $self->io( q(path_to_file) )->atomic;

Implements atomic file updates by writing to a temporary file and then renaming it on closure. This method stores the temporary pathname in the _atomic attribute

   $dirname = $self->io( q(path_to_file) )->basename( @suffixes );

Returns the File::Basename basename of the passed path

   my $io = $self->io( q(path_to_file) )->binary;

Sets binary mode

   my $io = $self->io( q(path_to_file) )->binmode( $layer );

Sets binmode to the given layer

The internal buffer used by read and write

   my $io = $self->io( q(path_to_file) )->chomp;

Causes input lines to be chomped when getline or getlines are called

Set the contents of the internal buffer to the null string

   $io->close;

Close the file or directory handle depending on type

Closes the open directory handle.

If the temporary atomic file exists, renames it to the original filename. Unlocks the file if it was locked. Closes the file handle

Deletes the atomic update temporary file if it exists. Then calls _close_file

   $self->io( $tempdir )->delete_tmp_files( $template );

Delete temporary files for this process (temporary file names include the process id). Temporary files are stored in the $tempdir. Can override the template filename pattern if required

If this is an atomic file update calls the delete method. If the object is still open it calls the close method

Initialises the current object as a directory

Returns the pattern that will match against the current or parent directory

   $dirname = $self->io( q(path_to_file) )->dirname;

Returns the File::Basename dirname of the passed path

Returns true if the pathname exists and is zero bytes in size

   my $io = $self->io( q(path_to_file) )->encoding( $encoding );

Apply the given encoding to the open file handle and store it on the _encoding attribute

Tests to see if the open file handle is showing an error and if it is it throws an eIOError

Returns true if the pathname exists

Initializes the current object as a file

Returns the filename part of pathname

Returns the directory part of pathname

Asserts the file open for reading. Get one line from the file handle. Chomp the line if the _chomp attribute is true. Check for errors. Close the file if the autoclose attribute is true and end of file has been read past

Like getline but calls getlines on the file handle and returns an array of lines

Sets default values for some attributes, takes two optional arguments; type and name

atomic_pref

Defaults to B_. It is prepended to the filename to create a temporary file for atomic updates

autoclose

Defaults to true. Attempts to read past end of file will cause the object to be closed

block_size

Defaults to 1024. The default block size used by the read method

exception_class

Defaults to undef. Can be set to the name of an class that provides the throw method

io_handle

Defaults to undef. This is set when the object is actually opened

is_open

Defaults to false. Set to true when the object is opened

name

Defaults to undef. This must be set in the call to the constructor or soon after

type

Defaults to false. Set by the dir and file methods to dir and file respectively. The dir method is called by the next method. The file method is called by the assert_open method if the type attribute is false

Return true if the pathname is absolute

   my $bool = $self->io( q(path_to_file) )->is_dir;

Tests to see if the IO object is a directory

   my $bool = $self->io( q(path_to_file) )->is_file;

Tests to see if the IO object is a file

Returns the length of the internal buffer

   my $io = $self->io( q(path_to_file) )->lock;

Causes _open_file to set a shared flock if its a read an exclusive flock for any other mode

Calls dir if the type is not already set. Asserts the directory open for reading and then calls read_dir to get the first/next entry. It returns an IO object for that entry

   my $io = $self->io( q(path_to_file) )->open( $mode, $perms );

Calls either _open_dir or _open_file depending on type. You do not usually need to call this method directly. It is called as required by assert_open

If the _assert attribute is true calls assert_dirpath to create the directory path if it does not exist. Opens the directory and stores the handle on the io_handle attribute

Opens the pathname with the given mode and permissions. Calls assert_filepath if assert is true. Mode defaults to the mode attribute value which defaults to r. Permissions defaults to the _perms attribute value. Throws eCannotOpen on error. If the open succeeds set_lock and set_binmode are called

   my $pathname = $io->pathname( $pathname );

Sets and returns then name attribute

   my $io = $self->io( q(path_to_file) )->perms( $perms );

Stores the given permissions on the _perms attribute

Asserts that the file is open for writing and then prints passed list of args to the open file handle. Throws ePrintError if the print statement fails

   $self->io( q(path_to_file) )->println( $line1, $line2, ... );

Calls print appending a newline to each of the passed list args that doesn't already have one

   my $bytes_read = $self->io( q(path_to_file) )->read( $buffer, $length );

Asserts that the pathname is open for reading then calls read on the open file handle. If called with args then these are passed to the read. If called with no args then the internal buffer is used instead. Returns the number of bytes read

Asserts that the file is open for reading. If called in an array context returns a list of all the entries in the directory. If called in a scalar context returns the first/next entry in the directory

Sets the currently selected binmode on the open file handle

Calls flock on the open file handle

In a scalar context calls all and returns its value. In an array context returns the list created by splitting the scalar return value on the system record separator. Will chomp each line if required

Returns a hash of the values returned by a stat call on the pathname

Create a randomly named temporary file in the name directory. The file name is prefixed with the creating processes id and the temporary directory defaults to /tmp

Exposes the throw method in the class exception class

Create a zero length file if one does not already exist with given file system permissions which default to 0664 octal. If the file already exists update it's last modified datetime stamp

Calls flock on the open file handle with the LOCK_UN option to release the Fcntl lock if one was set. Called by the file_close method

Sets the current encoding to utf8

   my $bytes_written = $self->io( q(pathname) )->write( $buffer, $length );

Asserts that the file is open for writing then write the $length bytes from $buffer. Checks for errors and returns the number of bytes written. If $buffer and $length are omitted the internal buffer is used. In this case the buffer contents are nulled out after the write

None

None

Class::Accessor::Fast

Exception::Class

There are no known incompatibilities in this module

There are no known bugs in this module. Please report problems to the address below. Patches are welcome

Peter Flanigan, <Support at RoxSoft.co.uk>

Copyright (c) 2008 Peter Flanigan. All rights reserved

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic

This program is distributed in the hope that it will be useful, but WITHOUT WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE