This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
+ Docs and test
authorAbe Timmerman <abe@ztreet.demon.nl>
Fri, 4 Jan 2002 18:42:33 +0000 (19:42 +0100)
committerJarkko Hietaniemi <jhi@iki.fi>
Fri, 4 Jan 2002 17:35:34 +0000 (17:35 +0000)
Message-ID: <bm5b3usi1f65td4c9bo9fand20p0vnupf2@4ax.com>

p4raw-id: //depot/perl@14056

MANIFEST
lib/Pod/Functions.pm
lib/Pod/t/Functions.t [new file with mode: 0644]

index 6c9cc68..02e4e35 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -1211,6 +1211,7 @@ lib/Pod/t/basic.pod               podlators test
 lib/Pod/t/basic.t              podlators test
 lib/Pod/t/basic.txt            podlators test
 lib/Pod/t/man.t                podlators test
+lib/Pod/t/Functions.t          See if Pod::Functions works
 lib/Pod/t/InputObjects.t       See if Pod::InputObjects works
 lib/Pod/t/latex.t              Test for Pod::LaTeX
 lib/Pod/t/parselink.t          podlators test
index 960b847..7f7e150 100644 (file)
@@ -1,13 +1,75 @@
 package Pod::Functions;
+use strict;
 
-#:vi:set ts=20
+=head1 NAME
 
-our $VERSION = '1.00';
+Pod::Functions - Group Perl's functions a la perlfunc.pod
+
+=head1 SYNOPSIS
+
+    use Pod:Functions;
+    
+    my @misc_ops = @{ $Kinds{ 'Misc' } };
+    my $misc_dsc = $Type_Description{ 'Misc' };
+
+or
+
+    perl /path/to/lib/Pod/Functions.pm
+
+This will print a grouped list of Perl's functions, like the 
+L<perlfunc/"Perl Functions by Category"> section.
+
+=head1 DESCRIPTION
+
+It exports the following variables:
+
+=over 4
+
+=item %Kinds
+
+This holds a hash-of-lists. Each list contains the functions in the catagory
+the key denotes.
+
+=item %Type
+
+In this hash each key represents a function and the value is the catagory.
+The catagory can be a comma separated list.
+
+=item %Flavor
+
+In this hash each key represents a function and the value is a short 
+description of that function.
+
+=item %Type_Description
+
+In this hash each key represents a catagory of functions and the value is 
+a short description of that catagory.
+
+=item @Type_Order
+
+This list of catagories is used to produce the same order as the
+L<perlfunc/"Perl Functions by Category"> section.
+
+=back
+
+=head1 CHANGES
+
+1.01 20011229 <abe@ztreet.demon.nl>
+    fixed some bugs that slipped in after 5.6.1
+    added the pod
+    finished making it strict safe
+
+1.00 ??
+    first numbered version
+
+=cut
+
+our $VERSION = '1.01';
 
 require Exporter;
 
-@ISA = qw(Exporter);
-@EXPORT = qw(%Kinds %Type %Flavor %Type_Description @Type_Order);
+our @ISA = qw(Exporter);
+our @EXPORT = qw(%Kinds %Type %Flavor %Type_Description @Type_Order);
 
 our(%Kinds, %Type, %Flavor);
 
@@ -65,16 +127,17 @@ while (<DATA>) {
     $Type{$name} = $type;
     $Flavor{$name} = $text;
     for my $t ( split /[,\s]+/, $type ) {
-       push @{$Kinds{$t}}, $name;
+        push @{$Kinds{$t}}, $name;
     }
-} 
+}
 
 close DATA;
 
+my( $typedesc, $list );
 unless (caller) { 
     foreach my $type ( @Type_Order ) {
-       my $list = join(", ", sort @{$Kinds{$type}});
-       my $typedesc = $Type_Description{$type} . ":";
+       $list = join(", ", sort @{$Kinds{$type}});
+       $typedesc = $Type_Description{$type} . ":";
        write;
     } 
 }
@@ -89,7 +152,7 @@ format =
        $list
 .
 
-1
+1;
 
 __DATA__
 -X     File    a file test (-r, -x, etc)
@@ -205,6 +268,7 @@ oct String,Math     convert a string to an octal number
 open   File    open a file, pipe, or descriptor
 opendir        File    open a directory
 ord    String  find a character's numeric representation
+our    Misc,Namespace  declare and assign a package variable (lexical scoping)
 pack   Binary,String   convert a list into a binary representation
 pipe   Process open a pair of connected filehandles
 pop    ARRAY   remove the last element from an array and return it
