WebReference.com - Perl Module Primer (2/5) | WebReference

WebReference.com - Perl Module Primer (2/5)

To page 1current pageTo page 3To page 4To page 5
[previous] [next]

Perl Module Primer

Let's begin our basic module analysis with a look at a basic module:

package SayHello;
sub hello_message {
   return "Hello, World!";
}
1;

That's about as basic as you can get, but even in this simplest of examples you probably see some things that confuse you, or that you haven't encountered before. So let's take a closer look.

The Package

Each module contains a package declaration--usually as the first statement of the file--and this package declaration must match the name of the file itself (the file will additionally have a ".pm" extension; so, in our example above, the module would reside in a file called "SayHello.pm"). Technically, package names follow Perl rules for variable naming; but when used as a module the standard convention is to begin your package name with an upper-case letter, to avoid conflicts with Perl pragmas, which we will later see are invoked in Perl scripts via the same mechanism used by modules. Additionally, when selecting a name for your private packages, such as a package that you'll be using strictly within your own organization and not for public release, you should try to pick a name that won't conflict with other public packages that you might want to use in the future; and that also conforms to the naming conventions for files on your operating system (remember that for module development, the package name will also be the name of the file that contains the module code, with an added .pm extension). One possibility is to use an underscore in your package name, since publicly available packages typically do not contain underscores. So our example module above might become "Say_Hello." And, down the road, if you decide you'd like to contribute your own modules for public consumption, you can (and should) enlist the help of the Perl community at large to help you decide how to name your new module (and you may even find other authors and/or modules that may benefit from your work, or that can assist you directly). Many helpful hints on public module naming and creation can be found on CPAN. But for now, let's continue our basic analysis with a brief definition of packages.

So what exactly is a package? A package is a way to separate chunks of Perl code from each other so that their namespaces do not collide. In brief, a namespace represents the collected symbols--i.e., variable names, sub routine names, etc.--that a script is aware of. In your single script applications you probably didn't need to worry about namespaces much; since you could easily know what variables and sub routine names you had defined and could therefore avoid attempting to redefine a name that was already in use. But remember that a module is intended to be a separate, reusable code block; it may be used in many scripts that we do not have any control over in the future. Packages allow us to code our module using our own variable and routine names without having to worry about inadvertently clobbering someone else's variables, such as an employee of our company who decides to use our module to add functionality to their own script--in the future.

While within a specific Perl package declaration, your script will have direct access only to the variables and functions defined within that package. By "direct access," I mean the ability to refer to the variables without any specific qualification; such as

$myVariable="foobar";
print $myVariable;

There are, however, "indirect" ways to access and use certain variables and functions in a module, and we'll discuss them on the next page (indeed, if there weren't, there wouldn't be much point in writing a module in the first place!)

By the way, I realize that many of the "rules" I'm presenting to you in this brief article have exceptions that I'm not delving into purely in the interest in keeping this tutorial as simple as possible. For example, a package declaration is not restricted to appearing only in modules; in fact, it can appear in any section of code, at any time, can span multiple files, and multiple package declarations can even appear in a single module file. But a common use for package declarations is to separate the namespaces of individual modules (and to define classes when used in an OOP context) as above; so that's the usage we're focusing on here.

Where's the Code?

You may have noticed that our simple module above has no actual executing code; only a single sub routine definition that itself is never called. So what good is it?

Remember that modules are not intended to be standalone applications; we'll never actually be running our module by itself. Instead, we'll be using our module to provide added functionality to a larger script (and, more than likely, many separate scripts) and therefore it is common for a module to contain a series of sub routine definitions but little or no actual execution code. This is not a rule, however; a module can have its own executing code, such as "global" (global to the module, that is) variable definitions and initializations. Just remember that this code--whatever it is--will be executed by every script that uses this module (and, in fact, will be executed before the script that calls it is even compiled; more on that later).

Return true

Your module must return a true value (or a value synonymous with true) so that Perl knows that it was loaded properly when it is used. This will often be the case without having to do anything special; as many Perl commands will return a value that will be interpreted as true anyway; but to be sure of it we use a common module coding trick: We include, as the last statement of the module, a single "command:"

1;

Perl interprets this expression and of course returns true since 1 is always interpreted as a true value.

While it's admittedly not at all useful (not many "Hello World" applications are) our module above is a complete, working construct, ready to be reused without modification in as many scripts as needed. But how do we actually use it in our own code? Chances are very good that you already know how...


To page 1current pageTo page 3To page 4To page 5
[previous] [next]

Created: April 7, 2005
Revised: April 7, 2005

URL: http://webreference.com/programming/perl/modules/2.html