This and other RFCs are available on the web at
http://dev.perl.org/rfc/
=head1 TITLE
Builtins : Make use of hashref context for garrulous builtins
=head1 VERSION
Maintainer: Damian Conway <[EMAIL PROTECTED]>
Date: 19 Sep 2000
Last Updated: 20 Sep 2000
Mailing List: [EMAIL PROTECTED]
Number: 259
Version: 2
Status: Developing
=head1 ABSTRACT
This RFC proposes the builtin functions that return a large number of
values in an array context should also detect hashref contexts (see RFC
21) and return their data in a kinder, gentler format.
=head1 DESCRIPTION
It's hard to remember the sequence of values that the following
builtins return:
stat/lstat
caller
localtime/gmtime
get*
and though it's easy to look them up, it's a pain to look them up
Every Single Time.
Moreover, code like this is far from self-documenting:
if ((stat $filename)[7] > 1000) {...}
if ((lstat $filename)[10] > time()-1000) {...}
if ((localtime(time))[3] > 5) {...}
if ($usage > (getpwent)[4]) {...}
@host{qw(name aliases addrtype length addrs)} = gethostbyname $name;
warn "Problem at " . join(":", @{[caller(0)]}[3,1,2]) . "\n";
It is proposed that, when one of these subroutines is called in the new
HASHREF context (RFC 21), it should return a reference to a hash of values,
with standardized keys. For example:
if (stat($filename)->{size} > 1000) {...}
if (lstat($filename)->{ctime} > time()-1000) {...}
if (localtime(time)->{mday} > 5) {...}
if ($usage > getpwent()->{quota}) {...}
%host = %{gethostbyname($name)};
warn "Problem at " . join(":", @{caller(0)}{qw(sub file line)} . "\n";
=head2 Standardized keys
The standardized keys for these functions would be:
=over 4
=item C<stat>/C<lstat>
'dev' Device number of filesystem
'ino' Inode number
'mode' File mode (type and permissions)
'nlink' Number of (hard) links to the file
'uid' Numeric user ID of file's owner
'gid' Numeric group ID of file's owner
'rdev' The device identifier (special files only)
'size' Total size of file, in bytes
'atime' Last access time in seconds since the epoch
'mtime' Last modify time in seconds since the epoch
'ctime' Inode change time in seconds since the epoch
'blksize' Preferred block size for file system I/O
'blocks' Actual number of blocks allocated
=item C<localtime>/C<gmtime>
'sec' Second
'min' Minute
'hour' Hour
'mon' Month
'year' Year
'mday' Day of the month
'wday' Day of the week
'yday' Day of the year
'isdst' Is daylight savings time in effect
(localtime only)
=item C<caller>
'package' Name of the package from which sub was called
'file' Name of the file from which sub was called
'line' Line in the file from which sub was called
'sub' Name by which sub was called
'args' Was sub called with args?
'want' Hash of values returned by want()
'eval' Text of EXPR within eval EXPR
'req' Was sub called from a C<require> (or C<use>)?
'hints' Pragmatic hints with which sub was compiled
'bitmask' Bitmask with which sub was compiled
=item C<getpw*>
'name' Username
'passwd' Crypted password
'uid' User ID
'gid' Group ID
'quota' Disk quota
'comment' Administrative comments
'gcos' User information
'dir' Home directory
'shell' Native shell
'expire' Expiry date of account of password
=item C<getgr*>
'name' Group name
'passwd' Group password
'gid' Group id
'members' Group members
=item C<gethost*>
'name' Official host name
'aliases' Other host names
'addrtype' Host address type
'length' Length of address
'addrs' Anonymous array of raw addresses in 'C4' format
=item C<getnet*>
'name' Official name of netwwork
'aliases' Other names for network
'addrtype' Type of network number
'net' Network number
=item C<getproto*>
'name' Official name of protocol
'aliases' Other names for protocol
'proto' Protocol number
=item C<getserv*>
'name' Official name of service
'aliases' Other names for service
'port' Port at which service resides
'proto' Protocol to be used
=back
=head1 MIGRATION ISSUES
None.
=head1 REFERENCES
This RFC explains the mechanism by which HASHREF context would be detected:
RFC 21: Replace C<wantarray> with a generic C<want> function
These RFCs propose (partial) alternative solutions to this problem:
RFC 37: Positional Return Lists Considered Harmful
RFC 127: Sane resolution to large function returns
RFC 48: Replace localtime() and gmtime() with date() and utcdate()
