NAME
    File::Flat - Implements a flat filesystem

SYNOPSIS
DESCRIPTION
    File::Flat implements a flat filesystem. A flat filesystem is a
    filesystem in which directories do not exist. It provides an abstraction
    over any normal filesystem which makes it appear as if directories do
    not exist. In effect, it will automatically create directories as
    needed. This is create for things like install scripts and such, as you
    never need to worry about the existance of directories, just write to a
    file, no matter where it is.

  Comprehensive Implementation
    The implementation of File::Flat is extremely comprehensive in scope. It
    has methods for all stardard file interaction taks, the -X series of
    tests, and some other things, such as slurp.

    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
    File::Flat tries to use more task orientated modules wherever possible.
    This includes the use of File::Copy, File::NCopy, File::Remove and
    others. These are mostly loaded on-demand.

  Non-Unix platforms
    File::Flat itself should be completely capable of handling any platform
    through it's exclusive use of File::Spec.

    However, some of the modules it relies upon, particularly File::Remove,
    and possible File::NCopy are not File::Spec happy yet. Results may wary
    on non Unix platforms. Users of non-Unix platforms are invited to patch
    File::Remove ( and possibly File::NCopy ) and File::Flat should work.

METHODS
  exists( filename )
    Tests for the existance of the file. This is an exact duplicate of the
    -e function.

  isaFile( filename )
    Tests whether "filename" is a file. This is an exact duplicate of the -f
    function.

  isaDirectory( filename )
    Test whether "filename" is a directory. This is an exact duplicate of
    the -d function.

  canRead( filename )
    Does the file or directory exist, and can we read from it.

  canWrite( filename )
    Does the file or directory exist, and can we write to it OR can we
    create the file or directory.

  canReadWrite( filename )
    Does a file or directory exist, and can we both read and write it.

  canExecute( filename )
    Does a file or directory exist, and can we execute it.

  canOpen( filename )
    Is this something we can open a filehandle to. Returns true if filename
    exists, is a file, and we can read from it.

  canRemove( filename )
    Can we remove the file or directory.

  isaText( filename )
    Does the file "filename" exist, and is it a text file.

  isaBinary( filename )
    Does the file "filename" exist, and is it a binary file.

  fileSize( filename )
    If the file exists, returns it's size in bytes. Returns undef if the
    file does not exist.

  open( filename ) OR open( mode, filename )
    Rough analogue of the open function, but creates directories on demand
    as needed. Supports most of the normal options to the normal open
    function.

    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 )
    The same as File::Flat->open( '<', 'filename' )

  getWriteHandle( filename )
    The same as File::Flat->open( '>', 'filename' )

  getAppendHandle( filename )
    The same as File::Flat->open( '>>', 'filename' )

  getReadWriteHandle( filename )
    The same as File::Flat->open( '+<', 'filename' )

  read( filename )
    Opens and reads in an entire file, chomping as needed.

    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 )
    Slurp 'slurp's a file in. This attempt to read the entire file into a
    variable in as quick and memory efficient method as possible.

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

  write( filename, scalar | scalar_ref | array_ref )
    The "write" method is the main method for writing content to a file. It
    takes two arguments, the location to write to, and the content to write,
    in several forms.

    If the file already exists, it will be clobered 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, scalar | scalar_ref | array_ref )
    This method is the same as "write", except that it appends to the end of
    an existing file ( or creates the file as needed ).

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

  overwrite( filename, scalar | scalar_ref | array_ref )
    Performs an atomic write over a file. It does this by writing to a
    temporary file, and moving the completed file over the top of the
    existing file ( or creating a new file as needed ). When writing to a
    file that is on the same partition as /tmp, this should always be
    atomic.

    This method otherwise acts the same as "write".

  copy( source, target )
    The "copy" method attempts to copy a file or directory from the source
    to the target. New directories to contain the target will be created as
    needed.

    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 )
    The "move" method follows the conventions of the 'mv' command, with the
    exception that the directories containing target will of course be
    created on demand.

  remove( filename )
    The "remove" method will remove a file, or recursively remove a
    directory.

  truncate( filename [, size ] )
    The "truncate" method will truncate an existing file to partular size. A
    size of 0 ( zero ) is used if no size is provided. If the file does not
    exists, it will be created, and set to 0. Attempting to truncate a
    directory will fail.

    Returns true on success, or undef on error.

  makeDirectory( directory [, mode ] )
    In the case where you do actually have to create a directory only, the
    "makeDirectory" method can be used to create a directory or any depth.

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

    Returns true on success, returns undef on error.

SUPPORT
    Contact the author

TO DO
      - Needs to be made more efficient.
      - File::Spec::Object needs to be written, and File::Flat ported to use it
      - Function interface to be written, to provide importable functions.

AUTHORS
            Adam Kennedy ( maintainer )
            cpan@ali.as
            http://ali.as/

SEE ALSO
    File::Spec

COPYRIGHT
    Copyright (c) 2002 Adam Kennedy. All rights reserved. This program is
    free software; you can redistribute it and/or modify it under the same
    terms as Perl itself.

    The full text of the license can be found in the LICENSE file included
    with this module.

