Comprehensive Implementation

All methods are statically called, for example, to write some stuff to a file.

  use File::Flat;
  File::Flat->write( 'filename', 'file contents' );

Use of other modules

Pruning and $AUTO_PRUNE

By default File::Flat does not prune, and pruning must be done explicitly, via either the "prune" in File::Flat method, or by setting the second argument to the "remove" in File::Flat method to be true.

However by setting the global $AUTO_PRUNE variable to true, File::Flat will automatically prune directories at all times. You should generally use this locally, such as in the following example.

  #!/usr/bin/perl
  
  use strict;
  use File::Flat;
  
  delete_files(@ARGV);
  exit();
  
  # Recursively delete and prune all files provided on the command line
  sub delete_files {
        local $File::Flat::AUTO_PRUNE = 1;
        foreach my $file ( @_ ) {
                File::Flat->remove( $file ) or die "Failed to delete $file";
        }
  }

Non-Unix platforms

exists $filename

isaFile $filename

isaDirectory $filename

canRead $filename

canWrite $filename

canReadWrite $filename

canExecute $filename

canOpen $filename

canRemove $filename

isaText $filename

isaBinary $filename

fileSize $filename

open [ $mode, ] $filename

In the single argument form, it takes modes in the form [mode]filename. For example, all the following are valid.

  File::Flat->open( 'filename' );
  File::Flat->open( '<filename' );
  File::Flat->open( '>filename' );
  File::Flat->open( '>>filename' );
  File::Flat->open( '+<filename' );

In the two argument form, it takes the following

  File::Flat->open( '<', 'filename' );
  File::Flat->open( '>', 'filename' );
  File::Flat->open( '>>', 'filename' );
  File::Flat->open( '+<', 'filename' );

It does not support the more esoteric forms of open, such us opening to a pipe or other such things.

On successfully opening the file, it returns it as an IO::File object. Returns undef on error.

getReadHandle $filename

getWriteHandle $filename

getAppendHandle $filename

getReadWriteHandle $filename

read $filename

In array context, it returns an array containing each line of the file. In scalar context, it returns a reference to an array containing each line of the file. It returns undef on error.

slurp $filename

On success, returns a reference to a scalar, containing the entire file. Returns undef on error.

write $filename, ( $content | \$content | \@content )

If the file already exists, it will be clobbered before writing starts. If the file doesn't exists, the file and any directories will be created as needed.

Content can be provided in three forms. The contents of a scalar argument will be written directly to the file. You can optionally pass a reference to the scalar. This is recommended when the file size is bigger than a few thousand characters, is it does not duplicate the file contents in memory. Alternatively, you can pass the content as a reference to an array containing the contents. To ensure uniformity, "write" will add a newline to each line, replacing any existing newline as needed.

Returns true on success, and undef on error.

append $filename, ( $content | \$content | \@content )

This is the method you should be using to write to log files, etc.

overwrite $filename, ( $content | \$content | \@content )

This method otherwise acts the same as "write".

copy $source, $target

For example "<File::Flat-"( './this', './a/b/c/d/that' );>> will create the directory structure required as needed.

In the file copy case, if the target already exists, and is a writable file, we replace the existing file, retaining file mode and owners. If the target is a directory, we do NOT copy into that directory, unlike with the 'cp' unix command. And error is instead returned.

"copy" will also do limited recursive copying or directories. If source is a directory, and target does not exists, a recursive copy of source will be made to target. If target already exists ( file or directory ), "copy" will returns with an error.

move $source, $target

remove $filename [, $prune ]

If a second (true) argument is provided, then once the file or directory has been deleted, the method will the automatically work its way upwards pruning (deleting) empty and thus presumably useless directories.

Returns true if the deletion (and pruning if requested) was a success, or "undef" otherwise.

prune $filename

For anyone familiar with CVS, it is similar to the "update -P" flag.

Returns true, or "undef" on error.

truncate $filename [, $size ]

Returns true on success, or undef on error.

makeDirectory $directory [, mode ]

An optional file mode ( default 0755 ) can be provided.

Returns true on success, returns undef on error.