This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
There is no getpw() function in User::grent.
[perl5.git] / lib / User / grent.pm
CommitLineData
36477c24 1package User::grent;
2use strict;
3
3b825e41 4use 5.006_001;
e74a82d7 5our $VERSION = '1.03';
17f410f9 6our(@EXPORT, @EXPORT_OK, %EXPORT_TAGS);
5f6213d8 7our ($gr_name, $gr_gid, $gr_passwd, @gr_members);
36477c24 8BEGIN {
9 use Exporter ();
36477c24 10 @EXPORT = qw(getgrent getgrgid getgrnam getgr);
5f6213d8 11 @EXPORT_OK = qw($gr_name $gr_gid $gr_passwd @gr_members);
36477c24 12 %EXPORT_TAGS = ( FIELDS => [ @EXPORT_OK, @EXPORT ] );
13}
36477c24 14
8cc95fdb 15# Class::Struct forbids use of @ISA
16sub import { goto &Exporter::import }
17
18use Class::Struct qw(struct);
36477c24 19struct 'User::grent' => [
20 name => '$',
21 passwd => '$',
22 gid => '$',
23 members => '@',
24];
25
26sub populate (@) {
27 return unless @_;
28 my $gob = new();
29 ($gr_name, $gr_passwd, $gr_gid) = @$gob[0,1,2] = @_[0,1,2];
30 @gr_members = @{$gob->[3]} = split ' ', $_[3];
31 return $gob;
32}
33
34sub getgrent ( ) { populate(CORE::getgrent()) }
35sub getgrnam ($) { populate(CORE::getgrnam(shift)) }
36sub getgrgid ($) { populate(CORE::getgrgid(shift)) }
37sub getgr ($) { ($_[0] =~ /^\d+/) ? &getgrgid : &getgrnam }
38
391;
40__END__
41
42=head1 NAME
43
2ae324a7 44User::grent - by-name interface to Perl's built-in getgr*() functions
36477c24 45
46=head1 SYNOPSIS
47
48 use User::grent;
49 $gr = getgrgid(0) or die "No group zero";
50 if ( $gr->name eq 'wheel' && @{$gr->members} > 1 ) {
51 print "gid zero name wheel, with other members";
52 }
53
e51e8357 54 use User::grent qw(:FIELDS);
36477c24 55 getgrgid(0) or die "No group zero";
56 if ( $gr_name eq 'wheel' && @gr_members > 1 ) {
57 print "gid zero name wheel, with other members";
58 }
59
60 $gr = getgr($whoever);
61
62=head1 DESCRIPTION
63
72692151 64This module's default exports override the core getgrent(), getgrgid(),
36477c24 65and getgrnam() functions, replacing them with versions that return
66"User::grent" objects. This object has methods that return the similarly
67named structure field name from the C's passwd structure from F<grp.h>;
68namely name, passwd, gid, and members (not mem). The first three
69return scalars, the last an array reference.
70
71You may also import all the structure fields directly into your namespace
72as regular variables using the :FIELDS import tag. (Note that this still
73overrides your core functions.) Access these fields as variables named
74with a preceding C<gr_>. Thus, C<$group_obj-E<gt>gid()> corresponds
75to $gr_gid if you import the fields. Array references are available as
76regular array variables, so C<@{ $group_obj-E<gt>members() }> would be
77simply @gr_members.
78
e74a82d7
JK
79The getgr() function is a simple front-end that forwards a numeric
80argument to getgrgid() and the rest to getgrnam().
36477c24 81
82To access this functionality without the core overrides,
83pass the C<use> an empty import list, and then access
84function functions with their full qualified names.
85On the other hand, the built-ins are still available
86via the C<CORE::> pseudo-package.
87
88=head1 NOTE
89
8cc95fdb 90While this class is currently implemented using the Class::Struct
36477c24 91module to build a struct-like class, you shouldn't rely upon this.
92
93=head1 AUTHOR
94
95Tom Christiansen