Front page | perl.perl5.porters |
Postings from September 2011
Re: Reordering perlvar
Thread Previous
|
Thread Next
From:
Tom Christiansen
Date:
September 26, 2011 12:40
Subject:
Re: Reordering perlvar
Message ID:
9712.1317065927@chthon
Ricardo Signes <perl.p5p@rjbs.manxome.org> wrote
on Mon, 26 Sep 2011 14:14:27 EDT:
>* Tom Christiansen <tchrist@perl.com> [2011-09-26T12:51:37]
>> In that case, why don't we just randomize everything? Certainly
>> perlfunc could use some useful randomizing in the same way.
> My pager can search by strings, meaning organizing sections by the
> header's spelling gets me nothing.
> My pager cannot group them by topic, the version in which we added
> them, or quite a few other properties. Picking one or more of those
> to use for organizing actually has benefits.
> I find the idea that anyone would be paging through perlvar trying to
> find things in dictionary order to be hard to swallow. "Oops, I paged
> past the P's, I'll have to go back a few pages..."
Really? Hm. I think I may.
I feel alphabetized lists are from a user interface point of view.
In the Camel, we take a two-pronged approach to things like
perlvar and perlfunc. We first show things grouped by
type, and then alphabetized. For example, for the special
names chapter:
Special Names Grouped by Type
Regular Expression Special Variables
Per-Filehandle Variables
Per-Package Special Variables
Program-wide Special Variables
Per-Package Special Filehandles
Per-Package Special Functions
Special Variables in Alphabetical Order
$a
$ACCUMULATOR, $^A
ARGV
$ARGV
@ARGV
ARGVOUT
$AUTOLOAD
$b
$BASETIME, $^T
$CHILD_ERROR, $?
$COMPILING, $^C
DATA
$DEBUGGING, $^D
${^ENCODING}
$EFFECTIVE_GROUP_ID, $)
$EFFECTIVE_USER_ID, $>
%ENV
$EVAL_ERROR, $@
$EXCEPTIONS_BEING_CAUGHT, $^S
$EXECUTABLE_NAME, $^X
And for example, for the functions chapter:
Perl Functions by Category
Scalar manipulation
Regular expressions and pattern matching
Numeric functions
Array processing
List processing
Hash processing
Input and output
Fixed-length data and records
Filehandles, files, and directories
Flow of program control
Scoping
Miscellaneous
Processes and process groups
Library modules
Classes and objects
Low-level socket access
System V interprocess communication
Fetching user and group information
Fetching network information
Time
Perl Functions in Alphabetical Order
accept
alarm
atan2
bind
binmode
bless
break
caller
chdir
To show how those work, here's the "regex special variables" subsection
from the special names chapter. This listing does not actually give the
full explanation, just the names. The full explanation is found in the
alphabetical section.
=head2 Regular Expression Special Variables
The following special variables related to pattern matching are visible
throughout the dynamic scope in which the pattern match occurred. In
other words, they behave as though they were declared with C<local>,
so you needn't declare them that way yourself. See A<5>.
$R<digits>
$& ($MATCH)
$' ($POSTMATCH)
$` ($PREMATCH)
${^MATCH}
${^POSTMATCH}
${^PREMATCH}
$+ ($LAST_PAREN_MATCH)
%+ (%LAST_PAREN_MATCH)
@+ (@LAST_MATCH_END)
@- (@LAST_MATCH_START)
%- (XXX: erroneously %FORMAT_LINES_LEFT)
$^R ($LAST_REGEXP_CODE_RESULT)
$^N ($LAST_SUBMATCH_RESULT)
Similarly, for the functions chapter, here is a sample of some
of the by-category groupings.
Hash processing
delete, each, exists, keys, values
Input and output
binmode, close, closedir, dbmclose, dbmopen, die, eof, fileno,
flock, format, getc, print, printf, read, readdir, readpipe,
rewinddir, say, seek, seekdir, select (ready file descriptors),
syscall, sysread, sysseek, syswrite, tell, telldir, truncate,
warn, write
Fixed-length data and records
pack, read, syscall, sysread, sysseek, syswrite, unpack, vec
Filehandles, files, and directories
chdir, chmod, chown, chroot, fcntl, glob, ioctl, link, lstat,
mkdir, open, opendir, readlink, rename, rmdir, select (ready file
descriptors), select (output filehandle), stat, symlink, sysopen,
umask, unlink, utime
As before, they are only listed in the birds of a feather sections;
the full descriptions are given in the alphabetized section that comes
afterwards. This two-pronged approach seems the best way to me--
which is why I did it that way. But opinions may, I suppose, differ.
One other place that might could stand that sort of dual orgaization
may be the envariables. Consider:
Environment Variables
HOME
LC_ALL, LC_CTYPE, LC_COLLATE, LC_NUMERIC, PERL_BADLANG
LOGDIR
PATH
PERL5DB
PERL5DB_THREADED
PERL5LIB
PERL5OPT
PERL5SHELL (Microsoft ports only)
PERLIO
PERLIO_DEBUG
PERLLIB
PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)
PERL_DEBUG_MSTATS
PERL_DESTRUCT_LEVEL
PERL_DL_NONLAZY
PERL_ENCODING
PERL_HASH_SEED
PERL_HASH_SEED_DEBUG
PERL_MEM_LOG
PERL_ROOT (specific to the VMS port)
PERL_SIGNALS
PERL_UNICODE
SYS$LOGIN (specific to the VMS port)
--tom
Thread Previous
|
Thread Next