diff options
| author | Andy Dougherty <doughera@lafcol.lafayette.edu> | 1995-05-30 01:56:48 +0000 |
|---|---|---|
| committer | Andy Dougherty <doughera@lafcol.lafayette.edu> | 1995-05-30 01:56:48 +0000 |
| commit | f06db76b9e41859439aeadb79feb6c603ee741ff (patch) | |
| tree | 0898eb19feb17c3aa0ff6916fc182a998f1b9949 /pod/modpods | |
| parent | d1b918924020f633640d8b8cc8294856a82ddc04 (diff) | |
| download | perl-f06db76b9e41859439aeadb79feb6c603ee741ff.tar.gz | |
This is my patch patch.1g for perl5.001.
This patch only includes updates to the lib/ directory and
the removal of the pod/modpods. The main things are the following:
The modpods are now embedded in their corresponding .pm files.
The Grand AutoLoader patch.
Updates to lib/ExtUtils/xsubpp by Paul Marquess
<pmarquess@bfsec.bt.co.uk>.
Minor changes to a very few modules and pods.
To apply, change to your perl directory, run the commands above, then
apply with
patch -p1 -N < thispatch.
After you apply this patch, you should go on to apply patch.1h and
patch.1i before reConfiguring and building.
Patch and enjoy,
Andy Dougherty doughera@lafcol.lafayette.edu
Dept. of Physics
Lafayette College, Easton PA
Here's the file-by-file description:
lib/AnyDBM_File.pm
Embedded pod.
lib/AutoLoader.pm
Grand AutoLoader patch.
Embedded pod.
lib/AutoSplit.pm
Grand AutoLoader patch.
Embedded pod.
Skip pod sections when splitting .pm files.
lib/Benchmark.pm
lib/Carp.pm
lib/Cwd.pm
lib/English.pm
Grand AutoLoader patch.
Embedded pod.
lib/Exporter.pm
Grand AutoLoader patch.
Embedded pod.
Update comments to match behavior.
lib/ExtUtils/MakeMaker.pm
Include installation of .pod and .pm files.
Space out documentation for better printing with pod2man.
lib/ExtUtils/xsubpp
Patches from Paul Marquess <pmarquess@bfsec.bt.co.uk>, 22 May 1995.
Now at version 1.4.
lib/File/Basename.pm
Embedded pod.
lib/File/CheckTree.pm
Embedded pod.
lib/File/Find.pm
Embedded pod.
Included finddepth pod too.
lib/FileHandle.pm
Embedded pod.
lib/Getopt/Long.pm
Embedded pod.
Fixed PERMUTE order bug.
lib/Getopt/Std.pm
Embedded pod.
Caught accessing undefined element off end of @arg array.
lib/I18N/Collate.pm
lib/IPC/Open2.pm
lib/IPC/Open3.pm
lib/Net/Ping.pm
Embedded pod.
lib/Term/Complete.pm
Embedded pod.
Changed name from complete to Complete to match documentation and
exported name.
lib/Text/Abbrev.pm
Embedded pod.
lib/Text/Tabs.pm
Updated.
lib/integer.pm
lib/less.pm
lib/sigtrap.pm
lib/strict.pm
lib/subs.pm
Embedded pod.
Diffstat (limited to 'pod/modpods')
33 files changed, 0 insertions, 2047 deletions
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>. |