Devil Killer Is Here MiNi Shell
MiNi SheLL

Current Path : /proc/thread-self/root/usr/local/man/man3/
Linux boscustweb5002.eigbox.net 5.4.91 #1 SMP Wed Jan 20 18:10:28 EST 2021 x86_64
Current File : //proc/thread-self/root/usr/local/man/man3/Return::Value.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Return::Value 3"
.TH Return::Value 3 "2006-11-14" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Return::Value \- Polymorphic Return Values
.SH "VERSION"
.IX Header "VERSION"
version 1.302
.PP
.Vb 1
\& $Id: /my/cs/projects/return/trunk/lib/Return/Value.pm 28007 2006-11-14T22:21:03.864745Z rjbs  $
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Used with basic function-call interface:
.PP
.Vb 1
\&  use Return::Value;
.Ve
.PP
.Vb 8
\&  sub send_over_network {
\&      my ($net, $send) = @_:
\&      if ( $net->transport( $send ) ) {
\&          return success;
\&      } else {
\&          return failure "Was not able to transport info.";
\&      }
\&  }
.Ve
.PP
.Vb 1
\&  my $result = $net->send_over_network(  "Data" );
.Ve
.PP
.Vb 5
\&  # boolean
\&  unless ( $result ) {
\&      # string
\&      print $result;
\&  }
.Ve
.PP
Or, build your Return::Value as an object:
.PP
.Vb 2
\&  sub build_up_return {
\&      my $return = failure;
.Ve
.PP
.Vb 4
\&      if ( ! foo() ) {
\&          $return->string("Can't foo!");
\&          return $return;
\&      }
.Ve
.PP
.Vb 5
\&      if ( ! bar() ) {
\&          $return->string("Can't bar");
\&          $return->prop(failures => \e@bars);
\&          return $return;
\&      }
.Ve
.PP
.Vb 4
\&      # we're okay if we made it this far.
\&      $return++;
\&      return $return; # success!
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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.
.PP
This module provides these features with a simple \s-1API\s0 that should get you what
you're looking for in each contex a return value is used in.
.Sh "Attributes"
.IX Subsection "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.
.IP "type" 4
.IX Item "type"
A value's type is either \*(L"success\*(R" or \*(L"failure\*(R" and (obviously) reflects
whether the value is returning success or failure.
.IP "errno" 4
.IX Item "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.
.IP "string" 4
.IX Item "string"
The value's string attribute is a simple message describing the value.
.IP "data" 4
.IX Item "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.)
.IP "prop" 4
.IX Item "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.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
The functional interface is highly recommended for use within functions
that are using \f(CW\*(C`Return::Value\*(C'\fR for return values.  It's simple and
straightforward, and builds the entire return value in one statement.
.IP "success" 4
.IX Item "success"
The \f(CW\*(C`success\*(C'\fR function returns a \f(CW\*(C`Return::Value\*(C'\fR with the type \*(L"success\*(R".
.Sp
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.
.Sp
.Vb 2
\& # simplest possible case
\& return success;
.Ve
.IP "failure" 4
.IX Item "failure"
\&\f(CW\*(C`failure\*(C'\fR is identical to \f(CW\*(C`success\*(C'\fR, but returns an object with the type
\&\*(L"failure\*(R"
.SH "METHODS"
.IX Header "METHODS"
The object \s-1API\s0 is useful in code that is catching \f(CW\*(C`Return::Value\*(C'\fR objects.
.IP "new" 4
.IX Item "new"
.Vb 7
\&  my $return = Return::Value->new(
\&      type   => 'failure',
\&      string => "YOU FAIL",
\&      prop   => {
\&          failed_objects => \e@objects,
\&      },
\&  );
.Ve
.Sp
Creates a new \f(CW\*(C`Return::Value\*(C'\fR object.  Named parameters can be used to set the
object's attributes.
.IP "bool" 4
.IX Item "bool"
.Vb 1
\&  print "it worked" if $result->bool;
.Ve
.Sp
Returns the result in boolean context: true for success, false for failure.
.IP "prop" 4
.IX Item "prop"
.Vb 3
\&  printf "%s: %s',
\&    $result->string, join ' ', @{$result->prop('strings')}
\&      unless $result->bool;
.Ve
.Sp
Returns the return value's properties. Accepts the name of
a property retured, or returns the properties hash reference
if given no name.
.IP "other attribute accessors" 4
.IX Item "other attribute accessors"
Simple accessors exist for the object's other attributes: \f(CW\*(C`type\*(C'\fR, \f(CW\*(C`errno\*(C'\fR,
\&\f(CW\*(C`string\*(C'\fR, and \f(CW\*(C`data\*(C'\fR.
.Sh "Overloading"
.IX Subsection "Overloading"
Several operators are overloaded for \f(CW\*(C`Return::Value\*(C'\fR objects. They are
listed here.
.IP "Stringification" 4
.IX Item "Stringification"
.Vb 1
\&  print "$result\en";
.Ve
.Sp
Stringifies to the string attribute.
.IP "Boolean" 4
.IX Item "Boolean"
.Vb 1
\&  print $result unless $result;
.Ve
.Sp
Returns the \f(CW\*(C`bool\*(C'\fR representation.
.IP "Numeric" 4
.IX Item "Numeric"
Also returns the \f(CW\*(C`bool\*(C'\fR value.
.IP "Dereference" 4
.IX Item "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 \f(CW\*(C`ref $result\->data\*(C'\fR to determine what kind of data (if any) was
passed.
.SH "TODO"
.IX Header "TODO"
No plans!
.SH "AUTHORS"
.IX Header "AUTHORS"
Casey West, <\fIcasey@geeknest.com\fR>.
.PP
Ricardo Signes, <\fIrjbs@cpan.org\fR>.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 3
\&  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.
.Ve
Creat By MiNi SheLL
Email: devilkiller@gmail.com