X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlmodlib.pod;h=2dc38dfd80a26c96dd3a20154d82866ecc18b0d2;hb=7185e5cc30e619cebead08968623dc42feff8b7e;hp=9d8b0f06c37ac20b14da672e27306f5b3dd2fc7b;hpb=f102b8834494e736221c17057fae0f964511ea18;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlmodlib.pod b/pod/perlmodlib.pod index 9d8b0f0..2dc38df 100644 --- a/pod/perlmodlib.pod +++ b/pod/perlmodlib.pod @@ -21,7 +21,7 @@ bulletproof. They work somewhat like pragmas in that they tend to affect the compilation of your program, and thus will usually work well only when used within a -C, or C. Most of these are locally scoped, so an inner BLOCK +C, or C. Most of these are lexically scoped, so an inner BLOCK may countermand any of these by saying: no integer; @@ -79,6 +79,10 @@ restrict named opcodes when compiling or running Perl code overload basic Perl operations +=item re + +alter behaviour of regular expressions + =item sigtrap enable simple signal handling @@ -157,6 +161,10 @@ get pathname of current working directory access to Berkeley DB +=item Devel::Peek + +data debugging tool for the XS programmer + =item Devel::SelfStubber generate stubs for a SelfLoading module @@ -225,6 +233,10 @@ write linker options files for dynamic extension add blib/* directories to @INC +=item Fatal + +make errors in builtins or Perl functions fatal + =item Fcntl load the C Fcntl.h defines @@ -253,6 +265,14 @@ traverse a file tree create or remove a series of directories +=item File::Spec + +portably perform operations on file names + +=item File::Spec::Functions + +function call interface to File::Spec module + =item File::stat by-name interface to Perl's builtin stat() functions @@ -267,7 +287,7 @@ supply object methods for filehandles =item FindBin -locate directory of original perl script +locate directory of original Perl script =item GDBM_File @@ -333,6 +353,11 @@ arbitrary size integer math package complex numbers and associated mathematical functions +=item Math::Trig + +simple interface to parts of Math::Complex for those who +need trigonometric functions only for real numbers + =item NDBM_File tied access to ndbm files @@ -359,7 +384,7 @@ by-name interface to Perl's builtin getserv*() functions =item Opcode -disable named opcodes when compiling or running perl code +disable named opcodes when compiling or running Perl code =item Pod::Text @@ -391,7 +416,7 @@ load functions only on demand =item Shell -run shell commands transparently within perl +run shell commands transparently within Perl =item Socket @@ -423,7 +448,7 @@ interface to various C packages =item Test::Harness -run perl standard test scripts with statistics +run Perl standard test scripts with statistics =item Text::Abbrev @@ -494,7 +519,7 @@ by-name interface to Perl's builtin getpw*() functions To find out I the modules installed on your system, including those without documentation or outside the standard release, do this: - find `perl -e 'print "@INC"'` -name '*.pm' -print + % find `perl -e 'print "@INC"'` -name '*.pm' -print They should all have their own documentation installed and accessible via your system man(1) command. If that fails, try the I program. @@ -595,84 +620,133 @@ You should try to choose one close to you: =item * Africa - South Africa ftp://ftp.is.co.za/programming/perl/CPAN/ + South Africa ftp://ftp.is.co.za/programming/perl/CPAN/ + ftp://ftpza.co.za/pub/mirrors/cpan/ =item * Asia - Hong Kong ftp://ftp.hkstar.com/pub/CPAN/ - Japan ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/ - ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/ - South Korea ftp://ftp.nuri.net/pub/CPAN/ - Taiwan ftp://dongpo.math.ncu.edu.tw/perl/CPAN/ - ftp://ftp.wownet.net/pub2/PERL/ + Armenia ftp://sunsite.aua.am/pub/CPAN/ + China ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/ + Hong Kong ftp://ftp.hkstar.com/pub/CPAN/ + Israel ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/ + Japan ftp://ftp.dti.ad.jp/pub/lang/CPAN/ + ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/ + ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/ + ftp://ftp.meisei-u.ac.jp/pub/CPAN/ + ftp://mirror.nucba.ac.jp/mirror/Perl/ + Singapore ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/ + South Korea ftp://ftp.bora.net/pub/CPAN/ + ftp://ftp.nuri.net/pub/CPAN/ + Taiwan ftp://ftp.wownet.net/pub2/PERL/ + ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/ + Thailand ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/ + ftp://ftp.nectec.or.th/pub/mirrors/CPAN/ =item * Australasia - Australia ftp://ftp.netinfo.com.au/pub/perl/CPAN/ - New Zealand ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/ + Australia ftp://cpan.topend.com.au/pub/CPAN/ + ftp://ftp.labyrinth.net.au/pub/perl/CPAN/ + ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/ + ftp://mirror.aarnet.edu.au/pub/perl/CPAN/ + New Zealand ftp://ftp.auckland.ac.nz/pub/perl/CPAN/ + ftp://sunsite.net.nz/pub/languages/perl/CPAN/ + +=item * +Central America + + Costa Rica ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/ =item * Europe - Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/ - Belgium ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/ - Czech Republic ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/ - Denmark ftp://sunsite.auc.dk/pub/languages/perl/CPAN/ - Finland ftp://ftp.funet.fi/pub/languages/perl/CPAN/ - France ftp://ftp.ibp.fr/pub/perl/CPAN/ - ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/ - Germany ftp://ftp.gmd.de/packages/CPAN/ - ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/ - ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/ - ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/ - ftp://ftp.uni-erlangen.de/pub/source/Perl/CPAN/ - ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/ - Greece ftp://ftp.ntua.gr/pub/lang/perl/ - Hungary ftp://ftp.kfki.hu/pub/packages/perl/CPAN/ - Italy ftp://cis.utovrm.it/CPAN/ - the Netherlands ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/ - ftp://ftp.EU.net/packages/cpan/ - Norway ftp://ftp.uit.no/pub/languages/perl/cpan/ - Poland ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/ - ftp://sunsite.icm.edu.pl/pub/CPAN/ - Portugal ftp://ftp.ci.uminho.pt/pub/lang/perl/ - ftp://ftp.telepac.pt/pub/CPAN/ - Russia ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/ - Slovenia ftp://ftp.arnes.si/software/perl/CPAN/ - Spain ftp://ftp.etse.urv.es/pub/mirror/perl/ - ftp://ftp.rediris.es/mirror/CPAN/ - Sweden ftp://ftp.sunet.se/pub/lang/perl/CPAN/ - UK ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/ - ftp://sunsite.doc.ic.ac.uk/packages/CPAN/ - ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/ + Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/ + Belgium ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/ + Bulgaria ftp://ftp.ntrl.net/pub/mirrors/CPAN/ + Croatia ftp://ftp.linux.hr/pub/CPAN/ + Czech Republic ftp://ftp.fi.muni.cz/pub/perl/ + ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/ + Denmark ftp://sunsite.auc.dk/pub/languages/perl/CPAN/ + Estonia ftp://ftp.ut.ee/pub/languages/perl/CPAN/ + Finland ftp://ftp.funet.fi/pub/languages/perl/CPAN/ + France ftp://ftp.lip6.fr/pub/perl/CPAN/ + ftp://ftp.oleane.net/pub/mirrors/CPAN/ + ftp://ftp.pasteur.fr/pub/computing/CPAN/ + Germany ftp://ftp.archive.de.uu.net/pub/CPAN/ + ftp://ftp.gmd.de/packages/CPAN/ + ftp://ftp.gwdg.de/pub/languages/perl/CPAN/ + ftp://ftp.leo.org/pub/comp/programming/languages/script/perl/CPAN/ + ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/ + ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/ + ftp://ftp.uni-erlangen.de/pub/source/CPAN/ + ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/ + Greece ftp://ftp.ntua.gr/pub/lang/perl/ + Hungary ftp://ftp.kfki.hu/pub/packages/perl/CPAN/ + Ireland ftp://sunsite.compapp.dcu.ie/pub/perl/ + Italy ftp://cis.uniRoma2.it/CPAN/ + ftp://ftp.flashnet.it/pub/CPAN/ + ftp://ftp.unipi.it/pub/mirror/perl/CPAN/ + Netherlands ftp://ftp.cs.uu.nl/mirror/CPAN/ + ftp://ftp.nluug.nl/pub/languages/perl/CPAN/ + Norway ftp://ftp.uit.no/pub/languages/perl/cpan/ + ftp://sunsite.uio.no/pub/languages/perl/CPAN/ + Poland ftp://ftp.man.szczecin.pl/pub/perl/CPAN/ + ftp://ftp.man.torun.pl/pub/doc/CPAN/ + ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/ + ftp://sunsite.icm.edu.pl/pub/CPAN/ + Portugal ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/ + ftp://ftp.ua.pt/pub/CPAN/ + Romania ftp://ftp.dntis.ro/pub/mirrors/perl-cpan/ + ftp://ftp.dnttm.ro/pub/CPAN/ + Russia ftp://cpan.npi.msu.su/CPAN/ + ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/ + Slovakia ftp://ftp.entry.sk/pub/languages/perl/CPAN/ + Slovenia ftp://ftp.arnes.si/software/perl/CPAN/ + Spain ftp://ftp.etse.urv.es/pub/perl/ + ftp://ftp.rediris.es/mirror/CPAN/ + Sweden ftp://ftp.sunet.se/pub/lang/perl/CPAN/ + Switzerland ftp://sunsite.cnlab-switch.ch/mirror/CPAN/ + Turkey ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/ + United Kingdom ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/ + ftp://ftp.flirble.org/pub/languages/perl/CPAN/ + ftp://ftp.plig.org/pub/CPAN/ + ftp://sunsite.doc.ic.ac.uk/packages/CPAN/ + ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/ =item * North America - Ontario ftp://ftp.utilis.com/public/CPAN/ - ftp://enterprise.ic.gc.ca/pub/perl/CPAN/ - Manitoba ftp://theory.uwinnipeg.ca/pub/CPAN/ - California ftp://ftp.digital.com/pub/plan/perl/CPAN/ - ftp://ftp.cdrom.com/pub/perl/CPAN/ - Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ - Florida ftp://ftp.cis.ufl.edu/pub/perl/CPAN/ - Illinois ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/ - Massachusetts ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/ - New York ftp://ftp.rge.com/pub/languages/perl/ - North Carolina ftp://ftp.duke.edu/pub/perl/ - Oklahoma ftp://ftp.ou.edu/mirrors/CPAN/ - Oregon http://www.perl.org/CPAN/ - ftp://ftp.orst.edu/pub/packages/CPAN/ - Pennsylvania ftp://ftp.epix.net/pub/languages/perl/ - Texas ftp://ftp.sedl.org/pub/mirrors/CPAN/ - ftp://ftp.metronet.com/pub/perl/ + Alberta ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/ + California ftp://ftp.cdrom.com/pub/perl/CPAN/ + ftp://ftp.digital.com/pub/plan/perl/CPAN/ + Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ + Florida ftp://ftp.cise.ufl.edu/pub/perl/CPAN/ + Illinois ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/ + Indiana ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/ + ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/ + Manitoba ftp://theory.uwinnipeg.ca/pub/CPAN/ + Massachusetts ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/ + ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/ + Mexico D.F. ftp://ftp.msg.com.mx/pub/CPAN/ + New York ftp://ftp.rge.com/pub/languages/perl/ + North Carolina ftp://ftp.duke.edu/pub/perl/ + Oklahoma ftp://ftp.ou.edu/mirrors/CPAN/ + Ontario ftp://ftp.crc.ca/pub/packages/perl/CPAN/ + Oregon ftp://ftp.orst.edu/pub/packages/CPAN/ + Pennsylvania ftp://ftp.epix.net/pub/languages/perl/ + Texas ftp://ftp.sedl.org/pub/mirrors/CPAN/ + Utah ftp://mirror.xmission.com/CPAN/ + Virginia ftp://ftp.perl.org/pub/perl/CPAN/ + ftp://ruff.cs.jmu.edu/pub/CPAN/ + Washington ftp://ftp.spu.edu/pub/CPAN/ =item * South America - Chile ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/ + Brazil ftp://cpan.if.usp.br/pub/mirror/CPAN/ + Chile ftp://ftp.ing.puc.cl/pub/unix/perl/CPAN/ + ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/ =back @@ -753,7 +827,7 @@ Avoid C<$r-EClass::func()> where using C<@ISA=qw(... Class ...)> and C<$r-Efunc()> would work (see L for more details). Use autosplit so little used or newly added functions won't be a -burden to programs which don't use them. Add test functions to +burden to programs that don't use them. Add test functions to the module after __END__ either using AutoSplit or by saying: eval join('',) || die $@ unless caller(); @@ -770,12 +844,12 @@ information in objects. Always use B<-w>. Try to C (or C). Remember that you can add C to individual blocks -of code which need less strictness. Always use B<-w>. Always use B<-w>! +of code that need less strictness. Always use B<-w>. Always use B<-w>! Follow the guidelines in the perlstyle(1) manual. =item Some simple style guidelines -The perlstyle manual supplied with perl has many helpful points. +The perlstyle manual supplied with Perl has many helpful points. Coding style is a matter of personal taste. Many people evolve their style over several years as they learn what helps them write and @@ -795,7 +869,7 @@ use mixed case with no underscores (need to be short and portable). You may find it helpful to use letter case to indicate the scope or nature of a variable. For example: - $ALL_CAPS_HERE constants only (beware clashes with perl vars) + $ALL_CAPS_HERE constants only (beware clashes with Perl vars) $Some_Caps_Here package-wide global/static $no_caps_here function scope my() or local() variables @@ -925,7 +999,7 @@ GPL and The Artistic Licence (see the files README, Copying, and Artistic). Larry has good reasons for NOT just using the GNU GPL. My personal recommendation, out of respect for Larry, Perl, and the -perl community at large is to state something simply like: +Perl community at large is to state something simply like: Copyright (c) 1995 Your Name. All rights reserved. This program is free software; you can redistribute it and/or @@ -960,7 +1034,7 @@ If possible you should place the module into a major ftp archive and include details of its location in your announcement. Some notes about ftp archives: Please use a long descriptive file -name which includes the version number. Most incoming directories +name that includes the version number. Most incoming directories will not be readable/listable, i.e., you won't be able to see your file after uploading it. Remember to send your email notification message as soon as possible after uploading else your file may get @@ -989,8 +1063,8 @@ Please remember to send me an updated entry for the Module list! =item Take care when changing a released module. -Always strive to remain compatible with previous released versions -(see 2.2 above) Otherwise try to add a mechanism to revert to the +Always strive to remain compatible with previous released versions. +Otherwise try to add a mechanism to revert to the old behaviour if people rely on it. Document incompatible changes. =back @@ -1010,7 +1084,7 @@ there is no need to convert a .pl file into a Module for just that. =item Consider the implications. -All the perl applications which make use of the script will need to +All Perl applications that make use of the script will need to be changed (slightly) if the script is converted into a module. Is it worth it unless you plan to make other changes at the same time? @@ -1053,7 +1127,7 @@ Don't delete the original .pl file till the new .pm one works! =item Complete applications rarely belong in the Perl Module Library. -=item Many applications contain some perl code which could be reused. +=item Many applications contain some Perl code that could be reused. Help save the world! Share your code in a form that makes it easy to reuse. @@ -1067,9 +1141,9 @@ to reuse. fragment of code built on top of the reusable modules. In these cases the application could invoked as: - perl -e 'use Module::Name; method(@ARGV)' ... + % perl -e 'use Module::Name; method(@ARGV)' ... or - perl -mModule::Name ... (in perl5.002 or higher) + % perl -mModule::Name ... (in perl5.002 or higher) =back