NAME

File::System::Table - A file system implementation for mounting other modules

SYNOPSIS

  use File::System;

  my $root = File::System->new('Table',
      '/'    => [ 'Real', root => '/home/foo' ],
      '/tmp' => [ 'Real', root => '/tmp' ],
      '/bin' => [ 'Real', root => '/bin' ],
  );

  my $file = $root->create('/tmp/dude', 'f');
  my $fh = $file->open('w');
  print $fh "Party on! Excellent!\n";
  close $fh;

DESCRIPTION

This file system module allows for the creation of a tabular virtual file system. Each File::System::Table is created with a root file system (at least) and then can have zero or more mounts to allow for more complicated file system handling. All mount points can be changed after the initial file system creation (except for the root, which is static).

MOUNT POINTS

There are a few rules regarding mount points that this system requires. This should be familiar to anyone familiar with Unix file system mounting:

1. The root mount point (/) is special and static. It cannot be unmounted except by deleting the file system object altogether.
2. A specific mount point cannot be mounted more than once. I.e., the following code would fail:

     $root = File::System->new('Table', '/' => [ 'Real' ]);
     $root->mount('/tmp' => [ 'Real', root => '/tmp' ]);
     $root->mount('/tmp' => [ 'Real', root => '/var/tmp' ]); 
     # ^^^ ERROR! Mount point already in use!

3. A file system may only be mounted onto existing containers. When mounting a path, the path must exist as per the already present mount table and that path must represent a container. Otherwise, an error will occur. I.e., the following code would fail:

     $root = File::System->new('Table', '/' => [ 'Real' ]);
     $obj = $root->lookup('/foo');
     $obj->remove('force') if defined $obj;
     $root->mount('/foo' => [ 'Real', root => '/tmp' ]);
     # ^^^ ERROR! Mount point does not exist!
   
     $root->mkfile('/foo');
     $root->mount('/foo' => [ 'Real', root => '/tmp' ]);
     # ^^^ ERROR! Mount point is not a container!

4. Any content or containers within a container that is mounted to within the parent is immediately invisible. These objects are hidden by the child mount until the file system is unmounted.
5. A mount point cannot be set above an existing mount point so that it would hide an existing mount. I.e., the following code would fail:

     $root = File::System->new('Table', '/' => [ 'Real' ]);
     $obj = $root->mkdir('/foo/bar');
     $obj->mount('/foo/bar' => [ 'Real', root => '/tmp' ]);
     $obj->mount('/foo' => [ 'Real', root => '/var/tmp' ]);
     # ^^^ ERROR! Mount point hides an already mounted file system!

6. As a corollary to the fifth principle, a mount point cannot be removed above another mount point below. If you mount one file system within another, the inner file system must be unmounted prior to unmounting the outer.

Because of these rules it is obvious that the order in which mounting takes place is significant and will affect the outcome. As such, the root mount must always be specified first in the constructor.

MOUNT TABLE API

This file system module provides a constructor (duh) and a few extra methods. All other methods are given in the documentation of File::System::Object.

$root = File::System->new('Table', '/' => $fs, ...)

The constructor establishes the initial mount table for the file system. The mount table must always contain at least one entry for the root directory (/). The root directory entry must always be the first entry given as well.

Each entry is made of two elements, the path to mount to and then a reference to either a reference to the file system object responsible for files under that mount point, or an array reference that can be passed to File::System to create a file system object.

$obj->mount($path, $fs)

Each entry is made of two elements, the path to mount to and then a reference to either a reference to the file system object responsible for files under that mount point, or an array reference that can be passed to File::System to create a file system object.

$unmounted_fs = $fs->unmount($path)

Unmounts the file system mounted to the given path. This method will raise an exception if the user attempts to unmount a path that has no file system mounted.

This method returns the file system that was mounted at the given path.

@paths = $fs->mounts

Returns the list of all paths that have been mounted to.

BUGS

The copy and move methods will fail if used between file systems. This can be remedied, but it will require some delicate planning that hasn't yet been done.

SEE ALSO

File::System, File::System::Object, File::System::Real, File::System::Layered

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

This library is distributed and licensed under the same terms as Perl itself.