.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "Class::Error 3"
.TH Class::Error 3 "2019-04-12" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Class::Error \- Delayed checking of object failure
.SH "VERSION 2.41"
.IX Header "VERSION 2.41"
Included in OOTools 2.41 distribution.
.PP
The latest versions changes are reported in the \fIChanges\fR file in
this distribution.
.PP
The distribution includes:
.IP "\(bu" 4
Class::constr
.Sp
Pragma to implement constructor methods
.IP "\(bu" 4
Class::props
.Sp
Pragma to implement lvalue accessors with options
.IP "\(bu" 4
Class::groups
.Sp
Pragma to implement groups of properties accessors with options
.IP "\(bu" 4
Class::Error
.Sp
Delayed checking of object failure
.IP "\(bu" 4
Object::props
.Sp
Pragma to implement lvalue accessors with options
.IP "\(bu" 4
Object::groups
.Sp
Pragma to implement groups of properties accessors with options
.IP "\(bu" 4
Class::Util
.Sp
Class utility functions
.SH "INSTALLATION"
.IX Header "INSTALLATION"
.IP "Prerequisites" 4
.IX Item "Prerequisites"
.Vb 1
\&    Perl version >= 5.6.1
.Ve
.IP "\s-1CPAN\s0" 4
.IX Item "CPAN"
.Vb 1
\&    perl \-MCPAN \-e \*(Aqinstall OOTools\*(Aq
.Ve
.IP "Standard installation" 4
.IX Item "Standard installation"
From the directory where this file is located, type:
.Sp
.Vb 4
\&    perl Makefile.PL
\&    make
\&    make test
\&    make install
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  package My::Package ;
\&
\&  use Class::Error ;
\&
\&  $undef_obj = Class::Error\->new($error, $errnum)
\&
\&  $undef_obj\->any_method ;              # won\*(Aqt die and will return $undef_obj
\&  print \*(Aqis false\*(Aq unless $undef_obj ;  # \*(Aqis false\*(Aq
\&  print "$undef_obj" ;                  # \*(Aq\*(Aq with warning "Use of uninitialized
\&                                        # value in string..."
\&  print $undef_obj\->any_method ;        # \*(Aq\*(Aq with same warning
\&
\&  $empty_obj = Class::Error\->new($error, $errnum, \*(Aq\*(Aq)
\&
\&  $empty_obj\->any_method ;              # won\*(Aqt die and will return $empty_obj
\&  print \*(Aqis false\*(Aq unless $empty_obj ;  # \*(Aqis false\*(Aq
\&  print "$empty_obj" ;                  # \*(Aq\*(Aq no warnings
\&  print $empty_obj\->any_method ;        # \*(Aq\*(Aq no warnings
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
You can use this module to return a Class::Error object instead of a simple
false value (e.g. when a sub or a property may return an object \s-1OR\s0 the undef
value on failure).
.PP
That feature allows to check on the object itself, or delay the checking after
calling any method on the object.
.PP
.Vb 2
\&   $obj = AnyClass\->new or die $obj\->error
\&   AnyClass\->new\->any_method or die Class::Error\->error  # static
.Ve
.PP
For example, compare the difference between the behaviour of \f(CW\*(C`obj_A\*(C'\fR
and \f(CW\*(C`obj_B\*(C'\fR if the \f(CW\*(C`AnyClass\->new\*(C'\fR would return false:
.PP
.Vb 9
\&   use Object::props
\&     ( { name    => \*(Aqobj_A\*(Aq,
\&         default => sub{ AnyClass\->new or undef }
\&       },
\&       { name    => \*(Aqobj_B\*(Aq,
\&         default => sub{ AnyClass\->new
\&                         or Class::Error\->new(\*(AqAnyClass\->new failed\*(Aq) }
\&       }
\&     );
\&
\&   # if AnyClass\->new would fail (returning a false value)
\&
\&   # this would die "Can\*(Aqt call method "any_method" on an undefined value..."
\&   $s\->obj_A\->any_method or do{ warn \*(Aqdoing something else...\*(Aq;
\&                                do_something_else()
\&                              };
\&   # but this would execute the do{} block
\&   $s\->obj_B\->any_method or do{ warn \*(Aqdoing something else...\*(Aq;
\&                                do_something_else()
\&                              };
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "\s-1AUTOLOAD\s0"
.IX Subsection "AUTOLOAD"
All the methods called on the Class::Error object (regardless the arguments)
return a reference to the object itself, thus allowing you to call methods
on methods:
.PP
.Vb 1
\&   $error_obj\->any_method(\*(Aqa\*(Aq, \*(Aqb\*(Aq)\->any_other_method...
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "new ([ error [, errnum [, false]]] )"
.IX Subsection "new ([ error [, errnum [, false]]] )"
.Vb 3
\&   $undef_obj = Class::Error\->new($error, $errnum)       # undef
\&   $empty_obj = Class::Error\->new($error, $errnum, \*(Aq\*(Aq)   # empty
\&   $zero_obj  = Class::Error\->new($error, $errnum, 0)    # 0
.Ve
.PP
The constructor accepts 3 optional arguments and returns a Class::Error object.
.PP
\&\fIerror\fR sets the error, which could be a simple string or any other
value (also stored in \f(CW$Class::Error::error\fR), \fIerrnum\fR sets the
error number (also stored in \f(CW$Class::Error::errnum\fR) which you can
retrieve with the \f(CW\*(C`error\*(C'\fR and \f(CW\*(C`errnum\*(C'\fR static or dynamic methods.
.PP
You can also pass a third argument (which must be false) to the new
method or leave it undef: the scalar reference to the \fIfalse\fR argument
will be used as the object value in any contexts (internally using
\&\f(CW\*(C`overload\*(C'\fR).
.PP
For example, if you leave the \fIfalse\fR argument as \f(CW\*(C`undef\*(C'\fR, the
Class::Error object itself is evaluated as undef in any contexts
(e.g. false in boolean context like the undef value), but unlike
the undef value, it is defined and allows you to call any methods on it.
.PP
\&\fBNote\fR: If you want to avoid the \*(L"use of uninitialized value...\*(R"
warning when you use the object itself (or the result of its methods)
in string context, you can pass an empty string to the constructor,
or the \f(CW0\fR value for numeric context. Use that feature only if you
know what you are doing, since a defined false value might make more
difficult the debgging of real errors.
.SS "error"
.IX Subsection "error"
Returns the last error string passed to the \fInew()\fR method:
.PP
.Vb 3
\&   AnyClass\->new\->any_method or die Class::Error\->error  # static
\&   $result = AnyClass\->new\->any_method or die $result\->error
\&   $obj = AnyClass\->new or die $obj\->error
.Ve
.SS "errnum"
.IX Subsection "errnum"
Returns the last error number passed to the \fInew()\fR method:
.PP
.Vb 2
\&   if ( Class::Error\->errnum == 230 ) { .... }  # static
\&   if ( $obj\->errnum == 230 ) { .... }
.Ve
.SH "SUPPORT and FEEDBACK"
.IX Header "SUPPORT and FEEDBACK"
If you need support or if you want just to send me some feedback or
request, please use this link: http://perl.4pro.net/?Class::Error.
.SH "AUTHOR and COPYRIGHT"
.IX Header "AUTHOR and COPYRIGHT"
Copyright 2004\-2005 by Domizio Demichelis.
.PP
All Rights Reserved. This module is free software. It may be used,
redistributed and/or modified under the same terms as perl itself.