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


package PSGConf::Action::GenerateFile;

use strict;

use PSGConf::Action::File;

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



###############################################################################
###  constructor
###############################################################################

sub new
{
	my ($class, %opts) = @_;
	my ($self) = \%opts;

#	die "PSGConf::Action::GenerateFile->new(): generate attribute missing\n"
#		if (!exists($opts{'generate'}));

	$self->{comment_str} = '###'
		if (!exists($self->{comment_str}));

	return PSGConf::Action::File::new($class, %$self);
}


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

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

	$self->_set_tmpfile($psgconf);

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

	### print command interperter, if applicable
	if (defined($self->{command_interp}))
	{
		print TMPFILE "$self->{command_interp}\n";
	}

	### print banner, if applicable
	if (defined($self->{comment_str}))
	{
		print TMPFILE "$self->{comment_str}\n";
		print TMPFILE "$self->{comment_str} $self->{name}";
		print TMPFILE " - $self->{description}"
			if (exists($self->{description}));
		print TMPFILE "\n$self->{comment_str}\n";
		print TMPFILE "$self->{comment_str} Automatically generated "
			      . "by $0 - DO NOT EDIT!\n";
		print TMPFILE "$self->{comment_str}\n";
	}

	### call plugin function
	if ($self->can('generate'))
	{
		$retval = $self->generate(\*TMPFILE, $psgconf);
	}
	else
	{
		$retval = &{$self->{generate}}($self, \*TMPFILE, $psgconf);
	}

	### close tmpfile
	close(TMPFILE)
		|| die $0 . ": close('$self->{tmpfile}'): $!";

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

	### check whether file changed
	return $self->_file_changed($psgconf);
}


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

1;

__END__

=head1 NAME

PSGConf::Action::GenerateFile - file-generator action class for PSGConf

=head1 SYNOPSIS

  use PSGConf::Action::GenerateFile;

  $psgconf->register_actions(
		PSGConf::Action::GenerateFile->new(
			'name'			=> '/path/to/file',
			'generate'		=> \&_subref,
			'command_interp'	=> '#!/path/to/binary',
			...
		),
		...
	);

=head1 DESCRIPTION

The B<PSGConf::Action::GenerateFile> module provides a B<PSGConf> action
class for generating a file programmatically.

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

=over 4

=item check()

Generates a tmpfile with the contents of the file to be copied.
If the tmpfile differs from the existing file, or if the existing file's
permissions are 

=back

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

=over 4

=item I<generate>

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 write the
new file to, and a reference to the B<PSGConf> object.  It can return
any value that the check() method can return.

Note: This attribute is deprecated and will be removed in a future
release.  Control modules that need to use this attribute should use
the B<PSGConf::Action::GenerateFile::Literal> module instead.

=item I<command_interp>

The string for the command interperter.  Usually will be I<#!/bin/sh>.
Printed before the I<comment_str> if defined.  The default is C<undef>.

=item I<comment_str>

The comment string for this particular file format.  If defined, a
banner will be printed to the top of the file indicating that it was
generated by B<psgconf>.  The default is "###".

=item I<description>

A short one-line description of the file's purpose.  This is not used
unless the I<comment_str> attribute is defined.

=back

The B<PSGConf::Action::GenerateFile> class does not use any other
attributes, but they can be set for use by the I<generate> function.

=head1 SEE ALSO

L<perl>

L<PSGConf>

L<PSGConf::Action::File>

=cut