###
###  Copyright 2000-2007 University of Illinois Board of Trustees
###  All rights reserved. 
###
###  PSGConf::Action::Symlink - symlink action type for psgconf
###
###  Campus Information Technologies and Educational Services
###  University of Illinois at Urbana-Champaign
###


package PSGConf::Action::Symlink;

use strict;

use File::Basename;
use File::Path;

use PSGConf::Action;

our @ISA = qw(PSGConf::Action);


###############################################################################
###  check method
###############################################################################

sub check
{
	my ($self) = @_;

	if (! -l $self->{name}
	    || readlink($self->{name}) ne $self->{link_to})
	{
		$self->{changed} = 1;
		return 1;
	}

	return 0;
}


###############################################################################
###  diff method
###############################################################################

sub diff
{
	my ($self) = @_;

	print "###############################################################################\n";
	print "### DIFF FOR $self->{name}\n";
	print "###          (original file does not exist)\n"
		if (! -e $self->{name});
	print "###############################################################################\n";
	if (-l $self->{name})
	{
		print "- symlink: $self->{name} -> ", readlink($self->{name}), "\n";
	}
	elsif (-d $self->{name})
	{
		print "- directory: $self->{name}\n";
	}
	elsif (-e $self->{name})
	{
		print "- file: $self->{name}\n";
	}
	print "+ symlink: $self->{name} -> $self->{link_to}\n\n";
}


###############################################################################
###  do() method
###############################################################################

sub do
{
	my ($self, $psgconf) = @_;

	### nuke pre-existing file if applicable
	if (-e $self->{name}
	    || -l $self->{name})
	{
		if (!$self->{backup})
		{
			rmtree($self->{name});
		}
		elsif (! $psgconf->save_file($self->{name}, $self->{backup}))
		{
			return -1;
		}
	}

	### create symlink
	mkpath(dirname($self->{name}));
	if (!symlink($self->{link_to}, $self->{name}))
	{
		warn "\t!!! symlink(\"$self->{link_to}\", "
			     . "\"$self->{name}\"): $!\n";
		return -1;
	}

	return 1;
}


###############################################################################
###  documentation
###############################################################################

1;

__END__

=head1 NAME

PSGConf::Action::Symlink - symlink action class for PSGConf

=head1 SYNOPSIS

  use PSGConf::Action::Symlink;

  $psgconf->register_actions(
		PSGConf::Action::Symlink->new(
			'name'		=> '/path/to/symlink',
			'link_to'	=> '/path/to/target',
			...
		),
		...
	);

=head1 DESCRIPTION

The B<PSGConf::Action::Symlink> module provides a B<PSGConf> action class
for creating a symlink.

The B<PSGConf::Action::Symlink> class is derived from the
B<PSGConf::Action> class, but it defines/overrides the
following methods:

=over 4

=item check()

If the file doesn't exist, is not a symlink, or is a symlink pointing to
the wrong place, returns 1.  Otherwise, returns 0.

=item diff()

Prints a message indicating the symlink that will be created.

=item do()

Actually creates the symlink, optionally backing up the original file.

=back

In addition to the attributes supported by the B<PSGConf::Action>
class, the B<PSGConf::Action::Symlink> class supports the following
attributes:

=over 4

=item I<link_to>

The path that the symlink should point to.

=item I<backup>

A boolean flag to indicate whether a backup copy of the existing file
will be saved.  If enabled, existing files will be saved under their
original name but with the prefix ".<backupext>".  Default is no
backup.

=back

=head1 SEE ALSO

L<perl>

L<PSGConf>

L<PSGConf::Action>

=cut