EditPageHistoryDiffInfoLikePages

Annotated edit history of perlmodlib(1) version 2, including all changes. View license author blame.

Rev	Author	#	Line
1	perry	1	PERLMODLIB
		2	!!!PERLMODLIB
		3	NAME
		4	DESCRIPTION
		5	THE PERL MODULE LIBRARY
		6	CPAN
		7	Modules: Creation, Use, and Abuse
		8	NOTE
		9	----
		10	!!NAME
		11
		12
		13	perlmodlib - constructing new Perl modules and finding existing ones
		14	!!DESCRIPTION
		15	!!THE PERL MODULE LIBRARY
		16
		17
		18	Many modules are included the Perl distribution. These are
		19	described below, and all end in ''.pm''. You may discover
		20	compiled library file (usually ending in ''.so'') or
		21	small pieces of modules to be autoloaded (ending in
		22	''.al''); these were automatically generated by the
		23	installation process. You may also discover files in the
		24	library directory that end in either ''.pl'' or
		25	''.ph''. These are old libraries supplied so that old
		26	programs that use them still run. The ''.pl'' files will
		27	all eventually be converted into standard modules, and the
		28	''.ph'' files made by __h2ph__ will probably end up as
		29	extension modules made by __h2xs__. (Some ''.ph''
		30	values may already be available through the
		31	POSIX , Errno, or Fcntl modules.) The
		32	__pl2pm__ file in the distribution may help in your
		33	conversion, but it's just a mechanical process and therefore
		34	far from bulletproof.
		35
		36
		37	__Pragmatic Modules__
		38
		39
		40	They work somewhat like compiler directives (pragmata) in
		41	that they tend to affect the compilation of your program,
		42	and thus will usually work well only when used within a
		43	use, or no. Most of these are lexically
		44	scoped, so an inner BLOCK may countermand
		45	them by saying:
		46
		47
		48	no integer;
		49	no strict 'refs';
		50	no warnings;
		51	which lasts until the end of that BLOCK .
		52
		53
		54	Some pragmas are lexically scoped--typically those that
		55	affect the $^H hints variable. Others affect the
		56	current package instead, like use vars and use
		57	subs, which allow you to predeclare a variables or
		58	subroutines within a particular ''file'' rather than just
		59	a block. Such declarations are effective for the entire file
		60	for which they were declared. You cannot rescind them with
		61	no vars or no subs.
		62
		63
		64	The following pragmas are defined (and have their own
		65	documentation).
		66
		67
		68	attributes
		69
		70
		71	Get/set subroutine or variable attributes
		72
		73
		74	attrs
		75
		76
		77	Set/get attributes of a subroutine (deprecated)
		78
		79
		80	autouse
		81
		82
		83	Postpone load of modules until a function is
		84	used
		85
		86
		87	base Establish IS-A relationship with base class at compile
		88	time
		89
		90
2	perry	91	blib Use !MakeMaker's uninstalled version of a
1	perry	92	package
		93
		94
		95	bytes
		96
		97
		98	Force byte semantics rather than character
		99	semantics
		100
		101
		102	charnames
		103
		104
		105	Define character names for N{named} string literal
		106	escape.
		107
		108
		109	constant
		110
		111
		112	Declare constants
		113
		114
		115	diagnostics
		116
		117
		118	Perl compiler pragma to force verbose warning
		119	diagnostics
		120
		121
		122	fields
		123
		124
		125	Compile-time class fields
		126
		127
		128	filetest
		129
		130
		131	Control the filetest permission operators
		132
		133
		134	integer
		135
		136
		137	Use integer arithmetic instead of floating
		138	point
		139
		140
		141	less Request less of something from the
		142	compiler
		143
		144
		145	lib Manipulate @INC at compile time
		146
		147
		148	locale
		149
		150
		151	Use and avoid POSIX locales for built-in
		152	operations
		153
		154
		155	open Set default disciplines for input and
		156	output
		157
		158
		159	ops Restrict unsafe operations when compiling
		160
		161
		162	overload
		163
		164
		165	Package for overloading perl operations
		166
		167
		168	re Alter regular expression behaviour
		169
		170
		171	sigtrap
		172
		173
		174	Enable simple signal handling
		175
		176
		177	strict
		178
		179
		180	Restrict unsafe constructs
		181
		182
		183	subs Predeclare sub names
		184
		185
		186	utf8 Enable/disable UTF-8 in source
		187	code
		188
		189
		190	vars Predeclare global variable names
		191	(obsolete)
		192
		193
		194	warnings
		195
		196
		197	Control optional warnings
		198
		199
		200	warnings::register
		201
		202
		203	Warnings import function
		204
		205
		206	__Standard Modules__
		207
		208
		209	Standard, bundled modules are all expected to behave in a
		210	well-defined manner with respect to namespace pollution
		211	because they use the Exporter module. See their own
		212	documentation for details.
		213
		214
		215	AnyDBM_File
		216
		217
		218	Provide framework for multiple DBMs
		219
		220
2	perry	221	!AutoLoader
1	perry	222
		223
		224	Load subroutines only on demand
		225
		226
2	perry	227	!AutoSplit
1	perry	228
		229
		230	Split a package for autoloading
		231
		232
		233	B The Perl Compiler
		234
		235
		236	B::Asmdata
		237
		238
		239	Autogenerated data about Perl ops, used to generate
		240	bytecode
		241
		242
		243	B::Assembler
		244
		245
		246	Assemble Perl bytecode
		247
		248
		249	B::Bblock
		250
		251
		252	Walk basic blocks
		253
		254
		255	B::Bytecode
		256
		257
		258	Perl compiler's bytecode backend
		259
		260
		261	B::C Perl compiler's C backend
		262
		263
		264	B::CC
		265
		266
		267	Perl compiler's optimized C translation backend
		268
		269
		270	B::Concise
		271
		272
		273	Walk Perl syntax tree, printing concise info about
		274	ops
		275
		276
		277	B::Debug
		278
		279
		280	Walk Perl syntax tree, printing debug info about
		281	ops
		282
		283
		284	B::Deparse
		285
		286
		287	Perl compiler backend to produce perl code
		288
		289
		290	B::Disassembler
		291
		292
		293	Disassemble Perl bytecode
		294
		295
		296	B::Lint
		297
		298
		299	Perl lint
		300
		301
		302	B::Showlex
		303
		304
		305	Show lexical variables used in functions or
		306	files
		307
		308
		309	B::Stackobj
		310
		311
		312	Helper module for CC backend
		313
		314
		315	B::Stash
		316
		317
		318	Show what stashes are loaded
		319
		320
		321	B::Terse
		322
		323
		324	Walk Perl syntax tree, printing terse info about
		325	ops
		326
		327
		328	B::Xref
		329
		330
		331	Generates cross reference reports for Perl
		332	programs
		333
		334
		335	Benchmark
		336
		337
		338	Benchmark running times of Perl code
		339
		340
2	perry	341	!ByteLoader
1	perry	342
		343
		344	Load byte compiled perl code
		345
		346
		347	CGI Simple Common Gateway Interface
		348	Class
		349
		350
		351	CGI::Apache
		352
		353
		354	Backward compatibility module for CGI
		355	.pm
		356
		357
		358	CGI::Carp
		359
		360
		361	CGI routines for writing to the
		362	HTTPD (or other) error log
		363
		364
		365	CGI::Cookie
		366
		367
		368	Interface to Netscape Cookies
		369
		370
		371	CGI::Fast
		372
		373
		374	CGI Interface for Fast
		375	CGI
		376
		377
		378	CGI::Pretty
		379
		380
		381	Module to produce nicely formatted HTML
		382	code
		383
		384
		385	CGI::Push
		386
		387
		388	Simple Interface to Server Push
		389
		390
		391	CGI::Switch
		392
		393
		394	Backward compatibility module for defunct
		395	CGI::Switch
		396
		397
		398	CGI::Util
		399
		400
		401	Internal utilities used by CGI
		402	module
		403
		404
		405	CPAN Query, download and build perl modules
		406	from CPAN sites
		407
		408
