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


package PSGConf::Action::ModifyFile;

use strict;

use PSGConf::Action::File;

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


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

sub check
{
	my ($self, $psgconf) = @_;
	my ($srcfile, $retval);

	$self->_set_tmpfile($psgconf);

	$srcfile = $self->{srcfile};
	$srcfile = $self->{name}
		if (!defined($srcfile));
	$srcfile = '/dev/null'
		if (! -e $srcfile);

	### open real file
	if (!open(SRCFILE, "<$srcfile"))
	{
		warn "\n\t!!! can't open file '$srcfile': $!\n";
		return -1;
	}

	### open tempfile
	if (!open(TMPFILE, ">$self->{tmpfile}"))
	{
		warn "\n\t!!! can't open tempfile '$self->{tmpfile}': $!\n";
		return -1;
	}

	### call plugin function
	$retval = &{$self->{modify_func}}($self, \*SRCFILE, \*TMPFILE,
					  $psgconf);

	### close files
	close(TMPFILE);
	close(SRCFILE);

	### skip or fail
	if ($retval != 1)
	{
		unlink($self->{tmpfile});
		return $retval;
	}

	### check for changes
	return $self->_file_changed($psgconf);
}


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

1;

__END__

=head1 NAME

PSGConf::Action::ModifyFile - file-modification action class for PSGConf

=head1 SYNOPSIS

  use PSGConf::Action::ModifyFile;

  $psgconf->register_actions(
		PSGConf::Action::ModifyFile->new(
			'name'		=> '/path/to/file',
			'modify_func'	=> \&_modify_subref,
			...
		),
		...
	);

=head1 DESCRIPTION

The B<PSGConf::Action::ModifyFile> module provides a B<PSGConf> action
class for modifying a file.

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

=over 4

=item check()

Generates a tmpfile by calling the subroutine referenced by the
I<modify_func> attribute.  If the tmpfile differs from the existing file,
or if the existing file's permissions or ownership needs to be changed,
returns 1.  Returns 0 if no changes are needed, or -1 on error.

=back

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

=over 4

=item I<modify_func>

A reference to the subroutine that will generate the file.  The subroutine
will be passed a reference to the B<PSGConf::Action::GenerateFile> object,
an open filehandle to read the existing file from (or F</dev/null> if
the file does not already exist), an open filehandle to write the new
file to, and a reference to the B<PSGConf> object.  It can return any
value that the check() method can return.

=item I<srcfile>

Specifies the source file that should be read.  If not defined, the
source file is the same as the target file.  The default is undefined.

Normally, this class modifies an existing file.  However, by setting
this option, you can use this class to create a file by "filtering"
data from a completely different file.

=back

=head1 SEE ALSO

L<perl>

L<PSGConf>

L<PSGConf::Action::File>

=cut