Object::Result(3pm)

🦋 Object::Result 🦋

okay so bestie, welcome to Object::Result(3pm), straight out of the User Contributed Perl Documentation section, and honestly? it's giving main character energy. ✨

---

💖 NAME 💖

Object::Result — Allow subs to build and return objects on-the-fly 🎀

---

🌸 VERSION 🌸

This document describes Object::Result version 0.000003. no cap, that's the one. 💅

---

✨ SYNOPSIS ✨

okay so here's the whole vibe in one code block, look at her:

use Object::Result;

sub get_time {
    # Return an object indicating failure...
    if (!load Time::HiRes => 'time') {
        result { <FAIL> }
    }

    # Set up some lexical state information...
    my $time = time();

    # Return an object with methods that use that information...
    result {
        # Named methods for returned object...
        timestamp  { return scalar localtime($time) }

        delay (Num $offset)  { $time += $offset }

        # Coercions for returned object...
        <STR>  { $self->timestamp; }  # String --> timestamp method
        <NUM>  { time() - $time;   }  # Number --> age of object
        <BOOL> { $self < 60;       }  # True for the first minute
    }
};

# And later...

# Get back an object...
my $now = get_time();

# Use it (as a string, as an object, as a number)...
say "It's $now";
say $now->timestamp;
say 'Recent' if $now < 0.1;

# Change the object's internal state...
$now->delay(50);

# Use the object as a (dynamically valued) boolean...
while ($now) {
    sleep 5;
    say "Are we there yet?";
}

like?? she does so much. 😭💖

---

🌈 DESCRIPTION 🌈

This module adds a new keyword to Perl: "result". 🫶

That keyword acts like a "return", except instead of handing back a list of values to return, it takes one single block that spells out the behaviour of the object you're returning — meaning its methods and its operator overloading. Then it just... returns that object for you. iconic.

The whole intention here? To make returning clean, properly encapsulated objects way less onerous... instead of doing the whole "here's a list of values" thing or handing back references to arrays or hashes. 🙈

So like, instead of:

my ($ID, $name, $uptime, $load, $users, $location, $contact)
    = get_server_status($server_ID);

if ($uptime) {
    say "$ID ($name) load: $load";
}

or:

my $server = get_server_status($server_ID);

if ($server->{uptime}) {
    say "$server->{ID} ($server->{name) load: $server->{load}";
}

you can just arrange the API to be object-based:

my $server = get_server_status($server_ID);

if ($server->is_up) {
    say $server->describe, ' load: ', $server->load;
}

The real advantage — and this is the part that ate, fr fr — is that inside the module providing "get_server_status()" you do not have to define a whole separate class implementing the objects that subroutine returns. And even more importantly, if you've got a dozen subroutines each returning their own specialized objects, you don't have to define a dozen separate classes to support them. 🎀

---

🧠 RATIONALE 🧠

