Needless to say, I rely heavily on perldoc. It's great, but like man pages, I often find them hard to read (man find completely bewilders me -- no humor intended). Today, a coworker was trying to understand overloading and his code was a bit confused. That's fair because when I first tried to understand overload from the docs, I was a bit confused and I eventually resorted to reading Perl modules which used overloading to understand what was going on. So I wrote a tiny example for him:

#!/usr/bin/perl -l

use strict;
use warnings;
{
    package Number;

    use overload 
      '+'      => \&plus,
      '""'     => \&value, 
      fallback => 1;

    use Scalar::Util qw(blessed looks_like_number);
    use Carp qw(carp croak);

    sub new {
        my ( $class, $number ) = @_;
        unless ( looks_like_number($number) ) {
            croak("($number) is not a valid number");
        }
        return bless { number => $number } => $class;
    }

    sub value { shift->{number} }

    sub plus {
        my ( $num1, $num2, $reversed ) = @_;
        if ($reversed) {
            carp("$num1 and $num2 are reversed");
        }
        return __PACKAGE__->new(
            $num1->value 
            + 
            ( blessed $num2 ? $num2->value : $num2 ) 
        );
    }
}

my $seven = Number->new(7);
my $pi    = Number->new(3.14);

# overloading stringification ('""') allows the following to work
print $seven + $pi;

# 'blessed' in &plus allows this to work
print $seven + $pi + 1 + $pi;

# without overloading, the above is:
print $seven->plus($pi)->plus(1)->plus($pi)->value;

# perl's smart enough to reverse these
print 3 + $seven;
[download]

While that's perhaps not the best use of overloading, it's clear. Once he saw that, he quickly understood the core concept and the rest of the docs were easy for him to read.

I would love to see more of this in the Perl documentation, right at the beginning of complicated sections.

Thanks to kyle and liverpole for pointing out a small typo (never code in a textarea kids!)

---

---

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		&
	<		&lt;
	>		&gt;
	[		&#91;
	]		&#93;

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.