view release on metacpan or  search on metacpan

lib/File/System/Table.pm  view on Meta::CPAN

  );

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

=head1 DESCRIPTION

This file system module allows for the creation of a tabular virtual file system. Each L<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 ...

=head2 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:

=over

=item 1.

The root mount point (F</>) is special and static. It cannot be unmounted except by deleting the file system object altogether.

=item 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!

=item 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!

=item 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.

=item 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!

=item 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.

=back

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.

=head2 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 L<File::System::Object>.

=over

=item $root = File::System-E<gt>new('Table', '/' =E<gt> $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 (F</>). 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 L<File::System> to create a file s...

=cut

sub new {
	my $class = shift;

	$_[0] eq '/'
		or croak "The first mount point given must always be the root (/), but found '$_[0]' instead.";

	my $self = bless { cwd => '/' }, $class;

	while (my ($mp, $fs) = splice @_, 0, 2) {
		$self->mount($mp, $fs);
	}

	return $self;
}

=item $obj-E<gt>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 L<File::System> to create a file s...

=cut

sub mount {
	my $self = shift;
	my $path = $self->normalize_path(shift);
	my $fs   = $self->_init_fs(shift);

	if ($path eq '/') {
		if (defined $self->{mounts}) {
			croak "The root mount point cannot be overridden.";
		} else {
			$self->{cwd_fs} = $self->{mounts}{$path} = $fs;
		}
	} else {
		my $dir = $self->lookup($path);

		defined $dir
			or croak "The mount point '$path' does not exist.";

		$dir->is_container
			or croak "The mount point '$path' is not a container.";