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