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


package PSGConf::Action::HomeDir;

use strict;

use File::Path;

use PSGConf::Action::MkDir;

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


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

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

	$self->SUPER::do($psgconf);

	if (defined($self->{user_info}->{populate_method}))
	{
		if (ref($self->{user_info}->{populate_method}))
		{
			$subref = $self->{user_info}->{populate_method};
		}
		else
		{
			$subref = \&{$self->{user_info}->{populate_method}};
		}

		$subref->($psgconf,
			  $self->{user_info},
			  $self->{user_info}->{populate_data})
			|| return -1;
	}

	return 1;
}


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

1;

__END__

=head1 NAME

PSGConf::Action::HomeDir - home directory creation action class for PSGConf

=head1 SYNOPSIS

  use PSGConf::Action::HomeDir;

  $psgconf->register_actions(
		PSGConf::Action::HomeDir->new(
			'name'		=> '/path/to/home/dir',
			'user_info'	=> { ... },
			'populate_method' => sub { ... },
			'populate_data'	=> ...,
			...
		),
		...
	);

=head1 DESCRIPTION

The B<PSGConf::Action::HomeDir> module provides a B<PSGConf> action class
for creating a user's home directory.

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

=over 4

=item do()

Creates the directory specified by the I<name> attribute.

If the I<populate_method> attribute was specified, calls the subroutine
specified by that attribute to populate the user's home directory.
Otherwise, changes the newly created directory to be owned by the I<uid>
and I<gid> entries in the I<user_info> attribute.

=back

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

=over 4

=item I<user_info>

A hash containing information about the user whose home directory is
specified by the I<name> attribute.

=item I<populate_method>

Specifies a subroutine that will be called to populate the user's
home directory.  The subroutine can be specified by a reference or
as a string containing the full symbol name of the subroutine (e.g.,
"Package::subroutine_name").

The specified subroutine will be called with three arguments: a reference
to the B<PSGConf> object, the value of the I<user_info> attribute,
and the value of the I<populate_data> attribute.

=item I<populate_data>

An extra parameter to be passed to the subroutine specified by the
I<populate_method> attribute.

=back

=head1 SEE ALSO

L<perl>

L<PSGConf>

L<PSGConf::Action::MkDir>

=cut