Writing Perl 5 Modules: An Introduction

1. Writing Perl 5 Modules:An Introduction Keith Arner

2. Outline • What do we mean by Modules and Classes? • Module Basics • Using Modules, Packages, Special Variables, Exporting Functions • Advanced Concepts • Autoloading, More Exporting, Versioning • Ask questions at any time

3. Topics Not Covered • Objects • Modules available on CPAN • Writing modules for CPAN distribution • Each of these would make a good topic for a future talk (Any volunteers?)

4. Modules and Classes • There are two types of modularization under Perl 5 • Modules : library functions • Classes : object-oriented programming

5. What is a Module? • A module is a .pm file that defines a library of related functions • Modules are conceptually similar to old-fashioned Perl libraries (.pl files), but have a cleaner implementation • selective namespace cluttering • simpler function invocation

6. How to use a Module Time::Local • use Time::Local;$time = timelocal($sec, $min, $hours, $mday, $mon, $year);print "Seconds since epoch: $time\n";

7. Module Basics • Learn by Example: MyRand.pm • Refer to attached printout of MyRand.pm • Note that line numbers are for reference purposes only

8. Package Names and Filenames • Package name is declared on line 1 • This should be the same as the filename, without the .pm extension • If it is different, your functions will not be exported correctly • Should begin with a capital letter to avoid possible conflict with pragmas

9. More on Package Names • package MyRandis file MyRand.pm • package Time is file Time.pm • package Time::Localis file Time/Local.pm • They have nothing to do with one another

10. The Package: Your Own Private Namespace • Each package is a separate namespace for functions and variables • There is no collision of names between namespaces • $seed in the package main and $seed in the package MyRand are distinct variables

11. Magic Variables • @EXPORT, @ISA and $VERSION have special meanings • @EXPORT tells Perl what functions you want to make available to the public • @ISA tells Perl how to export the functions (I won't go into the details) • $VERSION is used to indicate compatibility

12. Exporting Functions • Line 11 sets @EXPORT to contain a list of the names of functions to be exported • Note that we use qw() to generate the list • This is just syntactic sugar for:@EXPORT = ('srand', 'rand');

13. What does it mean to Export? • Your functions are defined in your own package • Exporting makes the functions available in another package as if they were defined in the other package • This is done by fiddling with symbol tables (which is a topic for another talk)

14. A Function is a Functionis a Function • On lines 19 and 23, functions are declared and written exactly as they would be anywhere else

15. Module Specific State • Line 15 declares a variable local to the module that can maintain it's state between function calls • $seed is visible to all functions in this file • $seed does not conflict with $seed in any other module, nor in a mainline program

16. Declaring Victory • All Perl modules must return a true value to indicate that they completed successfully • Line 35 shows the canonical return • Any true value will do: • 'true' • 3.1415926535 • $^O & $/ • (3..99)

17. How do you use it? • Make sure your module is in your include path, @INC • This can be augmented with -I or your PERL5LIB environment variable • use MyRand;srand(5);print rand;

18. Advanced Topics • Autoloading • Selective Exporting • Versioning • Much, much more

19. Autoloading • The autoloader is used to improve performance of large modules (such as POSIX.pm) • Functions are split into separate files and compiled only as needed • AutoSplit.pm is used to split modules

20. More Exporting • @EXPORT can export variables in addition to functions: • @EXPORT = qw(rand srand $seed) • @EXPORT_OK and %EXPORT_TAGS can be used to export selectively

21. Selective Exporting • It is not always desirable to export everything, so @EXPORT_OK is used • @EXPORT = qw (rand srand);@EXPORT_OK = qw ($seed); • use MyRand qw(rand $seed);

22. Fancy Exporting • Typing all the names of symbols to import can become a hassle, so %EXPORT_TAGS is used • @EXPORT = qw (rand srand);@EXPORT_OK = qw ($seed);%EXPORT_TAGS = ( funcs => [qw(rand srand)], vars => [qw($seed)] ); • use MyRand qw(:funcs :vars);

23. Versioning • $VERSION is used to indicate the version of the module • use MyRand 2.0; • will fail if $MyRand::VERSION < 2.0 • Can be used with RCS Keywords: • $VERSION = ('$REVISION 1.0$' =~ m/Revision ([^\$]+)/);

24. Much, much more • Overriding builtin functions • Cascading inheritance with @ISA • Automated Cleanup • Object Oriented Programming

25. References • Programming Perl, Second Edition. Wall, Christiansen & Schwartz • Chapters 5 and 7 • Man pages • perlmod(1) • Perl Cookbook. Christiansen & Torkington • Chapter 12

26. Summary • Modules are libraries of functions • A simple module just exports a set of functions • Perl modules can be expanded in many directions for arbitrarily sophisticated libraries