diff options
61 files changed, 1388 insertions, 2104 deletions
diff --git a/lib/AnyDBM_File.pm b/lib/AnyDBM_File.pm index ff9078652e..50acce412a 100644 --- a/lib/AnyDBM_File.pm +++ b/lib/AnyDBM_File.pm @@ -7,3 +7,86 @@ eval { require DB_File } || eval { require GDBM_File } || eval { require SDBM_File } || eval { require ODBM_File }; + +=head1 NAME + +AnyDBM_File - provide framework for multiple DBMs + +NDBM_File, ODBM_File, SDBM_File, GDBM_File - various DBM implementations + +=head1 SYNOPSIS + + use AnyDBM_File; + +=head1 DESCRIPTION + +This module is a "pure virtual base class"--it has nothing of its own. +It's just there to inherit from one of the various DBM packages. It +prefers ndbm for compatibility reasons with Perl 4, then Berkeley DB (See +L<DB_File>), GDBM, SDBM (which is always there--it comes with Perl), and +finally ODBM. This way old programs that used to use NDBM via dbmopen() +can still do so, but new ones can reorder @ISA: + + @AnyDBM_File::ISA = qw(DB_File GDBM_File NDBM_File); + +Note, however, that an explicit use overrides the specified order: + + use GDBM_File; + @AnyDBM_File::ISA = qw(DB_File GDBM_File NDBM_File); + +will only find GDBM_File. + +Having multiple DBM implementations makes it trivial to copy database formats: + + use POSIX; use NDBM_File; use DB_File; + tie %newhash, DB_File, $new_filename, O_CREAT|O_RDWR; + tie %oldhash, NDBM_File, $old_filename, 1, 0; + %newhash = %oldhash; + +=head2 DBM Comparisons + +Here's a partial table of features the different packages offer: + + odbm ndbm sdbm gdbm bsd-db + ---- ---- ---- ---- ------ + Linkage comes w/ perl yes yes yes yes yes + Src comes w/ perl no no yes no no + Comes w/ many unix os yes yes[0] no no no + Builds ok on !unix ? ? yes yes ? + Code Size ? ? small big big + Database Size ? ? small big? ok[1] + Speed ? ? slow ok fast + FTPable no no yes yes yes + Easy to build N/A N/A yes yes ok[2] + Size limits 1k 4k 1k[3] none none + Byte-order independent no no no no yes + Licensing restrictions ? ? no yes no + + +=over 4 + +=item [0] + +on mixed universe machines, may be in the bsd compat library, +which is often shunned. + +=item [1] + +Can be trimmed if you compile for one access method. + +=item [2] + +See L<DB_File>. +Requires symbolic links. + +=item [3] + +By default, but can be redefined. + +=back + +=head1 SEE ALSO + +dbm(3), ndbm(3), DB_File(3) + +=cut diff --git a/lib/AutoLoader.pm b/lib/AutoLoader.pm index 92109a3681..449498c367 100644 --- a/lib/AutoLoader.pm +++ b/lib/AutoLoader.pm @@ -1,6 +1,24 @@ package AutoLoader; use Carp; +=head1 NAME + +AutoLoader - load functions only on demand + +=head1 SYNOPSIS + + package FOOBAR; + use Exporter; + use AutoLoader; + @ISA = (Exporter, AutoLoader); + +=head1 DESCRIPTION + +This module tells its users that functions in the FOOBAR package are to be +autoloaded from F<auto/$AUTOLOAD.al>. See L<perlsub/"Autoloading">. + +=cut + AUTOLOAD { my $name = "auto/$AUTOLOAD.al"; $name =~ s#::#/#g; @@ -24,5 +42,23 @@ AUTOLOAD { } goto &$AUTOLOAD; } + +sub import +{ + my ($callclass, $callfile, $callline,$path,$callpack) = caller(0); + ($callpack = $callclass) =~ s#::#/#; + if (defined($path = $INC{$callpack . '.pm'})) + { + if ($path =~ s#^(.*)$callpack\.pm$#$1auto/$callpack/autosplit.ix# && -e $path) + { + eval {require $path}; + carp $@ if ($@); + } + else + { + croak "Have not loaded $callpack.pm"; + } + } +} 1; diff --git a/lib/AutoSplit.pm b/lib/AutoSplit.pm index a6422611bc..72f897d1b1 100644 --- a/lib/AutoSplit.pm +++ b/lib/AutoSplit.pm @@ -10,6 +10,19 @@ use Carp; @EXPORT = qw(&autosplit &autosplit_lib_modules); @EXPORT_OK = qw($Verbose $Keep $Maxlen $CheckForAutoloader $CheckModTime); +=head1 NAME + +AutoSplit - split a package for autoloading + +=head1 DESCRIPTION + +This function will split up your program into files that the AutoLoader +module can handle. Normally only used to build autoloading Perl library +modules, especially extensions (like POSIX). You should look at how +they're built out for details. + +=cut + # for portability warn about names longer than $maxlen $Maxlen = 8; # 8 for dos, 11 (14-".al") for SYSVR3 $Verbose = 1; # 0=none, 1=minimal, 2=list .al files @@ -83,7 +96,13 @@ sub autosplit_file{ open(IN, "<$filename") || die "AutoSplit: Can't open $filename: $!\n"; my($pm_mod_time) = (stat($filename))[9]; my($autoloader_seen) = 0; + my($in_pod) = 0; while (<IN>) { + # Skip pod text. + $in_pod = 1 if /^=/; + $in_pod = 0 if /^=cut/; + next if ($in_pod || /^=cut/); + # record last package name seen $package = $1 if (m/^\s*package\s+([\w:]+)\s*;/); ++$autoloader_seen if m/^\s*(use|require)\s+AutoLoader\b/; @@ -199,7 +218,9 @@ sub autosplit_file{ next if $names{substr($subname,0,$maxflen-3)}; my($file) = "$autodir/$modpname/$_"; print " deleting $file\n" if ($Verbose>=2); - unlink $file or carp "Unable to delete $file: $!"; + my($deleted,$thistime); # catch all versions on VMS + do { $deleted += ($thistime = unlink $file) } while ($thistime); + carp "Unable to delete $file: $!" unless $deleted; } closedir(OUTDIR); } @@ -207,7 +228,9 @@ sub autosplit_file{ open(TS,">$al_idx_file") or carp "AutoSplit: unable to create timestamp file ($al_idx_file): $!"; print TS "# Index created by AutoSplit for $filename (file acts as timestamp)\n"; + print TS "package $package;\n"; print TS map("sub $_ ;\n", @subnames); + print TS "1;\n"; close(TS); check_unique($package, $Maxlen, 1, @names); diff --git a/lib/Benchmark.pm b/lib/Benchmark.pm index a19caffdc8..40481f9662 100644 --- a/lib/Benchmark.pm +++ b/lib/Benchmark.pm @@ -1,5 +1,166 @@ package Benchmark; +=head1 NAME + +Benchmark - benchmark running times of code + +timethis - run a chunk of code several times + +timethese - run several chunks of code several times + +timeit - run a chunk of code and see how long it goes + +=head1 SYNOPSIS + + timethis ($count, "code"); + + timethese($count, { + 'Name1' => '...code1...', + 'Name2' => '...code2...', + }); + + $t = timeit($count, '...other code...') + print "$count loops of other code took:",timestr($t),"\n"; + +=head1 DESCRIPTION + +The Benchmark module encapsulates a number of routines to help you +figure out how long it takes to execute some code. + +=head2 Methods + +=over 10 + +=item new + +Returns the current time. Example: + + use Benchmark; + $t0 = new Benchmark; + # ... your code here ... + $t1 = new Benchmark; + $td = timediff($t1, $t0); + print "the code took:",timestr($dt),"\n"; + +=item debug + +Enables or disable debugging by setting the C<$Benchmark::Debug> flag: + + debug Benchmark 1; + $t = timeit(10, ' 5 ** $Global '); + debug Benchmark 0; + +=back + +=head2 Standard Exports + +The following routines will be exported into your namespace +if you use the Benchmark module: + +=over 10 + +=item timeit(COUNT, CODE) + +Arguments: COUNT is the number of time to run the loop, and +the second is the code to run. CODE may be a string containing the code, +a reference to the function to run, or a reference to a hash containing +keys which are names and values which are more CODE specs. + +Side-effects: prints out noise to standard out. + +Returns: a Benchmark object. + +=item timethis + +=item timethese + +=item timediff + +=item timestr + +=back + +=head2 Optional Exports + +The following routines will be exported into your namespace +if you specifically ask that they be imported: + +=over 10 + +clearcache + +clearallcache + +disablecache + +enablecache + +=back + +=head1 NOTES + +The data is stored as a list of values from the time and times +functions: + + ($real, $user, $system, $children_user, $children_system) + +in seconds for the whole loop (not divided by the number of rounds). + +The timing is done using time(3) and times(3). + +Code is executed in the caller's package. + +Enable debugging by: + + $Benchmark::debug = 1; + +The time of the null loop (a loop with the same +number of rounds but empty loop body) is subtracted +from the time of the real loop. + +The null loop times are cached, the key being the +number of rounds. The caching can be controlled using +calls like these: + + clearcache($key); + clearallcache(); + + disablecache(); + enablecache(); + +=head1 INHERITANCE + +Benchmark inherits from no other class, except of course +for Exporter. + +=head1 CAVEATS + +The real time timing is done using time(2) and +the granularity is therefore only one second. + +Short tests may produce negative figures because perl +can appear to take longer to execute the empty loop +than a short test; try: + + timethis(100,'1'); + +The system time of the null loop might be slightly +more than the system time of the loop with the actual +code and therefore the difference might end up being < 0. + +More documentation is needed :-( especially for styles and formats. + +=head1 AUTHORS + +Jarkko Hietaniemi <Jarkko.Hietaniemi@hut.fi>, +Tim Bunce <Tim.Bunce@ig.co.uk> + +=head1 MODIFICATION HISTORY + +September 8th, 1994; by Tim Bunce. + +=cut + # Purpose: benchmark running times of code. # # diff --git a/lib/Carp.pm b/lib/Carp.pm index c847b77b36..ba21d9c625 100644 --- a/lib/Carp.pm +++ b/lib/Carp.pm @@ -1,5 +1,29 @@ package Carp; +=head1 NAME + +carp - warn of errors (from perspective of caller) + +croak - die of errors (from perspective of caller) + +confess - die of errors with stack backtrace + +=head1 SYNOPSIS + + use Carp; + croak "We're outta here!"; + +=head1 DESCRIPTION + +The Carp routines are useful in your own modules because +they act like die() or warn(), but report where the error +was in the code they were called from. Thus if you have a +routine Foo() that has a carp() in it, then the carp() +will report the error as occurring where Foo() was called, +not where carp() was called. + +=cut + # This package implements handy routines for modules that wish to throw # exceptions outside of the current package. diff --git a/lib/Cwd.pm b/lib/Cwd.pm index 20b175c81d..af1167dfc8 100644 --- a/lib/Cwd.pm +++ b/lib/Cwd.pm @@ -3,6 +3,35 @@ require 5.000; require Exporter; use Config; +=head1 NAME + +getcwd - get pathname of current working directory + +=head1 SYNOPSIS + + require Cwd; + $dir = Cwd::getcwd(); + + use Cwd; + $dir = getcwd(); + + use Cwd 'chdir'; + chdir "/tmp"; + print $ENV{'PWD'}; + +=head1 DESCRIPTION + +The getcwd() function re-implements the getcwd(3) (or getwd(3)) functions +in Perl. If you ask to override your chdir() built-in function, then your +PWD environment variable will be kept up to date. (See +L<perlsub/Overriding builtin functions>.) + +The fastgetcwd() function looks the same as getcwd(), but runs faster. +It's also more dangerous because you might conceivably chdir() out of a +directory that you can't chdir() back into. + +=cut + @ISA = qw(Exporter); @EXPORT = qw(getcwd fastcwd); @EXPORT_OK = qw(chdir); diff --git a/lib/English.pm b/lib/English.pm index d40d28af7d..d82ba2cf52 100644 --- a/lib/English.pm +++ b/lib/English.pm @@ -3,6 +3,32 @@ package English; require Exporter; @ISA = (Exporter); +=head1 NAME + +English - use nice English (or awk) names for ugly punctuation variables + +=head1 SYNOPSIS + + use English; + ... + if ($ERRNO =~ /denied/) { ... } + +=head1 DESCRIPTION + +This module provides aliases for the built-in variables whose +names no one seems to like to read. Variables with side-effects +which get triggered just by accessing them (like $0) will still +be affected. + +For those variables that have an B<awk> version, both long +and short English alternatives are provided. For example, +the C<$/> variable can be referred to either $RS or +$INPUT_RECORD_SEPARATOR if you are using the English module. + +See L<perlvar> for a complete list of these. + +=cut + local $^W = 0; # Grandfather $NAME import diff --git a/lib/Exporter.pm b/lib/Exporter.pm index add5657fac..ca1ff3547c 100644 --- a/lib/Exporter.pm +++ b/lib/Exporter.pm @@ -2,31 +2,40 @@ package Exporter; =head1 Comments -If the first entry in an import list begins with /, ! or : then -treat the list as a series of specifications which either add to -or delete from the list of names to import. They are processed -left to right. Specifications are in the form: +If the first entry in an import list begins with !, : or / then the +list is treated as a series of specifications which either add to or +delete from the list of names to import. They are processed left to +right. Specifications are in the form: - [!]/pattern/ All names in @EXPORT and @EXPORT_OK which match [!]name This name only - [!]:tag All names in $EXPORT_TAGS{":tag"} [!]:DEFAULT All names in @EXPORT + [!]:tag All names in $EXPORT_TAGS{tag} anonymous list + [!]/pattern/ All names in @EXPORT and @EXPORT_OK which match -e.g., Foo.pm defines: +A leading ! indicates that matching names should be deleted from the +list of names to import. If the first specification is a deletion it +is treated as though preceded by :DEFAULT. If you just want to import +extra names in addition to the default set you will still need to +include :DEFAULT explicitly. + +e.g., Module.pm defines: @EXPORT = qw(A1 A2 A3 A4 A5); @EXPORT_OK = qw(B1 B2 B3 B4 B5); - %EXPORT_TAGS = (':T1' => [qw(A1 A2 B1 B2)], ':T2' => [qw(A1 A2 B3 B4)]); + %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]); Note that you cannot use tags in @EXPORT or @EXPORT_OK. Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK. Application says: - use Module qw(:T2 !B3 A3); + use Module qw(:DEFAULT :T2 !B3 A3); use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET); use POSIX qw(/^S_/ acos asin atan /^E/ !/^EXIT/); +You can set C<$Exporter::Verbose=1;> to see how the specifications are +being processed and what is actually being imported into modules. + =cut require 5.001; @@ -110,7 +119,7 @@ sub export { } } } - die "Can't continue with import errors.\n" if $oops; + Carp::croak("Can't continue with import errors.\n") if $oops; } else { @imports = @exports; diff --git a/lib/ExtUtils/MakeMaker.pm b/lib/ExtUtils/MakeMaker.pm index fb2dc14af4..0e3d0497f4 100644 --- a/lib/ExtUtils/MakeMaker.pm +++ b/lib/ExtUtils/MakeMaker.pm @@ -1,6 +1,6 @@ package ExtUtils::MakeMaker; -$Version = 4.094; # Last edited 17 Apr 1995 by Andy Dougherty +$Version = 4.095; # Last edited 17 Apr 1995 by Andy Dougherty use Config; use Carp; @@ -835,7 +835,7 @@ EOM } -sub init_dirscan { # --- File and Directory Lists (.xs .pm etc) +sub init_dirscan { # --- File and Directory Lists (.xs .pm .pod etc) my($name, %dir, %xs, %c, %h, %ignore, %pl_files); local(%pm); #the sub in find() has to see this hash @@ -853,7 +853,7 @@ sub init_dirscan { # --- File and Directory Lists (.xs .pm etc) $c{$name} = 1; } elsif ($name =~ /\.h$/){ $h{$name} = 1; - } elsif ($name =~ /\.p[ml]$/){ + } elsif ($name =~ /\.(p[ml]|pod)$/){ $pm{$name} = "\$(INST_LIBDIR)/$name"; } elsif ($name =~ /\.PL$/ && $name ne "Makefile.PL") { ($pl_files{$name} = $name) =~ s/\.PL$// ; @@ -2336,27 +2336,49 @@ F<E<lt>bailey@HMIVAX.HUMGEN.UPENN.EDUE<gt>>. =head1 MODIFICATION HISTORY v1, August 1994; by Andreas Koenig. Based on Andy Dougherty's Makefile.SH. + v2, September 1994 by Tim Bunce. + v3.0 October 1994 by Tim Bunce. + v3.1 November 11th 1994 by Tim Bunce. + v3.2 November 18th 1994 by Tim Bunce. + v3.3 November 27th 1994 by Andreas Koenig. + v3.4 December 7th 1994 by Andreas Koenig and Tim Bunce. + v3.5 December 15th 1994 by Tim Bunce. + v3.6 December 15th 1994 by Tim Bunce. + v3.7 December 30th 1994 By Tim Bunce + v3.8 January 17th 1995 By Andreas Koenig and Tim Bunce + v3.9 January 19th 1995 By Tim Bunce + v3.10 January 23rd 1995 By Tim Bunce + v3.11 January 24th 1995 By Andreas Koenig + v4.00 January 24th 1995 By Tim Bunce + v4.01 January 25th 1995 By Tim Bunce + v4.02 January 29th 1995 By Andreas Koenig + v4.03 January 30th 1995 By Andreas Koenig + v4.04 Februeary 5th 1995 By Andreas Koenig + v4.05 February 8th 1995 By Andreas Koenig + v4.06 February 10th 1995 By Andreas Koenig + v4.061 February 12th 1995 By Andreas Koenig + v4.08 - 4.085 February 14th-21st 1995 by Andreas Koenig Introduces EXE_FILES and INST_EXE for installing executable scripts @@ -2384,7 +2406,7 @@ Variable LIBPERL_A enables indirect setting of the switches -DEMBED, old_extliblist() code deleted, new_extliblist() renamed to extliblist(). Improved algorithm in extliblist, that returns ('','','') if no -library has been found, even if a -L directory has been found. +library has been found, even if a C<-L> directory has been found. Fixed a bug that didn't allow lib/ directory work as documented. @@ -2436,7 +2458,7 @@ v4.091 April 3 1995 by Andy Dougherty Another attempt to fix writedoc() from Dean Roehrich. -v4.092 April 11 1994 by Andreas Koenig +v4.092 April 11 1995 by Andreas Koenig Fixed a docu bug in hint file description. Added printing of a warning from eval in the hintfile section if the eval has errors. Moved @@ -2456,7 +2478,7 @@ line for the linking of a new static perl. Minor cosmetics. -v4.093 April 12 1994 by Andy Dougherty +v4.093 April 12 1995 by Andy Dougherty Rename distclean target to plain dist. Insert a dummy distclean target that's the same as realclean. This is more consistent with the @@ -2468,10 +2490,16 @@ are handled. Include Tim's suggestions about $verbose and more careful substitution of $(CC) for $Config{'cc'}. -v4.094 April 12 1994 by Andy Dougherty +v4.094 April 12 1995 by Andy Dougherty Include Andreas' improvement of $(CC) detection. +v4.095 May 30 1995 by Andy Dougherty + +Include installation of .pod and .pm files. + +Space out documentation for better printing with pod2man. + =head1 NOTES MakeMaker development work still to be done: diff --git a/lib/ExtUtils/xsubpp b/lib/ExtUtils/xsubpp index 21bbc4edee..3be47e005c 100755 --- a/lib/ExtUtils/xsubpp +++ b/lib/ExtUtils/xsubpp @@ -50,12 +50,97 @@ No environment variables are used. Larry Wall +=head1 MODIFICATION HISTORY + +=head2 1.0 + +I<xsubpp> as released with Perl 5.000 + +=head2 1.1 + +I<xsubpp> as released with Perl 5.001 + +=head2 1.2 + +Changes by Paul Marquess <pmarquess@bfsec.bt.co.uk>, 22 May 1995. + +=over 5 + +=item 1. + +Added I<xsubpp> version number for the first time. As previous releases +of I<xsubpp> did not have a formal version number, a numbering scheme +has been applied retrospectively. + +=item 2. + +If OUTPUT: is being used to specify output parameters and RETVAL is +also to be returned, it is now no longer necessary for the user to +ensure that RETVAL is specified last. + +=item 3. + +The I<xsubpp> version number, the .xs filename and a time stamp are +written to the generated .c file as a comment. + +=item 4. + +When I<xsubpp> is parsing the definition of both the input parameters +and the OUTPUT parameters, any duplicate definitions will be noted and +ignored. + +=item 5. + +I<xsubpp> is slightly more forgiving with extra whitespace. + +=back + +=head2 1.3 + +Changes by Paul Marquess <pmarquess@bfsec.bt.co.uk>, 23 May 1995. + +=over 5 + +=item 1. + +More whitespace restrictions have been relaxed. In particular some +cases where a tab character was used to delimit fields has been +removed. In these cases any whitespace will now suffice. + +The specific places where changes have been made are in the TYPEMAP +section of a typemap file and the input and OUTPUT: parameter +declarations sections in a .xs file. + +=item 2. + +More error checking added. + +Before processing each typemap file I<xsubpp> now checks that it is a +text file. If not an warning will be displayed. In addition, a warning +will be displayed if it is not possible to open the typemap file. + +In the TYPEMAP section of a typemap file, an error will be raised if +the line does not have 2 columns. + +When parsing input parameter declarations check that there is at least +a type and name pair. + +=back + +=head2 1.4 + +When parsing the OUTPUT arguments check that they are all present in +the corresponding input argument definitions. + =head1 SEE ALSO perl(1) =cut +# Global Constants +$XSUBPP_version = "1.4" ; + $usage = "Usage: xsubpp [-C++] [-except] [-typemap typemap] file.xs\n"; SWITCH: while ($ARGV[0] =~ s/^-//) { @@ -75,6 +160,27 @@ if ($pwd =~ /unrecognized command verb/) { $Is_VMS = 1; $pwd = $ENV{DEFAULT} } or ($dir, $filename) = ('.', $ARGV[0]); chdir($dir); +sub TrimWhitespace +{ + $_[0] =~ s/^\s+|\s+$//go ; +} + +sub TidyType +{ + local ($_) = @_ ; + + # rationalise any '*' by joining them into bunches and removing whitespace + s#\s*(\*+)\s*#$1#g; + + # change multiple whitespace into a single space + s/\s+/ /g ; + + # trim leading & trailing whitespace + TrimWhitespace($_) ; + + $_ ; +} + $typemap = shift @ARGV; foreach $typemap (@tm) { die "Can't find $typemap in $pwd\n" unless -r $typemap; @@ -83,7 +189,12 @@ unshift @tm, qw(../../../../lib/ExtUtils/typemap ../../../lib/ExtUtils/typemap ../../lib/ExtUtils/typemap ../../../typemap ../../typemap ../typemap typemap); foreach $typemap (@tm) { - open(TYPEMAP, $typemap) || next; + next unless -e $typemap ; + # skip directories, binary files etc. + warn("Warning: ignoring non-text typemap file '$typemap'\n"), next + unless -T $typemap ; + open(TYPEMAP, $typemap) + or warn ("Warning: could not open typemap file '$typemap': $!\n"), next; $mode = Typemap; $current = \$junk; while (<TYPEMAP>) { @@ -93,8 +204,16 @@ foreach $typemap (@tm) { if (/^TYPEMAP\s*$/) { $mode = Typemap, next } if ($mode eq Typemap) { chop; - ($typename, $kind) = split(/\t+/, $_, 2); - $type_kind{$typename} = $kind if $kind ne ''; + my $line = $_ ; + TrimWhitespace($_) ; + # skip blank lines and comment lines + next if /^$/ or /^#/ ; + my @words = split (' ') ; + blurt("Error: File '$typemap' Line $. '$line' TYPEMAP entry needs 2 columns\n"), next + unless @words >= 2 ; + my $kind = pop @words ; + TrimWhitespace($kind) ; + $type_kind{TidyType("@words")} = $kind ; } elsif ($mode eq Input) { if (/^\s/) { @@ -132,7 +251,19 @@ sub Q { $text; } -open(F, $filename) || die "cannot open $filename\n"; +# Identify the version of xsubpp used +$TimeStamp = localtime ; +print <<EOM ; +/* + * This file was generated automatically by xsubpp version $XSUBPP_version + * from $filename on $TimeStamp + * + */ + +EOM + + +open(F, $filename) or die "cannot open $filename: $!\n"; while (<F>) { last if ($Module, $foo, $Package, $foo1, $Prefix) = @@ -196,9 +327,11 @@ while (&fetch_para) { undef($class); undef($static); undef($elipsis); + undef($wantRETVAL) ; + undef(%arg_list) ; # extract return type, function name and arguments - $ret_type = shift(@line); + $ret_type = TidyType(shift(@line)); if ($ret_type =~ /^BOOT:/) { push (@BootCode, @line, "", "") ; next ; @@ -325,11 +458,20 @@ EOF $_ = shift(@line); last if /^\s*NOT_IMPLEMENTED_YET/; last if /^\s*(PPCODE|CODE|OUTPUT|CLEANUP|CASE)\s*:/; - ($var_type, $var_name, $var_init) = - /\s*([^\t]+)\s*([^\s=]+)\s*(=.*)?/; - # Catch common errors. More error checking required here. - blurt("Error: no tab in $pname argument declaration '$_'\n") - unless (m/\S+\s*\t\s*\S+/); + + TrimWhitespace($_) ; + # skip blank lines + next if /^$/ ; + my $line = $_ ; + # check for optional initialisation code + my $var_init = $1 if s/\s*(=.*)$// ; + + my @words = split (' ') ; + blurt("Error: invalid argument declaration '$line'"), next + unless @words >= 2 ; + my $var_name = pop @words ; + my $var_type = "@words" ; + # catch C style argument declaration (this could be made alowable syntax) warn("Warning: ignored semicolon in $pname argument declaration '$_'\n") if ($var_name =~ s/;//g); # eg SV *<tab>name; @@ -340,6 +482,11 @@ EOF $var_name =~ s/^&//; $var_addr{$var_name} = 1; } + + # Check for duplicate definitions + blurt ("Error: duplicate definition of argument '$var_name' ignored"), next + if $arg_list{$var_name} ++ ; + $thisdone |= $var_name eq "THIS"; $retvaldone |= $var_name eq "RETVAL"; $var_types{$var_name} = $var_type; @@ -425,29 +572,48 @@ EOF $func_name = $2; } print "$func_name($func_args);\n"; - &generate_output($ret_type, 0, "RETVAL") - unless $ret_type eq "void"; + $wantRETVAL = 1 + unless $ret_type eq "void"; } } # do output variables if (/^\s*OUTPUT\s*:/) { + my $gotRETVAL ; + my %outargs ; while (@line) { $_ = shift(@line); last if /^\s*CLEANUP\s*:/; - s/^\s+//; - ($outarg, $outcode) = split(/\t+/); + TrimWhitespace($_) ; + next if /^$/ ; + my ($outarg, $outcode) = /^(\S+)\s*(.*)/ ; + if (!$gotRETVAL and $outarg eq 'RETVAL') { + # deal with RETVAL last + push(@line, $_) ; + $gotRETVAL = 1 ; + undef ($wantRETVAL) ; + next ; + } + blurt ("Error: duplicate OUTPUT argument '$outarg' ignored"), next + if $outargs{$outarg} ++ ; + blurt ("Error: OUTPUT $outarg not an argument"), next + unless defined($args_match{$outarg}); + blurt("Error: No input definition for OUTPUT argument '$outarg' - ignored"), next + unless defined $var_types{$outarg} ; if ($outcode) { print "\t$outcode\n"; } else { - die "$outarg not an argument" - unless defined($args_match{$outarg}); $var_num = $args_match{$outarg}; &generate_output($var_types{$outarg}, $var_num, $outarg); } } } + + # all OUTPUT done, so now push the return value on the stack + &generate_output($ret_type, 0, "RETVAL") + if $wantRETVAL ; + # do cleanup if (/^\s*CLEANUP\s*:/) { while (@line) { @@ -533,7 +699,8 @@ sub generate_init { local($ntype); local($tk); - blurt("'$type' not in typemap"), return unless defined($type_kind{$type}); + $type = TidyType($type) ; + blurt("Error: '$type' not in typemap"), return unless defined($type_kind{$type}); ($ntype = $type) =~ s/\s*\*/Ptr/g; $subtype = $ntype; $subtype =~ s/Ptr$//; @@ -570,10 +737,11 @@ sub generate_output { local($argoff) = $num - 1; local($ntype); + $type = TidyType($type) ; if ($type =~ /^array\(([^,]*),(.*)\)/) { print "\tsv_setpvn($arg, (char *)$var, $2 * sizeof($1)), XFree((char *)$var);\n"; } else { - blurt("'$type' not in typemap"), return + blurt("Error: '$type' not in typemap"), return unless defined($type_kind{$type}); ($ntype = $type) =~ s/\s*\*/Ptr/g; $ntype =~ s/\(\)//g; diff --git a/lib/File/Basename.pm b/lib/File/Basename.pm index 5e09ae4977..596bff4494 100644 --- a/lib/File/Basename.pm +++ b/lib/File/Basename.pm @@ -1,5 +1,116 @@ package File::Basename; +=head1 NAME + +Basename - parse file specifications + +fileparse - split a pathname into pieces + +basename - extract just the filename from a path + +dirname - extract just the directory from a path + +=head1 SYNOPSIS + + use File::Basename; + + ($name,$path,$suffix) = fileparse($fullname,@suffixlist) + fileparse_set_fstype($os_string); + $basename = basename($fullname,@suffixlist); + $dirname = dirname($fullname); + + ($name,$path,$suffix) = fileparse("lib/File/Basename.pm","\.pm"); + fileparse_set_fstype("VMS"); + $basename = basename("lib/File/Basename.pm",".pm"); + $dirname = dirname("lib/File/Basename.pm"); + +=head1 DESCRIPTION + +These routines allow you to parse file specifications into useful +pieces using the syntax of different operating systems. + +=over 4 + +=item fileparse_set_fstype + +You select the syntax via the routine fileparse_set_fstype(). +If the argument passed to it contains one of the substrings +"VMS", "MSDOS", or "MacOS", the file specification syntax of that +operating system is used in future calls to fileparse(), +basename(), and dirname(). If it contains none of these +substrings, UNIX syntax is used. This pattern matching is +case-insensitive. If you've selected VMS syntax, and the file +specification you pass to one of these routines contains a "/", +they assume you are using UNIX emulation and apply the UNIX syntax +rules instead, for that function call only. + +If you haven't called fileparse_set_fstype(), the syntax is chosen +by examining the "osname" entry from the C<Config> package +according to these rules. + +=item fileparse + +The fileparse() routine divides a file specification into three +parts: a leading B<path>, a file B<name>, and a B<suffix>. The +B<path> contains everything up to and including the last directory +separator in the input file specification. The remainder of the input +file specification is then divided into B<name> and B<suffix> based on +the optional patterns you specify in C<@suffixlist>. Each element of +this list is interpreted as a regular expression, and is matched +against the end of B<name>. If this succeeds, the matching portion of +B<name> is removed and prepended to B<suffix>. By proper use of +C<@suffixlist>, you can remove file types or versions for examination. + +You are guaranteed that if you concatenate B<path>, B<name>, and +B<suffix> together in that order, the result will be identical to the +input file specification. + +=back + +=head1 EXAMPLES + +Using UNIX file syntax: + + ($base,$path,$type) = fileparse('/virgil/aeneid/draft.book7', + '\.book\d+'); + +would yield + + $base eq 'draft' + $path eq '/virgil/aeneid', + $tail eq '.book7' + +Similarly, using VMS syntax: + + ($name,$dir,$type) = fileparse('Doc_Root:[Help]Rhetoric.Rnh', + '\..*'); + +would yield + + $name eq 'Rhetoric' + $dir eq 'Doc_Root:[Help]' + $type eq '.Rnh' + +=item C<basename> + +The basename() routine returns the first element of the list produced +by calling fileparse() with the same arguments. It is provided for +compatibility with the UNIX shell command basename(1). + +=item C<dirname> + +The dirname() routine returns the directory portion of the input file +specification. When using VMS or MacOS syntax, this is identical to the +second element of the list produced by calling fileparse() with the same +input file specification. When using UNIX or MSDOS syntax, the return +value conforms to the behavior of the UNIX shell command dirname(1). This +is usually the same as the behavior of fileparse(), but differs in some +cases. For example, for the input file specification F<lib/>, fileparse() +considers the directory name to be F<lib/>, while dirname() considers the +directory name to be F<.>). + +=cut + require 5.000; use Config; require Exporter; @@ -62,7 +173,7 @@ sub fileparse_set_fstype { sub fileparse { my($fullname,@suffices) = @_; my($fstype) = $Fileparse_fstype; - my($dirpath,$tail,$suffix,$idx); + my($dirpath,$tail,$suffix); if ($fstype =~ /^VMS/i) { if ($fullname =~ m#/#) { $fstype = '' } # We're doing Unix emulation @@ -84,6 +195,7 @@ sub fileparse { } if (@suffices) { + $tail = ''; foreach $suffix (@suffices) { if ($basename =~ /($suffix)$/) { $tail = $1 . $tail; diff --git a/lib/File/CheckTree.pm b/lib/File/CheckTree.pm index a440bda71e..a39308b6c9 100644 --- a/lib/File/CheckTree.pm +++ b/lib/File/CheckTree.pm @@ -2,6 +2,45 @@ package File::CheckTree; require 5.000; require Exporter; +=head1 NAME + +validate - run many filetest checks on a tree + +=head1 SYNOPSIS + + use File::CheckTree; + + $warnings += validate( q{ + /vmunix -e || die + /boot -e || die + /bin cd + csh -ex + csh !-ug + sh -ex + sh !-ug + /usr -d || warn "What happened to $file?\n" + }); + +=head1 DESCRIPTION + +The validate() routine takes a single multiline string consisting of +lines containing a filename plus a file test to try on it. (The +file test may also be a "cd", causing subsequent relative filenames +to be interpreted relative to that directory.) After the file test +you may put C<|| die> to make it a fatal error if the file test fails. +The default is C<|| warn>. The file test may optionally have a "!' prepended +to test for the opposite condition. If you do a cd and then list some +relative filenames, you may want to indent them slightly for readability. +If you supply your own die() or warn() message, you can use $file to +interpolate the filename. + +Filetests may be bunched: "-rwx" tests for all of C<-r>, C<-w>, and C<-x>. +Only the first failed test of the bunch will produce a warning. + +The routine returns the number of warnings issued. + +=cut + @ISA = qw(Exporter); @EXPORT = qw(validate); diff --git a/lib/File/Find.pm b/lib/File/Find.pm index c7b0051ce2..ba495a140a 100644 --- a/lib/File/Find.pm +++ b/lib/File/Find.pm @@ -5,6 +5,61 @@ use Config; use Cwd; use File::Basename; +=head1 NAME + +find - traverse a file tree + +finddepth - traverse a directory structure depth-first + +=head1 SYNOPSIS + + use File::Find; + find(\&wanted, '/foo','/bar'); + sub wanted { ... } + + use File::Find; + finddepth(\&wanted, '/foo','/bar'); + sub wanted { ... } + +=head1 DESCRIPTION + +The wanted() function does whatever verifications you want. $dir contains +the current directory name, and $_ the current filename within that +directory. $name contains C<"$dir/$_">. You are chdir()'d to $dir when +the function is called. The function may set $prune to prune the tree. + +This library is primarily for the C<find2perl> tool, which when fed, + + find2perl / -name .nfs\* -mtime +7 \ + -exec rm -f {} \; -o -fstype nfs -prune + +produces something like: + + sub wanted { + /^\.nfs.*$/ && + (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) && + int(-M _) > 7 && + unlink($_) + || + ($nlink || (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_))) && + $dev < 0 && + ($prune = 1); + } + +Set the variable $dont_use_nlink if you're using AFS, since AFS cheats. + +C<finddepth> is just like C<find>, except that it does a depth-first +search. + +Here's another interesting wanted function. It will find all symlinks +that don't resolve: + + sub wanted { + -l && !-e && print "bogus link: $name\n"; + } + +=cut + @ISA = qw(Exporter); @EXPORT = qw(find finddepth $name $dir); diff --git a/lib/FileHandle.pm b/lib/FileHandle.pm index c45f446667..9408717a7c 100644 --- a/lib/FileHandle.pm +++ b/lib/FileHandle.pm @@ -2,6 +2,55 @@ package FileHandle; # Note that some additional FileHandle methods are defined in POSIX.pm. +=head1 NAME + +FileHandle - supply object methods for filehandles + +cacheout - keep more files open than the system permits + +=head1 SYNOPSIS + + use FileHandle; + autoflush STDOUT 1; + + cacheout($path); + print $path @data; + +=head1 DESCRIPTION + +See L<perlvar> for complete descriptions of each of the following supported C<FileHandle> +methods: + + print + autoflush + output_field_separator + output_record_separator + input_record_separator + input_line_number + format_page_number + format_lines_per_page + format_lines_left + format_name + format_top_name + format_line_break_characters + format_formfeed + +The cacheout() function will make sure that there's a filehandle +open for writing available as the pathname you give it. It automatically +closes and re-opens files if you exceed your system file descriptor maximum. + +=head1 BUGS + +F<sys/param.h> lies with its C<NOFILE> define on some systems, +so you may have to set $cacheout::maxopen yourself. + +Due to backwards compatibility, all filehandles resemble objects +of class C<FileHandle>, or actually classes derived from that class. +They actually aren't. Which means you can't derive your own +class from C<FileHandle> and inherit those methods. + +=cut + require 5.000; use English; use Exporter; diff --git a/lib/Getopt/Long.pm b/lib/Getopt/Long.pm index 48cda7e12a..43e1e58e59 100644 --- a/lib/Getopt/Long.pm +++ b/lib/Getopt/Long.pm @@ -5,6 +5,144 @@ require Exporter; @ISA = qw(Exporter); @EXPORT = qw(GetOptions); +=head1 NAME + +GetOptions - extended getopt processing + +=head1 SYNOPSIS + + use Getopt::Long; + $result = GetOptions (...option-descriptions...); + +=head1 DESCRIPTION + +The Getopt::Long module implements an extended getopt function called +GetOptions(). This function adheres to the new syntax (long option names, +no bundling). It tries to implement the better functionality of +traditional, GNU and POSIX getopt() functions. + +Each description should designate a valid Perl identifier, optionally +followed by an argument specifier. + +Values for argument specifiers are: + + <none> option does not take an argument + ! option does not take an argument and may be negated + =s :s option takes a mandatory (=) or optional (:) string argument + =i :i option takes a mandatory (=) or optional (:) integer argument + =f :f option takes a mandatory (=) or optional (:) real number argument + +If option "name" is set, it will cause the Perl variable $opt_name to +be set to the specified value. The calling program can use this +variable to detect whether the option has been set. Options that do +not take an argument will be set to 1 (one). + +Options that take an optional argument will be defined, but set to '' +if no actual argument has been supplied. + +If an "@" sign is appended to the argument specifier, the option is +treated as an array. Value(s) are not set, but pushed into array +@opt_name. + +Options that do not take a value may have an "!" argument specifier to +indicate that they may be negated. E.g. "foo!" will allow B<-foo> (which +sets $opt_foo to 1) and B<-nofoo> (which will set $opt_foo to 0). + +The option name may actually be a list of option names, separated by +'|'s, e.g. B<"foo|bar|blech=s". In this example, options 'bar' and +'blech' will set $opt_foo instead. + +Option names may be abbreviated to uniqueness, depending on +configuration variable $autoabbrev. + +Dashes in option names are allowed (e.g. pcc-struct-return) and will +be translated to underscores in the corresponding Perl variable (e.g. +$opt_pcc_struct_return). Note that a lone dash "-" is considered an +option, corresponding Perl identifier is $opt_ . + +A double dash "--" signals end of the options list. + +If the first option of the list consists of non-alphanumeric +characters only, it is interpreted as a generic option starter. +Everything starting with one of the characters from the starter will +be considered an option. + +The default values for the option starters are "-" (traditional), "--" +(POSIX) and "+" (GNU, being phased out). + +Options that start with "--" may have an argument appended, separated +with an "=", e.g. "--foo=bar". + +If configuration variable $getopt_compat is set to a non-zero value, +options that start with "+" may also include their arguments, +e.g. "+foo=bar". + +A return status of 0 (false) indicates that the function detected +one or more errors. + +=head1 EXAMPLES + +If option "one:i" (i.e. takes an optional integer argument), then +the following situations are handled: + + -one -two -> $opt_one = '', -two is next option + -one -2 -> $opt_one = -2 + +Also, assume "foo=s" and "bar:s" : + + -bar -xxx -> $opt_bar = '', '-xxx' is next option + -foo -bar -> $opt_foo = '-bar' + -foo -- -> $opt_foo = '--' + +In GNU or POSIX format, option names and values can be combined: + + +foo=blech -> $opt_foo = 'blech' + --bar= -> $opt_bar = '' + --bar=-- -> $opt_bar = '--' + +=over 12 + +=item $autoabbrev + +Allow option names to be abbreviated to uniqueness. +Default is 1 unless environment variable +POSIXLY_CORRECT has been set. + +=item $getopt_compat + +Allow '+' to start options. +Default is 1 unless environment variable +POSIXLY_CORRECT has been set. + +=item $option_start + +Regexp with option starters. +Default is (--|-) if environment variable +POSIXLY_CORRECT has been set, (--|-|\+) otherwise. + +=item $order + +Whether non-options are allowed to be mixed with +options. +Default is $REQUIRE_ORDER if environment variable +POSIXLY_CORRECT has been set, $PERMUTE otherwise. + +=item $ignorecase + +Ignore case when matching options. Default is 1. + +=item $debug + +Enable debugging output. Default is 0. + +=back + +=head1 NOTE + +Does not yet use the Exporter--or even packages!! +Thus, it's not a real module. + +=cut # newgetopt.pl -- new options parsing @@ -316,7 +454,7 @@ sub GetOptions { # Double dash is option list terminator. if ( $opt eq $argend ) { - unshift (@ret, @ARGV) if $order == $PERMUTE; + unshift (@ARGV, @ret) if $order == $PERMUTE; return ($error == 0); } elsif ( $opt =~ /^$genprefix/ ) { diff --git a/lib/Getopt/Std.pm b/lib/Getopt/Std.pm index e1de3b531f..4117ca7f8b 100644 --- a/lib/Getopt/Std.pm +++ b/lib/Getopt/Std.pm @@ -2,6 +2,30 @@ package Getopt::Std; require 5.000; require Exporter; +=head1 NAME + +getopt - Process single-character switches with switch clustering + +getopts - Process single-character switches with switch clustering + +=head1 SYNOPSIS + + use Getopt::Std; + getopt('oDI'); # -o, -D & -I take arg. Sets opt_* as a side effect. + getopts('oif:'); # -o & -i are boolean flags, -f takes an argument + # Sets opt_* as a side effect. + +=head1 DESCRIPTION + +The getopt() functions processes single-character switches with switch +clustering. Pass one argument which is a string containing all switches +that take an argument. For each switch found, sets $opt_x (where x is the +switch name) to the value of the argument, or 1 if no argument. Switches +which take an argument don't care whether there is a space between the +switch and the argument. + +=cut + @ISA = qw(Exporter); @EXPORT = qw(getopt getopts); @@ -64,7 +88,7 @@ sub getopts { ($first,$rest) = ($1,$2); $pos = index($argumentative,$first); if($pos >= 0) { - if($args[$pos+1] eq ':') { + if(defined($args[$pos+1]) and ($args[$pos+1] eq ':')) { shift(@ARGV); if($rest eq '') { ++$errs unless @ARGV; diff --git a/lib/I18N/Collate.pm b/lib/I18N/Collate.pm index 52c78abe83..35c8025367 100644 --- a/lib/I18N/Collate.pm +++ b/lib/I18N/Collate.pm @@ -1,5 +1,39 @@ package I18N::Collate; +=head1 NAME + +Collate - compare 8-bit scalar data according to the current locale + +=head1 SYNOPSIS + + use Collate; + setlocale(LC_COLLATE, 'locale-of-your-choice'); + $s1 = new Collate "scalar_data_1"; + $s2 = new Collate "scalar_data_2"; + +=head1 DESCRIPTION + +This module provides you with objects that will collate +according to your national character set, providing the +POSIX setlocale() function should be supported on your system. + +You can compare $s1 and $s2 above with + + $s1 le $s2 + +to extract the data itself, you'll need a dereference: $$s1 + +This uses POSIX::setlocale The basic collation conversion is done by +strxfrm() which terminates at NUL characters being a decent C routine. +collate_xfrm() handles embedded NUL characters gracefully. Due to C<cmp> +and overload magic, C<lt>, C<le>, C<eq>, C<ge>, and C<gt> work also. The +available locales depend on your operating system; try whether C<locale +-a> shows them or the more direct approach C<ls /usr/lib/nls/loc> or C<ls +/usr/lib/nls>. The locale names are probably something like +"xx_XX.(ISO)?8859-N". + +=cut + # Collate.pm # # Author: Jarkko Hietaniemi <Jarkko.Hietaniemi@hut.fi> diff --git a/lib/IPC/Open2.pm b/lib/IPC/Open2.pm index c59c7d6897..71f89f35c2 100644 --- a/lib/IPC/Open2.pm +++ b/lib/IPC/Open2.pm @@ -3,6 +3,51 @@ require 5.000; require Exporter; use Carp; +=head1 NAME + +IPC::Open2, open2 - open a process for both reading and writing + +=head1 SYNOPSIS + + use IPC::Open2; + $pid = open2('rdr', 'wtr', 'some cmd and args'); + # or + $pid = open2('rdr', 'wtr', 'some', 'cmd', 'and', 'args'); + +=head1 DESCRIPTION + +The open2() function spawns the given $cmd and connects $rdr for +reading and $wtr for writing. It's what you think should work +when you try + + open(HANDLE, "|cmd args"); + +open2() returns the process ID of the child process. It doesn't return on +failure: it just raises an exception matching C</^open2:/>. + +=head1 WARNING + +It will not create these file handles for you. You have to do this yourself. +So don't pass it empty variables expecting them to get filled in for you. + +Additionally, this is very dangerous as you may block forever. +It assumes it's going to talk to something like B<bc>, both writing to +it and reading from it. This is presumably safe because you "know" +that commands like B<bc> will read a line at a time and output a line at +a time. Programs like B<sort> that read their entire input stream first, +however, are quite apt to cause deadlock. + +The big problem with this approach is that if you don't have control +over source code being run in the the child process, you can't control what it does +with pipe buffering. Thus you can't just open a pipe to "cat -v" and continually +read and write a line from it. + +=head1 SEE ALSO + +See L<open3> for an alternative that handles STDERR as well. + +=cut + @ISA = qw(Exporter); @EXPORT = qw(open2); diff --git a/lib/IPC/Open3.pm b/lib/IPC/Open3.pm index 3426f19111..8d324ccb62 100644 --- a/lib/IPC/Open3.pm +++ b/lib/IPC/Open3.pm @@ -3,6 +3,31 @@ require 5.000; require Exporter; use Carp; +=head1 NAME + +IPC::Open3, open3 - open a process for reading, writing, and error handling + +=head1 SYNOPSIS + + $pid = open3('WTRFH', 'RDRFH', 'ERRFH' + 'some cmd and args', 'optarg', ...); + +=head1 DESCRIPTION + +Extremely similar to open2(), open3() spawns the given $cmd and +connects RDRFH for reading, WTRFH for writing, and ERRFH for errors. If +ERRFH is '', or the same as RDRFH, then STDOUT and STDERR of the child are +on the same file handle. + +If WTRFH begins with ">&", then WTRFH will be closed in the parent, and +the child will read from it directly. if RDRFH or ERRFH begins with +">&", then the child will send output directly to that file handle. In both +cases, there will be a dup(2) instead of a pipe(2) made. + +All caveats from open2() continue to apply. See L<open2> for details. + +=cut + @ISA = qw(Exporter); @EXPORT = qw(open3); diff --git a/lib/Net/Ping.pm b/lib/Net/Ping.pm index 2528f55255..cfc8f9f6a1 100644 --- a/lib/Net/Ping.pm +++ b/lib/Net/Ping.pm @@ -1,5 +1,44 @@ package Net::Ping; +=head1 NAME + +Net::Ping, pingecho - check a host for upness + +=head1 SYNOPSIS + + use Net::Ping; + print "'jimmy' is alive and kicking\n" if pingecho('jimmy', 10) ; + +=head1 DESCRIPTION + +This module contains routines to test for the reachability of remote hosts. +Currently the only routine implemented is pingecho(). + +pingecho() uses a TCP echo (I<not> an ICMP one) to determine if the +remote host is reachable. This is usually adequate to tell that a remote +host is available to rsh(1), ftp(1), or telnet(1) onto. + +=head2 Parameters + +=over 5 + +=item hostname + +The remote host to check, specified either as a hostname or as an IP address. + +=item timeout + +The timeout in seconds. If not specified it will default to 5 seconds. + +=back + +=head1 WARNING + +pingecho() uses alarm to implement the timeout, so don't set another alarm +while you are using it. + +=cut + # Authors: karrer@bernina.ethz.ch (Andreas Karrer) # pmarquess@bfsec.bt.co.uk (Paul Marquess) diff --git a/lib/Term/Complete.pm b/lib/Term/Complete.pm index 10b12a2b5c..97c71fe43f 100644 --- a/lib/Term/Complete.pm +++ b/lib/Term/Complete.pm @@ -37,7 +37,7 @@ CONFIG: { $erase2 = "\010"; } -sub complete { +sub Complete { $prompt = shift; if (ref $_[0] || $_[0] =~ /^\*/) { @cmp_lst = sort @{$_[0]}; diff --git a/lib/Text/Abbrev.pm b/lib/Text/Abbrev.pm index 77370d37c3..d12dfb36a6 100644 --- a/lib/Text/Abbrev.pm +++ b/lib/Text/Abbrev.pm @@ -2,6 +2,28 @@ package Text::Abbrev; require 5.000; require Exporter; +=head1 NAME + +abbrev - create an abbreviation table from a list + +=head1 SYNOPSIS + + use Abbrev; + abbrev *HASH, LIST + + +=head1 DESCRIPTION + +Stores all unambiguous truncations of each element of LIST +as keys key in the associative array indicated by C<*hash>. +The values are the original list elements. + +=head1 EXAMPLE + + abbrev(*hash,qw("list edit send abort gripe")); + +=cut + @ISA = qw(Exporter); @EXPORT = qw(abbrev); diff --git a/lib/Text/Tabs.pm b/lib/Text/Tabs.pm index c90d1aa672..fa866988cf 100644 --- a/lib/Text/Tabs.pm +++ b/lib/Text/Tabs.pm @@ -2,10 +2,10 @@ # expand and unexpand tabs as per the unix expand and # unexpand programs. # -# expand and unexpand operate on arrays of lines. Do not -# feed strings that contain newlines to them. +# expand and unexpand operate on arrays of lines. # # David Muir Sharnoff <muir@idiom.com> +# Version: 4/19/95 # package Text::Tabs; @@ -19,29 +19,45 @@ $tabstop = 8; sub expand { - my @l = @_; - for $_ (@l) { - 1 while s/^([^\t]*)(\t+)/ - $1 . (" " x - ($tabstop * length($2) - - (length($1) % $tabstop))) - /e; + my (@l) = @_; + my $l, @k; + my $nl; + for $l (@l) { + $nl = $/ if chomp($l); + @k = split($/,$l); + for $_ (@k) { + 1 while s/^([^\t]*)(\t+)/ + $1 . (" " x + ($tabstop * length($2) + - (length($1) % $tabstop))) + /e; + } + $l = join("\n",@k).$nl; } - return @l; + return @l if $#l > 0; + return $l[0]; } sub unexpand { - my @l = &expand(@_); + my (@l) = &expand(@_); my @e; - for $x (@l) { - @e = split(/(.{$tabstop})/,$x); - for $_ (@e) { - s/ +$/\t/; + my $k, @k; + my $nl; + for $k (@l) { + $nl = $/ if chomp($k); + @k = split($/,$k); + for $x (@k) { + @e = split(/(.{$tabstop})/,$x); + for $_ (@e) { + s/ +$/\t/; + } + $x = join('',@e); } - $x = join('',@e); + $k = join("\n",@k).$nl; } - return @l; + return @l if $#l > 0; + return $l[0]; } 1; diff --git a/lib/integer.pm b/lib/integer.pm index 74039bb962..a88ce6a77c 100644 --- a/lib/integer.pm +++ b/lib/integer.pm @@ -1,5 +1,26 @@ package integer; +=head1 NAME + +integer - Perl pragma to compute arithmetic in integer instead of double + +=head1 SYNOPSIS + + use integer; + $x = 10/3; + # $x is now 3, not 3.33333333333333333 + +=head1 DESCRIPTION + +This tells the compiler that it's okay to use integer operations +from here to the end of the enclosing BLOCK. On many machines, +this doesn't matter a great deal for most computations, but on those +without floating point hardware, it can make a big difference. + +See L<perlmod/Pragmatic Modules>. + +=cut + sub import { $^H |= 1; } diff --git a/lib/less.pm b/lib/less.pm index a95484ff76..5e055f3920 100644 --- a/lib/less.pm +++ b/lib/less.pm @@ -1,2 +1,19 @@ package less; + +=head1 NAME + +less - Perl pragma to request less of something from the compiler + +=head1 DESCRIPTION + +Currently unimplemented, this may someday be a compiler directive +to make certain trade-offs, such as perhaps + + use less 'memory'; + use less 'CPU'; + use less 'fat'; + + +=cut + 1; diff --git a/lib/sigtrap.pm b/lib/sigtrap.pm index 72b9cb6044..dd4df906fa 100644 --- a/lib/sigtrap.pm +++ b/lib/sigtrap.pm @@ -1,5 +1,27 @@ package sigtrap; +=head1 NAME + +sigtrap - Perl pragma to enable stack backtrace on unexpected signals + +=head1 SYNOPSIS + + use sigtrap; + use sigtrap qw(BUS SEGV PIPE SYS ABRT TRAP); + +=head1 DESCRIPTION + +The C<sigtrap> pragma initializes some default signal handlers that print +a stack dump of your Perl program, then sends itself a SIGABRT. This +provides a nice starting point if something horrible goes wrong. + +By default, handlers are installed for the ABRT, BUS, EMT, FPE, ILL, PIPE, +QUIT, SEGV, SYS, TERM, and TRAP signals. + +See L<perlmod/Pragmatic Modules>. + +=cut + require Carp; sub import { diff --git a/lib/strict.pm b/lib/strict.pm index adaf47c720..d35c6c105c 100644 --- a/lib/strict.pm +++ b/lib/strict.pm @@ -1,5 +1,73 @@ package strict; +=head1 NAME + +strict - Perl pragma to restrict unsafe constructs + +=head1 SYNOPSIS + + use strict; + + use strict "vars"; + use strict "refs"; + use strict "subs"; + + use strict; + no strict "vars"; + +=head1 DESCRIPTION + +If no import list is supplied, all possible restrictions are assumed. +(This is the safest mode to operate in, but is sometimes too strict for +casual programming.) Currently, there are three possible things to be +strict about: "subs", "vars", and "refs". + +=over 6 + +=item C<strict refs> + +This generates a runtime error if you +use symbolic references (see L<perlref>). + + use strict 'refs'; + $ref = \$foo; + print $$ref; # ok + $ref = "foo"; + print $$ref; # runtime error; normally ok + +=item C<strict vars> + +This generates a compile-time error if you access a variable that wasn't +localized via C<my()> or wasn't fully qualified. Because this is to avoid +variable suicide problems and subtle dynamic scoping issues, a merely +local() variable isn't good enough. See L<perlfunc/my> and +L<perlfunc/local>. + + use strict 'vars'; + $X::foo = 1; # ok, fully qualified + my $foo = 10; # ok, my() var + local $foo = 9; # blows up + +The local() generated a compile-time error because you just touched a global +name without fully qualifying it. + +=item C<strict subs> + +This disables the poetry optimization, +generating a compile-time error if you +try to use a bareword identifier that's not a subroutine. + + use strict 'subs'; + $SIG{PIPE} = Plumber; # blows up + $SIG{"PIPE"} = "Plumber"; # just fine + +=back + +See L<perlmod/Pragmatic Modules>. + + +=cut + sub bits { my $bits = 0; foreach $sememe (@_) { diff --git a/lib/subs.pm b/lib/subs.pm index 8b5835770f..0dbbaddd11 100644 --- a/lib/subs.pm +++ b/lib/subs.pm @@ -1,5 +1,23 @@ package subs; +=head1 NAME + +subs - Perl pragma to predeclare sub names + +=head1 SYNOPSIS + + use subs qw(frob); + frob 3..10; + +=head1 DESCRIPTION + +This will predeclare all the subroutine whose names are +in the list, allowing you to use them without parentheses +even before they're declared. + +See L<perlmod/Pragmatic Modules> and L<strict/subs>. + +=cut require 5.000; $ExportLevel = 0; diff --git a/pod/modpods/Abbrev.pod b/pod/modpods/Abbrev.pod deleted file mode 100644 index 85ec88ef85..0000000000 --- a/pod/modpods/Abbrev.pod +++ /dev/null @@ -1,19 +0,0 @@ -=head1 NAME - -abbrev - create an abbreviation table from a list - -=head1 SYNOPSIS - - use Abbrev; - abbrev *HASH, LIST - - -=head1 DESCRIPTION - -Stores all unambiguous truncations of each element of LIST -as keys key in the associative array indicated by C<*hash>. -The values are the original list elements. - -=head1 EXAMPLE - - abbrev(*hash,qw("list edit send abort gripe")); diff --git a/pod/modpods/AnyDBMFile.pod b/pod/modpods/AnyDBMFile.pod deleted file mode 100644 index 5692144586..0000000000 --- a/pod/modpods/AnyDBMFile.pod +++ /dev/null @@ -1,80 +0,0 @@ -=head1 NAME - -AnyDBM_File - provide framework for multiple DBMs - -NDBM_File, ODBM_File, SDBM_File, GDBM_File - various DBM implementations - -=head1 SYNOPSIS - - use AnyDBM_File; - -=head1 DESCRIPTION - -This module is a "pure virtual base class"--it has nothing of its own. -It's just there to inherit from one of the various DBM packages. It -prefers ndbm for compatibility reasons with Perl 4, then Berkeley DB (See -L<DB_File>), GDBM, SDBM (which is always there--it comes with Perl), and -finally ODBM. This way old programs that used to use NDBM via dbmopen() -can still do so, but new ones can reorder @ISA: - - @AnyDBM_File::ISA = qw(DB_File GDBM_File NDBM_File); - -Note, however, that an explicit use overrides the specified order: - - use GDBM_File; - @AnyDBM_File::ISA = qw(DB_File GDBM_File NDBM_File); - -will only find GDBM_File. - -Having multiple DBM implementations makes it trivial to copy database formats: - - use POSIX; use NDBM_File; use DB_File; - tie %newhash, DB_File, $new_filename, O_CREAT|O_RDWR; - tie %oldhash, NDBM_File, $old_filename, 1, 0; - %newhash = %oldhash; - -=head2 DBM Comparisons - -Here's a partial table of features the different packages offer: - - odbm ndbm sdbm gdbm bsd-db - ---- ---- ---- ---- ------ - Linkage comes w/ perl yes yes yes yes yes - Src comes w/ perl no no yes no no - Comes w/ many unix os yes yes[0] no no no - Builds ok on !unix ? ? yes yes ? - Code Size ? ? small big big - Database Size ? ? small big? ok[1] - Speed ? ? slow ok fast - FTPable no no yes yes yes - Easy to build N/A N/A yes yes ok[2] - Size limits 1k 4k 1k[3] none none - Byte-order independent no no no no yes - Licensing restrictions ? ? no yes no - - -=over 4 - -=item [0] - -on mixed universe machines, may be in the bsd compat library, -which is often shunned. - -=item [1] - -Can be trimmed if you compile for one access method. - -=item [2] - -See L<DB_File>. -Requires symbolic links. - -=item [3] - -By default, but can be redefined. - -=back - -=head1 SEE ALSO - -dbm(3), ndbm(3), DB_File(3) diff --git a/pod/modpods/AutoLoader.pod b/pod/modpods/AutoLoader.pod deleted file mode 100644 index 203f951e39..0000000000 --- a/pod/modpods/AutoLoader.pod +++ /dev/null @@ -1,16 +0,0 @@ -=head1 NAME - -AutoLoader - load functions only on demand - -=head1 SYNOPSIS - - package FOOBAR; - use Exporter; - use AutoLoader; - @ISA = (Exporter, AutoLoader); - -=head1 DESCRIPTION - -This module tells its users that functions in the FOOBAR package are to be -autoloaded from F<auto/$AUTOLOAD.al>. See L<perlsub/"Autoloading">. - diff --git a/pod/modpods/AutoSplit.pod b/pod/modpods/AutoSplit.pod deleted file mode 100644 index 86df8c018b..0000000000 --- a/pod/modpods/AutoSplit.pod +++ /dev/null @@ -1,11 +0,0 @@ -=head1 NAME - -AutoSplit - split a package for autoloading - -=head1 DESCRIPTION - -This function will split up your program into files that the AutoLoader -module can handle. Normally only used to build autoloading Perl library -modules, especially extensions (like POSIX). You should look at how -they're built out for details. - diff --git a/pod/modpods/Basename.pod b/pod/modpods/Basename.pod deleted file mode 100644 index b0f8229e3b..0000000000 --- a/pod/modpods/Basename.pod +++ /dev/null @@ -1,108 +0,0 @@ -=head1 NAME - -Basename - parse file specifications - -fileparse - split a pathname into pieces - -basename - extract just the filename from a path - -dirname - extract just the directory from a path - -=head1 SYNOPSIS - - use File::Basename; - - ($name,$path,$suffix) = fileparse($fullname,@suffixlist) - fileparse_set_fstype($os_string); - $basename = basename($fullname,@suffixlist); - $dirname = dirname($fullname); - - ($name,$path,$suffix) = fileparse("lib/File/Basename.pm",".pm"); - fileparse_set_fstype("VMS"); - $basename = basename("lib/File/Basename.pm",".pm"); - $dirname = dirname("lib/File/Basename.pm"); - -=head1 DESCRIPTION - -These routines allow you to parse file specifications into useful -pieces using the syntax of different operating systems. - -=over 4 - -=item fileparse_set_fstype - -You select the syntax via the routine fileparse_set_fstype(). -If the argument passed to it contains one of the substrings -"VMS", "MSDOS", or "MacOS", the file specification syntax of that -operating system is used in future calls to fileparse(), -basename(), and dirname(). If it contains none of these -substrings, UNIX syntax is used. This pattern matching is -case-insensitive. If you've selected VMS syntax, and the file -specification you pass to one of these routines contains a "/", -they assume you are using UNIX emulation and apply the UNIX syntax -rules instead, for that function call only. - -If you haven't called fileparse_set_fstype(), the syntax is chosen -by examining the "osname" entry from the C<Config> package -according to these rules. - -=item fileparse - -The fileparse() routine divides a file specification into three -parts: a leading B<path>, a file B<name>, and a B<suffix>. The -B<path> contains everything up to and including the last directory -separator in the input file specification. The remainder of the input -file specification is then divided into B<name> and B<suffix> based on -the optional patterns you specify in C<@suffixlist>. Each element of -this list is interpreted as a regular expression, and is matched -against the end of B<name>. If this succeeds, the matching portion of -B<name> is removed and prepended to B<suffix>. By proper use of -C<@suffixlist>, you can remove file types or versions for examination. - -You are guaranteed that if you concatenate B<path>, B<name>, and -B<suffix> together in that order, the result will be identical to the -input file specification. - -=back - -=head1 EXAMPLES - -Using UNIX file syntax: - - ($base,$path,$type) = fileparse('/virgil/aeneid/draft.book7', - '\.book\d+'); - -would yield - - $base eq 'draft' - $path eq '/virgil/aeneid', - $tail eq '.book7' - -Similarly, using VMS syntax: - - ($name,$dir,$type) = fileparse('Doc_Root:[Help]Rhetoric.Rnh', - '\..*'); - -would yield - - $name eq 'Rhetoric' - $dir eq 'Doc_Root:[Help]' - $type eq '.Rnh' - -=item C<basename> - -The basename() routine returns the first element of the list produced -by calling fileparse() with the same arguments. It is provided for -compatibility with the UNIX shell command basename(1). - -=item C<dirname> - -The dirname() routine returns the directory portion of the input file -specification. When using VMS or MacOS syntax, this is identical to the -second element of the list produced by calling fileparse() with the same -input file specification. When using UNIX or MSDOS syntax, the return -value conforms to the behavior of the UNIX shell command dirname(1). This -is usually the same as the behavior of fileparse(), but differs in some -cases. For example, for the input file specification F<lib/>, fileparse() -considers the directory name to be F<lib/>, while dirname() considers the -directory name to be F<.>). diff --git a/pod/modpods/Benchmark.pod b/pod/modpods/Benchmark.pod deleted file mode 100644 index 6b7d949336..0000000000 --- a/pod/modpods/Benchmark.pod +++ /dev/null @@ -1,159 +0,0 @@ -=head1 NAME - -Benchmark - benchmark running times of code - -timethis - run a chunk of code several times - -timethese - run several chunks of code several times - -timeit - run a chunk of code and see how long it goes - -=head1 SYNOPSIS - - timethis ($count, "code"); - - timethese($count, { - 'Name1' => '...code1...', - 'Name2' => '...code2...', - }); - - $t = timeit($count, '...other code...') - print "$count loops of other code took:",timestr($t),"\n"; - -=head1 DESCRIPTION - -The Benchmark module encapsulates a number of routines to help you -figure out how long it takes to execute some code. - -=head2 Methods - -=over 10 - -=item new - -Returns the current time. Example: - - use Benchmark; - $t0 = new Benchmark; - # ... your code here ... - $t1 = new Benchmark; - $td = timediff($t1, $t0); - print "the code took:",timestr($dt),"\n"; - -=item debug - -Enables or disable debugging by setting the C<$Benchmark::Debug> flag: - - debug Benchmark 1; - $t = timeit(10, ' 5 ** $Global '); - debug Benchmark 0; - -=back - -=head2 Standard Exports - -The following routines will be exported into your namespace -if you use the Benchmark module: - -=over 10 - -=item timeit(COUNT, CODE) - -Arguments: COUNT is the number of time to run the loop, and -the second is the code to run. CODE may be a string containing the code, -a reference to the function to run, or a reference to a hash containing -keys which are names and values which are more CODE specs. - -Side-effects: prints out noise to standard out. - -Returns: a Benchmark object. - -=item timethis - -=item timethese - -=item timediff - -=item timestr - -=back - -=head2 Optional Exports - -The following routines will be exported into your namespace -if you specifically ask that they be imported: - -=over 10 - -clearcache - -clearallcache - -disablecache - -enablecache - -=back - -=head1 NOTES - -The data is stored as a list of values from the time and times -functions: - - ($real, $user, $system, $children_user, $children_system) - -in seconds for the whole loop (not divided by the number of rounds). - -The timing is done using time(3) and times(3). - -Code is executed in the caller's package. - -Enable debugging by: - - $Benchmark::debug = 1; - -The time of the null loop (a loop with the same -number of rounds but empty loop body) is subtracted -from the time of the real loop. - -The null loop times are cached, the key being the -number of rounds. The caching can be controlled using -calls like these: - - clearcache($key); - clearallcache(); - - disablecache(); - enablecache(); - -=head1 INHERITANCE - -Benchmark inherits from no other class, except of course -for Exporter. - -=head1 CAVEATS - -The real time timing is done using time(2) and -the granularity is therefore only one second. - -Short tests may produce negative figures because perl -can appear to take longer to execute the empty loop -than a short test; try: - - timethis(100,'1'); - -The system time of the null loop might be slightly -more than the system time of the loop with the actual -code and therefore the difference might end up being < 0. - -More documentation is needed :-( especially for styles and formats. - -=head1 AUTHORS - -Jarkko Hietaniemi <Jarkko.Hietaniemi@hut.fi>, -Tim Bunce <Tim.Bunce@ig.co.uk> - -=head1 MODIFICATION HISTORY - -September 8th, 1994; by Tim Bunce. - diff --git a/pod/modpods/Carp.pod b/pod/modpods/Carp.pod deleted file mode 100644 index b5439779ac..0000000000 --- a/pod/modpods/Carp.pod +++ /dev/null @@ -1,22 +0,0 @@ -=head1 NAME - -carp - warn of errors (from perspective of caller) - -croak - die of errors (from perspective of caller) - -confess - die of errors with stack backtrace - -=head1 SYNOPSIS - - use Carp; - croak "We're outta here!"; - -=head1 DESCRIPTION - -The Carp routines are useful in your own modules because -they act like die() or warn(), but report where the error -was in the code they were called from. Thus if you have a -routine Foo() that has a carp() in it, then the carp() -will report the error as occurring where Foo() was called, -not where carp() was called. - diff --git a/pod/modpods/CheckTree.pod b/pod/modpods/CheckTree.pod deleted file mode 100644 index cc06eeeda3..0000000000 --- a/pod/modpods/CheckTree.pod +++ /dev/null @@ -1,37 +0,0 @@ -=head1 NAME - -validate - run many filetest checks on a tree - -=head1 SYNOPSIS - - use File::CheckTree; - - $warnings += validate( q{ - /vmunix -e || die - /boot -e || die - /bin cd - csh -ex - csh !-ug - sh -ex - sh !-ug - /usr -d || warn "What happened to $file?\n" - }); - -=head1 DESCRIPTION - -The validate() routine takes a single multiline string consisting of -lines containing a filename plus a file test to try on it. (The -file test may also be a "cd", causing subsequent relative filenames -to be interpreted relative to that directory.) After the file test -you may put C<|| die> to make it a fatal error if the file test fails. -The default is C<|| warn>. The file test may optionally have a "!' prepended -to test for the opposite condition. If you do a cd and then list some -relative filenames, you may want to indent them slightly for readability. -If you supply your own die() or warn() message, you can use $file to -interpolate the filename. - -Filetests may be bunched: "-rwx" tests for all of C<-r>, C<-w>, and C<-x>. -Only the first failed test of the bunch will produce a warning. - -The routine returns the number of warnings issued. - diff --git a/pod/modpods/Collate.pod b/pod/modpods/Collate.pod deleted file mode 100644 index 852fd1f4bd..0000000000 --- a/pod/modpods/Collate.pod +++ /dev/null @@ -1,31 +0,0 @@ -=head1 NAME - -Collate - compare 8-bit scalar data according to the current locale - -=head1 SYNOPSIS - - use Collate; - setlocale(LC_COLLATE, 'locale-of-your-choice'); - $s1 = new Collate "scalar_data_1"; - $s2 = new Collate "scalar_data_2"; - -=head1 DESCRIPTION - -This module provides you with objects that will collate -according to your national character set, providing the -POSIX setlocale() function should be supported on your system. - -You can compare $s1 and $s2 above with - - $s1 le $s2 - -to extract the data itself, you'll need a dereference: $$s1 - -This uses POSIX::setlocale The basic collation conversion is done by -strxfrm() which terminates at NUL characters being a decent C routine. -collate_xfrm() handles embedded NUL characters gracefully. Due to C<cmp> -and overload magic, C<lt>, C<le>, C<eq>, C<ge>, and C<gt> work also. The -available locales depend on your operating system; try whether C<locale --a> shows them or the more direct approach C<ls /usr/lib/nls/loc> or C<ls -/usr/lib/nls>. The locale names are probably something like -"xx_XX.(ISO)?8859-N". diff --git a/pod/modpods/Config.pod b/pod/modpods/Config.pod deleted file mode 100644 index 141fb67393..0000000000 --- a/pod/modpods/Config.pod +++ /dev/null @@ -1,40 +0,0 @@ -=head1 NAME - -Config - access Perl configuration option - -=head1 SYNOPSIS - - use Config; - if ($Config{'cc'} =~ /gcc/) { - print "built by gcc\n"; - } - -=head1 DESCRIPTION - -The Config module contains everything that was available to the -C<Configure> program at Perl build time. Shell variables from -F<config.sh> are stored in the readonly-variable C<%Config>, indexed by -their names. - -=head1 EXAMPLE - -Here's a more sophisticated example of using %Config: - - use Config; - - defined $Config{sig_name} || die "No sigs?"; - foreach $name (split(' ', $Config{sig_name})) { - $signo{$name} = $i; - $signame[$i] = $name; - $i++; - } - - print "signal #17 = $signame[17]\n"; - if ($signo{ALRM}) { - print "SIGALRM is $signo{ALRM}\n"; - } - -=head1 NOTE - -This module contains a good example of how to make a variable -readonly to those outside of it. diff --git a/pod/modpods/Cwd.pod b/pod/modpods/Cwd.pod deleted file mode 100644 index 042db8112e..0000000000 --- a/pod/modpods/Cwd.pod +++ /dev/null @@ -1,26 +0,0 @@ -=head1 NAME - -getcwd - get pathname of current working directory - -=head1 SYNOPSIS - - require Cwd; - $dir = Cwd::getcwd(); - - use Cwd; - $dir = getcwd(); - - use Cwd 'chdir'; - chdir "/tmp"; - print $ENV{'PWD'}; - -=head1 DESCRIPTION - -The getcwd() function re-implements the getcwd(3) (or getwd(3)) functions -in Perl. If you ask to override your chdir() built-in function, then your -PWD environment variable will be kept up to date. (See -L<perlsub/Overriding builtin functions>.) - -The fastgetcwd() function looks the same as getcwd(), but runs faster. -It's also more dangerous because you might conceivably chdir() out of a -directory that you can't chdir() back into. diff --git a/pod/modpods/DB_File.pod b/pod/modpods/DB_File.pod deleted file mode 100644 index 919743b7ca..0000000000 --- a/pod/modpods/DB_File.pod +++ /dev/null @@ -1,319 +0,0 @@ -=head1 NAME - -DB_File - Perl5 access to Berkeley DB - -=head1 SYNOPSIS - - use DB_File ; - - [$X =] tie %hash, DB_File, $filename [, $flags, $mode, $DB_HASH] ; - [$X =] tie %hash, DB_File, $filename, $flags, $mode, $DB_BTREE ; - [$X =] tie @array, DB_File, $filename, $flags, $mode, $DB_RECNO ; - - $status = $X->del($key [, $flags]) ; - $status = $X->put($key, $value [, $flags]) ; - $status = $X->get($key, $value [, $flags]) ; - $status = $X->seq($key, $value [, $flags]) ; - $status = $X->sync([$flags]) ; - $status = $X->fd ; - - untie %hash ; - untie @array ; - -=head1 DESCRIPTION - -B<DB_File> is a module which allows Perl programs to make use of -the facilities provided by Berkeley DB. If you intend to use this -module you should really have a copy of the Berkeley DB manual -page at hand. The interface defined here -mirrors the Berkeley DB interface closely. - -Berkeley DB is a C library which provides a consistent interface to a number of -database formats. -B<DB_File> provides an interface to all three of the database types currently -supported by Berkeley DB. - -The file types are: - -=over 5 - -=item DB_HASH - -This database type allows arbitrary key/data pairs to be stored in data files. -This is equivalent to the functionality provided by -other hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM. -Remember though, the files created using DB_HASH are -not compatible with any of the other packages mentioned. - -A default hashing algorithm, which will be adequate for most applications, -is built into Berkeley DB. -If you do need to use your own hashing algorithm it is possible to write your -own in Perl and have B<DB_File> use it instead. - -=item DB_BTREE - -The btree format allows arbitrary key/data pairs to be stored in a sorted, -balanced binary tree. - -As with the DB_HASH format, it is possible to provide a user defined Perl routine -to perform the comparison of keys. By default, though, the keys are stored -in lexical order. - -=item DB_RECNO - -DB_RECNO allows both fixed-length and variable-length flat text files to be -manipulated using -the same key/value pair interface as in DB_HASH and DB_BTREE. -In this case the key will consist of a record (line) number. - -=back - -=head2 How does DB_File interface to Berkeley DB? - -B<DB_File> allows access to Berkeley DB files using the tie() mechanism -in Perl 5 (for full details, see L<perlfunc/tie()>). -This facility allows B<DB_File> to access Berkeley DB files using -either an associative array (for DB_HASH & DB_BTREE file types) or an -ordinary array (for the DB_RECNO file type). - -In addition to the tie() interface, it is also possible to use most of the -functions provided in the Berkeley DB API. - -=head2 Differences with Berkeley DB - -Berkeley DB uses the function dbopen() to open or create a -database. Below is the C prototype for dbopen(). - - DB* - dbopen (const char * file, int flags, int mode, - DBTYPE type, const void * openinfo) - -The parameter C<type> is an enumeration which specifies which of the 3 -interface methods (DB_HASH, DB_BTREE or DB_RECNO) is to be used. -Depending on which of these is actually chosen, the final parameter, -I<openinfo> points to a data structure which allows tailoring of the -specific interface method. - -This interface is handled -slightly differently in B<DB_File>. Here is an equivalent call using -B<DB_File>. - - tie %array, DB_File, $filename, $flags, $mode, $DB_HASH ; - -The C<filename>, C<flags> and C<mode> parameters are the direct equivalent -of their dbopen() counterparts. The final parameter $DB_HASH -performs the function of both the C<type> and C<openinfo> -parameters in dbopen(). - -In the example above $DB_HASH is actually a reference to a hash object. -B<DB_File> has three of these pre-defined references. -Apart from $DB_HASH, there is also $DB_BTREE and $DB_RECNO. - -The keys allowed in each of these pre-defined references is limited to the names -used in the equivalent C structure. -So, for example, the $DB_HASH reference will only allow keys called C<bsize>, -C<cachesize>, C<ffactor>, C<hash>, C<lorder> and C<nelem>. - -To change one of these elements, just assign to it like this - - $DB_HASH{cachesize} = 10000 ; - - -=head2 RECNO - - -In order to make RECNO more compatible with Perl the array offset for all -RECNO arrays begins at 0 rather than 1 as in Berkeley DB. - - -=head2 In Memory Databases - -Berkeley DB allows the creation of in-memory databases by using NULL (that is, a -C<(char *)0 in C) in -place of the filename. -B<DB_File> uses C<undef> instead of NULL to provide this functionality. - - -=head2 Using the Berkeley DB Interface Directly - -As well as accessing Berkeley DB using a tied hash or array, it is also -possible to make direct use of most of the functions defined in the Berkeley DB -documentation. - - -To do this you need to remember the return value from the tie. - - $db = tie %hash, DB_File, "filename" - -Once you have done that, you can access the Berkeley DB API functions directly. - - $db->put($key, $value, R_NOOVERWRITE) ; - -All the functions defined in L<dbx(3X)> are available except -for close() and dbopen() itself. -The B<DB_File> interface to these functions have been implemented to mirror -the the way Berkeley DB works. In particular note that all the functions return -only a status value. Whenever a Berkeley DB function returns data via one of -its parameters, the B<DB_File> equivalent does exactly the same. - -All the constants defined in L<dbopen> are also available. - -Below is a list of the functions available. - -=over 5 - -=item get - -Same as in C<recno> except that the flags parameter is optional. -Remember the value -associated with the key you request is returned in the $value parameter. - -=item put - -As usual the flags parameter is optional. - -If you use either the R_IAFTER or -R_IBEFORE flags, the key parameter will have the record number of the inserted -key/value pair set. - -=item del - -The flags parameter is optional. - -=item fd - -As in I<recno>. - -=item seq - -The flags parameter is optional. - -Both the key and value parameters will be set. - -=item sync - -The flags parameter is optional. - -=back - -=head1 EXAMPLES - -It is always a lot easier to understand something when you see a real example. -So here are a few. - -=head2 Using HASH - - use DB_File ; - use Fcntl ; - - tie %h, DB_File, "hashed", O_RDWR|O_CREAT, 0640, $DB_HASH ; - - # Add a key/value pair to the file - $h{"apple"} = "orange" ; - - # Check for existence of a key - print "Exists\n" if $h{"banana"} ; - - # Delete - delete $h{"apple"} ; - - untie %h ; - -=head2 Using BTREE - -Here is sample of code which used BTREE. Just to make life more interesting -the default comparision function will not be used. Instead a Perl sub, C<Compare()>, -will be used to do a case insensitive comparison. - - use DB_File ; - use Fcntl ; - - sub Compare - { - my ($key1, $key2) = @_ ; - - "\L$key1" cmp "\L$key2" ; - } - - $DB_BTREE->{compare} = 'Compare' ; - - tie %h, DB_File, "tree", O_RDWR|O_CREAT, 0640, $DB_BTREE ; - - # Add a key/value pair to the file - $h{'Wall'} = 'Larry' ; - $h{'Smith'} = 'John' ; - $h{'mouse'} = 'mickey' ; - $h{'duck'} = 'donald' ; - - # Delete - delete $h{"duck"} ; - - # Cycle through the keys printing them in order. - # Note it is not necessary to sort the keys as - # the btree will have kept them in order automatically. - foreach (keys %h) - { print "$_\n" } - - untie %h ; - -Here is the output from the code above. - - mouse - Smith - Wall - - -=head2 Using RECNO - - use DB_File ; - use Fcntl ; - - $DB_RECNO->{psize} = 3000 ; - - tie @h, DB_File, "text", O_RDWR|O_CREAT, 0640, $DB_RECNO ; - - # Add a key/value pair to the file - $h[0] = "orange" ; - - # Check for existence of a key - print "Exists\n" if $h[1] ; - - untie @h ; - - - -=head1 WARNINGS - -If you happen find any other functions defined in the source for this module -that have not been mentioned in this document -- beware. -I may drop them at a moments notice. - -If you cannot find any, then either you didn't look very hard or the moment has -passed and I have dropped them. - -=head1 BUGS - -Some older versions of Berkeley DB had problems with fixed length records -using the RECNO file format. The newest version at the time of writing -was 1.85 - this seems to have fixed the problems with RECNO. - -I am sure there are bugs in the code. If you do find any, or can suggest any -enhancements, I would welcome your comments. - -=head1 AVAILABILITY - -Berkeley DB is available via the hold C<ftp.cs.berkeley.edu> in the -directory C</ucb/4bsd/db.tar.gz>. It is I<not> under the GPL. - -=head1 SEE ALSO - -L<perl(1)>, L<dbopen(3)>, L<hash(3)>, L<recno(3)>, L<btree(3)> - -Berkeley DB is available from F<ftp.cs.berkeley.edu> in the directory F</ucb/4bsd>. - -=head1 AUTHOR - -The DB_File interface was written by -Paul Marquess <pmarquess@bfsec.bt.co.uk>. -Questions about the DB system itself may be addressed to -Keith Bostic <bostic@cs.berkeley.edu>. diff --git a/pod/modpods/Dynaloader.pod b/pod/modpods/Dynaloader.pod deleted file mode 100644 index 344fb6944a..0000000000 --- a/pod/modpods/Dynaloader.pod +++ /dev/null @@ -1,316 +0,0 @@ -=head1 NAME - -DynaLoader - Dynamically load C libraries into Perl code - -dl_error(), dl_findfile(), dl_expandspec(), dl_load_file(), dl_find_symbol(), dl_undef_symbols(), dl_install_xsub(), boostrap() - routines used by DynaLoader modules - -=head1 SYNOPSIS - - require DynaLoader; - push (@ISA, 'DynaLoader'); - - -=head1 DESCRIPTION - -This specification defines a standard generic interface to the dynamic -linking mechanisms available on many platforms. Its primary purpose is -to implement automatic dynamic loading of Perl modules. - -The DynaLoader is designed to be a very simple high-level -interface that is sufficiently general to cover the requirements -of SunOS, HP-UX, NeXT, Linux, VMS and other platforms. - -It is also hoped that the interface will cover the needs of OS/2, -NT etc and allow pseudo-dynamic linking (using C<ld -A> at runtime). - -This document serves as both a specification for anyone wishing to -implement the DynaLoader for a new platform and as a guide for -anyone wishing to use the DynaLoader directly in an application. - -It must be stressed that the DynaLoader, by itself, is practically -useless for accessing non-Perl libraries because it provides almost no -Perl-to-C 'glue'. There is, for example, no mechanism for calling a C -library function or supplying arguments. It is anticipated that any -glue that may be developed in the future will be implemented in a -separate dynamically loaded module. - -DynaLoader Interface Summary - - @dl_library_path - @dl_resolve_using - @dl_require_symbols - $dl_debug - Implemented in: - bootstrap($modulename) Perl - @filepaths = dl_findfile(@names) Perl - - $libref = dl_load_file($filename) C - $symref = dl_find_symbol($libref, $symbol) C - @symbols = dl_undef_symbols() C - dl_install_xsub($name, $symref [, $filename]) C - $message = dl_error C - -=over 4 - -=item @dl_library_path - -The standard/default list of directories in which dl_findfile() will -search for libraries etc. Directories are searched in order: -$dl_library_path[0], [1], ... etc - -@dl_library_path is initialised to hold the list of 'normal' directories -(F</usr/lib>, etc) determined by B<Configure> (C<$Config{'libpth'}>). This should -ensure portability across a wide range of platforms. - -@dl_library_path should also be initialised with any other directories -that can be determined from the environment at runtime (such as -LD_LIBRARY_PATH for SunOS). - -After initialisation @dl_library_path can be manipulated by an -application using push and unshift before calling dl_findfile(). -Unshift can be used to add directories to the front of the search order -either to save search time or to override libraries with the same name -in the 'normal' directories. - -The load function that dl_load_file() calls may require an absolute -pathname. The dl_findfile() function and @dl_library_path can be -used to search for and return the absolute pathname for the -library/object that you wish to load. - -=item @dl_resolve_using - -A list of additional libraries or other shared objects which can be -used to resolve any undefined symbols that might be generated by a -later call to load_file(). - -This is only required on some platforms which do not handle dependent -libraries automatically. For example the Socket Perl extension library -(F<auto/Socket/Socket.so>) contains references to many socket functions -which need to be resolved when it's loaded. Most platforms will -automatically know where to find the 'dependent' library (e.g., -F</usr/lib/libsocket.so>). A few platforms need to to be told the location -of the dependent library explicitly. Use @dl_resolve_using for this. - -Example usage: - - @dl_resolve_using = dl_findfile('-lsocket'); - -=item @dl_require_symbols - -A list of one or more symbol names that are in the library/object file -to be dynamically loaded. This is only required on some platforms. - -=item dl_error() - -Syntax: - - $message = dl_error(); - -Error message text from the last failed DynaLoader function. Note -that, similar to errno in unix, a successful function call does not -reset this message. - -Implementations should detect the error as soon as it occurs in any of -the other functions and save the corresponding message for later -retrieval. This will avoid problems on some platforms (such as SunOS) -where the error message is very temporary (e.g., dlerror()). - -=item $dl_debug - -Internal debugging messages are enabled when $dl_debug is set true. -Currently setting $dl_debug only affects the Perl side of the -DynaLoader. These messages should help an application developer to -resolve any DynaLoader usage problems. - -$dl_debug is set to C<$ENV{'PERL_DL_DEBUG'}> if defined. - -For the DynaLoader developer/porter there is a similar debugging -variable added to the C code (see dlutils.c) and enabled if Perl was -built with the B<-DDEBUGGING> flag. This can also be set via the -PERL_DL_DEBUG environment variable. Set to 1 for minimal information or -higher for more. - -=item dl_findfile() - -Syntax: - - @filepaths = dl_findfile(@names) - -Determine the full paths (including file suffix) of one or more -loadable files given their generic names and optionally one or more -directories. Searches directories in @dl_library_path by default and -returns an empty list if no files were found. - -Names can be specified in a variety of platform independent forms. Any -names in the form B<-lname> are converted into F<libname.*>, where F<.*> is -an appropriate suffix for the platform. - -If a name does not already have a suitable prefix and/or suffix then -the corresponding file will be searched for by trying combinations of -prefix and suffix appropriate to the platform: "$name.o", "lib$name.*" -and "$name". - -If any directories are included in @names they are searched before -@dl_library_path. Directories may be specified as B<-Ldir>. Any other names -are treated as filenames to be searched for. - -Using arguments of the form C<-Ldir> and C<-lname> is recommended. - -Example: - - @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix)); - - -=item dl_expandspec() - -Syntax: - - $filepath = dl_expandspec($spec) - -Some unusual systems, such as VMS, require special filename handling in -order to deal with symbolic names for files (i.e., VMS's Logical Names). - -To support these systems a dl_expandspec() function can be implemented -either in the F<dl_*.xs> file or code can be added to the autoloadable -dl_expandspec(0 function in F<DynaLoader.pm>). See F<DynaLoader.pm> for more -information. - -=item dl_load_file() - -Syntax: - - $libref = dl_load_file($filename) - -Dynamically load $filename, which must be the path to a shared object -or library. An opaque 'library reference' is returned as a handle for -the loaded object. Returns undef on error. - -(On systems that provide a handle for the loaded object such as SunOS -and HPUX, $libref will be that handle. On other systems $libref will -typically be $filename or a pointer to a buffer containing $filename. -The application should not examine or alter $libref in any way.) - -This is function that does the real work. It should use the current -values of @dl_require_symbols and @dl_resolve_using if required. - - SunOS: dlopen($filename) - HP-UX: shl_load($filename) - Linux: dld_create_reference(@dl_require_symbols); dld_link($filename) - NeXT: rld_load($filename, @dl_resolve_using) - VMS: lib$find_image_symbol($filename,$dl_require_symbols[0]) - - -=item dl_find_symbol() - -Syntax: - - $symref = dl_find_symbol($libref, $symbol) - -Return the address of the symbol $symbol or C<undef> if not found. If the -target system has separate functions to search for symbols of different -types then dl_find_symbol() should search for function symbols first and -then other types. - -The exact manner in which the address is returned in $symref is not -currently defined. The only initial requirement is that $symref can -be passed to, and understood by, dl_install_xsub(). - - SunOS: dlsym($libref, $symbol) - HP-UX: shl_findsym($libref, $symbol) - Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol) - NeXT: rld_lookup("_$symbol") - VMS: lib$find_image_symbol($libref,$symbol) - - -=item dl_undef_symbols() - -Example - - @symbols = dl_undef_symbols() - -Return a list of symbol names which remain undefined after load_file(). -Returns C<()> if not known. Don't worry if your platform does not provide -a mechanism for this. Most do not need it and hence do not provide it. - - -=item dl_install_xsub() - -Syntax: - - dl_install_xsub($perl_name, $symref [, $filename]) - -Create a new Perl external subroutine named $perl_name using $symref as -a pointer to the function which implements the routine. This is simply -a direct call to newXSUB(). Returns a reference to the installed -function. - -The $filename parameter is used by Perl to identify the source file for -the function if required by die(), caller() or the debugger. If -$filename is not defined then "DynaLoader" will be used. - - -=item boostrap() - -Syntax: - -bootstrap($module) - -This is the normal entry point for automatic dynamic loading in Perl. - -It performs the following actions: - -=over 8 - -=item * - -locates an auto/$module directory by searching @INC - -=item * - -uses dl_findfile() to determine the filename to load - -=item * - -sets @dl_require_symbols to C<("boot_$module")> - -=item * - -executes an F<auto/$module/$module.bs> file if it exists -(typically used to add to @dl_resolve_using any files which -are required to load the module on the current platform) - -=item * - -calls dl_load_file() to load the file - -=item * - -calls dl_undef_symbols() and warns if any symbols are undefined - -=item * - -calls dl_find_symbol() for "boot_$module" - -=item * - -calls dl_install_xsub() to install it as "${module}::bootstrap" - -=item * - -calls &{"${module}::bootstrap"} to bootstrap the module - -=back - -=back - - -=head1 AUTHOR - -This interface is based on the work and comments of (in no particular -order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno -Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, and others. - -Larry Wall designed the elegant inherited bootstrap mechanism and -implemented the first Perl 5 dynamic loader using it. - -Tim Bunce, 11 August 1994. diff --git a/pod/modpods/English.pod b/pod/modpods/English.pod deleted file mode 100644 index d6b26beaf2..0000000000 --- a/pod/modpods/English.pod +++ /dev/null @@ -1,24 +0,0 @@ -=head1 NAME - -English - use nice English (or awk) names for ugly punctuation variables - -=head1 SYNOPSIS - - use English; - ... - if ($ERRNO =~ /denied/) { ... } - -=head1 DESCRIPTION - -This module provides aliases for the built-in variables whose -names no one seems to like to read. Variables with side-effects -which get triggered just by accessing them (like $0) will still -be affected. - -For those variables that have an B<awk> version, both long -and short English alternatives are provided. For example, -the C<$/> variable can be referred to either $RS or -$INPUT_RECORD_SEPARATOR if you are using the English module. - -See L<perlvar> for a complete list of these. - diff --git a/pod/modpods/Env.pod b/pod/modpods/Env.pod deleted file mode 100644 index 44344998bd..0000000000 --- a/pod/modpods/Env.pod +++ /dev/null @@ -1,31 +0,0 @@ -=head1 NAME - -Env - Perl module that imports environment variables - -=head1 DESCRIPTION - -Perl maintains environment variables in a pseudo-associative-array -named %ENV. For when this access method is inconvenient, the Perl -module C<Env> allows environment variables to be treated as simple -variables. - -The Env::import() function ties environment variables with suitable -names to global Perl variables with the same names. By default it -does so with all existing environment variables (C<keys %ENV>). If -the import function receives arguments, it takes them to be a list of -environment variables to tie; it's okay if they don't yet exist. - -After an environment variable is tied, merely use it like a normal variable. -You may access its value - - @path = split(/:/, $PATH); - -or modify it - - $PATH .= ":."; - -however you'd like. -To remove a tied environment variable from -the environment, assign it the undefined value - - undef $PATH; diff --git a/pod/modpods/Exporter.pod b/pod/modpods/Exporter.pod deleted file mode 100644 index 050fafa4ba..0000000000 --- a/pod/modpods/Exporter.pod +++ /dev/null @@ -1,60 +0,0 @@ -=head1 NAME - -Exporter - module to control namespace manipulations - -import - import functions into callers namespace - -=head1 SYNOPSIS - - package WhatEver; - require Exporter; - @ISA = (Exporter); - @EXPORT = qw(func1, $foo, %tabs); - @EXPORT_OK = qw(sin cos); - ... - use WhatEver; - use WhatEver 'sin'; - -=head1 DESCRIPTION - -The Exporter module is used by well-behaved Perl modules to -control what they will export into their user's namespace. -The WhatEver module above has placed in its export list -the function C<func1()>, the scalar C<$foo>, and the -hash C<%tabs>. When someone decides to -C<use WhatEver>, they get those identifiers grafted -onto their own namespace. That means the user of -package whatever can use the function func1() instead -of fully qualifying it as WhatEver::func1(). - -You should be careful of such namespace pollution. -Of course, the user of the WhatEver module is free to -use a C<require> instead of a C<use>, which will -preserve the sanctity of their namespace. - -In particular, you almost certainly shouldn't -automatically export functions whose names are -already used in the language. For this reason, -the @EXPORT_OK list contains those function which -may be selectively imported, as the sin() function -was above. -See L<perlsub/Overriding builtin functions>. - -You can't import names that aren't in either the @EXPORT -or the @EXPORT_OK list. - -Remember that these two constructs are identical: - - use WhatEver; - - BEGIN { - require WhatEver; - import Module; - } - -The import() function above is not predefined in the -language. Rather, it's a method in the Exporter module. -A sneaky library writer could conceivably have an import() -method that behaved differently from the standard one, but -that's not very friendly. - diff --git a/pod/modpods/Fcntl.pod b/pod/modpods/Fcntl.pod deleted file mode 100644 index 165153e475..0000000000 --- a/pod/modpods/Fcntl.pod +++ /dev/null @@ -1,20 +0,0 @@ -=head1 NAME - -Fcntl - load the C Fcntl.h defines - -=head1 SYNOPSIS - - use Fcntl; - -=head1 DESCRIPTION - -This module is just a translation of the C F<fnctl.h> file. -Unlike the old mechanism of requiring a translated F<fnctl.ph> -file, this uses the B<h2xs> program (see the Perl source distribution) -and your native C compiler. This means that it has a -far more likely chance of getting the numbers right. - -=head1 NOTE - -Only C<#define> symbols get translated; you must still correctly -pack up your own arguments to pass as args for locking functions, etc. diff --git a/pod/modpods/FileHandle.pod b/pod/modpods/FileHandle.pod deleted file mode 100644 index d595617973..0000000000 --- a/pod/modpods/FileHandle.pod +++ /dev/null @@ -1,46 +0,0 @@ -=head1 NAME - -FileHandle - supply object methods for filehandles - -cacheout - keep more files open than the system permits - -=head1 SYNOPSIS - - use FileHandle; - autoflush STDOUT 1; - - cacheout($path); - print $path @data; - -=head1 DESCRIPTION - -See L<perlvar> for complete descriptions of each of the following supported C<FileHandle> -methods: - - print - autoflush - output_field_separator - output_record_separator - input_record_separator - input_line_number - format_page_number - format_lines_per_page - format_lines_left - format_name - format_top_name - format_line_break_characters - format_formfeed - -The cacheout() function will make sure that there's a filehandle -open for writing available as the pathname you give it. It automatically -closes and re-opens files if you exceed your system file descriptor maximum. - -=head1 BUGS - -F<sys/param.h> lies with its C<NOFILE> define on some systems, -so you may have to set $cacheout::maxopen yourself. - -Due to backwards compatibility, all filehandles resemble objects -of class C<FileHandle>, or actually classes derived from that class. -They actually aren't. Which means you can't derive your own -class from C<FileHandle> and inherit those methods. diff --git a/pod/modpods/Find.pod b/pod/modpods/Find.pod deleted file mode 100644 index 40a2aed300..0000000000 --- a/pod/modpods/Find.pod +++ /dev/null @@ -1,44 +0,0 @@ -=head1 NAME - -find - traverse a file tree - -=head1 SYNOPSIS - - use File::Find; - find(\&wanted, '/foo','/bar'); - sub wanted { ... } - -=head1 DESCRIPTION - -The wanted() function does whatever verifications you want. $dir contains -the current directory name, and $_ the current filename within that -directory. $name contains C<"$dir/$_">. You are chdir()'d to $dir when -the function is called. The function may set $prune to prune the tree. - -This library is primarily for the C<find2perl> tool, which when fed, - - find2perl / -name .nfs\* -mtime +7 \ - -exec rm -f {} \; -o -fstype nfs -prune - -produces something like: - - sub wanted { - /^\.nfs.*$/ && - (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) && - int(-M _) > 7 && - unlink($_) - || - ($nlink || (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_))) && - $dev < 0 && - ($prune = 1); - } - -Set the variable $dont_use_nlink if you're using AFS, since AFS cheats. - -Here's another interesting wanted function. It will find all symlinks -that don't resolve: - - sub wanted { - -l && !-e && print "bogus link: $name\n"; - } - diff --git a/pod/modpods/Finddepth.pod b/pod/modpods/Finddepth.pod deleted file mode 100644 index c6512655d1..0000000000 --- a/pod/modpods/Finddepth.pod +++ /dev/null @@ -1,14 +0,0 @@ -=head1 NAME - -finddepth - traverse a directory structure depth-first - -=head1 SYNOPSIS - - use File::Finddepth; - finddepth(\&wanted, '/foo','/bar'); - sub wanted { ... } - -=head2 DESCRIPTION - -This is just like C<File::Find>, except that it does a depth-first -search and uses finddepth() rather than find(). diff --git a/pod/modpods/GetOptions.pod b/pod/modpods/GetOptions.pod deleted file mode 100644 index ca64639968..0000000000 --- a/pod/modpods/GetOptions.pod +++ /dev/null @@ -1,137 +0,0 @@ -=head1 NAME - -Getopt::Long, GetOptions - extended getopt processing - -=head1 SYNOPSIS - - use Getopt::Long; - $result = GetOptions (...option-descriptions...); - -=head1 DESCRIPTION - -This package implements an extended getopt function. This function adheres -to the new syntax (long option names, no bundling). -It tries to implement the better functionality of traditional, GNU and -POSIX getopt() functions. - -Each description should designate a valid Perl identifier, optionally -followed by an argument specifier. - -Values for argument specifiers are: - - <none> option does not take an argument - ! option does not take an argument and may be negated - =s :s option takes a mandatory (=) or optional (:) string argument - =i :i option takes a mandatory (=) or optional (:) integer argument - =f :f option takes a mandatory (=) or optional (:) real number argument - -If option "name" is set, it will cause the Perl variable $opt_name to -be set to the specified value. The calling program can use this -variable to detect whether the option has been set. Options that do -not take an argument will be set to 1 (one). - -Options that take an optional argument will be defined, but set to '' -if no actual argument has been supplied. - -If an "@" sign is appended to the argument specifier, the option is -treated as an array. Value(s) are not set, but pushed into array -@opt_name. - -Options that do not take a value may have an "!" argument spacifier to -indicate that they may be negated. E.g. "foo!" will allow B<-foo> (which -sets $opt_foo to 1) and B<-nofoo> (which will set $opt_foo to 0). - -The option name may actually be a list of option names, separated by -'|'s, e.g. B<"foo|bar|blech=s". In this example, options 'bar' and -'blech' will set $opt_foo instead. - -Option names may be abbreviated to uniqueness, depending on -configuration variable $autoabbrev. - -Dashes in option names are allowed (e.g. pcc-struct-return) and will -be translated to underscores in the corresponding Perl variable (e.g. -$opt_pcc_struct_return). Note that a lone dash "-" is considered an -option, corresponding Perl identifier is $opt_ . - -A double dash "--" signals end of the options list. - -If the first option of the list consists of non-alphanumeric -characters only, it is interpreted as a generic option starter. -Everything starting with one of the characters from the starter will -be considered an option. - -The default values for the option starters are "-" (traditional), "--" -(POSIX) and "+" (GNU, being phased out). - -Options that start with "--" may have an argument appended, separated -with an "=", e.g. "--foo=bar". - -If configuration varaible $getopt_compat is set to a non-zero value, -options that start with "+" may also include their arguments, -e.g. "+foo=bar". - -A return status of 0 (false) indicates that the function detected -one or more errors. - -=head1 EXAMPLES - -If option "one:i" (i.e. takes an optional integer argument), then -the following situations are handled: - - -one -two -> $opt_one = '', -two is next option - -one -2 -> $opt_one = -2 - -Also, assume "foo=s" and "bar:s" : - - -bar -xxx -> $opt_bar = '', '-xxx' is next option - -foo -bar -> $opt_foo = '-bar' - -foo -- -> $opt_foo = '--' - -In GNU or POSIX format, option names and values can be combined: - - +foo=blech -> $opt_foo = 'blech' - --bar= -> $opt_bar = '' - --bar=-- -> $opt_bar = '--' - -=over 12 - -=item $autoabbrev - -Allow option names to be abbreviated to uniqueness. -Default is 1 unless environment variable -POSIXLY_CORRECT has been set. - -=item $getopt_compat - -Allow '+' to start options. -Default is 1 unless environment variable -POSIXLY_CORRECT has been set. - -=item $option_start - -Regexp with option starters. -Default is (--|-) if environment variable -POSIXLY_CORRECT has been set, (--|-|\+) otherwise. - -=item $order - -Whether non-options are allowed to be mixed with -options. -Default is $REQUIRE_ORDER if environment variable -POSIXLY_CORRECT has been set, $PERMUTE otherwise. - -=item $ignorecase - -Ignore case when matching options. Default is 1. - -=item $debug - -Enable debugging output. Default is 0. - -=back - -=head1 NOTE - -Does not yet use the Exporter--or even packages!! -Thus, it's not a real module. - diff --git a/pod/modpods/Getopt.pod b/pod/modpods/Getopt.pod deleted file mode 100644 index 9cda9ec03f..0000000000 --- a/pod/modpods/Getopt.pod +++ /dev/null @@ -1,153 +0,0 @@ -=head1 NAME - -getopt - Process single-character switches with switch clustering - -getopts - Process single-character switches with switch clustering - -GetOptions - extended getopt processing - -=head1 SYNOPSIS - - use Getopt::Std; - getopt('oDI'); # -o, -D & -I take arg. Sets opt_* as a side effect. - getopts('oif:'); # -o & -i are boolean flags, -f takes an argument - # Sets opt_* as a side effect. - - use Getopt::Long; - $result = GetOptions (...option-descriptions...); - -=head1 DESCRIPTION - -The getopt() functions processes single-character switches with switch -clustering. Pass one argument which is a string containing all switches -that take an argument. For each switch found, sets $opt_x (where x is the -switch name) to the value of the argument, or 1 if no argument. Switches -which take an argument don't care whether there is a space between the -switch and the argument. - -The Getopt::Long module implements an extended getopt function called -GetOptions(). This function adheres to the new syntax (long option names, -no bundling). It tries to implement the better functionality of -traditional, GNU and POSIX getopt() functions. - -Each description should designate a valid Perl identifier, optionally -followed by an argument specifier. - -Values for argument specifiers are: - - <none> option does not take an argument - ! option does not take an argument and may be negated - =s :s option takes a mandatory (=) or optional (:) string argument - =i :i option takes a mandatory (=) or optional (:) integer argument - =f :f option takes a mandatory (=) or optional (:) real number argument - -If option "name" is set, it will cause the Perl variable $opt_name to -be set to the specified value. The calling program can use this -variable to detect whether the option has been set. Options that do -not take an argument will be set to 1 (one). - -Options that take an optional argument will be defined, but set to '' -if no actual argument has been supplied. - -If an "@" sign is appended to the argument specifier, the option is -treated as an array. Value(s) are not set, but pushed into array -@opt_name. - -Options that do not take a value may have an "!" argument specifier to -indicate that they may be negated. E.g. "foo!" will allow B<-foo> (which -sets $opt_foo to 1) and B<-nofoo> (which will set $opt_foo to 0). - -The option name may actually be a list of option names, separated by -'|'s, e.g. B<"foo|bar|blech=s". In this example, options 'bar' and -'blech' will set $opt_foo instead. - -Option names may be abbreviated to uniqueness, depending on -configuration variable $autoabbrev. - -Dashes in option names are allowed (e.g. pcc-struct-return) and will -be translated to underscores in the corresponding Perl variable (e.g. -$opt_pcc_struct_return). Note that a lone dash "-" is considered an -option, corresponding Perl identifier is $opt_ . - -A double dash "--" signals end of the options list. - -If the first option of the list consists of non-alphanumeric -characters only, it is interpreted as a generic option starter. -Everything starting with one of the characters from the starter will -be considered an option. - -The default values for the option starters are "-" (traditional), "--" -(POSIX) and "+" (GNU, being phased out). - -Options that start with "--" may have an argument appended, separated -with an "=", e.g. "--foo=bar". - -If configuration variable $getopt_compat is set to a non-zero value, -options that start with "+" may also include their arguments, -e.g. "+foo=bar". - -A return status of 0 (false) indicates that the function detected -one or more errors. - -=head1 EXAMPLES - -If option "one:i" (i.e. takes an optional integer argument), then -the following situations are handled: - - -one -two -> $opt_one = '', -two is next option - -one -2 -> $opt_one = -2 - -Also, assume "foo=s" and "bar:s" : - - -bar -xxx -> $opt_bar = '', '-xxx' is next option - -foo -bar -> $opt_foo = '-bar' - -foo -- -> $opt_foo = '--' - -In GNU or POSIX format, option names and values can be combined: - - +foo=blech -> $opt_foo = 'blech' - --bar= -> $opt_bar = '' - --bar=-- -> $opt_bar = '--' - -=over 12 - -=item $autoabbrev - -Allow option names to be abbreviated to uniqueness. -Default is 1 unless environment variable -POSIXLY_CORRECT has been set. - -=item $getopt_compat - -Allow '+' to start options. -Default is 1 unless environment variable -POSIXLY_CORRECT has been set. - -=item $option_start - -Regexp with option starters. -Default is (--|-) if environment variable -POSIXLY_CORRECT has been set, (--|-|\+) otherwise. - -=item $order - -Whether non-options are allowed to be mixed with -options. -Default is $REQUIRE_ORDER if environment variable -POSIXLY_CORRECT has been set, $PERMUTE otherwise. - -=item $ignorecase - -Ignore case when matching options. Default is 1. - -=item $debug - -Enable debugging output. Default is 0. - -=back - -=head1 NOTE - -Does not yet use the Exporter--or even packages!! -Thus, it's not a real module. - diff --git a/pod/modpods/MakeMaker.pod b/pod/modpods/MakeMaker.pod deleted file mode 100644 index 0655729598..0000000000 --- a/pod/modpods/MakeMaker.pod +++ /dev/null @@ -1,24 +0,0 @@ -=head1 NAME - -MakeMaker - generate a Makefile for Perl extension - -=head1 SYNOPSIS - - use ExtUtils::MakeMaker; - -=head1 DESCRIPTION - -This utility is designed to write a Makefile for an extension module from -a Makefile.PL. It splits the task of generating the Makefile into several -subroutines that can be individually overridden. Each subroutine returns -the text it wishes to have written to the Makefile. - -The best way to learn to use this is to look at how some of the -extensions are generated, such as Socket. - -=head1 AUTHOR - -Andy Dougherty <F<doughera@lafcol.lafayette.edu>>, -Andreas Koenig <F<k@franz.ww.TU-Berlin.DE>>, -and -Tim Bunce <F<Tim.Bunce@ig.co.uk>>. diff --git a/pod/modpods/Open2.pod b/pod/modpods/Open2.pod deleted file mode 100644 index 942f68446d..0000000000 --- a/pod/modpods/Open2.pod +++ /dev/null @@ -1,43 +0,0 @@ -=head1 NAME - -IPC::Open2, open2 - open a process for both reading and writing - -=head1 SYNOPSIS - - use IPC::Open2; - $pid = open2('rdr', 'wtr', 'some cmd and args'); - # or - $pid = open2('rdr', 'wtr', 'some', 'cmd', 'and', 'args'); - -=head1 DESCRIPTION - -The open2() function spawns the given $cmd and connects $rdr for -reading and $wtr for writing. It's what you think should work -when you try - - open(HANDLE, "|cmd args"); - -open2() returns the process ID of the child process. It doesn't return on -failure: it just raises an exception matching C</^open2:/>. - -=head1 WARNING - -It will not create these file handles for you. You have to do this yourself. -So don't pass it empty variables expecting them to get filled in for you. - -Additionally, this is very dangerous as you may block forever. -It assumes it's going to talk to something like B<bc>, both writing to -it and reading from it. This is presumably safe because you "know" -that commands like B<bc> will read a line at a time and output a line at -a time. Programs like B<sort> that read their entire input stream first, -however, are quite apt to cause deadlock. - -The big problem with this approach is that if you don't have control -over source code being run in the the child process, you can't control what it does -with pipe buffering. Thus you can't just open a pipe to "cat -v" and continually -read and write a line from it. - -=head1 SEE ALSO - -See L<open3> for an alternative that handles STDERR as well. - diff --git a/pod/modpods/Open3.pod b/pod/modpods/Open3.pod deleted file mode 100644 index 690d8ffdfb..0000000000 --- a/pod/modpods/Open3.pod +++ /dev/null @@ -1,23 +0,0 @@ -=head1 NAME - -IPC::Open3, open3 - open a process for reading, writing, and error handling - -=head1 SYNOPSIS - - $pid = open3('WTRFH', 'RDRFH', 'ERRFH' - 'some cmd and args', 'optarg', ...); - -=head1 DESCRIPTION - -Extremely similar to open2(), open3() spawns the given $cmd and -connects RDRFH for reading, WTRFH for writing, and ERRFH for errors. If -ERRFH is '', or the same as RDRFH, then STDOUT and STDERR of the child are -on the same file handle. - -If WTRFH begins with ">&", then WTRFH will be closed in the parent, and -the child will read from it directly. if RDRFH or ERRFH begins with -">&", then the child will send output directly to that file handle. In both -cases, there will be a dup(2) instead of a pipe(2) made. - -All caveats from open2() continue to apply. See L<open2> for details. - diff --git a/pod/modpods/POSIX.pod b/pod/modpods/POSIX.pod deleted file mode 100644 index 110e46b21b..0000000000 --- a/pod/modpods/POSIX.pod +++ /dev/null @@ -1,53 +0,0 @@ -=head1 NAME - -POSIX - Perl interface to IEEE 1003.1 namespace - -=head1 SYNOPSIS - - use POSIX; - use POSIX 'strftime'; - -=head1 DESCRIPTION - -The POSIX module permits you to access all (or nearly all) the standard -POSIX 1003.1 identifiers. Things which are C<#defines> in C, like EINTR -or O_NDELAY, are automatically exported into your namespace. All -functions are only exported if you ask for them explicitly. Most likely -people will prefer to use the fully-qualified function names. - -To get a list of all the possible identifiers available to you--and -their semantics--you should pick up a 1003.1 spec, or look in the -F<POSIX.pm> module. - -=head1 EXAMPLES - - printf "EINTR is %d\n", EINTR; - - POSIX::setsid(0); - - $fd = POSIX::open($path, O_CREAT|O_EXCL|O_WRONLY, 0644); - # note: that's a filedescriptor, *NOT* a filehandle - -=head1 NOTE - -The POSIX module is probably the most complex Perl module supplied with -the standard distribution. It incorporates autoloading, namespace games, -and dynamic loading of code that's in Perl, C, or both. It's a great -source of wisdom. - -=head1 CAVEATS - -A few functions are not implemented because they are C specific. If you -attempt to call these, they will print a message telling you that they -aren't implemented, and suggest using the Perl equivalent should one -exist. For example, trying to access the setjmp() call will elicit the -message "setjmp() is C-specific: use eval {} instead". - -Furthermore, some evil vendors will claim 1003.1 compliance, but in fact -are not so: they will not pass the PCTS (POSIX Compliance Test Suites). -For example, one vendor may not define EDEADLK, or the semantics of the -errno values set by open(2) might not be quite right. Perl does not -attempt to verify POSIX compliance. That means you can currently -successfully say "use POSIX", and then later in your program you find -that your vendor has been lax and there's no usable ICANON macro after -all. This could be construed to be a bug. diff --git a/pod/modpods/Ping.pod b/pod/modpods/Ping.pod deleted file mode 100644 index fc52925118..0000000000 --- a/pod/modpods/Ping.pod +++ /dev/null @@ -1,37 +0,0 @@ -=head1 NAME - -Net::Ping, pingecho - check a host for upness - -=head1 SYNOPSIS - - use Net::Ping; - print "'jimmy' is alive and kicking\n" if pingecho('jimmy', 10) ; - -=head1 DESCRIPTION - -This module contains routines to test for the reachability of remote hosts. -Currently the only routine implemented is pingecho(). - -pingecho() uses a TCP echo (I<not> an ICMP one) to determine if the -remote host is reachable. This is usually adequate to tell that a remote -host is available to rsh(1), ftp(1), or telnet(1) onto. - -=head2 Parameters - -=over 5 - -=item hostname - -The remote host to check, specified either as a hostname or as an IP address. - -=item timeout - -The timeout in seconds. If not specified it will default to 5 seconds. - -=back - -=head1 WARNING - -pingecho() uses alarm to implement the timeout, so don't set another alarm -while you are using it. - diff --git a/pod/modpods/Socket.pod b/pod/modpods/Socket.pod deleted file mode 100644 index 7dfab25b26..0000000000 --- a/pod/modpods/Socket.pod +++ /dev/null @@ -1,23 +0,0 @@ -=head1 NAME - -Socket - load the C socket.h defines - -=head1 SYNOPSIS - - use Socket; - - $proto = (getprotobyname('udp'))[2]; - socket(Socket_Handle, PF_INET, SOCK_DGRAM, $proto); - -=head1 DESCRIPTION - -This module is just a translation of the C F<socket.h> file. -Unlike the old mechanism of requiring a translated F<socket.ph> -file, this uses the B<h2xs> program (see the Perl source distribution) -and your native C compiler. This means that it has a -far more likely chance of getting the numbers right. - -=head1 NOTE - -Only C<#define> symbols get translated; you must still correctly -pack up your own arguments to pass to bind(), etc. diff --git a/pod/modpods/integer.pod b/pod/modpods/integer.pod deleted file mode 100644 index d459bca385..0000000000 --- a/pod/modpods/integer.pod +++ /dev/null @@ -1,18 +0,0 @@ -=head1 NAME - -integer - Perl pragma to compute arithmetic in integer instead of double - -=head1 SYNOPSIS - - use integer; - $x = 10/3; - # $x is now 3, not 3.33333333333333333 - -=head1 DESCRIPTION - -This tells the compiler that it's okay to use integer operations -from here to the end of the enclosing BLOCK. On many machines, -this doesn't matter a great deal for most computations, but on those -without floating point hardware, it can make a big difference. - -See L<perlmod/Pragmatic Modules>. diff --git a/pod/modpods/less.pod b/pod/modpods/less.pod deleted file mode 100644 index 37c962e90b..0000000000 --- a/pod/modpods/less.pod +++ /dev/null @@ -1,13 +0,0 @@ -=head1 NAME - -less - Perl pragma to request less of something from the compiler - -=head1 DESCRIPTION - -Currently unimplemented, this may someday be a compiler directive -to make certain trade-offs, such as perhaps - - use less 'memory'; - use less 'CPU'; - use less 'fat'; - diff --git a/pod/modpods/sigtrap.pod b/pod/modpods/sigtrap.pod deleted file mode 100644 index ecc35421cc..0000000000 --- a/pod/modpods/sigtrap.pod +++ /dev/null @@ -1,19 +0,0 @@ -=head1 NAME - -sigtrap - Perl pragma to enable stack backtrace on unexpected signals - -=head1 SYNOPSIS - - use sigtrap; - use sigtrap qw(BUS SEGV PIPE SYS ABRT TRAP); - -=head1 DESCRIPTION - -The C<sigtrap> pragma initializes some default signal handlers that print -a stack dump of your Perl program, then sends itself a SIGABRT. This -provides a nice starting point if something horrible goes wrong. - -By default, handlers are installed for the ABRT, BUS, EMT, FPE, ILL, PIPE, -QUIT, SEGV, SYS, TERM, and TRAP signals. - -See L<perlmod/Pragmatic Modules>. diff --git a/pod/modpods/strict.pod b/pod/modpods/strict.pod deleted file mode 100644 index 34a9c86934..0000000000 --- a/pod/modpods/strict.pod +++ /dev/null @@ -1,65 +0,0 @@ -=head1 NAME - -strict - Perl pragma to restrict unsafe constructs - -=head1 SYNOPSIS - - use strict; - - use strict "vars"; - use strict "refs"; - use strict "subs"; - - use strict; - no strict "vars"; - -=head1 DESCRIPTION - -If no import list is supplied, all possible restrictions are assumed. -(This is the safest mode to operate in, but is sometimes too strict for -casual programming.) Currently, there are three possible things to be -strict about: "subs", "vars", and "refs". - -=over 6 - -=item C<strict refs> - -This generates a runtime error if you -use symbolic references (see L<perlref>). - - use strict 'refs'; - $ref = \$foo; - print $$ref; # ok - $ref = "foo"; - print $$ref; # runtime error; normally ok - -=item C<strict vars> - -This generates a compile-time error if you access a variable that wasn't -localized via C<my()> or wasn't fully qualified. Because this is to avoid -variable suicide problems and subtle dynamic scoping issues, a merely -local() variable isn't good enough. See L<perlfunc/my> and -L<perlfunc/local>. - - use strict 'vars'; - $X::foo = 1; # ok, fully qualified - my $foo = 10; # ok, my() var - local $foo = 9; # blows up - -The local() generated a compile-time error because you just touched a global -name without fully qualifying it. - -=item C<strict subs> - -This disables the poetry optimization, -generating a compile-time error if you -try to use a bareword identifier that's not a subroutine. - - use strict 'subs'; - $SIG{PIPE} = Plumber; # blows up - $SIG{"PIPE"} = "Plumber"; # just fine - -=back - -See L<perlmod/Pragmatic Modules>. - diff --git a/pod/modpods/subs.pod b/pod/modpods/subs.pod deleted file mode 100644 index b54b6754ce..0000000000 --- a/pod/modpods/subs.pod +++ /dev/null @@ -1,16 +0,0 @@ -=head1 NAME - -subs - Perl pragma to predeclare sub names - -=head1 SYNOPSIS - - use subs qw(frob); - frob 3..10; - -=head1 DESCRIPTION - -This will predeclare all the subroutine whose names are -in the list, allowing you to use them without parentheses -even before they're declared. - -See L<perlmod/Pragmatic Modules> and L<strict/subs>. |