Use perltooc to Find the Right Perl OO Documentation

perltooc is not a compiler, a module installer or a tutorial command. On this machine it is a short manual page that points you towards the two documents you need for object-oriented Perl: perlootut for the concepts and recommended approaches, and perlobj for the mechanics of Perl's built-in object system. This guide turns that pointer into a small, testable workflow.

You will finish with the documentation open locally, a minimal Perl class that constructs an object and calls a method, and a clear boundary between core Perl OO and larger CPAN-based object systems. Allow about 15 minutes if Perl is already installed. The examples only create files in a temporary directory and do not need root.

Prerequisites

• Perl 5 and the perl-doc package. The installed reference used for this guide is Perl 5.38.2, package version 5.38.2-3.2ubuntu0.6.
• A shell with perldoc available. If perldoc is missing, install the distribution's documentation package through its normal package-management process before continuing.
• A writable temporary directory for the example program.

1. Confirm what perltooc provides

Start by checking the local page rather than assuming that its name denotes a runnable program. The page's description says that it links to information on object-oriented programming, and its description names perlootut and perlobj. It also says that those documents supersede the tutorial that used to be in perltooc.

perldoc perltooc

Use the terminal pager's normal search and quit keys. A non-interactive check is useful in scripts or when you want to capture the text:

perldoc -T perltooc | sed -n '1,35p'

Expected output includes the name perltooc and links to perlootut and perlobj. The -T option selects plain text output; it does not change the documentation.

2. Read the documents in the useful order

Read the tutorial first when you are learning the model. It covers objects, classes, methods, attributes, inheritance, composition and roles, then discusses systems such as Moose and Moo. It assumes that you already know basic Perl syntax, variables, operators and subroutines.

perldoc perlootut

Read the object reference when a detail needs checking, such as how a package becomes a class, how an invocant is passed to a method, how bless associates a reference with a package, or how method lookup works.

perldoc perlobj

For a quick existence check without opening a pager:

perldoc -l perltooc perlootut perlobj

Each argument should print a local documentation path. If a particular document is unavailable, the local perltooc page is still useful evidence: it identifies the missing reference that the installed package should provide.

3. Run a minimal core-Perl object example

The following example uses only Perl's built-in conventions. A package acts as the class name. A constructor is an ordinary subroutine, here called new. The constructor blesses a hash reference into the package, and the method receives the object as its first argument.

example_dir=$(mktemp -d /tmp/perltooc-example.XXXXXX)
trap 'rm -rf "$example_dir"' EXIT
cat > "$example_dir/person.pl" <<'PERL'
use strict;
use warnings;

package Person;

sub new {
    my ($class, %args) = @_;
    return bless { name => $args{name} }, $class;
}

sub greeting {
    my ($self) = @_;
    return "Hello, " . $self->{name} . "\n";
}

package main;

my $person = Person->new(name => 'Ada');
print $person->greeting;
PERL
perl "$example_dir/person.pl"

Expected output:

Hello, Ada

The temporary directory is removed when the shell exits. The trap is a cleanup mechanism for this example, not a requirement of Perl OO. If you adapt the program into a real project, put it in your normal source tree and remove the temporary-directory wrapper.

4. Check the boundaries before choosing a framework

This small class demonstrates the low-level object model, but it is deliberately not a recommendation to hand-build every production class. The local reference describes Perl's default OO facilities as minimal. perlootut then discusses established systems that can provide constructors, accessors, roles and other conventions.

Use the core example to understand code you inherit and to test a language feature with no extra dependencies. Before adding a CPAN dependency, check the project's supported Perl versions, dependency policy and test suite. A framework choice is a project decision, not something that perltooc decides for you.

One common distraction is treating a package name as proof that it is a class. In Perl, any package can participate in OO, but its behaviour comes from how it is written and used. Another is assuming that every constructor must be named new. That name is conventional, not a special keyword.

Common failures

• perldoc: command not found: install perl-doc using your distribution's package manager, then repeat the version and lookup checks.
• Page perltooc does not exist: the documentation package is incomplete or your search path is unusual. Check perldoc -V and the package contents before changing PERL5LIB.
• The example prints an undefined value: check the constructor argument and the hash key. The example uses name consistently in construction and in greeting.
• A method call fails: check the arrow syntax and confirm that the reference was blessed into the package containing the method.