/ 
Return-Value-1.302
River stage two • 3 direct dependents • 48 total dependents
/ Return::Value

NAME

Return::Value - Polymorphic Return Values

VERSION

version 1.302

$Id: /my/cs/projects/return/trunk/lib/Return/Value.pm 28007 2006-11-14T22:21:03.864745Z rjbs  $

SYNOPSIS

Used with basic function-call interface:

use Return::Value;

sub send_over_network {
    my ($net, $send) = @_:
    if ( $net->transport( $send ) ) {
        return success;
    } else {
        return failure "Was not able to transport info.";
    }
}

my $result = $net->send_over_network(  "Data" );

# boolean
unless ( $result ) {
    # string
    print $result;
}

Or, build your Return::Value as an object:

sub build_up_return {
    my $return = failure;
    
    if ( ! foo() ) {
        $return->string("Can't foo!");
        return $return;
    }
    
    if ( ! bar() ) {
        $return->string("Can't bar");
        $return->prop(failures => \@bars);
        return $return;
    }
    
    # we're okay if we made it this far.
    $return++;
    return $return; # success!
}

DESCRIPTION

Polymorphic return values are really useful. Often, we just want to know if something worked or not. Other times, we'd like to know what the error text was. Still others, we may want to know what the error code was, and what the error properties were. We don't want to handle objects or data structures for every single return value, but we do want to check error conditions in our code because that's what good programmers do.

When functions are successful they may return true, or perhaps some useful data. In the quest to provide consistent return values, this gets confusing between complex, informational errors and successful return values.

This module provides these features with a simple API that should get you what you're looking for in each contex a return value is used in.

Attributes

All return values have a set of attributes that package up the information returned. All attributes can be accessed or changed via methods of the same name, unless otherwise noted. Many can also be accessed via overloaded operations on the object, as noted below.

type

A value's type is either "success" or "failure" and (obviously) reflects whether the value is returning success or failure.

errno

The errno attribute stores the error number of the return value. For success-type results, it is by default undefined. For other results, it defaults to 1.

string

The value's string attribute is a simple message describing the value.

data

The data attribute stores a reference to a hash or array, and can be used as a simple way to return extra data. Data stored in the data attribute can be accessed by dereferencing the return value itself. (See below.)

prop

The most generic attribute of all, prop is a hashref that can be used to pass an arbitrary number of data structures, just like the data attribute. Unlike the data attribute, though, these structures must be retrived via method calls.

FUNCTIONS

The functional interface is highly recommended for use within functions that are using Return::Value for return values. It's simple and straightforward, and builds the entire return value in one statement.

success

The success function returns a Return::Value with the type "success".

Additional named parameters may be passed to set the returned object's attributes. The first, optional, parameter is the string attribute and does not need to be named. All other parameters must be passed by name.

# simplest possible case
return success;
failure

failure is identical to success, but returns an object with the type "failure"

METHODS

The object API is useful in code that is catching Return::Value objects.

new
my $return = Return::Value->new(
    type   => 'failure',
    string => "YOU FAIL",
    prop   => {
        failed_objects => \@objects,
    },
);

Creates a new Return::Value object. Named parameters can be used to set the object's attributes.

bool
print "it worked" if $result->bool;

Returns the result in boolean context: true for success, false for failure.

prop
printf "%s: %s',
  $result->string, join ' ', @{$result->prop('strings')}
    unless $result->bool;

Returns the return value's properties. Accepts the name of a property retured, or returns the properties hash reference if given no name.

other attribute accessors

Simple accessors exist for the object's other attributes: type, errno, string, and data.

Overloading

Several operators are overloaded for Return::Value objects. They are listed here.

Stringification
print "$result\n";

Stringifies to the string attribute.

Boolean
print $result unless $result;

Returns the bool representation.

Numeric

Also returns the bool value.

Dereference

Dereferencing the value as a hash or array will return the value of the data attribute, if it matches that type, or an empty reference otherwise. You can check ref $result->data to determine what kind of data (if any) was passed.

TODO

No plans!

AUTHORS

Casey West, <casey@geeknest.com>.

Ricardo Signes, <rjbs@cpan.org>.

COPYRIGHT

Copyright (c) 2004-2006 Casey West and Ricardo SIGNES.  All rights reserved.
This module is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.