Use perlbot to Find Perl's Object-Oriented Documentation

You will finish with a quick way to navigate Perl's object-oriented documentation from a Linux shell, and a clear choice between the introductory tutorial and the lower-level reference. On this machine, perlbot is a documentation page, not a program that runs an OO example.

Allow about ten minutes. You need the perl-doc package and an ordinary shell account. The examples use Perl 5.38.2 and perl-doc 5.38.2-3.2ubuntu0.6. Reading the pages does not change files, services or system configuration, so no elevated privileges are needed.

1. Check what is installed

Confirm the Perl and documentation package versions before following examples from elsewhere. Package revisions vary between Linux releases:

$ perl -e 'print "$^V\n"'
v5.38.2
$ dpkg-query -W -f='${Package} ${Version}\n' perl-doc
perl-doc 5.38.2-3.2ubuntu0.6

If the second command reports that the package is not installed, stop here and install the documentation through your normal package-management process. That is the only step in this guide that might require administrator access, for example with sudo apt install perl-doc. Do not run an installation command merely because a tutorial mentions it: first check your distribution and package policy.

Checkpoint: you should have a Perl version and a package version. If perl itself is missing, the documentation is not useful until Perl is available.

2. Open perlbot as a manual page

Use the installed manual database to read the page:

$ man perlbot

The page is intentionally short. Its practical instruction is to continue with perlootut and perlobj. It also says that an older collection of Perl OO tricks has been superseded. Therefore, an empty-looking page is not a failed installation and there are no perlbot flags to discover.

For a terminal-friendly rendering that is easier to search or pipe into another command, use perldoc:

$ perldoc -t perlbot
NAME
    perlbot - Links to information on object-oriented programming in Perl

DESCRIPTION
    For information on OO programming with Perl, please see perlootut and
    perlobj.

The exact spacing can differ with the pager and Perl release. The useful check is that the page names appear. Locate the source file without opening an editor:

$ perldoc -l perlbot
/usr/share/perl/5.38.2/pod/perlbot.pod

3. Choose the right next page

Start with perlootut when you are learning the vocabulary or deciding how a Perl class should be used. It introduces objects, classes, methods, attributes, constructors and inheritance, then discusses the OO systems commonly used from CPAN. It assumes that you already know basic Perl syntax, variables, operators and subroutine calls.

$ perldoc perlootut

Use perlobj when you need the mechanics behind existing code or are maintaining an object system built close to Perl's core:

$ perldoc perlobj

That reference explains that a Perl object is a data structure associated with a class, a class is normally a package, and a method receives an object or class name as its first argument. It covers references, bless, method lookup, inheritance and related details. If you are writing ordinary application code, read the tutorial first rather than starting with the implementation details.

4. Verify the pages are the installed ones

When several Perl versions are present, ask perldoc which files it will use:

$ for page in perlbot perlootut perlobj; do
>     printf '%s: ' "$page"
>     perldoc -l "$page"
> done
perlbot: /usr/share/perl/5.38.2/pod/perlbot.pod
perlootut: /usr/share/perl/5.38.2/pod/perlootut.pod
perlobj: /usr/share/perl/5.38.2/pod/perlobj.pod

Your paths may contain a different version directory. That is expected. A useful failure is also specific: if perldoc -l perlobj says it cannot find the page, inspect perl-doc installation and the active Perl path before copying examples from an unrelated release.

Do not confuse the documentation name with an executable. command -v perlbot normally prints nothing on this installation because perlbot is installed as POD and a manual page. Use man perlbot or perldoc perlbot; do not add a guessed path to a script or try to execute the compressed manual file.

5. Read examples with the right safety boundary

The documentation pages are explanatory and read-only. Code copied from them can still create files, load modules, call network services or alter data when you run it. Test an example in a disposable directory and inspect what it does before using real paths or credentials. No command in this guide creates an object, changes a Perl module or modifies system state, so there is nothing to undo.

If your real goal is to understand a module already installed on the host, identify the module first and then read its documentation with perldoc Module::Name. Keep that separate from perlbot: perlbot points to the language's OO documentation and does not select a framework for your project.