(Skip straight ahead to INTERFACE if you already get it... or if you just don't care why this approach is better. no judgement, bestie 💜)

Subroutines that return lists of values make client code brittle: it is far too easy to mess up the unpacking. 😭

my ($ID, $name, $uptime, $users, $load, $contact, $location)
    = get_server_status($server_ID);

Subroutines that return hash references aren't much better honestly: sure, they keep all the information together, and they kill off the order dependency when you're unpacking it — but it's also very easy to misspell a key and thereby create a silent bug. 💀

my $server = get_server_status($server_ID);

if ($server->{up_time}) {
    say "$server->{id} ($server->{name) load: $server->{load}";
}

Like hashrefs, properly encapsulated objects keep all the returned information together and let you grab it by name — but they can also provide extra methods to simplify common tasks, and the OO syntax makes it a fatal error to misspell any access attempt. periodt. 👑

my $server = get_server_status($server_ID);

if ($server->up_time) {
    say $server->describe, ' load: ', $server->lode;
}
# dies with: "No such method 'lode' at demo.pl line 27"

The only downside? Object-based return values are tedious to set up. If you've got multiple subroutines in your API, each one may need to return a unique type of object, which means you have to define as many distinct support classes as you have subroutines. And even with helper modules (such as Moose or Object::InsideOut) that is a substantial amount of extra work. 🙈

sub get_server_status ($server_ID)  {
    my $status_ref = _acquire_status_somehow_for($server_ID);

    return GSS::Result->new(status => $status_ref);
}

# Class implementing result objects for get_server_status()...
package GSS::Result {
    use Moose;

    has status => (is => 'ro', required => 1);

    sub ID       { my $self = shift; $self->status->{ID}       }
    sub name     { my $self = shift; $self->status->{name}     }
    sub uptime   { my $self = shift; $self->status->{uptime}   }
    sub load     { my $self = shift; $self->status->{load}     }
    sub users    { my $self = shift; $self->status->{users}    }
    sub location { my $self = shift; $self->status->{location} }
    sub contact  { my $self = shift; $self->status->{contact}  }

    sub is_up    { my $self = shift; $self->uptime > 0         }

    sub describe {
        my $self = shift;
        $self->ID . ' (' . $self->name . ')';
    }
}

The Object::Result module lets you have your cake (per-subroutine return objects) without requiring quite so much baking (of per-subroutine support clases). 🍓✨

---

🎀 INTERFACE 🎀

The module lexically inserts a new keyword ("result") into any scope when it is loaded. slay.

That keyword takes a single block of code containing zero or more method specifications, and builds an object which supplies those methods. Then — plot twist — the keyword causes the surrounding subroutine to immediately return that object. 🦋

---

💅 Defining named methods 💅

To define a normal named method for the result object, you specify its name followed by a block implementing its body. So like, if you want to say the result object has two methods — "succeeded()" and "fitness()" — you write:

result {
    succeeded { return $outcome > 0 }
    fitness   { return $outcome * $sample->{metric} }
}

Methods may be specified with parameter lists, and those are implemented by the Method::Signatures module. like so:

result {
    succeeded (Num $threshold = 0) {
        return $outcome > $threshold
    }

    fitness {
        return $outcome * $sample->{metric}
    }
}

If you don't specify a parameter list, "result" methods are assumed to take no arguments (which is Method::Signatures' default behaviour, iykyk). 🧚

---

and bestie, we are SO not done — there's more of this page coming, hold on 💜

🌸 Data storage for result objects 🌸

okay bestie, here's the tea on where your result object actually keeps its stuff 💅

Result methods get their information (e.g. $outcome and $sample) from the lexical variables declared in the surrounding subroutine. For example:

sub estimate_fitness ($sample, $environment) {
    my $outcome = $sample->{metric} < $environment->{max_impact}
        ? $environment->{fitness_func}->($sample->{max})
        : $environment->{max_survivability};

    result {
        succeeded (Num $threshold = 0) {
            return $outcome > $threshold
        }

        fitness {
            return $outcome * $sample->{metric}
        }
    }
}

In other words, the various methods defined in the result block become closures over the variables inside the surrounding subroutine, and the result object can use those variables as its private storage (i.e. its attributes/fields). it's giving "the object is just vibing inside your lexicals" ✨

For example, the full get_server_status() subroutine shown earlier in RATIONALE could be implemented as:

