my $result1 = $Person->name('Homer');
my $result2 = $result1->job('safety inspector');
my $result3 = $result2->wife('Marge');
$result3->fav_food('Duff');
[download]

sub name {
    my ($self, $value) = @_;
    
    if (defined $value) { # if a value is given
        $self->{name} = $value; # set the value
        return $self; # return the original object
    }

    return $self->{name}; # else return the name
}
[download]

So why do you sometimes see the original object ($Person in this case) have multiple method calls originating from the original obect on multiple lines? Because if the method returns a value other than itself (which is quite common), it will try to call the method on that value, and most likely fail.

elusion : http://matt.diephouse.com

In your first example, the assumption I would make based on what I see is that

1. $interface is a handle to an object that has a method, handler() that takes a parameter ($client) and returns an object.

   This object is probably the handler object for the specified client for this interface.

2. This handler object has a method parse that takes a string, in this case probably a filename, and either parses that string, or possibly the contents of a file who's name is held in that string.

   That the results of the parsing are not returned immediately suggests that the latter is more likely, and subsequent calls to the handler would be needed to verify and/or retrive thos results.

   That no attempt is made to check any return code from the parse call would worry me slightly.

In the second example, the code looks remenicient of much of the Java Library API's, where accessor methods for 'set' operations return their own handle allowing calls to the 'set' methods to be chained.

So that $Person is the handle to an object that has (at least 4) private attributes (name,job,wife,favorite_food), and accessor methods that return (at least when a parameter os passed) their object handle, thus leading to the notational 'short-hand' of

$Person->name('Homer')->job('safety inspector')->wife('Marge')->fav_fo
+od('Duff');
[download]

instead of

$Person->name('Homer');
$Person->job('safety inspector');
$Person->wife('Marge');
$Person->fav_food('Duff');
[download]

Of course the real answer is that you shouldn't need to make these assumptions, as you should be able to consult the documentation, even if, in the worse-case scenario, the only documentation is the source code.

One of the joys of an interpreted language (interpreter/compiler debate aside) is that you always have the source to fall back on. None of the agony of trying to maintain and/or modify code that uses binary libararies for which the source and or documentation has long since disappeared or never existed in the first place.

Your second example

$Person->name('Homer')
->job('safety inspector')
->wife('Marge')
->fav_food('Duff');
[download]

seems to be just plain weird. I might be (and almost certainly am) missing something - the same thing as you in that case :) - but I read this as "execute the method fav_food on the object returned by executing wife on the object returned by executing job on the object returned by executing name on the thingy referenced in $person" (arguments left out to save what little shreds of clarity remaining). Beats me. Help.

CU

Robartes -

You are right, it does appear to be plain weird. It should evaluate differently than The_Don expected, with the -> operators operating left to right, so you did read it correctly. BrowserUK made a note about the Java APIs working this way, perhaps name(),job(),wife(), and (presumably)fav_food() all return the object that called it, that much is not clear.
Personally, when writing classes I tend to have my mutators (set()s) return nothing, making a clear distinction between accessors and mutators (except in certain circumstances).

Newlines added for "clarity":

print LWP::UserAgent->new()->
        request(
                HTTP::Request->new(GET => 'http://geeksalad.org')
                )->content;
[download]

if (($_=LWP::UserAgent->new()->
    request(
        HTTP::Request->new(GET=>'http://geeksalad.org')
            ))->is_success) {
        print $_->content;
}
[download]

This mess is more commonly written as something like (edited from the LWP manpage):

# Create a user agent object
use LWP::UserAgent;
$ua = new LWP::UserAgent;
my $req = new HTTP::Request POST => 'http://geeksalad.org';
my $res = $ua->request($req);
if ($res->is_success) {
    print $res->content;
} else {
    print "Bad luck this time\n";
}
[download]

I would again like to thank the Monastery for their responses. I have come to the final assumption that each call to the objects that set an attribute return the object; thus, 'set' calls can be chained.

The final answer, which is so simple I that I apparently ignored, is that the '->' is left associative. This behavior as best I can tell mimics Java completely and I understand completely (I was taught computer science using Java).

To address why I did not resort to source code for a definitive answer. The code that the system uses automatically creates accessor methods using a %fields hash. I do not have enough knowledge of existing modules to know where / how these accessors are automagically created nor if the auto-functions are a result of a CPAN module, an in-house module, or a hybrid. However, my past experience with the system has shown me that the level of extension with OO Perl reaches levels so deep and convoluded that it was a much better use of time to ask for assistance from strangers with no knowledge of the innner-workings than to seek assistance in-house.

Again, I would like to thank everyone for their help. ++ for everyone ! :-)

the_Don
...making offers others can't rufuse.