.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "Object::Lazy 3pm"
.TH Object::Lazy 3pm "2022-10-16" "perl v5.34.0" "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"
Object::Lazy \- create objects late from non\-owned (foreign) classes
.SH "VERSION"
.IX Header "VERSION"
0.16
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Foo 123; # because the class of the real object is Foo, version could be 123
\&    use Object::Lazy;
\&
\&    my $foo = Object::Lazy\->new(
\&        sub {
\&            return Foo\->new;
\&        },
\&    );
\&
\&    bar($foo);
\&
\&    sub bar {
\&        my $foo = shift;
\&
\&        if ($condition) {
\&            # a foo object will be created
\&            print $foo\->output;
\&        }
\&        else {
\&            # foo object is not created
\&        }
\&
\&        return;
\&    }
.Ve
.PP
To combine this and a lazy use, write somthing like that:
.PP
.Vb 1
\&    use Object::Lazy;
\&
\&    my $foo = Object::Lazy\->new(
\&        sub {
\&            # 3 lines instead of "use Foo 123"
\&            require Foo;
\&            Foo\->import;
\&            Foo\->VERSION(\*(Aq123\*(Aq);
\&            return Foo\->new;
\&        },
\&    );
\&
\&    # and so on
.Ve
.PP
After a build object the scalar which hold the object will be updated too.
.PP
.Vb 2
\&  $object\->method;
\&  ^^^^^^^\-\-\-\-\-\-\-\-\-\-\-\-\-\- will update this scalar after a build
.Ve
.PP
Read topic \s-1SUBROUTINES/METHODS\s0 to find the entended constructor
and all the optional parameters.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
Inside of this Distribution is a directory named example.
Run this *.pl files.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements lazy evaluation
and can create lazy objects from every class.
.PP
Creates a dummy object including a subroutine
which knows how to build the real object.
.PP
Later, if a method of the object is called,
the real object will be built.
.PP
Inherited methods from \s-1UNIVERSAL\s0.pm are implemented and so overwritten.
This are isa, \s-1DOES,\s0 can and \s-1VERSION.\s0
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.SS "method new"
.IX Subsection "method new"
\fIshort constructor\fR
.IX Subsection "short constructor"
.PP
.Vb 5
\&    $object = Object::Lazy\->new(
\&        sub {
\&            return RealClass\->new(...);
\&        },
\&    );
.Ve
.PP
\fIextended constructor\fR
.IX Subsection "extended constructor"
.PP
.Vb 5
\&    $object = Object::Lazy\->new({
\&        build => sub {
\&            return RealClass\->new(...);
\&        },
\&    });
.Ve
.IP "\(bu" 4
optional parameter isa
.Sp
There are 3 ways to check the class or inheritance.
.Sp
If there is no parameter isa, the object must be built before.
.Sp
If the \f(CW\*(C`use RealClass;\*(C'\fR is outside of \f(CW\*(C`<build =\*(C'\fR sub {...}>>
then the class method \f(CW\*(C`<RealClass\-\*(C'\fRisa(...);>> checks the class or inheritance.
.Sp
Otherwise the isa parameter is a full notation of the class
and possible of the inheritance.
.Sp
.Vb 4
\&    $object = Object::Lazy\->new({
\&        ...
\&        isa => \*(AqRealClass\*(Aq,
\&    });
.Ve
.Sp
or
.Sp
.Vb 4
\&    $object = Object::Lazy\->new({
\&        ...
\&        isa => [qw(RealClass BaseClassOfRealClass)],
\&    });
.Ve
.IP "\(bu" 4
optional parameter \s-1DOES\s0
.Sp
It is similar to parameter isa.
But do not note the inheritance.
Note the Rules here.
.Sp
.Vb 4
\&    $object = Object::Lazy\->new({
\&        ...
\&        DOES => \*(AqRole1\*(Aq,
\&    });
.Ve
.Sp
or
.Sp
.Vb 4
\&    $object = Object::Lazy\->new({
\&        ...
\&        DOES => [qw(Role1 Role2)],
\&    });
.Ve
.IP "\(bu" 4
optional parameter \s-1VERSION\s0
.Sp
For the \s-1VERSION\s0 method tell Object::Lazy which version shold be checked.
.Sp
.Vb 4
\&    $object = Object::Lazy\->new({
\&        ...
\&        VERSION => \*(Aq123\*(Aq,
\&    });
.Ve
.Sp
or
.Sp
.Vb 1
\&    use version;
\&
\&    $object = Object::Lazy\->new({
\&        ...
\&        VERSION => qv(\*(Aq1.2.3\*(Aq), # version object
\&    });
.Ve
.IP "\(bu" 4
optional parameter version_from
.Sp
For the \s-1VERSION\s0 method tell Object::Lazy which class shold be version checked.
.Sp
.Vb 4
\&    $object = Object::Lazy\->new({
\&        ...
\&        version_from => \*(AqRealClass\*(Aq,
\&    });
.Ve
.IP "\(bu" 4
optional parameter logger
.Sp
Optional notation of the logger code to show the build process.
.Sp
.Vb 7
\&    $object = Object::Lazy\->new({
\&        ...
\&        logger => sub {
\&            my $at_stack = shift;
\&            print "RealClass $at_stack";
\&        },
\&    });
.Ve
.IP "\(bu" 4
optional parameter ref
.Sp
Optional notation of the ref answer.
.Sp
It is not a good idea to use the Object::Lazy::Ref module by default.
But there are situations, the lazy idea would run down the river
if I had not implemented this feature.
.Sp
.Vb 1
\&    use Object::Lazy::Ref; # overwrite CORE::GLOBAL::ref
\&
\&    $object = Object::Lazy\->new({
\&        ...
\&        ref => \*(AqRealClass\*(Aq,
\&    });
\&
\&    $boolean_true = ref $object eq \*(AqRealClass\*(Aq;
.Ve
.SS "method isa"
.IX Subsection "method isa"
If no isa parameter was given at method new, the object will build.
.PP
Otherwise the method isa checks by isa class method
or only the given parameters.
.PP
.Vb 1
\&    $boolean = $object\->isa(\*(AqRealClass\*(Aq);
.Ve
.PP
or
.PP
.Vb 1
\&    $boolean = $object\->isa(\*(AqBaseClassOfRealClass\*(Aq);
.Ve
.SS "method \s-1DOES\s0"
.IX Subsection "method DOES"
If no isa or \s-1DOES\s0 parameter was given at method new, the object will build.
.PP
Otherwise the method \s-1DOES\s0 checks by \s-1DOES\s0 class method
or only the given parameters isa and \s-1DOES.\s0
.PP
.Vb 1
\&    $boolean = $object\->DOES(\*(AqRole\*(Aq);
.Ve
.SS "method can"
.IX Subsection "method can"
The object will build. After that the can method checks the built object.
.PP
.Vb 1
\&    $coderef_or_undef = $object\->can(\*(Aqmethod\*(Aq);
.Ve
.SS "method \s-1VERSION\s0"
.IX Subsection "method VERSION"
If no \s-1VERSION\s0 or version_from parameter was given at method new,
the object will build.
.PP
\fI\s-1VERSION\s0 parameter set\fR
.IX Subsection "VERSION parameter set"
.PP
The given version will be returnd or checked.
.PP
.Vb 1
\&    $version = $object\->VERSION;
.Ve
.PP
or
.PP
.Vb 1
\&    $object\->VERSION($required_version);
.Ve
.PP
\fIversion_from parameter set\fR
.IX Subsection "version_from parameter set"
.PP
The version of the class in version_from will be returnd or checked.
This class should be used or required before.
Is that not possible use parameter \s-1VERSION\s0 instead.
.PP
.Vb 1
\&    $version = $object\->VERSION;
.Ve
.PP
or
.PP
.Vb 1
\&    $object\->VERSION($required_version);
.Ve
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
The constructor can confess at false parameters.
.PP
\&\s-1UNIVERSAL 1.04\s0 (Perl 5.10) required for method \s-1DOES.\s0
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
nothing
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
Carp
.PP
Try::Tiny
.PP
Object::Lazy::Validate
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
not known
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
\&\s-1UNIVERSAL\s0.pm 1.04 implements \s-1DOES\s0 first time.
This version is part of the Perl 5.10 distribution.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1UNIVERSAL\s0
.PP
Data::Lazy The scalar will be built at \f(CW\*(C`my $scalar = shift;\*(C'\fR at first sub call.
.PP
Scalar::Defer The scalar will be built at \f(CW\*(C`my $scalar = shift;\*(C'\fR at first sub call.
.PP
Class::LazyObject No, I don't write my own class/package.
.PP
Object::Realize::Later No, I don't write my own class/package.
.PP
Class::Cache There are lazy parameters too.
.PP
Object::Trampoline This is nearly the same idea.
.PP
Objects::Collection::Object Object created at call of method isa.
.SH "AUTHOR"
.IX Header "AUTHOR"
Steffen Winkler
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (c) 2007 \- 2020,
Steffen Winkler
\&\f(CW\*(C`<steffenw at cpan.org>\*(C'\fR.
All rights reserved.
.PP
This module is free software;
you can redistribute it and/or modify it
under the same terms as Perl itself.