Provided by: libreturn-value-perl_1.666001-1_all bug

NAME

       Return::Value - (deprecated) polymorphic return values

VERSION

       version 1.666001

DO NOT USE THIS LIBRARY

       This library will begin issuing deprecation warnings in June 2010.

       Return::Value was a bad idea.  i'm sorry that I had it, sorry that I followed through, and
       sorry that it got used in other useful libraries.  Fortunately there are not many things
       using it.  One of those things is Email::Send which is also deprecated in favor of
       Email::Sender.

       There's no reason to specify a new module to replace Return::Value.  In general, routines
       should return values of uniform type or throw exceptions.  Return::Value tried to be a
       uniform type for all routines, but has so much weird behavior that it ends up being
       confusing and not very Perl-like.

       Objects that are false are just a dreadful idea in almost every circumstance, especially
       when the object has useful properties.

       Please do not use this library.  You will just regret it later.

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 a horrible idea, but this library was written based on the
       notion that they were 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 simplistic API that should get you what you're
       looking for in each context 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

       Add deprecation.

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.