sub get_server_status ($server_ID)  {
    my $status_ref = _acquire_status_somehow_for($server_ID);

    result {
        ID       { $status_ref->{ID}         }
        name     { $status_ref->{name}       }
        uptime   { $status_ref->{uptime}     }
        load     { $status_ref->{load}       }
        users    { $status_ref->{users}      }
        location { $status_ref->{location}   }
        contact  { $status_ref->{contact}    }
        is_up    { $status_ref->{uptime} > 0 }
        describe { "$status_ref->{ID} ($status_ref->{name})" }
}

using the lexical $status_ref as the object's attribute storage. iconic behaviour honestly 🫶

Note that methods can also modify this private data, so the result object from get_server_status() could also support subsequent annotations on the result:

sub get_server_status ($server_ID)  {
    my $status_ref = _acquire_status_somehow_for($server_ID);
    my @annotations;

    result {
        # All the methods defined in the previous version, plus...

        add_note  ($msg) { push @annotations, $msg; }
        get_notes        { return @annotations;     }

}

---

🦋 Coercions 🦋

Perl allows classes to specify coercive overloadings, so that their objects can then be treated as if they were booleans, strings, numbers, integers, or references to scalars, arrays, hashes, regexes, subroutines, or typeglobs. the range?? unmatched, no cap

The result keyword supports this kind of type-coercion too. Coercion methods can be specified by naming the specific type in angle brackets. For example, get_server_status() could return a result object that is true only if the server is up, and which stringifies to a printable summary of the status, like so:

sub get_server_status ($server_ID)  {
    my $status_ref = _acquire_status_somehow_for($server_ID);

    result {
        # All the methods defined in the previous version, plus...

        <BOOL>  { return $status_ref->{uptime} > 0;          }
        <STR>   { return $self->describe . ': ' $self->load; }
}

Note that, because all methods (named or coercive) are implemented via the Method::Signatures module, they automagically get a $self variable. bestie you literally don't have to do anything, it just shows up 😭💖

The following coercions are supported:

• Treat object as boolean: <BOOL>
• Treat object as string: <STR>
• Treat object as integer: <INT>
• Treat object as number: <NUM>
• Treat object as scalar ref: <SCALAR>
• Treat object as array ref: <ARRAY>
• Treat object as hash ref: <HASH>
• Treat object as typeblob ref/filehandle: <GLOB>
• Treat object as regex: <REGEXP> or <REGEX>
• Treat object as subroutine ref: <CODE> or <SUB>

In addition, the coercions to reference types can have the suffix REF appended to their names (e.g. <HASHREF>, <ARRAYREF>, <SUBREF>, etc.) ✨

Coercion methods take no arguments (except the implicit $self) and are expected to return either a value of the appropriate type, or some other object with a suitable coercion overloading (i.e. the same requirements as for coercions specified via use overload). no extra args, no notes, just vibes and correct types

By default, if a result object is asked for a particular coercion (apart from boolean; see "Boolean coercions"), but did not have that coercion explicitly defined, then the result object immediately throws an exception. See "Default coercions" for a way to change this behaviour. 💀

👑 Boolean coercions 👑

By default, any result object that has at least one method or coercion defined will evaluate true in a boolean context...as if they all had the following coercion implicitly defined:

result {
    <BOOL> { return 1 }
    ...
}

However, as a special case, result objects with no methods at all:

result { }

always evaluate false (besides having several other useful features; see "Result objects for failure signalling"). the empty result is lowkey the main character here 👑

You can override these default boolean coercion behaviours simply by defining an explicit <BOOL> coercion yourself:

result {
    <BOOL> { return defined $outcome }
    ...
}

Or, if a result object has other methods, but should nevertheless always evaluate false, you can define that explicitly too:

result {
    <BOOL> { return 0 }
    ...
}

Note, however, that in such cases it may be more effective to use a failure object.

🎀 Default coercions 🎀

Although "missing" coercions default to throwing an exception, it's also possible to specify that something else should happen when an unimplemented coercion is requested...by using the <DEFAULT> specifier. plot twist!! you get to choose what happens ✨

For example, to convert the normal exception-throwing response into merely warning about an unimplemented coercion:

result {
    # Actual methods and coercions here

    <DEFAULT> ($requested_coercion, $obj_origin) {
        carp "Can't convert result of $obj_origin to $requested_coercion";
    }
}

Or to revert the object to Perl's built-in behaviours (i.e. address-as-integer in a numeric context, REFTYPE=CLASSNAME(0xADDRESS) in a string context, etc.) you could specify:

result {
    # Actual methods and coercions here

    <DEFAULT> { return $self }
}

As the first example implies, the <DEFAULT> coercion method is passed two extra arguments apart from the usual $self. The first argument is a string containing the name of the missing coercion that was requested: '<STR>', or '<NUM>', or '<HASH>', etc. The second argument is a string indicating the origin of the result object being coerced. That second argument is of the form:

'call to __SUBNAME__() at __FILE__ line __LINE__'

and may be useful for generating more informative warnings or errors within a <DEFAULT> coercion. 🫶

---

🧚 Cleaning up result objects 🧚

If a result object manages some external resource, you can also set up a destructor for that object, using the <DESTROY> pseudo-coercion:

sub open_output_file ($filename) {
    open my $fh, '>', $filename or croak $!;

    result {
        write   (@whatever)  { print @whatever; }
        writeln (@whatever)  {   say @whatever; }

        <BOOL> { return not $fh->eof  }
        <GLOB> { return $fh           }

        # Make sure file is flushed before closing...
        <DESTROY> {
            $fh->flush();
            $fh->close();
        }
    }
}

cleanup queen behaviour, we love a tidy destructor 💅

---

💀 Result objects for failure signalling 💀

The default behaviour of missing coercions provides an easy way to produce so-called "contingent exceptions" (a.k.a. "failure objects").

In particular, a result statement of the form:

result { <FAIL> }

or its exact equivalent, an "empty" result:

result { }

returns an object that evaluates false in boolean contexts and throws an exception when used in any other way (i.e. whenever it has a method called on it, or it is used as a string, number, regex, or reference). The result object also throws an exception if it is destroyed without having been tested in a boolean context. do NOT ignore it bestie, it will come for you 😭

That is, the two forms shown above are equivalent to something like:

{
    my $tested_as_boolean = 0;
    my $error_msg = $@ // $! // $?;
    result {
        <BOOL>    { $tested_as_boolean++; return 0;          }
        <DEFAULT> { croak $error_msg;                        }
        <DESTROY> { croak $error_msg if !$tested_as_boolean; }
    }
}

If you want the exceptions to throw something else, you can give the <FAIL> specifier a block, which will then be called instead to generate the argument(s) to <croak():

# Throw a different string as the exception...
result {
    <FAIL> { "Could not load file: $!" }
}

# Throw an exception object...
result {
    <FAIL> { X::File::NoLoad->new($!) }
}

Failure objects such as these are a useful way of signalling errors, because the client code can test the result object (in which case it evaluates false like a typical undef or 0 or "" failure value):

my $status = get_server_status();

if ($status) {     # 'if' test fails if sub returned failure object
    say $status;
}

Or the client code can decide not to bother testing it, in which case it dies when used in any non-boolean way (or not used at all):

my $status = get_server_status();

say $status;       # Dies here if sub returned failure object

Thus the exception-on-failure is contingent: it will be thrown if the object is used in (almost) any way, unless the failure object has been "defused" by testing it for in a boolean context. 🦋

💅 DIAGNOSTICS 💅

Okay so bestie, sometimes things go sideways, and this module is very dramatic about telling you why. Every complaint it makes, decoded for you 👇

---

🔍 Compile-time diagnostics

These ones hit you before your code even runs, at compile time. Rude, but honest.

• "Invalid syntax for 'result' statement. Expected block but found %s" — the result keyword takes exactly one block after it, and you gave it something else. Iconic mistake, honestly. Maybe what you actually wanted was a plain old return instead of result? 👀
• "Missing definition for %s method" — you named a method or a coercion inside the result block but never gave it an implementation, like, no block of code for it to actually execute. She needs the body, babes 💀
• "Invalid definition for %s method. Expected parameter list or method block, but found %s" — you declared a method or coercion name inside the result block, so the module was sitting there all expectant, waiting for either a parameter list specification or a block implementing that method or coercion. Instead it found something else right after the method name, and reported the syntax error. It's giving unmet expectations 😭

🚨 Run-time diagnostics

These ones show up while your code is actually running. The plot twists.

• "Object returned by %s can't be used as %s" — you tried to coerce a result object returned by result into some other type (a number, a string, a reference, etc.) but the result block never explicitly specified that coercion. The fix? Add the appropriate coercion specification to the result block. 🫶

Or, if what you actually wanted was just the vanilla Perl behaviours when coercing result objects like these, add this to the result block:

<DEFAULT> { $self }

• "Call to %s failed: %s Failure detected at %s" — you called a subroutine that handed back a failure object (so, a result {<FAIL>}). Here's the thing: failure objects can only be tested for their boolean value. Do literally anything else with one — or nothing at all — and you get this exception. And that's the whole point, because that's exactly what <FAIL> is supposed to do. No notes. 💅

---

🎀 CONFIGURATION AND ENVIRONMENT 🎀

Object::Result requires no configuration files or environment variables.

Like, none. Zero setup. Just vibes. ✨

---

🔥 DEPENDENCIES 🔥

• Keyword::Simple — to install the result keyword.
• PPI — to parse the new result-block syntax cleanly.
• Method::Signatures — to support signatures on methods declared within a result block. Also used internally within the module's own implementation.

---

🌈 INCOMPATIBILITIES 🌈

None reported.

---

💀 BUGS AND LIMITATIONS 💀

No bugs have been reported.

Please report any bugs or feature requests to bug-object-result@rt.cpan.org, or through the web interface at <http://rt.cpan.org>.

---

👑 AUTHOR 👑

Damian Conway <DCONWAY@CPAN.org>

---

📜 LICENCE AND COPYRIGHT 📜

Copyright (c) 2014, Damian Conway <DCONWAY@CPAN.org>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

---

⚠️ DISCLAIMER OF WARRANTY ⚠️

okay bestie, this part is in ALL CAPS energy for a reason — it's the legal bit, and it's not a drill 🙈

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

---

That's the whole page, bestie — we made it 🎉 This version came straight from the manual page for perl v5.36.0, dated 2023-08-02, and it's Object::Result(3pm) in the flesh. Now go forth and result responsibly 💖✨🦋