VCS::CMSynergy::Users - Perl interface to CM Synergy user administration

VCS-CMSynergy documentation Contained in the VCS-CMSynergy distribution.

Index

Code Index:

NAME

Top

VCS::CMSynergy::Users - Perl interface to CM Synergy user administration

SYNOPSIS

Top

  use VCS::CMSynergy::Users;

  $hash_ref = $ccm->users;
  $ccm->users(\%user_roles);
  $ccm->add_user($user, @roles);
  $ccm->delete_user($user);
  @roles = $ccm->get_roles($user);
  $ccm->add_roles($user, @roles);
  $ccm->delete_roles($user, @roles);

DESCRIPTION

Top

NOTE: This interface is subject to change.

  use VCS::CMSynergy;
  use VCS::CMSynergy::Users;

  my $ccm = VCS::CMSynergy->new(database => "/ccmdb/test/tut62/db");

  $ccm->add_user('jluser', qw(developer build_mgr));

METHODS

Top

users

  $hash_ref = $ccm->users;
  $ccm->users($hash_ref);

The first form gets the table of users and their roles as a hash ref. The keys are the user names and the values are array refs containing the user's roles, e.g.

  $hash_ref = {
    'jluser'	=> [ qw(developer) ],
    'psizzle'	=> [ qw(developer build_mgr) ],
    ...
    };

You need not be in the ccm_admin role to use this form (because it is not implemented via ccm users).

The second form replaces the existing table of users and their roles with the contents of $hashref. Duplicate roles will be removed from $hashref's values before writing back the table. You must be in the ccm_admin role to use this form.

All operations try to preserve the order of roles (add_roles appends the roles that are actually new for the user). This mostly matters for the role listed first for a user, as CM Synergy uses this as default role for the user's session when the user calls ccm start without the -r option.

If you have one of the modules Tie::Hash::Indexed or Tie::IxHash installed, than the value returned by users is actually a reference to a tied hash that preserves the insertion order of keys. In this case, the order of hash keys reflects the order of user lines in the users "file".

Note that

  $ccm->users($ccm->users);

always results in a functionally equivalent users table. The order of user lines may have changed, though, unless an order preserving hash was used as decribed above.

Note: For typical CM Synergy administrator usage it is usually more convenient to use one of the methods below.

add_user

  $ccm->add_user($user, @roles);

Adds the user with the given roles. If the user already exists her roles will be reset to the ones given.

delete_user

  $ccm->delete_user($user);

Deletes the user. No error is signalled if the user doesn't exist.

add_roles

  $ccm->add_roles($user, @roles);

Grants the given roles to the user. It is no error if the user already has some of the given rules.

delete_roles

  $ccm->delete_roles($user, @roles);

Revokes the given roles from the user. It is no error if the user doesn't have any of the given rules.

get_roles

  @roles = $ccm->get_roles($user);

Returns the roles for the user. Returns an empty list if the user doesn't exist.

SEE ALSO

Top

VCS::CMSynergy VCS::CMSynergy::Object, VCS::CMSynergy::Client,

AUTHORS

Top

Roderich Schupp, argumentum GmbH <schupp@argumentum.de>

VCS-CMSynergy documentation Contained in the VCS-CMSynergy distribution. 
package VCS::CMSynergy::Users;

# Copyright (c) 2001-2010 argumentum GmbH, 
# See COPYRIGHT section in VCS/CMSynergy.pod for usage and distribution rights.

our $VERSION = do { (my $v = q$Revision: 381 $) =~ s/^.*:\s*//; $v };


package VCS::CMSynergy;


my $UseIndexedHash;
foreach (qw/Tie::Hash::Indexed Tie::IxHash/)
{
    $UseIndexedHash = $_, last if eval "require $_";
}

sub users
{
    my $self = shift;
    return $self->set_error("too many arguments") unless @_ <= 1;

    # NOTE: For getting the list of users we use 
    # "ccm attr -show users base-1:model:base" because every role can do that -
    # whereas "ccm users" requires the ccm_admin role.
    if (@_ == 0)
    {
	my $text = $self->get_attribute(users => $self->base_model);
	return unless defined $text;
	
	my $users = {};
	tie %$users, $UseIndexedHash if $UseIndexedHash;

	foreach (split(/\n/, $text))
	{
	    my ($user, $roles) = /^ \s* user \s+ (\S+) \s* = \s* (.*) ;/x;
	    next unless defined $user;
	    $users->{$user} = [ split(" ", $roles) ];
	}

	return $users;
    }

    my $users = shift;
    return $self->set_error("illegal type of argument (hash ref expected)") 
	unless ref $users eq "HASH";

    my $text = "";
    while (my ($user, $roles) = each %$users)
    {
	return $self->set_error("illegal value for user `$user' (array ref expected)")
	    unless ref $roles eq "ARRAY";
	return $self->set_error("no roles defined for user `$user'")
	    unless @$roles;

	# remove duplicates
	my %dup;
	$text .= "user $user = " . join(" ", grep { !$dup{$_}++ } @$roles) . ";\n";
    }

    my ($rc, $out, $err) = $self->ccm_with_text_editor($text, qw(users));
    return $self->set_error($err || $out) unless $rc == 0;
    return $users;
}


sub add_user
{
    my ($self, $user, @roles) = @_;

    my $users = $self->users;
    return unless $users;

    $users->{$user} = \@roles;

    $self->users($users);
}


sub delete_user
{
    my ($self, $user) = @_;

    my $users = $self->users;
    return unless $users;

    delete $users->{$user};

    $self->users($users);
}


sub add_roles
{
    my ($self, $user, @roles) = @_;

    my $users = $self->users;
    return unless $users;

    return $self->set_error("user `$user' doesn't exist")
	unless $users->{$user};

    push @{ $users->{$user} }, @roles;

    $self->users($users);
}


sub delete_roles
{
    my ($self, $user, @roles) = @_;

    my $users = $self->users;
    return unless $users;

    return $self->set_error("user `$user' doesn't exist")
	unless exists $users->{$user};
 
    my %del;
    @del{@roles} = ();

    $users->{$user} = [ grep { !exists $del{$_} } @{ $users->{$user} } ];

    $self->users($users);
}


sub get_roles
{
    my ($self, $user) = @_;

    my $users = $self->users;
    return unless $users;

    my $roles = $users->{$user};
    return $roles ? @$roles : ();
}


1;