1PERLMODLIB(1) Perl Programmers Reference Guide PERLMODLIB(1)
2
6 perlmodlib - constructing new Perl modules and finding existing ones
7
9 Many modules are included in the Perl distribution. These are
10 described below, and all end in .pm. You may discover compiled library
11 files (usually ending in .so) or small pieces of modules to be
12 autoloaded (ending in .al); these were automatically generated by the
13 installation process. You may also discover files in the library
14 directory that end in either .pl or .ph. These are old libraries
15 supplied so that old programs that use them still run. The .pl files
16 will all eventually be converted into standard modules, and the .ph
17 files made by h2ph will probably end up as extension modules made by
18 h2xs. (Some .ph values may already be available through the POSIX,
19 Errno, or Fcntl modules.) The pl2pm file in the distribution may help
20 in your conversion, but it's just a mechanical process and therefore
21 far from bulletproof.
22 Pragmatic Modules
24 They work somewhat like compiler directives (pragmata) in that they
25 tend to affect the compilation of your program, and thus will usually
26 work well only when used within a "use", or "no". Most of these are
27 lexically scoped, so an inner BLOCK may countermand them by saying:
28 no integer;
30 no strict 'refs';
31 no warnings;
32 which lasts until the end of that BLOCK.
34 Some pragmas are lexically scoped--typically those that affect the $^H
36 hints variable. Others affect the current package instead, like "use
37 vars" and "use subs", which allow you to predeclare a variables or
38 subroutines within a particular file rather than just a block. Such
39 declarations are effective for the entire file for which they were
40 declared. You cannot rescind them with "no vars" or "no subs".
41 The following pragmas are defined (and have their own documentation).
43 attributes Get/set subroutine or variable attributes
45 autodie Replace functions with ones that succeed or die with
47 lexical scope
48 autodie::exception
50 Exceptions from autodying functions.
51 autodie::exception::system
53 Exceptions from autodying system().
54 autodie::hints
56 Provide hints about user subroutines to autodie
57 autodie::skip
59 Skip a package when throwing autodie exceptions
60 autouse Postpone load of modules until a function is used
62 base Establish an ISA relationship with base classes at compile
64 time
65 bigfloat Transparent big floating point number support for Perl
67 bigint Transparent big integer support for Perl
69 bignum Transparent big number support for Perl
71 bigrat Transparent big rational number support for Perl
73 blib Use MakeMaker's uninstalled version of a package
75 builtin Import built-in utility functions
77 bytes Expose the individual bytes of characters
79 charnames Access to Unicode character names and named character
81 sequences; also define character names
82 constant Declare constants
84 deprecate Perl pragma for deprecating the inclusion of a module in
86 core
87 diagnostics Produce verbose warning diagnostics
89 encoding Allows you to write your script in non-ASCII and non-UTF-8
91 encoding::warnings
93 Warn on implicit encoding conversions
94 experimental
96 Experimental features made easy
97 feature Enable new features
99 fields Compile-time class fields
101 filetest Control the filetest permission operators
103 if "use" a Perl module if a condition holds
105 integer Use integer arithmetic instead of floating point
107 less Request less of something
109 lib Manipulate @INC at compile time
111 locale Use or avoid POSIX locales for built-in operations
113 mro Method Resolution Order
115 ok Alternative to Test::More::use_ok
117 open Set default PerlIO layers for input and output
119 ops Restrict unsafe operations when compiling
121 overload Package for overloading Perl operations
123 overloading Lexically control overloading
125 parent Establish an ISA relationship with base classes at compile
127 time
128 re Alter regular expression behaviour
130 sigtrap Enable simple signal handling
132 sort Control sort() behaviour
134 strict Restrict unsafe constructs
136 subs Predeclare subroutine names
138 threads Perl interpreter-based threads
140 threads::shared
142 Perl extension for sharing data structures between threads
143 utf8 Enable/disable UTF-8 (or UTF-EBCDIC) in source code
145 vars Predeclare global variable names
147 version Perl extension for Version Objects
149 vmsish Control VMS-specific language features
151 warnings Control optional warnings
153 warnings::register
155 Warnings import function
156 Standard Modules
158 Standard, bundled modules are all expected to behave in a well-defined
159 manner with respect to namespace pollution because they use the
160 Exporter module. See their own documentation for details.
161 It's possible that not all modules listed below are installed on your
163 system. For example, the GDBM_File module will not be installed if you
164 don't have the gdbm library.
165 Amiga::ARexx
167 Perl extension for ARexx support
168 Amiga::Exec Perl extension for low level amiga support
170 AnyDBM_File Provide framework for multiple DBMs
172 App::Cpan Easily interact with CPAN from the command line
174 App::Prove Implements the "prove" command.
176 App::Prove::State
178 State storage for the "prove" command.
179 App::Prove::State::Result
181 Individual test suite results.
182 App::Prove::State::Result::Test
184 Individual test results.
185 Archive::Tar
187 Module for manipulations of tar archives
188 Archive::Tar::File
190 A subclass for in-memory extracted file from Archive::Tar
191 Attribute::Handlers
193 Simpler definition of attribute handlers
194 AutoLoader Load subroutines only on demand
196 AutoSplit Split a package for autoloading
198 B The Perl Compiler Backend
200 B::Concise Walk Perl syntax tree, printing concise info about ops
202 B::Deparse Perl compiler backend to produce perl code
204 B::Op_private
206 OP op_private flag definitions
207 B::Showlex Show lexical variables used in functions or files
209 B::Terse Walk Perl syntax tree, printing terse info about ops
211 B::Xref Generates cross reference reports for Perl programs
213 Benchmark Benchmark running times of Perl code
215 "IO::Socket::IP"
217 Family-neutral IP socket supporting both IPv4 and IPv6
218 "Socket" Networking constants and support functions
220 CORE Namespace for Perl's core routines
222 CPAN Query, download and build perl modules from CPAN sites
224 CPAN::API::HOWTO
226 A recipe book for programming with CPAN.pm
227 CPAN::Debug Internal debugging for CPAN.pm
229 CPAN::Distroprefs
231 Read and match distroprefs
232 CPAN::FirstTime
234 Utility for CPAN::Config file Initialization
235 CPAN::HandleConfig
237 Internal configuration handling for CPAN.pm
238 CPAN::Kwalify
240 Interface between CPAN.pm and Kwalify.pm
241 CPAN::Meta The distribution metadata for a CPAN dist
243 CPAN::Meta::Converter
245 Convert CPAN distribution metadata structures
246 CPAN::Meta::Feature
248 An optional feature provided by a CPAN distribution
249 CPAN::Meta::History
251 History of CPAN Meta Spec changes
252 CPAN::Meta::History::Meta_1_0
254 Version 1.0 metadata specification for META.yml
255 CPAN::Meta::History::Meta_1_1
257 Version 1.1 metadata specification for META.yml
258 CPAN::Meta::History::Meta_1_2
260 Version 1.2 metadata specification for META.yml
261 CPAN::Meta::History::Meta_1_3
263 Version 1.3 metadata specification for META.yml
264 CPAN::Meta::History::Meta_1_4
266 Version 1.4 metadata specification for META.yml
267 CPAN::Meta::Merge
269 Merging CPAN Meta fragments
270 CPAN::Meta::Prereqs
272 A set of distribution prerequisites by phase and type
273 CPAN::Meta::Requirements
275 A set of version requirements for a CPAN dist
276 CPAN::Meta::Spec
278 Specification for CPAN distribution metadata
279 CPAN::Meta::Validator
281 Validate CPAN distribution metadata structures
282 CPAN::Meta::YAML
284 Read and write a subset of YAML for CPAN Meta files
285 CPAN::Nox Wrapper around CPAN.pm without using any XS module
287 CPAN::Plugin
289 Base class for CPAN shell extensions
290 CPAN::Plugin::Specfile
292 Proof of concept implementation of a trivial CPAN::Plugin
293 CPAN::Queue Internal queue support for CPAN.pm
295 CPAN::Tarzip
297 Internal handling of tar archives for CPAN.pm
298 CPAN::Version
300 Utility functions to compare CPAN versions
301 Carp Alternative warn and die for modules
303 Class::Struct
305 Declare struct-like datatypes as Perl classes
306 Compress::Raw::Bzip2
308 Low-Level Interface to bzip2 compression library
309 Compress::Raw::Zlib
311 Low-Level Interface to zlib compression library
312 Compress::Zlib
314 Interface to zlib compression library
315 Config Access Perl configuration information
317 Config::Extensions
319 Hash lookup of which core extensions were built.
320 Config::Perl::V
322 Structured data retrieval of perl -V output
323 Cwd Get pathname of current working directory
325 DB Programmatic interface to the Perl debugging API
327 DBM_Filter Filter DBM keys/values
329 DBM_Filter::compress
331 Filter for DBM_Filter
332 DBM_Filter::encode
334 Filter for DBM_Filter
335 DBM_Filter::int32
337 Filter for DBM_Filter
338 DBM_Filter::null
340 Filter for DBM_Filter
341 DBM_Filter::utf8
343 Filter for DBM_Filter
344 DB_File Perl5 access to Berkeley DB version 1.x
346 Data::Dumper
348 Stringified perl data structures, suitable for both
349 printing and "eval"
350 Devel::PPPort
352 Perl/Pollution/Portability
353 Devel::Peek A data debugging tool for the XS programmer
355 Devel::SelfStubber
357 Generate stubs for a SelfLoading module
358 Digest Modules that calculate message digests
360 Digest::MD5 Perl interface to the MD5 Algorithm
362 Digest::SHA Perl extension for SHA-1/224/256/384/512
364 Digest::base
366 Digest base class
367 Digest::file
369 Calculate digests of files
370 DirHandle (obsolete) supply object methods for directory handles
372 Dumpvalue Provides screen dump of Perl data.
374 DynaLoader Dynamically load C libraries into Perl code
376 Encode Character encodings in Perl
378 Encode::Alias
380 Alias definitions to encodings
381 Encode::Byte
383 Single Byte Encodings
384 Encode::CJKConstants
386 Internally used by Encode::??::ISO_2022_*
387 Encode::CN China-based Chinese Encodings
389 Encode::CN::HZ
391 Internally used by Encode::CN
392 Encode::Config
394 Internally used by Encode
395 Encode::EBCDIC
397 EBCDIC Encodings
398 Encode::Encoder
400 Object Oriented Encoder
401 Encode::Encoding
403 Encode Implementation Base Class
404 Encode::GSM0338
406 ETSI GSM 03.38 Encoding
407 Encode::Guess
409 Guesses encoding from data
410 Encode::JP Japanese Encodings
412 Encode::JP::H2Z
414 Internally used by Encode::JP::2022_JP*
415 Encode::JP::JIS7
417 Internally used by Encode::JP
418 Encode::KR Korean Encodings
420 Encode::KR::2022_KR
422 Internally used by Encode::KR
423 Encode::MIME::Header
425 MIME encoding for an unstructured email header
426 Encode::MIME::Name
428 Internally used by Encode
429 Encode::PerlIO
431 A detailed document on Encode and PerlIO
432 Encode::Supported
434 Encodings supported by Encode
435 Encode::Symbol
437 Symbol Encodings
438 Encode::TW Taiwan-based Chinese Encodings
440 Encode::Unicode
442 Various Unicode Transformation Formats
443 Encode::Unicode::UTF7
445 UTF-7 encoding
446 English Use nice English (or awk) names for ugly punctuation
448 variables
449 Env Perl module that imports environment variables as scalars
451 or arrays
452 Errno System errno constants
454 Exporter Implements default import method for modules
456 Exporter::Heavy
458 Exporter guts
459 ExtUtils::CBuilder
461 Compile and link C code for Perl modules
462 ExtUtils::CBuilder::Platform::Windows
464 Builder class for Windows platforms
465 ExtUtils::Command
467 Utilities to replace common UNIX commands in Makefiles etc.
468 ExtUtils::Command::MM
470 Commands for the MM's to use in Makefiles
471 ExtUtils::Constant
473 Generate XS code to import C header constants
474 ExtUtils::Constant::Base
476 Base class for ExtUtils::Constant objects
477 ExtUtils::Constant::Utils
479 Helper functions for ExtUtils::Constant
480 ExtUtils::Constant::XS
482 Generate C code for XS modules' constants.
483 ExtUtils::Embed
485 Utilities for embedding Perl in C/C++ applications
486 ExtUtils::Install
488 Install files from here to there
489 ExtUtils::Installed
491 Inventory management of installed modules
492 ExtUtils::Liblist
494 Determine libraries to use and how to use them
495 ExtUtils::MM
497 OS adjusted ExtUtils::MakeMaker subclass
498 ExtUtils::MM::Utils
500 ExtUtils::MM methods without dependency on
501 ExtUtils::MakeMaker
502 ExtUtils::MM_AIX
504 AIX specific subclass of ExtUtils::MM_Unix
505 ExtUtils::MM_Any
507 Platform-agnostic MM methods
508 ExtUtils::MM_BeOS
510 Methods to override UN*X behaviour in ExtUtils::MakeMaker
511 ExtUtils::MM_Cygwin
513 Methods to override UN*X behaviour in ExtUtils::MakeMaker
514 ExtUtils::MM_DOS
516 DOS specific subclass of ExtUtils::MM_Unix
517 ExtUtils::MM_Darwin
519 Special behaviors for OS X
520 ExtUtils::MM_MacOS
522 Once produced Makefiles for MacOS Classic
523 ExtUtils::MM_NW5
525 Methods to override UN*X behaviour in ExtUtils::MakeMaker
526 ExtUtils::MM_OS2
528 Methods to override UN*X behaviour in ExtUtils::MakeMaker
529 ExtUtils::MM_OS390
531 OS390 specific subclass of ExtUtils::MM_Unix
532 ExtUtils::MM_QNX
534 QNX specific subclass of ExtUtils::MM_Unix
535 ExtUtils::MM_UWIN
537 U/WIN specific subclass of ExtUtils::MM_Unix
538 ExtUtils::MM_Unix
540 Methods used by ExtUtils::MakeMaker
541 ExtUtils::MM_VMS
543 Methods to override UN*X behaviour in ExtUtils::MakeMaker
544 ExtUtils::MM_VOS
546 VOS specific subclass of ExtUtils::MM_Unix
547 ExtUtils::MM_Win32
549 Methods to override UN*X behaviour in ExtUtils::MakeMaker
550 ExtUtils::MM_Win95
552 Method to customize MakeMaker for Win9X
553 ExtUtils::MY
555 ExtUtils::MakeMaker subclass for customization
556 ExtUtils::MakeMaker
558 Create a module Makefile
559 ExtUtils::MakeMaker::Config
561 Wrapper around Config.pm
562 ExtUtils::MakeMaker::FAQ
564 Frequently Asked Questions About MakeMaker
565 ExtUtils::MakeMaker::Locale
567 Bundled Encode::Locale
568 ExtUtils::MakeMaker::Tutorial
570 Writing a module with MakeMaker
571 ExtUtils::Manifest
573 Utilities to write and check a MANIFEST file
574 ExtUtils::Miniperl
576 Write the C code for miniperlmain.c and perlmain.c
577 ExtUtils::Mkbootstrap
579 Make a bootstrap file for use by DynaLoader
580 ExtUtils::Mksymlists
582 Write linker options files for dynamic extension
583 ExtUtils::PL2Bat
585 Batch file creation to run perl scripts on Windows
586 ExtUtils::Packlist
588 Manage .packlist files
589 ExtUtils::ParseXS
591 Converts Perl XS code into C code
592 ExtUtils::ParseXS::Constants
594 Initialization values for some globals
595 ExtUtils::ParseXS::Eval
597 Clean package to evaluate code in
598 ExtUtils::ParseXS::Utilities
600 Subroutines used with ExtUtils::ParseXS
601 ExtUtils::Typemaps
603 Read/Write/Modify Perl/XS typemap files
604 ExtUtils::Typemaps::Cmd
606 Quick commands for handling typemaps
607 ExtUtils::Typemaps::InputMap
609 Entry in the INPUT section of a typemap
610 ExtUtils::Typemaps::OutputMap
612 Entry in the OUTPUT section of a typemap
613 ExtUtils::Typemaps::Type
615 Entry in the TYPEMAP section of a typemap
616 ExtUtils::XSSymSet
618 Keep sets of symbol names palatable to the VMS linker
619 ExtUtils::testlib
621 Add blib/* directories to @INC
622 Fatal Replace functions with equivalents which succeed or die
624 Fcntl Load the C Fcntl.h defines
626 File::Basename
628 Parse file paths into directory, filename and suffix.
629 File::Compare
631 Compare files or filehandles
632 File::Copy Copy files or filehandles
634 File::DosGlob
636 DOS like globbing and then some
637 File::Fetch A generic file fetching mechanism
639 File::Find Traverse a directory tree.
641 File::Glob Perl extension for BSD glob routine
643 File::GlobMapper
645 Extend File Glob to Allow Input and Output Files
646 File::Path Create or remove directory trees
648 File::Spec Portably perform operations on file names
650 File::Spec::AmigaOS
652 File::Spec for AmigaOS
653 File::Spec::Cygwin
655 Methods for Cygwin file specs
656 File::Spec::Epoc
658 Methods for Epoc file specs
659 File::Spec::Functions
661 Portably perform operations on file names
662 File::Spec::Mac
664 File::Spec for Mac OS (Classic)
665 File::Spec::OS2
667 Methods for OS/2 file specs
668 File::Spec::Unix
670 File::Spec for Unix, base for other File::Spec modules
671 File::Spec::VMS
673 Methods for VMS file specs
674 File::Spec::Win32
676 Methods for Win32 file specs
677 File::Temp Return name and handle of a temporary file safely
679 File::stat By-name interface to Perl's built-in stat() functions
681 FileCache Keep more files open than the system permits
683 FileHandle Supply object methods for filehandles
685 Filter::Simple
687 Simplified source filtering
688 Filter::Util::Call
690 Perl Source Filter Utility Module
691 FindBin Locate directory of original perl script
693 GDBM_File Perl5 access to the gdbm library.
695 Getopt::Long
697 Extended processing of command line options
698 Getopt::Std Process single-character switches with switch clustering
700 HTTP::Tiny A small, simple, correct HTTP/1.1 client
702 Hash::Util A selection of general-utility hash subroutines
704 Hash::Util::FieldHash
706 Support for Inside-Out Classes
707 I18N::Collate
709 Compare 8-bit scalar data according to the current locale
710 I18N::LangTags
712 Functions for dealing with RFC3066-style language tags
713 I18N::LangTags::Detect
715 Detect the user's language preferences
716 I18N::LangTags::List
718 Tags and names for human languages
719 I18N::Langinfo
721 Query locale information
722 IO Load various IO modules
724 IO::Compress::Base
726 Base Class for IO::Compress modules
727 IO::Compress::Bzip2
729 Write bzip2 files/buffers
730 IO::Compress::Deflate
732 Write RFC 1950 files/buffers
733 IO::Compress::FAQ
735 Frequently Asked Questions about IO::Compress
736 IO::Compress::Gzip
738 Write RFC 1952 files/buffers
739 IO::Compress::RawDeflate
741 Write RFC 1951 files/buffers
742 IO::Compress::Zip
744 Write zip files/buffers
745 IO::Dir Supply object methods for directory handles
747 IO::File Supply object methods for filehandles
749 IO::Handle Supply object methods for I/O handles
751 IO::Pipe Supply object methods for pipes
753 IO::Poll Object interface to system poll call
755 IO::Seekable
757 Supply seek based methods for I/O objects
758 IO::Select OO interface to the select system call
760 IO::Socket Object interface to socket communications
762 IO::Socket::INET
764 Object interface for AF_INET domain sockets
765 IO::Socket::UNIX
767 Object interface for AF_UNIX domain sockets
768 IO::Uncompress::AnyInflate
770 Uncompress zlib-based (zip, gzip) file/buffer
771 IO::Uncompress::AnyUncompress
773 Uncompress gzip, zip, bzip2, zstd, xz, lzma, lzip, lzf or
774 lzop file/buffer
775 IO::Uncompress::Base
777 Base Class for IO::Uncompress modules
778 IO::Uncompress::Bunzip2
780 Read bzip2 files/buffers
781 IO::Uncompress::Gunzip
783 Read RFC 1952 files/buffers
784 IO::Uncompress::Inflate
786 Read RFC 1950 files/buffers
787 IO::Uncompress::RawInflate
789 Read RFC 1951 files/buffers
790 IO::Uncompress::Unzip
792 Read zip files/buffers
793 IO::Zlib IO:: style interface to Compress::Zlib
795 IPC::Cmd Finding and running system commands made easy
797 IPC::Msg SysV Msg IPC object class
799 IPC::Open2 Open a process for both reading and writing using open2()
801 IPC::Open3 Open a process for reading, writing, and error handling
803 using open3()
804 IPC::Semaphore
806 SysV Semaphore IPC object class
807 IPC::SharedMem
809 SysV Shared Memory IPC object class
810 IPC::SysV System V IPC constants and system calls
812 Internals Reserved special namespace for internals related functions
814 JSON::PP JSON::XS compatible pure-Perl module.
816 JSON::PP::Boolean
818 Dummy module providing JSON::PP::Boolean
819 List::Util A selection of general-utility list subroutines
821 List::Util::XS
823 Indicate if List::Util was compiled with a C compiler
824 Locale::Maketext
826 Framework for localization
827 Locale::Maketext::Cookbook
829 Recipes for using Locale::Maketext
830 Locale::Maketext::Guts
832 Deprecated module to load Locale::Maketext utf8 code
833 Locale::Maketext::GutsLoader
835 Deprecated module to load Locale::Maketext utf8 code
836 Locale::Maketext::Simple
838 Simple interface to Locale::Maketext::Lexicon
839 Locale::Maketext::TPJ13
841 Article about software localization
842 MIME::Base64
844 Encoding and decoding of base64 strings
845 MIME::QuotedPrint
847 Encoding and decoding of quoted-printable strings
848 Math::BigFloat
850 Arbitrary size floating point math package
851 Math::BigInt
853 Arbitrary size integer math package
854 Math::BigInt::Calc
856 Pure Perl module to support Math::BigInt
857 Math::BigInt::FastCalc
859 Math::BigInt::Calc with some XS for more speed
860 Math::BigInt::Lib
862 Virtual parent class for Math::BigInt libraries
863 Math::BigRat
865 Arbitrary size rational number math package
866 Math::Complex
868 Complex numbers and associated mathematical functions
869 Math::Trig Trigonometric functions
871 Memoize Make functions faster by trading space for time
873 Memoize::AnyDBM_File
875 Glue to provide EXISTS for AnyDBM_File for Storable use
876 Memoize::Expire
878 Plug-in module for automatic expiration of memoized values
879 Memoize::ExpireFile
881 Test for Memoize expiration semantics
882 Memoize::ExpireTest
884 Test for Memoize expiration semantics
885 Memoize::NDBM_File
887 Glue to provide EXISTS for NDBM_File for Storable use
888 Memoize::SDBM_File
890 Glue to provide EXISTS for SDBM_File for Storable use
891 Memoize::Storable
893 Store Memoized data in Storable database
894 Module::CoreList
896 What modules shipped with versions of perl
897 Module::CoreList::Utils
899 What utilities shipped with versions of perl
900 Module::Load
902 Runtime require of both modules and files
903 Module::Load::Conditional
905 Looking up module information / loading at runtime
906 Module::Loaded
908 Mark modules as loaded or unloaded
909 Module::Metadata
911 Gather package and POD information from perl module files
912 NDBM_File Tied access to ndbm files
914 NEXT Provide a pseudo-class NEXT (et al) that allows method
916 redispatch
917 Net::Cmd Network Command class (as used by FTP, SMTP etc)
919 Net::Config Local configuration data for libnet
921 Net::Domain Attempt to evaluate the current host's internet name and
923 domain
924 Net::FTP FTP Client class
926 Net::FTP::dataconn
928 FTP Client data connection class
929 Net::NNTP NNTP Client class
931 Net::Netrc OO interface to users netrc file
933 Net::POP3 Post Office Protocol 3 Client class (RFC1939)
935 Net::Ping Check a remote host for reachability
937 Net::SMTP Simple Mail Transfer Protocol Client
939 Net::Time Time and daytime network client interface
941 Net::hostent
943 By-name interface to Perl's built-in gethost*() functions
944 Net::libnetFAQ
946 Libnet Frequently Asked Questions
947 Net::netent By-name interface to Perl's built-in getnet*() functions
949 Net::protoent
951 By-name interface to Perl's built-in getproto*() functions
952 Net::servent
954 By-name interface to Perl's built-in getserv*() functions
955 O Generic interface to Perl Compiler backends
957 ODBM_File Tied access to odbm files
959 Opcode Disable named opcodes when compiling perl code
961 POSIX Perl interface to IEEE Std 1003.1
963 Params::Check
965 A generic input parsing/checking mechanism.
966 Parse::CPAN::Meta
968 Parse META.yml and META.json CPAN metadata files
969 Perl::OSType
971 Map Perl operating system names to generic types
972 PerlIO On demand loader for PerlIO layers and root of PerlIO::*
974 name space
975 PerlIO::encoding
977 Encoding layer
978 PerlIO::mmap
980 Memory mapped IO
981 PerlIO::scalar
983 In-memory IO, scalar IO
984 PerlIO::via Helper class for PerlIO layers implemented in perl
986 PerlIO::via::QuotedPrint
988 PerlIO layer for quoted-printable strings
989 Pod::Checker
991 Check pod documents for syntax errors
992 Pod::Escapes
994 For resolving Pod E<...> sequences
995 Pod::Functions
997 Group Perl's functions a la perlfunc.pod
998 Pod::Html Module to convert pod files to HTML
1000 Pod::Html::Util
1002 Helper functions for Pod-Html
1003 Pod::Man Convert POD data to formatted *roff input
1005 Pod::ParseLink
1007 Parse an L<> formatting code in POD text
1008 Pod::Perldoc
1010 Look up Perl documentation in Pod format.
1011 Pod::Perldoc::BaseTo
1013 Base for Pod::Perldoc formatters
1014 Pod::Perldoc::GetOptsOO
1016 Customized option parser for Pod::Perldoc
1017 Pod::Perldoc::ToANSI
1019 Render Pod with ANSI color escapes
1020 Pod::Perldoc::ToChecker
1022 Let Perldoc check Pod for errors
1023 Pod::Perldoc::ToMan
1025 Let Perldoc render Pod as man pages
1026 Pod::Perldoc::ToNroff
1028 Let Perldoc convert Pod to nroff
1029 Pod::Perldoc::ToPod
1031 Let Perldoc render Pod as ... Pod!
1032 Pod::Perldoc::ToRtf
1034 Let Perldoc render Pod as RTF
1035 Pod::Perldoc::ToTerm
1037 Render Pod with terminal escapes
1038 Pod::Perldoc::ToText
1040 Let Perldoc render Pod as plaintext
1041 Pod::Perldoc::ToTk
1043 Let Perldoc use Tk::Pod to render Pod
1044 Pod::Perldoc::ToXml
1046 Let Perldoc render Pod as XML
1047 Pod::Simple Framework for parsing Pod
1049 Pod::Simple::Checker
1051 Check the Pod syntax of a document
1052 Pod::Simple::Debug
1054 Put Pod::Simple into trace/debug mode
1055 Pod::Simple::DumpAsText
1057 Dump Pod-parsing events as text
1058 Pod::Simple::DumpAsXML
1060 Turn Pod into XML
1061 Pod::Simple::HTML
1063 Convert Pod to HTML
1064 Pod::Simple::HTMLBatch
1066 Convert several Pod files to several HTML files
1067 Pod::Simple::JustPod
1069 Just the Pod, the whole Pod, and nothing but the Pod
1070 Pod::Simple::LinkSection
1072 Represent "section" attributes of L codes
1073 Pod::Simple::Methody
1075 Turn Pod::Simple events into method calls
1076 Pod::Simple::PullParser
1078 A pull-parser interface to parsing Pod
1079 Pod::Simple::PullParserEndToken
1081 End-tokens from Pod::Simple::PullParser
1082 Pod::Simple::PullParserStartToken
1084 Start-tokens from Pod::Simple::PullParser
1085 Pod::Simple::PullParserTextToken
1087 Text-tokens from Pod::Simple::PullParser
1088 Pod::Simple::PullParserToken
1090 Tokens from Pod::Simple::PullParser
1091 Pod::Simple::RTF
1093 Format Pod as RTF
1094 Pod::Simple::Search
1096 Find POD documents in directory trees
1097 Pod::Simple::SimpleTree
1099 Parse Pod into a simple parse tree
1100 Pod::Simple::Subclassing
1102 Write a formatter as a Pod::Simple subclass
1103 Pod::Simple::Text
1105 Format Pod as plaintext
1106 Pod::Simple::TextContent
1108 Get the text content of Pod
1109 Pod::Simple::XHTML
1111 Format Pod as validating XHTML
1112 Pod::Simple::XMLOutStream
1114 Turn Pod into XML
1115 Pod::Text Convert POD data to formatted text
1117 Pod::Text::Color
1119 Convert POD data to formatted color ASCII text
1120 Pod::Text::Overstrike
1122 Convert POD data to formatted overstrike text
1123 Pod::Text::Termcap
1125 Convert POD data to ASCII text with format escapes
1126 Pod::Usage Extracts POD documentation and shows usage information
1128 SDBM_File Tied access to sdbm files
1130 Safe Compile and execute code in restricted compartments
1132 Scalar::Util
1134 A selection of general-utility scalar subroutines
1135 Search::Dict
1137 Look - search for key in dictionary file
1138 SelectSaver Save and restore selected file handle
1140 SelfLoader Load functions only on demand
1142 Storable Persistence for Perl data structures
1144 Sub::Util A selection of utility subroutines for subs and CODE
1146 references
1147 Symbol Manipulate Perl symbols and their names
1149 Sys::Hostname
1151 Try every conceivable way to get hostname
1152 Sys::Syslog Perl interface to the UNIX syslog(3) calls
1154 Sys::Syslog::Win32
1156 Win32 support for Sys::Syslog
1157 TAP::Base Base class that provides common functionality to
1159 TAP::Parser
1160 TAP::Formatter::Base
1162 Base class for harness output delegates
1163 TAP::Formatter::Color
1165 Run Perl test scripts with color
1166 TAP::Formatter::Console
1168 Harness output delegate for default console output
1169 TAP::Formatter::Console::ParallelSession
1171 Harness output delegate for parallel console output
1172 TAP::Formatter::Console::Session
1174 Harness output delegate for default console output
1175 TAP::Formatter::File
1177 Harness output delegate for file output
1178 TAP::Formatter::File::Session
1180 Harness output delegate for file output
1181 TAP::Formatter::Session
1183 Abstract base class for harness output delegate
1184 TAP::Harness
1186 Run test scripts with statistics
1187 TAP::Harness::Env
1189 Parsing harness related environmental variables where
1190 appropriate
1191 TAP::Object Base class that provides common functionality to all
1193 "TAP::*" modules
1194 TAP::Parser Parse TAP output
1196 TAP::Parser::Aggregator
1198 Aggregate TAP::Parser results
1199 TAP::Parser::Grammar
1201 A grammar for the Test Anything Protocol.
1202 TAP::Parser::Iterator
1204 Base class for TAP source iterators
1205 TAP::Parser::Iterator::Array
1207 Iterator for array-based TAP sources
1208 TAP::Parser::Iterator::Process
1210 Iterator for process-based TAP sources
1211 TAP::Parser::Iterator::Stream
1213 Iterator for filehandle-based TAP sources
1214 TAP::Parser::IteratorFactory
1216 Figures out which SourceHandler objects to use for a given
1217 Source
1218 TAP::Parser::Multiplexer
1220 Multiplex multiple TAP::Parsers
1221 TAP::Parser::Result
1223 Base class for TAP::Parser output objects
1224 TAP::Parser::Result::Bailout
1226 Bailout result token.
1227 TAP::Parser::Result::Comment
1229 Comment result token.
1230 TAP::Parser::Result::Plan
1232 Plan result token.
1233 TAP::Parser::Result::Pragma
1235 TAP pragma token.
1236 TAP::Parser::Result::Test
1238 Test result token.
1239 TAP::Parser::Result::Unknown
1241 Unknown result token.
1242 TAP::Parser::Result::Version
1244 TAP syntax version token.
1245 TAP::Parser::Result::YAML
1247 YAML result token.
1248 TAP::Parser::ResultFactory
1250 Factory for creating TAP::Parser output objects
1251 TAP::Parser::Scheduler
1253 Schedule tests during parallel testing
1254 TAP::Parser::Scheduler::Job
1256 A single testing job.
1257 TAP::Parser::Scheduler::Spinner
1259 A no-op job.
1260 TAP::Parser::Source
1262 A TAP source & meta data about it
1263 TAP::Parser::SourceHandler
1265 Base class for different TAP source handlers
1266 TAP::Parser::SourceHandler::Executable
1268 Stream output from an executable TAP source
1269 TAP::Parser::SourceHandler::File
1271 Stream TAP from a text file.
1272 TAP::Parser::SourceHandler::Handle
1274 Stream TAP from an IO::Handle or a GLOB.
1275 TAP::Parser::SourceHandler::Perl
1277 Stream TAP from a Perl executable
1278 TAP::Parser::SourceHandler::RawTAP
1280 Stream output from raw TAP in a scalar/array ref.
1281 TAP::Parser::YAMLish::Reader
1283 Read YAMLish data from iterator
1284 TAP::Parser::YAMLish::Writer
1286 Write YAMLish data
1287 Term::ANSIColor
1289 Color screen output using ANSI escape sequences
1290 Term::Cap Perl termcap interface
1292 Term::Complete
1294 Perl word completion module
1295 Term::ReadLine
1297 Perl interface to various "readline" packages.
1298 Test Provides a simple framework for writing test scripts
1300 Test2 Framework for writing test tools that all work together.
1302 Test2::API Primary interface for writing Test2 based testing tools.
1304 Test2::API::Breakage
1306 What breaks at what version
1307 Test2::API::Context
1309 Object to represent a testing context.
1310 Test2::API::Instance
1312 Object used by Test2::API under the hood
1313 Test2::API::InterceptResult
1315 Representation of a list of events.
1316 Test2::API::InterceptResult::Event
1318 Representation of an event for use in
1319 Test2::API::InterceptResult::Hub
1321 Hub used by InterceptResult.
1322 Test2::API::InterceptResult::Squasher
1324 Encapsulation of the algorithm that
1325 Test2::API::Stack
1327 Object to manage a stack of Test2::Hub
1328 Test2::Event
1330 Base class for events
1331 Test2::Event::Bail
1333 Bailout!
1334 Test2::Event::Diag
1336 Diag event type
1337 Test2::Event::Encoding
1339 Set the encoding for the output stream
1340 Test2::Event::Exception
1342 Exception event
1343 Test2::Event::Fail
1345 Event for a simple failed assertion
1346 Test2::Event::Generic
1348 Generic event type.
1349 Test2::Event::Note
1351 Note event type
1352 Test2::Event::Ok
1354 Ok event type
1355 Test2::Event::Pass
1357 Event for a simple passing assertion
1358 Test2::Event::Plan
1360 The event of a plan
1361 Test2::Event::Skip
1363 Skip event type
1364 Test2::Event::Subtest
1366 Event for subtest types
1367 Test2::Event::TAP::Version
1369 Event for TAP version.
1370 Test2::Event::V2
1372 Second generation event.
1373 Test2::Event::Waiting
1375 Tell all procs/threads it is time to be done
1376 Test2::EventFacet
1378 Base class for all event facets.
1379 Test2::EventFacet::About
1381 Facet with event details.
1382 Test2::EventFacet::Amnesty
1384 Facet for assertion amnesty.
1385 Test2::EventFacet::Assert
1387 Facet representing an assertion.
1388 Test2::EventFacet::Control
1390 Facet for hub actions and behaviors.
1391 Test2::EventFacet::Error
1393 Facet for errors that need to be shown.
1394 Test2::EventFacet::Hub
1396 Facet for the hubs an event passes through.
1397 Test2::EventFacet::Info
1399 Facet for information a developer might care about.
1400 Test2::EventFacet::Info::Table
1402 Intermediary representation of a table.
1403 Test2::EventFacet::Meta
1405 Facet for meta-data
1406 Test2::EventFacet::Parent
1408 Facet for events contains other events
1409 Test2::EventFacet::Plan
1411 Facet for setting the plan
1412 Test2::EventFacet::Render
1414 Facet that dictates how to render an event.
1415 Test2::EventFacet::Trace
1417 Debug information for events
1418 Test2::Formatter
1420 Namespace for formatters.
1421 Test2::Formatter::TAP
1423 Standard TAP formatter
1424 Test2::Hub The conduit through which all events flow.
1426 Test2::Hub::Interceptor
1428 Hub used by interceptor to grab results.
1429 Test2::Hub::Interceptor::Terminator
1431 Exception class used by
1432 Test2::Hub::Subtest
1434 Hub used by subtests
1435 Test2::IPC Turn on IPC for threading or forking support.
1437 Test2::IPC::Driver
1439 Base class for Test2 IPC drivers.
1440 Test2::IPC::Driver::Files
1442 Temp dir + Files concurrency model.
1443 Test2::Tools::Tiny
1445 Tiny set of tools for unfortunate souls who cannot use
1446 Test2::Transition
1448 Transition notes when upgrading to Test2
1449 Test2::Util Tools used by Test2 and friends.
1451 Test2::Util::ExternalMeta
1453 Allow third party tools to safely attach meta-data
1454 Test2::Util::Facets2Legacy
1456 Convert facet data to the legacy event API.
1457 Test2::Util::HashBase
1459 Build hash based classes.
1460 Test2::Util::Trace
1462 Legacy wrapper fro Test2::EventFacet::Trace.
1463 Test::Builder
1465 Backend for building test libraries
1466 Test::Builder::Formatter
1468 Test::Builder subclass of Test2::Formatter::TAP
1469 Test::Builder::IO::Scalar
1471 A copy of IO::Scalar for Test::Builder
1472 Test::Builder::Module
1474 Base class for test modules
1475 Test::Builder::Tester
1477 Test testsuites that have been built with
1478 Test::Builder::Tester::Color
1480 Turn on colour in Test::Builder::Tester
1481 Test::Builder::TodoDiag
1483 Test::Builder subclass of Test2::Event::Diag
1484 Test::Harness
1486 Run Perl standard test scripts with statistics
1487 Test::Harness::Beyond
1489 Beyond make test
1490 Test::More Yet another framework for writing test scripts
1492 Test::Simple
1494 Basic utilities for writing tests.
1495 Test::Tester
1497 Ease testing test modules built with Test::Builder
1498 Test::Tester::Capture
1500 Help testing test modules built with Test::Builder
1501 Test::Tester::CaptureRunner
1503 Help testing test modules built with Test::Builder
1504 Test::Tutorial
1506 A tutorial about writing really basic tests
1507 Test::use::ok
1509 Alternative to Test::More::use_ok
1510 Text::Abbrev
1512 Abbrev - create an abbreviation table from a list
1513 Text::Balanced
1515 Extract delimited text sequences from strings.
1516 Text::ParseWords
1518 Parse text into an array of tokens or array of arrays
1519 Text::Tabs Expand and unexpand tabs like unix expand(1) and
1521 unexpand(1)
1522 Text::Wrap Line wrapping to form simple paragraphs
1524 Thread Manipulate threads in Perl (for old code only)
1526 Thread::Queue
1528 Thread-safe queues
1529 Thread::Semaphore
1531 Thread-safe semaphores
1532 Tie::Array Base class for tied arrays
1534 Tie::File Access the lines of a disk file via a Perl array
1536 Tie::Handle Base class definitions for tied handles
1538 Tie::Hash Base class definitions for tied hashes
1540 Tie::Hash::NamedCapture
1542 Named regexp capture buffers
1543 Tie::Memoize
1545 Add data to hash when needed
1546 Tie::RefHash
1548 Use references as hash keys
1549 Tie::Scalar Base class definitions for tied scalars
1551 Tie::StdHandle
1553 Base class definitions for tied handles
1554 Tie::SubstrHash
1556 Fixed-table-size, fixed-key-length hashing
1557 Time::HiRes High resolution alarm, sleep, gettimeofday, interval timers
1559 Time::Local Efficiently compute time from local and GMT time
1561 Time::Piece Object Oriented time objects
1563 Time::Seconds
1565 A simple API to convert seconds to other date values
1566 Time::gmtime
1568 By-name interface to Perl's built-in gmtime() function
1569 Time::localtime
1571 By-name interface to Perl's built-in localtime() function
1572 Time::tm Internal object used by Time::gmtime and Time::localtime
1574 UNIVERSAL Base class for ALL classes (blessed references)
1576 Unicode::Collate
1578 Unicode Collation Algorithm
1579 Unicode::Collate::CJK::Big5
1581 Weighting CJK Unified Ideographs
1582 Unicode::Collate::CJK::GB2312
1584 Weighting CJK Unified Ideographs
1585 Unicode::Collate::CJK::JISX0208
1587 Weighting JIS KANJI for Unicode::Collate
1588 Unicode::Collate::CJK::Korean
1590 Weighting CJK Unified Ideographs
1591 Unicode::Collate::CJK::Pinyin
1593 Weighting CJK Unified Ideographs
1594 Unicode::Collate::CJK::Stroke
1596 Weighting CJK Unified Ideographs
1597 Unicode::Collate::CJK::Zhuyin
1599 Weighting CJK Unified Ideographs
1600 Unicode::Collate::Locale
1602 Linguistic tailoring for DUCET via Unicode::Collate
1603 Unicode::Normalize
1605 Unicode Normalization Forms
1606 Unicode::UCD
1608 Unicode character database
1609 User::grent By-name interface to Perl's built-in getgr*() functions
1611 User::pwent By-name interface to Perl's built-in getpw*() functions
1613 VMS::DCLsym Perl extension to manipulate DCL symbols
1615 VMS::Filespec
1617 Convert between VMS and Unix file specification syntax
1618 VMS::Stdio Standard I/O functions via VMS extensions
1620 Win32 Interfaces to some Win32 API Functions
1622 Win32API::File
1624 Low-level access to Win32 system API calls for files/dirs.
1625 Win32CORE Win32 CORE function stubs
1627 XS::APItest Test the perl C API
1629 XS::Typemap Module to test the XS typemaps distributed with perl
1631 XSLoader Dynamically load C libraries into Perl code
1633 autodie::Scope::Guard
1635 Wrapper class for calling subs at end of scope
1636 autodie::Scope::GuardStack
1638 Hook stack for managing scopes via %^H
1639 autodie::Util
1641 Internal Utility subroutines for autodie and Fatal
1642 version::Internals
1644 Perl extension for Version Objects
1645 To find out all modules installed on your system, including those
1647 without documentation or outside the standard release, just use the
1648 following command (under the default win32 shell, double quotes should
1649 be used instead of single quotes).
1650 % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \
1652 'find { wanted => sub { print canonpath $_ if /\.pm\z/ },
1653 no_chdir => 1 }, @INC'
1654 (The -T is here to prevent @INC from being populated by "PERL5LIB",
1656 "PERLLIB", and "PERL_USE_UNSAFE_INC".) They should all have their own
1657 documentation installed and accessible via your system man(1) command.
1658 If you do not have a find program, you can use the Perl find2perl
1659 program instead, which generates Perl code as output you can run
1660 through perl. If you have a man program but it doesn't find your
1661 modules, you'll have to fix your manpath. See perl for details. If
1662 you have no system man command, you might try the perldoc program.
1663 Note also that the command "perldoc perllocal" gives you a (possibly
1665 incomplete) list of the modules that have been further installed on
1666 your system. (The perllocal.pod file is updated by the standard
1667 MakeMaker install process.)
1668 Extension Modules
1670 Extension modules are written in C (or a mix of Perl and C). They are
1671 usually dynamically loaded into Perl if and when you need them, but may
1672 also be linked in statically. Supported extension modules include
1673 Socket, Fcntl, and POSIX.
1674 Many popular C extension modules do not come bundled (at least, not
1676 completely) due to their sizes, volatility, or simply lack of time for
1677 adequate testing and configuration across the multitude of platforms on
1678 which Perl was beta-tested. You are encouraged to look for them on
1679 CPAN (described below), or using web search engines like Google or
1680 DuckDuckGo.
1681
1683 CPAN stands for Comprehensive Perl Archive Network; it's a globally
1684 replicated trove of Perl materials, including documentation, style
1685 guides, tricks and traps, alternate ports to non-Unix systems and
1686 occasional binary distributions for these. Search engines for CPAN
1687 can be found at https://www.cpan.org/
1688 Most importantly, CPAN includes around a thousand unbundled modules,
1690 some of which require a C compiler to build. Major categories of
1691 modules are:
1692 • Language Extensions and Documentation Tools
1694 • Development Support
1696 • Operating System Interfaces
1698 • Networking, Device Control (modems) and InterProcess Communication
1700 • Data Types and Data Type Utilities
1702 • Database Interfaces
1704 • User Interfaces
1706 • Interfaces to / Emulations of Other Programming Languages
1708 • File Names, File Systems and File Locking (see also File Handles)
1710 • String Processing, Language Text Processing, Parsing, and Searching
1712 • Option, Argument, Parameter, and Configuration File Processing
1714 • Internationalization and Locale
1716 • Authentication, Security, and Encryption
1718 • World Wide Web, HTML, HTTP, CGI, MIME
1720 • Server and Daemon Utilities
1722 • Archiving and Compression
1724 • Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
1726 • Mail and Usenet News
1728 • Control Flow Utilities (callbacks and exceptions etc)
1730 • File Handle and Input/Output Stream Utilities
1732 • Miscellaneous Modules
1734 You can find the CPAN online at <https://www.cpan.org/>
1736
1738 (The following section is borrowed directly from Tim Bunce's modules
1739 file, available at your nearest CPAN site.)
1740 Perl implements a class using a package, but the presence of a package
1742 doesn't imply the presence of a class. A package is just a namespace.
1743 A class is a package that provides subroutines that can be used as
1744 methods. A method is just a subroutine that expects, as its first
1745 argument, either the name of a package (for "static" methods), or a
1746 reference to something (for "virtual" methods).
1747 A module is a file that (by convention) provides a class of the same
1749 name (sans the .pm), plus an import method in that class that can be
1750 called to fetch exported symbols. This module may implement some of
1751 its methods by loading dynamic C or C++ objects, but that should be
1752 totally transparent to the user of the module. Likewise, the module
1753 might set up an AUTOLOAD function to slurp in subroutine definitions on
1754 demand, but this is also transparent. Only the .pm file is required to
1755 exist. See perlsub, perlobj, and AutoLoader for details about the
1756 AUTOLOAD mechanism.
1757 Guidelines for Module Creation
1759 • Do similar modules already exist in some form?
1760 If so, please try to reuse the existing modules either in whole or
1762 by inheriting useful features into a new class. If this is not
1763 practical try to get together with the module authors to work on
1764 extending or enhancing the functionality of the existing modules.
1765 A perfect example is the plethora of packages in perl4 for dealing
1766 with command line options.
1767 If you are writing a module to expand an already existing set of
1769 modules, please coordinate with the author of the package. It
1770 helps if you follow the same naming scheme and module interaction
1771 scheme as the original author.
1772 • Try to design the new module to be easy to extend and reuse.
1774 Try to "use warnings;" (or "use warnings qw(...);"). Remember that
1776 you can add "no warnings qw(...);" to individual blocks of code
1777 that need less warnings.
1778 Use blessed references. Use the two argument form of bless to
1780 bless into the class name given as the first parameter of the
1781 constructor, e.g.,:
1782 sub new {
1784 my $class = shift;
1785 return bless {}, $class;
1786 }
1787 or even this if you'd like it to be used as either a static or a
1789 virtual method.
1790 sub new {
1792 my $self = shift;
1793 my $class = ref($self) || $self;
1794 return bless {}, $class;
1795 }
1796 Pass arrays as references so more parameters can be added later
1798 (it's also faster). Convert functions into methods where
1799 appropriate. Split large methods into smaller more flexible ones.
1800 Inherit methods from other modules if appropriate.
1801 Avoid class name tests like: "die "Invalid" unless ref $ref eq
1803 'FOO'". Generally you can delete the "eq 'FOO'" part with no harm
1804 at all. Let the objects look after themselves! Generally, avoid
1805 hard-wired class names as far as possible.
1806 Avoid "$r->Class::func()" where using "@ISA=qw(... Class ...)" and
1808 "$r->func()" would work.
1809 Use autosplit so little used or newly added functions won't be a
1811 burden to programs that don't use them. Add test functions to the
1812 module after __END__ either using AutoSplit or by saying:
1813 eval join('',<main::DATA>) || die $@ unless caller();
1815 Does your module pass the 'empty subclass' test? If you say
1817 "@SUBCLASS::ISA = qw(YOURCLASS);" your applications should be able
1818 to use SUBCLASS in exactly the same way as YOURCLASS. For example,
1819 does your application still work if you change: "$obj =
1820 YOURCLASS->new();" into: "$obj = SUBCLASS->new();" ?
1821 Avoid keeping any state information in your packages. It makes it
1823 difficult for multiple other packages to use yours. Keep state
1824 information in objects.
1825 Always use -w.
1827 Try to "use strict;" (or "use strict qw(...);"). Remember that you
1829 can add "no strict qw(...);" to individual blocks of code that need
1830 less strictness.
1831 Always use -w.
1833 Follow the guidelines in perlstyle.
1835 Always use -w.
1837 • Some simple style guidelines
1839 The perlstyle manual supplied with Perl has many helpful points.
1841 Coding style is a matter of personal taste. Many people evolve
1843 their style over several years as they learn what helps them write
1844 and maintain good code. Here's one set of assorted suggestions
1845 that seem to be widely used by experienced developers:
1846 Use underscores to separate words. It is generally easier to read
1848 $var_names_like_this than $VarNamesLikeThis, especially for non-
1849 native speakers of English. It's also a simple rule that works
1850 consistently with VAR_NAMES_LIKE_THIS.
1851 Package/Module names are an exception to this rule. Perl informally
1853 reserves lowercase module names for 'pragma' modules like integer
1854 and strict. Other modules normally begin with a capital letter and
1855 use mixed case with no underscores (need to be short and portable).
1856 You may find it helpful to use letter case to indicate the scope or
1858 nature of a variable. For example:
1859 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
1861 $Some_Caps_Here package-wide global/static
1862 $no_caps_here function scope my() or local() variables
1863 Function and method names seem to work best as all lowercase.
1865 e.g., "$obj->as_string()".
1866 You can use a leading underscore to indicate that a variable or
1868 function should not be used outside the package that defined it.
1869 • Select what to export.
1871 Do NOT export method names!
1873 Do NOT export anything else by default without a good reason!
1875 Exports pollute the namespace of the module user. If you must
1877 export try to use @EXPORT_OK in preference to @EXPORT and avoid
1878 short or common names to reduce the risk of name clashes.
1879 Generally anything not exported is still accessible from outside
1881 the module using the ModuleName::item_name (or
1882 "$blessed_ref->method") syntax. By convention you can use a
1883 leading underscore on names to indicate informally that they are
1884 'internal' and not for public use.
1885 (It is actually possible to get private functions by saying: "my
1887 $subref = sub { ... }; &$subref;". But there's no way to call
1888 that directly as a method, because a method must have a name in the
1889 symbol table.)
1890 As a general rule, if the module is trying to be object oriented
1892 then export nothing. If it's just a collection of functions then
1893 @EXPORT_OK anything but use @EXPORT with caution.
1894 • Select a name for the module.
1896 This name should be as descriptive, accurate, and complete as
1898 possible. Avoid any risk of ambiguity. Always try to use two or
1899 more whole words. Generally the name should reflect what is
1900 special about what the module does rather than how it does it.
1901 Please use nested module names to group informally or categorize a
1902 module. There should be a very good reason for a module not to
1903 have a nested name. Module names should begin with a capital
1904 letter.
1905 Having 57 modules all called Sort will not make life easy for
1907 anyone (though having 23 called Sort::Quick is only marginally
1908 better :-). Imagine someone trying to install your module
1909 alongside many others.
1910 If you are developing a suite of related modules/classes it's good
1912 practice to use nested classes with a common prefix as this will
1913 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1914 Xyz::Model etc. Use the modules in this list as a naming guide.
1915 If adding a new module to a set, follow the original author's
1917 standards for naming modules and the interface to methods in those
1918 modules.
1919 If developing modules for private internal or project specific use,
1921 that will never be released to the public, then you should ensure
1922 that their names will not clash with any future public module. You
1923 can do this either by using the reserved Local::* category or by
1924 using a category name that includes an underscore like Foo_Corp::*.
1925 To be portable each component of a module name should be limited to
1927 11 characters. If it might be used on MS-DOS then try to ensure
1928 each is unique in the first 8 characters. Nested modules make this
1929 easier.
1930 For additional guidance on the naming of modules, please consult:
1932 https://pause.perl.org/pause/query?ACTION=pause_namingmodules
1934 or send mail to the <module-authors@perl.org> mailing list.
1936 • Have you got it right?
1938 How do you know that you've made the right decisions? Have you
1940 picked an interface design that will cause problems later? Have you
1941 picked the most appropriate name? Do you have any questions?
1942 The best way to know for sure, and pick up many helpful
1944 suggestions, is to ask someone who knows. The
1945 <module-authors@perl.org> mailing list is useful for this purpose;
1946 it's also accessible via news interface as perl.module-authors at
1947 nntp.perl.org.
1948 All you need to do is post a short summary of the module, its
1950 purpose and interfaces. A few lines on each of the main methods is
1951 probably enough. (If you post the whole module it might be ignored
1952 by busy people - generally the very people you want to read it!)
1953 Don't worry about posting if you can't say when the module will be
1955 ready - just say so in the message. It might be worth inviting
1956 others to help you, they may be able to complete it for you!
1957 • README and other Additional Files.
1959 It's well known that software developers usually fully document the
1961 software they write. If, however, the world is in urgent need of
1962 your software and there is not enough time to write the full
1963 documentation please at least provide a README file containing:
1964 • A description of the module/package/extension etc.
1966 • A copyright notice - see below.
1968 • Prerequisites - what else you may need to have.
1970 • How to build it - possible changes to Makefile.PL etc.
1972 • How to install it.
1974 • Recent changes in this release, especially
1976 incompatibilities
1977 • Changes / enhancements you plan to make in the future.
1979 If the README file seems to be getting too large you may wish to
1981 split out some of the sections into separate files: INSTALL,
1982 Copying, ToDo etc.
1983 • Adding a Copyright Notice.
1985 How you choose to license your work is a personal decision.
1987 The general mechanism is to assert your Copyright and then make
1988 a declaration of how others may copy/use/modify your work.
1989 Perl, for example, is supplied with two types of licence: The
1991 GNU GPL and The Artistic Licence (see the files README,
1992 Copying, and Artistic, or perlgpl and perlartistic). Larry has
1993 good reasons for NOT just using the GNU GPL.
1994 My personal recommendation, out of respect for Larry, Perl, and
1996 the Perl community at large is to state something simply like:
1997 Copyright (c) 1995 Your Name. All rights reserved.
1999 This program is free software; you can redistribute it and/or
2000 modify it under the same terms as Perl itself.
2001 This statement should at least appear in the README file. You
2003 may also wish to include it in a Copying file and your source
2004 files. Remember to include the other words in addition to the
2005 Copyright.
2006 • Give the module a version/issue/release number.
2008 To be fully compatible with the Exporter and MakeMaker modules
2010 you should store your module's version number in a non-my
2011 package variable called $VERSION. This should be a positive
2012 floating point number with at least two digits after the
2013 decimal (i.e., hundredths, e.g, "$VERSION = "0.01""). Don't
2014 use a "1.3.2" style version. See Exporter for details.
2015 It may be handy to add a function or method to retrieve the
2017 number. Use the number in announcements and archive file names
2018 when releasing the module (ModuleName-1.02.tar.Z). See perldoc
2019 ExtUtils::MakeMaker.pm for details.
2020 • How to release and distribute a module.
2022 If possible, register the module with CPAN. Follow the
2024 instructions and links on:
2025 https://www.cpan.org/modules/04pause.html
2027 and upload to:
2029 https://pause.perl.org/
2031 and notify <modules@perl.org>. This will allow anyone to
2033 install your module using the "cpan" tool distributed with
2034 Perl.
2035 By using the WWW interface you can ask the Upload Server to
2037 mirror your modules from your ftp or WWW site into your own
2038 directory on CPAN!
2039 • Take care when changing a released module.
2041 Always strive to remain compatible with previous released
2043 versions. Otherwise try to add a mechanism to revert to the
2044 old behavior if people rely on it. Document incompatible
2045 changes.
2046 Guidelines for Converting Perl 4 Library Scripts into Modules
2048 • There is no requirement to convert anything.
2049 If it ain't broke, don't fix it! Perl 4 library scripts should
2051 continue to work with no problems. You may need to make some minor
2052 changes (like escaping non-array @'s in double quoted strings) but
2053 there is no need to convert a .pl file into a Module for just that.
2054 • Consider the implications.
2056 All Perl applications that make use of the script will need to be
2058 changed (slightly) if the script is converted into a module. Is it
2059 worth it unless you plan to make other changes at the same time?
2060 • Make the most of the opportunity.
2062 If you are going to convert the script to a module you can use the
2064 opportunity to redesign the interface. The guidelines for module
2065 creation above include many of the issues you should consider.
2066 • The pl2pm utility will get you started.
2068 This utility will read *.pl files (given as parameters) and write
2070 corresponding *.pm files. The pl2pm utilities does the following:
2071 • Adds the standard Module prologue lines
2073 • Converts package specifiers from ' to ::
2075 • Converts die(...) to croak(...)
2077 • Several other minor changes
2079 Being a mechanical process pl2pm is not bullet proof. The converted
2081 code will need careful checking, especially any package statements.
2082 Don't delete the original .pl file till the new .pm one works!
2083 Guidelines for Reusing Application Code
2085 • Complete applications rarely belong in the Perl Module Library.
2086 • Many applications contain some Perl code that could be reused.
2088 Help save the world! Share your code in a form that makes it easy
2090 to reuse.
2091 • Break-out the reusable code into one or more separate module files.
2093 • Take the opportunity to reconsider and redesign the interfaces.
2095 • In some cases the 'application' can then be reduced to a small
2097 fragment of code built on top of the reusable modules. In these
2099 cases the application could invoked as:
2100 % perl -e 'use Module::Name; method(@ARGV)' ...
2102 or
2103 % perl -mModule::Name ... (in perl5.002 or higher)
2104
2106 Perl does not enforce private and public parts of its modules as you
2107 may have been used to in other languages like C++, Ada, or Modula-17.
2108 Perl doesn't have an infatuation with enforced privacy. It would
2109 prefer that you stayed out of its living room because you weren't
2110 invited, not because it has a shotgun.
2111 The module and its user have a contract, part of which is common law,
2113 and part of which is "written". Part of the common law contract is
2114 that a module doesn't pollute any namespace it wasn't asked to. The
2115 written contract for the module (A.K.A. documentation) may make other
2116 provisions. But then you know when you "use RedefineTheWorld" that
2117 you're redefining the world and willing to take the consequences.
2118perl v5.36.3 2023-11-30 PERLMODLIB(1)