2	perry	409	CPAN::!FirstTime
1	perry	410
		411
		412	Utility for CPAN::Config file Initialization
		413
		414
		415	CPAN::Nox
		416
		417
		418	Wrapper around CPAN .pm without using any
		419	XS module
		420
		421
		422	Carp Warn of errors (from perspective of
		423	caller)
		424
		425
		426	Carp::Heavy
		427
		428
		429	Carp guts
		430
		431
		432	Class::Struct
		433
		434
		435	Declare struct-like datatypes as Perl classes
		436
		437
		438	Cwd Get pathname of current working directory
		439
		440
		441	DB Programmatic interface to the Perl
		442	debugging API (draft, subject to
		443
		444
		445	DB_File
		446
		447
		448	Perl5 access to Berkeley DB version
		449	1.x
		450
		451
2	perry	452	Devel::!SelfStubber
1	perry	453
		454
2	perry	455	Generate stubs for a !SelfLoading module
1	perry	456
		457
2	perry	458	!DirHandle
1	perry	459
		460
		461	Supply object methods for directory handles
		462
		463
		464	Dumpvalue
		465
		466
		467	Provides screen dump of Perl data.
		468
		469
		470	English
		471
		472
		473	Use nice English (or awk) names for ugly punctuation
		474	variables
		475
		476
		477	Env Perl module that imports environment variables as
		478	scalars or arrays
		479
		480
		481	Exporter
		482
		483
		484	Implements default import method for modules
		485
		486
		487	Exporter::Heavy
		488
		489
		490	Exporter guts
		491
		492
2	perry	493	!ExtUtils::Command
1	perry	494
		495
		496	Utilities to replace common UNIX commands in
		497	Makefiles etc.
		498
		499
2	perry	500	!ExtUtils::Embed
1	perry	501
		502
		503	Utilities for embedding Perl in C/C ++
		504	applications
		505
		506
2	perry	507	!ExtUtils::Install
1	perry	508
		509
		510	Install files from here to there
		511
		512
2	perry	513	!ExtUtils::Installed
1	perry	514
		515
		516	Inventory management of installed modules
		517
		518
2	perry	519	!ExtUtils::Liblist
1	perry	520
		521
		522	Determine libraries to use and how to use them
		523
		524
2	perry	525	!ExtUtils::MM_Cygwin
1	perry	526
		527
		528	Methods to override UN*X behaviour in
2	perry	529	!ExtUtils::!MakeMaker
1	perry	530
		531
2	perry	532	!ExtUtils::MM_OS2
1	perry	533
		534
		535	Methods to override UN*X behaviour in
2	perry	536	!ExtUtils::!MakeMaker
1	perry	537
		538
2	perry	539	!ExtUtils::MM_Unix
1	perry	540
		541
2	perry	542	Methods used by !ExtUtils::!MakeMaker
1	perry	543
		544
2	perry	545	!ExtUtils::MM_VMS
1	perry	546
		547
		548	Methods to override UN*X behaviour in
2	perry	549	!ExtUtils::!MakeMaker
1	perry	550
		551
2	perry	552	!ExtUtils::MM_Win32
1	perry	553
		554
		555	Methods to override UN*X behaviour in
2	perry	556	!ExtUtils::!MakeMaker
1	perry	557
		558
2	perry	559	!ExtUtils::!MakeMaker
1	perry	560
		561
		562	Create an extension Makefile
		563
		564
2	perry	565	!ExtUtils::Manifest
1	perry	566
		567
		568	Utilities to write and check a MANIFEST
		569	file
		570
		571
2	perry	572	!ExtUtils::Mkbootstrap
1	perry	573
		574
2	perry	575	Make a bootstrap file for use by !DynaLoader
1	perry	576
		577
2	perry	578	!ExtUtils::Mksymlists
1	perry	579
		580
		581	Write linker options files for dynamic
		582	extension
		583
		584
2	perry	585	!ExtUtils::Packlist
1	perry	586
		587
		588	Manage .packlist files
		589
		590
2	perry	591	!ExtUtils::testlib
1	perry	592
		593
		594	Add blib/* directories to @INC
		595
		596
		597	Fatal
		598
		599
		600	Replace functions with equivalents which succeed or
		601	die
		602
		603
		604	Fcntl
		605
		606
		607	Load the C Fcntl.h defines
		608
		609
		610	File::Basename
		611
		612
		613	Split a pathname into pieces
		614
		615
2	perry	616	File::!CheckTree
1	perry	617
		618
		619	Run many filetest checks on a tree
		620
		621
		622	File::Compare
		623
		624
		625	Compare files or filehandles
		626
		627
		628	File::Copy
		629
		630
		631	Copy files or filehandles
		632
		633
2	perry	634	File::!DosGlob
1	perry	635
		636
		637	DOS like globbing and then some
		638
		639
		640	File::Find
		641
		642
		643	Traverse a file tree
		644
		645
		646	File::Path
		647
		648
		649	Create or remove directory trees
		650
		651
		652	File::Spec
		653
		654
		655	Portably perform operations on file names
		656
		657
		658	File::Spec::Epoc
		659
		660
		661	Methods for Epoc file specs
		662
		663
		664	File::Spec::Functions
		665
		666
		667	Portably perform operations on file names
		668
		669
		670	File::Spec::Mac
		671
		672
		673	File::Spec for MacOS
		674
		675
		676	File::Spec::OS2
		677
		678
		679	Methods for OS/2 file specs
		680
		681
		682	File::Spec::Unix
		683
		684
		685	Methods used by File::Spec
		686
		687
		688	File::Spec::VMS
		689
		690
		691	Methods for VMS file specs
		692
		693
		694	File::Spec::Win32
		695
		696
		697	Methods for Win32 file specs
		698
		699
		700	File::Temp
		701
		702
		703	Return name and handle of a temporary file
		704	safely
		705
		706
		707	File::stat
		708
		709
		710	By-name interface to Perl's built-in ''stat()''
		711	functions
		712
		713
2	perry	714	!FileCache
1	perry	715
		716
		717	Keep more files open than the system permits
		718
		719
2	perry	720	!FileHandle
1	perry	721
		722
		723	Supply object methods for filehandles
		724
		725
2	perry	726	!FindBin
1	perry	727
		728
		729	Locate directory of original perl script
		730
		731
		732	GDBM_File
		733
		734
		735	Perl5 access to the gdbm library.
		736
		737
		738	Getopt::Long
		739
		740
		741	Extended processing of command line options
		742
		743
		744	Getopt::Std
		745
		746
		747	Process single-character switches with switch
		748	clustering
		749
		750
		751	I18N::Collate
		752
		753
		754	Compare 8-bit scalar data according to the current
		755	locale
		756
		757
		758	IO Load various IO
		759	modules
		760
		761
		762	IPC::Open2
		763
		764
		765	Open a process for both reading and writing
		766
		767
		768	IPC::Open3
		769
		770
		771	Open a process for reading, writing, and error
		772	handling
		773
		774
2	perry	775	Math::!BigFloat
1	perry	776
		777
		778	Arbitrary length float math package
		779
		780
2	perry	781	Math::!BigInt
1	perry	782
		783
		784	Arbitrary size integer math package
		785
		786
		787	Math::Complex
		788
		789
		790	Complex numbers and associated mathematical
		791	functions
		792
		793
		794	Math::Trig
		795
		796
		797	Trigonometric functions
		798
		799
		800	Net::Ping
		801
		802
		803	Check a remote host for reachability
		804
		805
		806	Net::hostent
		807
		808
		809	By-name interface to Perl's built-in gethost*()
		810	functions
		811
		812
		813	Net::netent
		814
		815
		816	By-name interface to Perl's built-in getnet*()
		817	functions
		818
		819
		820	Net::protoent
		821
		822
		823	By-name interface to Perl's built-in getproto*()
		824	functions
		825
		826
		827	Net::servent
		828
		829
		830	By-name interface to Perl's built-in getserv*()
		831	functions
		832
		833
		834	O Generic interface to Perl Compiler backends
		835
		836
		837	Opcode
		838
		839
		840	Disable named opcodes when compiling perl code
		841
		842
		843	POSIX
		844
		845
		846	Perl interface to IEEE Std
		847	1003.1
		848
		849
		850	Pod::Checker
		851
		852
		853	Check pod documents for syntax errors
		854
		855
		856	Pod::Find
		857
		858
		859	Find POD documents in directory
		860	trees
		861
		862
		863	Pod::Html
		864
		865
		866	Module to convert pod files to
		867	HTML
		868
		869
2	perry	870	Pod::!InputObjects
1	perry	871
		872
		873	Objects representing POD input paragraphs,
		874	commands, etc.
		875
		876
		877	Pod::LaTeX
		878
		879
		880	Convert Pod data to formatted Latex
		881
		882
		883	Pod::Man
		884
		885
		886	Convert POD data to formatted *roff
		887	input
		888
		889
2	perry	890	Pod::!ParseUtils
1	perry	891
		892
		893	Helpers for POD parsing and
		894	conversion
		895
		896
		897	Pod::Parser
		898
		899
		900	Base class for creating POD filters and
		901	translators
		902
		903
		904	Pod::Plainer
		905
		906
		907	Perl extension for converting Pod to old style
		908	Pod.
		909
		910
		911	Pod::Select
		912
		913
		914	Extract selected sections of POD from
		915	input
		916
		917
		918	Pod::Text
		919
		920
		921	Convert POD data to formatted
		922	ASCII text
		923
		924
		925	Pod::Text::Color
		926
		927
		928	Convert POD data to formatted color
		929	ASCII text
		930
		931
		932	Pod::Text::Overstrike
		933
		934
		935	Convert POD data to formatted overstrike
		936	text
		937
		938
		939	Pod::Text::Termcap
		940
		941
		942	Convert POD data to ASCII text
		943	with format escapes
		944
		945
		946	Pod::Usage
		947
		948
		949	Print a usage message from embedded pod
		950	documentation
		951
		952
		953	SDBM_File
		954
		955
		956	Tied access to sdbm files
		957
		958
		959	Safe Compile and execute code in restricted
		960	compartments
		961
		962
		963	Search::Dict
		964
		965
		966	Search for key in dictionary file
		967
		968
2	perry	969	!SelectSaver
1	perry	970
		971
		972	Save and restore selected file handle
		973
		974
2	perry	975	!SelfLoader
1	perry	976
		977
		978	Load functions only on demand
		979
		980
		981	Shell
		982
		983
		984	Run shell commands transparently within perl
		985
		986
		987	Socket
		988
		989
		990	Load the C socket.h defines and structure
		991	manipulators
		992
		993
		994	Symbol
		995
		996
		997	Manipulate Perl symbols and their names
		998
		999
		1000	Term::ANSIColor
		1001
		1002
		1003	Color screen output using ANSI escape
		1004	sequences
		1005
		1006
		1007	Term::Cap
		1008
		1009
		1010	Perl termcap interface
		1011
		1012
		1013	Term::Complete
		1014
		1015
		1016	Perl word completion module
		1017
		1018
2	perry	1019	Term::!ReadLine
1	perry	1020
		1021
		1022	Perl interface to various readline packages.
		1023	If
		1024
		1025
		1026	Test Provides a simple framework for writing test
		1027	scripts
		1028
		1029
		1030	Test::Harness
		1031
		1032
		1033	Run perl standard test scripts with statistics
		1034
		1035
		1036	Text::Abbrev
		1037
		1038
		1039	Create an abbreviation table from a list
		1040
		1041
2	perry	1042	Text::!ParseWords
1	perry	1043
		1044
		1045	Parse text into an array of tokens or array of
		1046	arrays
		1047
		1048
		1049	Text::Soundex
		1050
		1051
		1052	Implementation of the Soundex Algorithm as Described by
		1053	Knuth
		1054
		1055
		1056	Text::Tabs
		1057
		1058
		1059	Expand and unexpand tabs per the unix expand(1) and
		1060	unexpand(1)
		1061
		1062
		1063	Text::Wrap
		1064
		1065
		1066	Line wrapping to form simple paragraphs
		1067
		1068
		1069	Thread
		1070
		1071
		1072	Manipulate threads in Perl ( EXPERIMENTAL ,
		1073	subject to change)
		1074
		1075
		1076	Thread::Queue
		1077
		1078
		1079	Thread-safe queues
		1080
		1081
		1082	Thread::Semaphore
		1083
		1084
		1085	Thread-safe semaphores
		1086
		1087
		1088	Thread::Signal
		1089
		1090
		1091	Start a thread which runs signal handlers
		1092	reliably
		1093
		1094
		1095	Thread::Specific
		1096
		1097
		1098	Thread-specific keys
		1099
		1100
		1101	Tie::Array
		1102
		1103
		1104	Base class for tied arrays
		1105
		1106
		1107	Tie::Handle
		1108
		1109
		1110	Base class definitions for tied handles
		1111
		1112
		1113	Tie::Hash
		1114
		1115
		1116	Base class definitions for tied hashes
		1117
		1118
2	perry	1119	Tie::!RefHash
1	perry	1120
		1121
		1122	Use references as hash keys
		1123
		1124
		1125	Tie::Scalar
		1126
		1127
		1128	Base class definitions for tied scalars
		1129
		1130
2	perry	1131	Tie::!SubstrHash
1	perry	1132
		1133
		1134	Fixed-table-size, fixed-key-length hashing
		1135
		1136
		1137	Time::Local
		1138
		1139
		1140	Efficiently compute time from local and GMT
		1141	time
		1142
		1143
		1144	Time::gmtime
		1145
		1146
		1147	By-name interface to Perl's built-in ''gmtime()''
		1148	function
		1149
		1150
		1151	Time::localtime
		1152
		1153
		1154	By-name interface to Perl's built-in ''localtime()''
		1155	function
		1156
		1157
		1158	Time::tm
		1159
		1160
		1161	Internal object used by Time::gmtime and
		1162	Time::localtime
		1163
		1164
		1165	UNIVERSAL
		1166
		1167
		1168	Base class for ALL classes (blessed
		1169	references)
		1170
		1171
		1172	User::grent
		1173
		1174
		1175	By-name interface to Perl's built-in getgr*()
		1176	functions
		1177
		1178
		1179	User::pwent
		1180
		1181
		1182	By-name interface to Perl's built-in getpw*()
		1183	functions
		1184
		1185
		1186	Win32
		1187
		1188
		1189	Interfaces to some Win32 API
		1190	Functions
		1191
		1192
		1193	To find out ''all'' modules installed on your system,
		1194	including those without documentation or outside the
		1195	standard release, just do this:
		1196
		1197
		1198	% find `perl -e 'print
		1199	They should all have their own documentation installed and accessible via your system man(1) command. If you do not have a __find__ program, you can use the Perl __find2perl__ program instead, which generates Perl code as output you can run through perl. If you have a __man__ program but it doesn't find your modules, you'll have to fix your manpath. See perl for details. If you have no system __man__ command, you might try the __perldoc__ program.
		1200
		1201
		1202	__Extension Modules__
		1203
		1204
		1205	Extension modules are written in C (or a mix of Perl and C).
		1206	They are usually dynamically loaded into Perl if and when
		1207	you need them, but may also be be linked in statically.
		1208	Supported extension modules include Socket, Fcntl, and
		1209	POSIX .
		1210
		1211
		1212	Many popular C extension modules do not come bundled (at
		1213	least, not completely) due to their sizes, volatility, or
		1214	simply lack of time for adequate testing and configuration
		1215	across the multitude of platforms on which Perl was
		1216	beta-tested. You are encouraged to look for them on
		1217	CPAN (described below), or using web search
		1218	engines like Alta Vista or Deja News.
		1219	!!CPAN
		1220
		1221
		1222	CPAN stands for Comprehensive Perl Archive
		1223	Network; it's a globally replicated trove of Perl materials,
		1224	including documentation, style guides, tricks and traps,
		1225	alternate ports to non-Unix systems and occasional binary
		1226	distributions for these. Search engines for
		1227	CPAN can be found at http://cpan.perl.com/
		1228	and at http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl
		1229	.
		1230
		1231
		1232	Most importantly, CPAN includes around a
		1233	thousand unbundled modules, some of which require a C
		1234	compiler to build. Major categories of modules
		1235	are:
		1236
		1237
		1238	Language Extensions and Documentation Tools
		1239
		1240
		1241	Development Support
		1242
		1243
		1244	Operating System Interfaces
		1245
		1246
2	perry	1247	Networking, Device Control (modems) and !InterProcess
1	perry	1248	Communication
		1249
		1250
		1251	Data Types and Data Type Utilities
		1252
		1253
		1254	Database Interfaces
		1255
		1256
		1257	User Interfaces
		1258
		1259
		1260	Interfaces to / Emulations of Other Programming
		1261	Languages
		1262
		1263
		1264	File Names, File Systems and File Locking (see also File
		1265	Handles)
		1266
		1267
		1268	String Processing, Language Text Processing, Parsing, and
		1269	Searching
		1270
		1271
		1272	Option, Argument, Parameter, and Configuration File
		1273	Processing
		1274
		1275
		1276	Internationalization and Locale
		1277
		1278
		1279	Authentication, Security, and Encryption
		1280
		1281
		1282	World Wide Web, HTML , HTTP ,
		1283	CGI , MIME
		1284
		1285
		1286	Server and Daemon Utilities
		1287
		1288
		1289	Archiving and Compression
		1290
		1291
		1292	Images, Pixmap and Bitmap Manipulation, Drawing, and
		1293	Graphing
		1294
		1295
		1296	Mail and Usenet News
		1297
		1298
		1299	Control Flow Utilities (callbacks and exceptions
		1300	etc)
		1301
		1302
		1303	File Handle and Input/Output Stream Utilities
		1304
		1305
		1306	Miscellaneous Modules
		1307
		1308
		1309	Registered CPAN sites as of this writing
		1310	include the following. You should try to choose one close to
		1311	you:
		1312
		1313
		1314	__Africa__
		1315
		1316
		1317	South Africa
		1318
		1319
		1320	ftp://ftp.is.co.za/programming/perl/CPAN/
		1321	ftp://ftp.saix.net/pub/CPAN/
		1322	ftp://ftpza.co.za/pub/mirrors/cpan/
		1323	ftp://ftp.sun.ac.za/CPAN/
		1324
		1325
		1326	__Asia__
		1327
		1328
		1329	China
		1330
		1331
		1332	ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
		1333	http://www2.linuxforum.net/mirror/CPAN/
		1334	http://cpan.shellhung.org/
		1335	ftp://ftp.shellhung.org/pub/CPAN
		1336
		1337
		1338	Hong Kong
		1339
		1340
		1341	http://CPAN.pacific.net.hk/
		1342	ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
		1343
		1344
		1345	Indonesia
		1346
		1347
		1348	http://piksi.itb.ac.id/CPAN/
		1349	ftp://mirrors.piksi.itb.ac.id/CPAN/
		1350	http://CPAN.mweb.co.id/
		1351	ftp://ftp.mweb.co.id/pub/languages/perl/CPAN/
		1352
		1353
		1354	Israel
		1355
		1356
		1357	http://www.iglu.org.il:/pub/CPAN/
		1358	ftp://ftp.iglu.org.il/pub/CPAN/
		1359	http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
		1360	ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
		1361
		1362
		1363	Japan
		1364
		1365
		1366	ftp://ftp.u-aizu.ac.jp/pub/lang/perl/CPAN/
		1367	ftp://ftp.kddlabs.co.jp/CPAN/
		1368	http://mirror.nucba.ac.jp/mirror/Perl/
		1369	ftp://mirror.nucba.ac.jp/mirror/Perl/
		1370	ftp://ftp.meisei-u.ac.jp/pub/CPAN/
		1371	ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
		1372	ftp://ftp.dti.ad.jp/pub/lang/CPAN/
		1373	ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
		1374
		1375
		1376	Saudi Arabia
		1377
		1378
		1379	ftp://ftp.isu.net.sa/pub/CPAN/
		1380
		1381
		1382	Singapore
		1383
		1384
		1385	http://cpan.hjc.edu.sg
		1386	http://ftp.nus.edu.sg/unix/perl/CPAN/
		1387	ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
		1388
		1389
		1390	South Korea
		1391
		1392
		1393	http://CPAN.bora.net/
		1394	ftp://ftp.bora.net/pub/CPAN/
		1395	http://ftp.kornet.net/CPAN/
		1396	ftp://ftp.kornet.net/pub/CPAN/
		1397	ftp://ftp.nuri.net/pub/CPAN/
		1398
		1399
		1400	Taiwan
		1401
		1402
		1403	ftp://coda.nctu.edu.tw/UNIX/perl/CPAN
		1404	ftp://ftp.ee.ncku.edu.tw/pub/perl/CPAN/
		1405	ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
		1406
		1407
		1408	Thailand
		1409
		1410
		1411	http://download.nectec.or.th/CPAN/
		1412	ftp://ftp.nectec.or.th/pub/languages/CPAN/
		1413	ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
		1414
		1415
		1416	__Central America__
		1417
		1418
		1419	Costa Rica
		1420
		1421
		1422	ftp://ftp.linux.co.cr/mirrors/CPAN/
		1423	http://ftp.ucr.ac.cr/Unix/CPAN/
		1424	ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
		1425
		1426
		1427	__Europe__
		1428
		1429
		1430	Austria
		1431
		1432
		1433	ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
		1434
		1435
		1436	Belgium
		1437
		1438
		1439	http://ftp.easynet.be/CPAN/
		1440	ftp://ftp.easynet.be/CPAN/
		1441	ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
		1442
		1443
		1444	Bulgaria
		1445
		1446
		1447	ftp://ftp.ntrl.net/pub/mirrors/CPAN/
		1448
		1449
		1450	Croatia
		1451
		1452
		1453	ftp://ftp.linux.hr/pub/CPAN/
		1454
		1455
		1456	Czech Republic
		1457
		1458
		1459	http://www.fi.muni.cz/pub/perl/
		1460	ftp://ftp.fi.muni.cz/pub/perl/
		1461	ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/
		1462
		1463
		1464	Denmark
		1465
		1466
		1467	ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
		1468	http://www.cpan.dk/CPAN/
		1469	ftp://www.cpan.dk/ftp.cpan.org/CPAN/
		1470
		1471
		1472	England
		1473
		1474
		1475	http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN
		1476	ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
		1477	ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
		1478	ftp://ftp.flirble.org/pub/languages/perl/CPAN/
		1479	ftp://ftp.plig.org/pub/CPAN/
		1480	ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
		1481	http://mirror.uklinux.net/CPAN/
		1482	ftp://mirror.uklinux.net/pub/CPAN/
		1483	ftp://usit.shef.ac.uk/pub/packages/CPAN/
		1484
		1485
		1486	Estonia
		1487
		1488
		1489	ftp://ftp.ut.ee/pub/languages/perl/CPAN/
		1490
		1491
		1492	Finland
		1493
		1494
		1495	ftp://ftp.funet.fi/pub/languages/perl/CPAN/
		1496
		1497
		1498	France
		1499
		1500
		1501	ftp://cpan.ftp.worldonline.fr/pub/CPAN/
		1502	ftp://ftp.club-internet.fr/pub/perl/CPAN/
		1503	ftp://ftp.lip6.fr/pub/perl/CPAN/
		1504	ftp://ftp.oleane.net/pub/mirrors/CPAN/
		1505	ftp://ftp.pasteur.fr/pub/computing/CPAN/
		1506	ftp://cpan.cict.fr/pub/CPAN/
		1507	ftp://ftp.uvsq.fr/pub/perl/CPAN/
		1508
		1509
		1510	Germany
		1511
		1512
		1513	ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
		1514	ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
		1515	ftp://ftp.uni-erlangen.de/pub/source/CPAN/
		1516	ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN
		1517	ftp://ftp.gigabell.net/pub/CPAN/
		1518	http://ftp.gwdg.de/pub/languages/perl/CPAN/
		1519	ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
		1520	ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
		1521	ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
		1522	ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
		1523	ftp://ftp.gmd.de/mirrors/CPAN/
		1524
		1525
		1526	Greece
		1527
		1528
		1529	ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
		1530	ftp://ftp.ntua.gr/pub/lang/perl/
		1531
		1532
		1533	Hungary
		1534
		1535
		1536	http://cpan.artifact.hu/
		1537	ftp://cpan.artifact.hu/CPAN/
		1538	ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
		1539
		1540
		1541	Iceland
		1542
		1543
		1544	http://cpan.gm.is/
		1545	ftp://ftp.gm.is/pub/CPAN/
		1546
		1547
		1548	Ireland
		1549
		1550
		1551	http://cpan.indigo.ie/
		1552	ftp://cpan.indigo.ie/pub/CPAN/
		1553	http://sunsite.compapp.dcu.ie/pub/perl/
		1554	ftp://sunsite.compapp.dcu.ie/pub/perl/
		1555
		1556
		1557	Italy
		1558
		1559
		1560	http://cpan.nettuno.it/
		1561	http://gusp.dyndns.org/CPAN/
		1562	ftp://gusp.dyndns.org/pub/CPAN
		1563	http://softcity.iol.it/cpan
		1564	ftp://softcity.iol.it/pub/cpan
		1565	ftp://ftp.unina.it/pub/Other/CPAN/
		1566	ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
		1567	ftp://cis.uniRoma2.it/CPAN/
		1568	ftp://ftp.edisontel.it/pub/CPAN_Mirror/
		1569	ftp://ftp.flashnet.it/pub/CPAN/
		1570
		1571
		1572	Latvia
		1573
		1574
		1575	http://kvin.lv/pub/CPAN/
		1576
		1577
		1578	Netherlands
		1579
		1580
		1581	ftp://download.xs4all.nl/pub/mirror/CPAN/
		1582	ftp://ftp.nl.uu.net/pub/CPAN/
		1583	ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
		1584	ftp://ftp.cpan.nl/pub/CPAN/
		1585	http://www.cs.uu.nl/mirror/CPAN/
		1586	ftp://ftp.cs.uu.nl/mirror/CPAN/
		1587
		1588
		1589	Norway
		1590
		1591
		1592	ftp://sunsite.uio.no/pub/languages/perl/CPAN/
		1593	ftp://ftp.uit.no/pub/languages/perl/cpan/
		1594
		1595
		1596	Poland
		1597
		1598
		1599	ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
		1600	ftp://ftp.mega.net.pl/pub/mirrors/ftp.perl.com/
		1601	ftp://ftp.man.torun.pl/pub/doc/CPAN/
		1602	ftp://sunsite.icm.edu.pl/pub/CPAN/
		1603
		1604
		1605	Portugal
		1606
		1607
		1608	ftp://ftp.ua.pt/pub/CPAN/
		1609	ftp://perl.di.uminho.pt/pub/CPAN/
		1610	ftp://ftp.ist.utl.pt/pub/CPAN/
		1611	ftp://ftp.netc.pt/pub/CPAN/
		1612
		1613
		1614	Romania
		1615
		1616
		1617	ftp://archive.logicnet.ro/mirrors/ftp.cpan.org/CPAN/
		1618	ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/
		1619	ftp://ftp.dntis.ro/pub/cpan/
		1620	ftp://ftp.opsynet.com/cpan/
		1621	ftp://ftp.dnttm.ro/pub/CPAN/
		1622	ftp://ftp.timisoara.roedu.net/mirrors/CPAN/
		1623
		1624
		1625	Russia
		1626
		1627
		1628	ftp://ftp.chg.ru/pub/lang/perl/CPAN/
		1629	http://cpan.rinet.ru/
		1630	ftp://cpan.rinet.ru/pub/mirror/CPAN/
		1631	ftp://ftp.aha.ru/pub/CPAN/
		1632	ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
		1633
		1634
		1635	Slovakia
		1636
		1637
		1638	ftp://ftp.entry.sk/pub/languages/perl/CPAN/
		1639
		1640
		1641	Slovenia
		1642
		1643
		1644	ftp://ftp.arnes.si/software/perl/CPAN/
		1645
		1646
		1647	Spain
		1648
		1649
		1650	ftp://ftp.rediris.es/mirror/CPAN/
		1651	ftp://ftp.etse.urv.es/pub/perl/
		1652
		1653
		1654	Sweden
		1655
		1656
		1657	http://ftp.du.se/CPAN/
		1658	ftp://ftp.du.se/pub/CPAN/
		1659	ftp://ftp.sunet.se/pub/lang/perl/CPAN/
		1660
		1661
		1662	Switzerland
		1663
		1664
		1665	ftp://ftp.danyk.ch/CPAN/
		1666	ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
		1667
		1668
		1669	Turkey
		1670
		1671
		1672	ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
		1673
		1674
		1675	__North America__
		1676
		1677
		1678	Canada
		1679
		1680
		1681	Alberta
		1682
		1683
		1684	http://sunsite.ualberta.ca/pub/Mirror/CPAN/
		1685	ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
		1686
		1687
		1688	Manitoba
		1689
		1690
		1691	http://theoryx5.uwinnipeg.ca/pub/CPAN/
		1692	ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
		1693
		1694
		1695	Nova Scotia
		1696
		1697
		1698	ftp://cpan.chebucto.ns.ca/pub/CPAN/
		1699
		1700
		1701	Ontario
		1702
		1703
		1704	ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
		1705
		1706
		1707	Mexico
		1708
		1709
		1710	http://www.msg.com.mx/CPAN/
		1711	ftp://ftp.msg.com.mx/pub/CPAN/
		1712
		1713
		1714	United States
		1715
		1716
		1717	Alabama
		1718
		1719
		1720	http://mirror.hiwaay.net/CPAN/
		1721	ftp://mirror.hiwaay.net/CPAN/
		1722
		1723
		1724	California
		1725
		1726
		1727	http://www.cpan.org/
		1728	ftp://ftp.cpan.org/CPAN/
		1729	ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
		1730	ftp://ftp.digital.com/pub/plan/perl/CPAN/
		1731	http://www.kernel.org/pub/mirrors/cpan/
		1732	ftp://ftp.kernel.org/pub/mirrors/cpan/
		1733	http://www.perl.com/CPAN/
		1734	http://download.sourceforge.net/mirrors/CPAN/
		1735
		1736
		1737	Colorado
		1738
		1739
		1740	ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
		1741
		1742
		1743	Florida
		1744
		1745
		1746	ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
		1747
		1748
		1749	Georgia
		1750
		1751
		1752	ftp://ftp.twoguys.org/CPAN/
		1753
		1754
		1755	Illinois
		1756
		1757
		1758	http://www.neurogames.com/mirrors/CPAN
		1759	http://uiarchive.uiuc.edu/mirrors/ftp/ftp.cpan.org/pub/CPAN/
		1760	ftp://uiarchive.uiuc.edu/mirrors/ftp/ftp.cpan.org/pub/CPAN/
		1761
		1762
		1763	Indiana
		1764
		1765
		1766	ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
		1767	http://cpan.nitco.com/
		1768	ftp://cpan.nitco.com/pub/CPAN/
		1769	ftp://cpan.in-span.net/
		1770	http://csociety-ftp.ecn.purdue.edu/pub/CPAN
		1771	ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN
		1772
		1773
		1774	Kentucky
		1775
		1776
		1777	http://cpan.uky.edu/
		1778	ftp://cpan.uky.edu/pub/CPAN/
		1779
		1780
		1781	Massachusetts
		1782
		1783
		1784	ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
		1785	ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
		1786
		1787
		1788	New Jersey
		1789
		1790
		1791	ftp://ftp.cpanel.net/pub/CPAN/
		1792
		1793
		1794	New York
		1795
		1796
		1797	ftp://ftp.freesoftware.com/pub/perl/CPAN/
		1798	http://www.deao.net/mirrors/CPAN/
		1799	ftp://ftp.deao.net/pub/CPAN/
		1800	ftp://ftp.stealth.net/pub/mirrors/ftp.cpan.org/pub/CPAN/
		1801	http://mirror.nyc.anidea.com/CPAN/
		1802	ftp://mirror.nyc.anidea.com/pub/CPAN/
		1803	http://www.rge.com/pub/languages/perl/
		1804	ftp://ftp.rge.com/pub/languages/perl/
		1805	ftp://mirrors.cloud9.net/pub/mirrors/CPAN/
		1806
		1807
		1808	North Carolina
		1809
		1810
		1811	ftp://ftp.duke.edu/pub/perl/
		1812
		1813
		1814	Ohio
		1815
		1816
		1817	ftp://ftp.loaded.net/pub/CPAN/
		1818
		1819
		1820	Oklahoma
		1821
		1822
		1823	ftp://ftp.ou.edu/mirrors/CPAN/
		1824
		1825
		1826	Oregon
		1827
		1828
		1829	ftp://ftp.orst.edu/pub/packages/CPAN/
		1830
		1831
		1832	Pennsylvania
		1833
		1834
		1835	http://ftp.epix.net/CPAN/
		1836	ftp://ftp.epix.net/pub/languages/perl/
		1837	ftp://carroll.cac.psu.edu/pub/CPAN/
		1838
		1839
		1840	Tennessee
		1841
		1842
		1843	ftp://ftp.sunsite.utk.edu/pub/CPAN/
		1844
		1845
		1846	Texas
		1847
		1848
		1849	http://ftp.sedl.org/pub/mirrors/CPAN/
		1850	http://jhcloos.com/pub/mirror/CPAN/
		1851	ftp://jhcloos.com/pub/mirror/CPAN/
		1852
		1853
		1854	Utah
		1855
		1856
		1857	ftp://mirror.xmission.com/CPAN/
		1858
		1859
		1860	Virginia
		1861
		1862
		1863	http://mirrors.rcn.net/pub/lang/CPAN/
		1864	ftp://mirrors.rcn.net/pub/lang/CPAN/
		1865	ftp://ruff.cs.jmu.edu/pub/CPAN/
		1866	http://perl.Liquidation.com/CPAN/
		1867
		1868
		1869	Washington
		1870
		1871
		1872	http://cpan.llarian.net/
		1873	ftp://cpan.llarian.net/pub/CPAN/
		1874	ftp://ftp-mirror.internap.com/pub/CPAN/
		1875	ftp://ftp.spu.edu/pub/CPAN/
		1876
		1877
		1878	__Oceania__
		1879
		1880
		1881	Australia
		1882
		1883
		1884	http://ftp.planetmirror.com/pub/CPAN/
		1885	ftp://ftp.planetmirror.com/pub/CPAN/
		1886	ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
		1887	ftp://cpan.topend.com.au/pub/CPAN/
		1888
		1889
		1890	New Zealand
		1891
		1892
		1893	ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
		1894
		1895
		1896	__South America__
		1897
		1898
		1899	Argentina
		1900
		1901
		1902	ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/
		1903
		1904
		1905	Brazil
		1906
		1907
		1908	ftp://cpan.pop-mg.com.br/pub/CPAN/
		1909	ftp://ftp.matrix.com.br/pub/perl/
		1910	ftp://cpan.if.usp.br/pub/mirror/CPAN/
		1911
		1912
		1913	Chile
		1914
		1915
		1916	ftp://ftp.psinet.cl/pub/programming/perl/CPAN/
		1917	ftp://sunsite.dcc.uchile.cl/pub/lang/perl/
		1918
		1919
		1920	For an up-to-date listing of CPAN sites, see
		1921	http://www.cpan.org/SITES or ftp://www.cpan.org/SITES
		1922	.
		1923	!!Modules: Creation, Use, and Abuse
		1924
		1925
		1926	(The following section is borrowed directly from Tim Bunce's
		1927	modules file, available at your nearest CPAN
		1928	site.)
		1929
		1930
		1931	Perl implements a class using a package, but the presence of
		1932	a package doesn't imply the presence of a class. A package
		1933	is just a namespace. A class is a package that provides
		1934	subroutines that can be used as methods. A method is just a
		1935	subroutine that expects, as its first argument, either the
		1936	name of a package (for ``static'' methods), or a reference
		1937	to something (for ``virtual'' methods).
		1938
		1939
		1940	A module is a file that (by convention) provides a class of
		1941	the same name (sans the .pm), plus an import method in that
		1942	class that can be called to fetch exported symbols. This
		1943	module may implement some of its methods by loading dynamic
		1944	C or C ++ objects, but that should be totally
		1945	transparent to the user of the module. Likewise, the module
		1946	might set up an AUTOLOAD function to slurp in
		1947	subroutine definitions on demand, but this is also
		1948	transparent. Only the ''.pm'' file is required to exist.
2	perry	1949	See perlsub, perltoot, and !AutoLoader for details about the
1	perry	1950	AUTOLOAD mechanism.
		1951
		1952
		1953	__Guidelines for Module Creation__
		1954
		1955
		1956	Do similar modules already exist in some form?
		1957
		1958
		1959	If so, please try to reuse the existing modules either in
		1960	whole or by inheriting useful features into a new class. If
		1961	this is not practical try to get together with the module
		1962	authors to work on extending or enhancing the functionality
		1963	of the existing modules. A perfect example is the plethora
		1964	of packages in perl4 for dealing with command line
		1965	options.
		1966
		1967
		1968	If you are writing a module to expand an already existing
		1969	set of modules, please coordinate with the author of the
		1970	package. It helps if you follow the same naming scheme and
		1971	module interaction scheme as the original
		1972	author.
		1973
		1974
		1975	Try to design the new module to be easy to extend and
		1976	reuse.
		1977
		1978
		1979	Try to use warnings; (or use warnings
		1980	qw(...);). Remember that you can add no warnings
		1981	qw(...); to individual blocks of code that need less
		1982	warnings.
		1983
		1984
		1985	Use blessed references. Use the two argument form of bless
		1986	to bless into the class name given as the first parameter of
		1987	the constructor, e.g.,:
		1988
		1989
		1990	sub new {
		1991	my $class = shift;
		1992	return bless {}, $class;
		1993	}
		1994	or even this if you'd like it to be used as either a static or a virtual method.
		1995
		1996
		1997	sub new {
		1998	my $self = shift;
		1999	my $class = ref($self) $self;
		2000	return bless {}, $class;
		2001	}
		2002	Pass arrays as references so more parameters can be added later (it's also faster). Convert functions into methods where appropriate. Split large methods into smaller more flexible ones. Inherit methods from other modules if appropriate.
		2003
		2004
		2005	Avoid class name tests like: die
		2006	. Generally you can delete the
		2007	eq 'FOO' part with no harm at all. Let the objects
		2008	look after themselves! Generally, avoid hard-wired class
		2009	names as far as possible.
		2010
		2011
		2012	Avoid $r- where using
		2013	@ISA=qw(... Class ...) and $r-
		2014	would work (see perlbot for more details).
		2015
		2016
		2017	Use autosplit so little used or newly added functions won't
		2018	be a burden to programs that don't use them. Add test
2	perry	2019	functions to the module after __END__ either using !AutoSplit
1	perry	2020	or by saying:
		2021
		2022
		2023	eval join('',
		2024	Does your module pass the 'empty subclass' test? If you say @SUBCLASS::ISA = qw(YOURCLASS); your applications should be able to use SUBCLASS in exactly the same way as YOURCLASS . For example, does your application still work if you change: $obj = new YOURCLASS; into: $obj = new SUBCLASS; ?
		2025
		2026
		2027	Avoid keeping any state information in your packages. It
		2028	makes it difficult for multiple other packages to use yours.
		2029	Keep state information in objects.
		2030
		2031
		2032	Always use __-w__.
		2033
		2034
		2035	Try to use strict; (or use strict
		2036	qw(...);). Remember that you can add no strict
		2037	qw(...); to individual blocks of code that need less
		2038	strictness.
		2039
		2040
		2041	Always use __-w__.
		2042
		2043
		2044	Follow the guidelines in the perlstyle(1)
		2045	manual.
		2046
		2047
		2048	Always use __-w__.
		2049
		2050
		2051	Some simple style guidelines
		2052
		2053
		2054	The perlstyle manual supplied with Perl has many helpful
		2055	points.
		2056
		2057
		2058	Coding style is a matter of personal taste. Many people
		2059	evolve their style over several years as they learn what
		2060	helps them write and maintain good code. Here's one set of
		2061	assorted suggestions that seem to be widely used by
		2062	experienced developers:
		2063
		2064
		2065	Use underscores to separate words. It is generally easier to
		2066	read $var_names_like_this than
2	perry	2067	$!VarNamesLikeThis, especially for non-native
1	perry	2068	speakers of English. It's also a simple rule that works
		2069	consistently with VAR_NAMES_LIKE_THIS
		2070	.
		2071
		2072
		2073	Package/Module names are an exception to this rule. Perl
		2074	informally reserves lowercase module names for 'pragma'
		2075	modules like integer and strict. Other modules normally
		2076	begin with a capital letter and use mixed case with no
		2077	underscores (need to be short and portable).
		2078
		2079
		2080	You may find it helpful to use letter case to indicate the
		2081	scope or nature of a variable. For example:
		2082
		2083
		2084	$ALL_CAPS_HERE constants only (beware clashes with Perl vars)
		2085	$Some_Caps_Here package-wide global/static
		2086	$no_caps_here function scope my() or local() variables
		2087	Function and method names seem to work best as all lowercase. e.g., $obj-.
		2088
		2089
		2090	You can use a leading underscore to indicate that a variable
		2091	or function should not be used outside the package that
		2092	defined it.
		2093
		2094
		2095	Select what to export.
		2096
		2097
		2098	Do NOT export method names!
		2099
		2100
		2101	Do NOT export anything else by default
		2102	without a good reason!
		2103
		2104
		2105	Exports pollute the namespace of the module user. If you
		2106	must export try to use @EXPORT_OK in preference to
		2107	@EXPORT and avoid short or common names to reduce
		2108	the risk of name clashes.
		2109
		2110
		2111	Generally anything not exported is still accessible from
2	perry	2112	outside the module using the !ModuleName::item_name (or
1	perry	2113	$blessed_ref-) syntax. By convention you
		2114	can use a leading underscore on names to indicate informally
		2115	that they are 'internal' and not for public
		2116	use.
		2117
		2118
		2119	(It is actually possible to get private functions by saying:
		2120	my $subref = sub { ... }; . But
		2121	there's no way to call that directly as a method, because a
		2122	method must have a name in the symbol table.)
		2123
		2124
		2125	As a general rule, if the module is trying to be object
		2126	oriented then export nothing. If it's just a collection of
		2127	functions then @EXPORT_OK anything but use
		2128	@EXPORT with caution.
		2129
		2130
		2131	Select a name for the module.
		2132
		2133
		2134	This name should be as descriptive, accurate, and complete
		2135	as possible. Avoid any risk of ambiguity. Always try to use
		2136	two or more whole words. Generally the name should reflect
		2137	what is special about what the module does rather than how
		2138	it does it. Please use nested module names to group
		2139	informally or categorize a module. There should be a very
		2140	good reason for a module not to have a nested name. Module
		2141	names should begin with a capital letter.
		2142
		2143
		2144	Having 57 modules all called Sort will not make life easy
		2145	for anyone (though having 23 called Sort::Quick is only
		2146	marginally better :-). Imagine someone trying to install
		2147	your module alongside many others. If in any doubt ask for
		2148	suggestions in comp.lang.perl.misc.
		2149
		2150
		2151	If you are developing a suite of related modules/classes
		2152	it's good practice to use nested classes with a common
		2153	prefix as this will avoid namespace clashes. For example:
		2154	Xyz::Control, Xyz::View, Xyz::Model etc. Use the modules in
		2155	this list as a naming guide.
		2156
		2157
		2158	If adding a new module to a set, follow the original
		2159	author's standards for naming modules and the interface to
		2160	methods in those modules.
		2161
		2162
		2163	If developing modules for private internal or project
		2164	specific use, that will never be released to the public,
		2165	then you should ensure that their names will not clash with
		2166	any future public module. You can do this either by using
		2167	the reserved Local::* category or by using a category name
		2168	that includes an underscore like Foo_Corp::*.
		2169
		2170
		2171	To be portable each component of a module name should be
		2172	limited to 11 characters. If it might be used on MS-DOS then
		2173	try to ensure each is unique in the first 8 characters.
		2174	Nested modules make this easier.
		2175
		2176
		2177	Have you got it right?
		2178
		2179
		2180	How do you know that you've made the right decisions? Have
		2181	you picked an interface design that will cause problems
		2182	later? Have you picked the most appropriate name? Do you
		2183	have any questions?
		2184
		2185
		2186	The best way to know for sure, and pick up many helpful
		2187	suggestions, is to ask someone who knows.
		2188	Comp.lang.perl.misc is read by just about all the people who
		2189	develop modules and it's the best place to ask.
		2190
		2191
		2192	All you need to do is post a short summary of the module,
		2193	its purpose and interfaces. A few lines on each of the main
		2194	methods is probably enough. (If you post the whole module it
		2195	might be ignored by busy people - generally the very people
		2196	you want to read it!)
		2197
		2198
		2199	Don't worry about posting if you can't say when the module
		2200	will be ready - just say so in the message. It might be
		2201	worth inviting others to help you, they may be able to
		2202	complete it for you!
		2203
		2204
		2205	README and other Additional
		2206	Files.
		2207
		2208
		2209	It's well known that software developers usually fully
		2210	document the software they write. If, however, the world is
		2211	in urgent need of your software and there is not enough time
		2212	to write the full documentation please at least provide a
		2213	README file containing:
		2214
		2215
		2216	A description of the module/package/extension
		2217	etc.
		2218
		2219
		2220	A copyright notice - see below.
		2221
		2222
		2223	Prerequisites - what else you may need to have.
		2224
		2225
		2226	How to build it - possible changes to Makefile.PL
		2227	etc.
		2228
		2229
		2230	How to install it.
		2231
		2232
		2233	Recent changes in this release, especially
		2234	incompatibilities
		2235
		2236
		2237	Changes / enhancements you plan to make in the
		2238	future.
		2239
		2240
		2241	If the README file seems to be getting too
		2242	large you may wish to split out some of the sections into
2	perry	2243	separate files: INSTALL , Copying, !ToDo
1	perry	2244	etc.
		2245
		2246
		2247	Adding a Copyright Notice.
		2248
		2249
		2250	How you choose to license your work is a personal decision.
		2251	The general mechanism is to assert your Copyright and then
		2252	make a declaration of how others may copy/use/modify your
		2253	work.
		2254
		2255
		2256	Perl, for example, is supplied with two types of licence:
		2257	The GNU GPL and The Artistic Licence (see the
		2258	files README , Copying, and Artistic). Larry
		2259	has good reasons for NOT just using the
		2260	GNU GPL .
		2261
		2262
		2263	My personal recommendation, out of respect for Larry, Perl,
		2264	and the Perl community at large is to state something simply
		2265	like:
		2266
		2267
		2268	Copyright (c) 1995 Your Name. All rights reserved.
		2269	This program is free software; you can redistribute it and/or
		2270	modify it under the same terms as Perl itself.
		2271	This statement should at least appear in the README file. You may also wish to include it in a Copying file and your source files. Remember to include the other words in addition to the Copyright.
		2272
		2273
		2274	Give the module a version/issue/release number.
		2275
		2276
2	perry	2277	To be fully compatible with the Exporter and !MakeMaker
1	perry	2278	modules you should store your module's version number in a
		2279	non-my package variable called $VERSION. This
		2280	should be a floating point number with at least two digits
		2281	after the decimal (i.e., hundredths, e.g, $VERSION =
		2282	). Don't use a ``1.3.2'' style version.
		2283	See Exporter for details.
		2284
		2285
		2286	It may be handy to add a function or method to retrieve the
		2287	number. Use the number in announcements and archive file
2	perry	2288	names when releasing the module (!ModuleName-1.02.tar.Z). See
		2289	perldoc !ExtUtils::!MakeMaker.pm for details.
1	perry	2290
		2291
		2292	How to release and distribute a module.
		2293
		2294
		2295	It's good idea to post an announcement of the availability
		2296	of your module (or the module itself if small) to the
		2297	comp.lang.perl.announce Usenet newsgroup. This will at least
		2298	ensure very wide once-off distribution.
		2299
		2300
		2301	If possible, register the module with CPAN .
		2302	You should include details of its location in your
		2303	announcement.
		2304
		2305
		2306	Some notes about ftp archives: Please use a long descriptive
		2307	file name that includes the version number. Most incoming
		2308	directories will not be readable/listable, i.e., you won't
		2309	be able to see your file after uploading it. Remember to
		2310	send your email notification message as soon as possible
		2311	after uploading else your file may get deleted
		2312	automatically. Allow time for the file to be processed
		2313	and/or check the file has been processed before announcing
		2314	its location.
		2315
		2316
		2317	FTP Archives for Perl Modules:
		2318
		2319
		2320	Follow the instructions and links on:
		2321
		2322
		2323	http://www.cpan.org/modules/00modlist.long.html
		2324	http://www.cpan.org/modules/04pause.html
		2325	or upload to one of these sites:
		2326
		2327
		2328	https://pause.kbx.de/pause/
		2329	http://pause.perl.org/pause/
		2330	and notify
		2331
		2332
		2333	By using the WWW interface you can ask the
		2334	Upload Server to mirror your modules from your ftp or
		2335	WWW site into your own directory on
		2336	CPAN !
		2337
		2338
		2339	Please remember to send me an updated entry for the Module
		2340	list!
		2341
		2342
		2343	Take care when changing a released module.
		2344
		2345
		2346	Always strive to remain compatible with previous released
		2347	versions. Otherwise try to add a mechanism to revert to the
		2348	old behavior if people rely on it. Document incompatible
		2349	changes.
		2350
		2351
		2352	__Guidelines for Converting Perl 4 Library Scripts into
		2353	Modules__
		2354
		2355
		2356	There is no requirement to convert anything.
		2357
		2358
		2359	If it ain't broke, don't fix it! Perl 4 library scripts
		2360	should continue to work with no problems. You may need to
		2361	make some minor changes (like escaping non-array @'s in
		2362	double quoted strings) but there is no need to convert a .pl
		2363	file into a Module for just that.
		2364
		2365
		2366	Consider the implications.
		2367
		2368
		2369	All Perl applications that make use of the script will need
		2370	to be changed (slightly) if the script is converted into a
		2371	module. Is it worth it unless you plan to make other changes
		2372	at the same time?
		2373
		2374
		2375	Make the most of the opportunity.
		2376
		2377
		2378	If you are going to convert the script to a module you can
		2379	use the opportunity to redesign the interface. The
		2380	guidelines for module creation above include many of the
		2381	issues you should consider.
		2382
		2383
		2384	The pl2pm utility will get you started.
		2385
		2386
		2387	This utility will read *.pl files (given as parameters) and
		2388	write corresponding *.pm files. The pl2pm utilities does the
		2389	following:
		2390
		2391
		2392	Adds the standard Module prologue lines
		2393
		2394
		2395	Converts package specifiers from ' to ::
		2396
		2397
		2398	Converts die(...) to croak(...)
		2399
		2400
		2401	Several other minor changes
		2402
		2403
		2404	Being a mechanical process pl2pm is not bullet proof. The
		2405	converted code will need careful checking, especially any
		2406	package statements. Don't delete the original .pl file till
		2407	the new .pm one works!
		2408
		2409
		2410	__Guidelines for Reusing Application Code__
		2411
		2412
		2413	Complete applications rarely belong in the Perl Module
		2414	Library.
		2415
		2416
		2417	Many applications contain some Perl code that could be
		2418	reused.
		2419
		2420
		2421	Help save the world! Share your code in a form that makes it
		2422	easy to reuse.
		2423
		2424
		2425	Break-out the reusable code into one or more separate module
		2426	files.
		2427
		2428
		2429	Take the opportunity to reconsider and redesign the
		2430	interfaces.
		2431
		2432
		2433	In some cases the 'application' can then be reduced to a
		2434	small
		2435
		2436
		2437	fragment of code built on top of the reusable modules. In
		2438	these cases the application could invoked as:
		2439
		2440
		2441	% perl -e 'use Module::Name; method(@ARGV)' ...
		2442	or
		2443	% perl -mModule::Name ... (in perl5.002 or higher)
		2444	!!NOTE
		2445
		2446
		2447	Perl does not enforce private and public parts of its
		2448	modules as you may have been used to in other languages like
		2449	C ++ , Ada, or Modula-17. Perl doesn't have
		2450	an infatuation with enforced privacy. It would prefer that
		2451	you stayed out of its living room because you weren't
		2452	invited, not because it has a shotgun.
		2453
		2454
		2455	The module and its user have a contract, part of which is
		2456	common law, and part of which is ``written''. Part of the
		2457	common law contract is that a module doesn't pollute any
		2458	namespace it wasn't asked to. The written contract for the
		2459	module (A.K.A. documentation) may make other provisions. But
2	perry	2460	then you know when you use !RedefineTheWorld that
1	perry	2461	you're redefining the world and willing to take the
		2462	consequences.
		2463	----