diff --git a/lib/Pod/t/Functions.t b/lib/Pod/t/Functions.t
new file mode 100644 (file)
index 0000000..43a6545
--- /dev/null
@@ -0,0 +1,160 @@
+#!perl
+
+BEGIN {
+       chdir 't' if -d 't';
+       @INC = '../lib';
+
+}
+
+use File::Basename;
+use File::Spec;
+
+use Test::More;
+plan tests => 9;
+
+
+use_ok( 'Pod::Functions' );
+
+# How do you test exported vars?
+my( $pkg_ref, $exp_ref ) = ( \%Pod::Functions::Kinds, \%Kinds );
+is( $pkg_ref, $exp_ref, '%Pod::Functions::Kinds exported' );
+
+( $pkg_ref, $exp_ref ) = ( \%Pod::Functions::Type, \%Type );
+is( $pkg_ref, $exp_ref, '%Pod::Functions::Type exported' );
+
+( $pkg_ref, $exp_ref ) = ( \%Pod::Functions::Flavor, \%Flavor );
+is( $pkg_ref, $exp_ref, '%Pod::Functions::Flavor exported' );
+
+( $pkg_ref, $exp_ref ) = ( \%Pod::Functions::Type_Description, 
+                           \%Type_Description );
+is( $pkg_ref, $exp_ref, '%Pod::Functions::Type_Description exported' );
+
+( $pkg_ref, $exp_ref ) = ( \@Pod::Functions::Type_Order, \@Type_Order );
+is( $pkg_ref, $exp_ref, '@Pod::Functions::Type_Order exported' );
+
+# Check @Type_Order
+my @catagories = qw(
+    String  Regexp Math ARRAY     LIST    HASH    I/O
+    Binary  File   Flow Namespace Misc    Process Modules
+    Objects Socket SysV User      Network Time
+);
+
+ok( eq_array( \@Type_Order, \@catagories ),
+    '@Type_Order' );
+
+my @cat_keys = grep exists $Type_Description{ $_ } => @Type_Order;
+
+ok( eq_array( \@cat_keys, \@catagories ),
+    'keys() %Type_Description' );
+
+my( undef, $path ) = fileparse( $0 );
+my $pod_functions = File::Spec->catfile( 
+    $path, File::Spec->updir, 'Functions.pm' );
+
+SKIP: {
+       my $test_out = do { local $/; <DATA> }; 
+       
+       skip( "Can't fork '$^X': $!", 1) 
+           unless open my $fh, "$^X $pod_functions |";
+       my $fake_out = do { local $/; <$fh> };
+       while ( <$fh> ) { $fake_out .= $_ }
+       skip( "Pipe error: $!", 1)
+           unless close $fh;
+
+    is( $fake_out, $test_out, 'run as plain program' );
+}
+
+=head1 NAME
+
+Functions.t - Test Pod::Functions
+
+=head1 AUTHOR
+
+20011229 Abe Timmerman <abe@ztreet.demon.nl>
+
+=cut
+
+__DATA__
+
+Functions for SCALARs or strings:
+     chomp, chop, chr, crypt, hex, index, lc, lcfirst, length,
+     oct, ord, pack, q/STRING/, qq/STRING/, reverse, rindex,
+     sprintf, substr, tr///, uc, ucfirst, y///
+
+Regular expressions and pattern matching:
+     m//, pos, qr/PATTERN/, quotemeta, s///, split, study
+
+Numeric functions:
+     abs, atan2, cos, exp, hex, int, log, oct, rand, sin, sqrt,
+     srand
+
+Functions for real @ARRAYs:
+     pop, push, shift, splice, unshift
+
+Functions for list data:
+     grep, join, map, qw/STRING/, reverse, sort, unpack
+
+Functions for real %HASHes:
+     delete, each, exists, keys, values
+
+Input and output functions:
+     binmode, close, closedir, dbmclose, dbmopen, die, eof,
+     fileno, flock, format, getc, print, printf, read, readdir,
+     readline, rewinddir, seek, seekdir, select, syscall,
+     sysread, sysseek, syswrite, tell, telldir, truncate, warn,
+     write
+
+Functions for fixed length data or records:
+     pack, read, syscall, sysread, sysseek, syswrite, unpack,
+     vec
+
+Functions for filehandles, files, or directories:
+     -X, chdir, chmod, chown, chroot, fcntl, glob, ioctl, link,
+     lstat, mkdir, open, opendir, readlink, rename, rmdir,
+     stat, symlink, umask, unlink, utime
+
+Keywords related to control flow of your perl program:
+     caller, continue, die, do, dump, eval, exit, goto, last,
+     next, prototype, redo, return, sub, wantarray
+
+Keywords altering or affecting scoping of identifiers:
+     caller, import, local, my, our, package, use
+
+Miscellaneous functions:
+     defined, dump, eval, formline, local, my, our, prototype,
+     reset, scalar, undef, wantarray
+
+Functions for processes and process groups:
+     alarm, exec, fork, getpgrp, getppid, getpriority, kill,
+     pipe, qx/STRING/, setpgrp, setpriority, sleep, system,
+     times, wait, waitpid
+
+Keywords related to perl modules:
+     do, import, no, package, require, use
+
+Keywords related to classes and object-orientedness:
+     bless, dbmclose, dbmopen, package, ref, tie, untie, use
+
+Low-level socket functions:
+     accept, bind, connect, getpeername, getsockname,
+     getsockopt, listen, recv, send, setsockopt, shutdown,
+     socket, socketpair
+
+System V interprocess communication functions:
+     msgctl, msgget, msgrcv, msgsnd, semctl, semget, semop,
+     shmctl, shmget, shmread, shmwrite
+
+Fetching user and group info:
+     endgrent, endhostent, endnetent, endpwent, getgrent,
+     getgrgid, getgrnam, getlogin, getpwent, getpwnam,
+     getpwuid, setgrent, setpwent
+
+Fetching network info:
+     endprotoent, endservent, gethostbyaddr, gethostbyname,
+     gethostent, getnetbyaddr, getnetbyname, getnetent,
+     getprotobyname, getprotobynumber, getprotoent,
+     getservbyname, getservbyport, getservent, sethostent,
+     setnetent, setprotoent, setservent
+
+Time-related functions:
+     gmtime, localtime, time, times