G.3. Modules with Object-Oriented Interfaces

So suppose that one day you want to write a program that will automate the process of ftp ing a bunch of files from one server down to your local machine, and then off to another server.

A quick browse through search.cpan.org turns up the module Net::FTP, which you can download and install using normal installation instructions (unless your sysadmin has already installed it, as many have).

Like Text::Wrap or any other module with a familiarly functional interface, you start off using Net::FTP in your program by saying:

use Net::FTP;

However, that's where the similarity ends. The first hint of difference is that the documentation for Net::FTP refers to it as a class. A class is a kind of module, but one that has an object-oriented interface.

Whereas modules like Text::Wrap provide bits of useful code as functions, to be called like function(parameters) or like PackageName::function(parameters), Net::FTP and other modules with object-oriented interfaces provide methods. Methods are sort of like functions in that they have a name and parameters; but methods look different, and are different, because you have to call them with a syntax that has a class name or an object as a special argument. I'll explain the syntax for method calls, and then later explain what they all mean.

Some methods are meant to be called as class methods, with the class name (same as the module name) as a special argument. Class methods look like this:

ClassName->methodname(parameter1, parameter2, ...)
ClassName->methodname( )   # if no parameters
ClassName->methodname     # same as above

which you will sometimes see written:

methodname ClassName (parameter1, parameter2, ...)
methodname ClassName      # if no parameters

Basically, all class methods are for making new objects, and methods that make objects are called constructors (and the process of making them is called "constructing" or "instantiating"). Constructor methods typically have the name "new," or something including "new" (new_from_file, etc.); but they can conceivably be named anything—DBI's constructor method is named "connect," for example.

The object that a constructor method returns is typically captured in a scalar variable:

$object = ClassName->new(param1, param2...);

Once you have an object (more later on exactly what that is), you can use the other kind of method call syntax, the syntax for object method calls. Calling object methods is just like class methods, except that instead of the ClassName as the special argument, you use an expression that yields an object. Usually this is just a scalar variable that you earlier captured the output of the constructor in. Object method calls look like this:

$object->methodname(parameter1, parameter2, ...);
$object->methodname( )   # if no parameters
$object->methodname     # same as above

which is occasionally written as:

methodname $object (parameter1, parameter2, ...)
methodname $object      # if no parameters

Examples of method calls are:

my $session1 = Net::FTP->new("ftp.myhost.com");
  # Calls a class method "new", from class Net::FTP,
  #  with the single parameter "ftp.myhost.com",
  #  and saves the return value (which is, as usual,
  #  an object), in $session1.
  # Could also be written:
  #  new Net::FTP('ftp.myhost.com')
  || die "failed to login!\n";
   # calling the object method "login"
print "Dir:\n", $session1->dir( ), "\n";
  # same as $session1->quit( )
print "Done\n";

Incidentally, I suggest always using the syntaxes with parentheses and -> in them,[8] and avoiding the syntaxes that start out methodname $object or methodname ModuleName. When everything's going right, they all mean the same thing as the -> variants, but the syntax with -> is more visually distinct from function calls, as well as being immune to some kinds of rare but puzzling ambiguities that can arise when you're trying to call methods that have the same name as subroutines you've defined.

[8] The character-pair -> is supposed to look like an arrow, not "negative greater-than"!

But, syntactic alternatives aside, all this talk of constructing objects and object methods begs the question—what is an object? There are several angles to this question that the rest of this article will answer in turn: what can you do with objects? what's in an object? what's an object value? and why do some modules use objects at all?