[DOC PATCH] Carp.pm pod typo
[p5sagit/p5-mst-13.2.git] / lib / User / grent.pm
CommitLineData
36477c24 1package User::grent;
2use strict;
3
3b825e41 4use 5.006_001;
b75c8c73 5our $VERSION = '1.00';
17f410f9 6our(@EXPORT, @EXPORT_OK, %EXPORT_TAGS);
36477c24 7BEGIN {
8 use Exporter ();
36477c24 9 @EXPORT = qw(getgrent getgrgid getgrnam getgr);
10 @EXPORT_OK = qw($gr_name $gr_gid $gr_passwd $gr_mem @gr_members);
11 %EXPORT_TAGS = ( FIELDS => [ @EXPORT_OK, @EXPORT ] );
12}
13use vars @EXPORT_OK;
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
54 use User::grent qw(:FIELDS;
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
64This module's default exports override the core getgrent(), getgruid(),
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
ae83f377 79The getpw() function is a simple front-end that forwards
36477c24 80a numeric argument to getpwuid() and the rest to getpwnam().
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