NAME

Object::Lazy - create objects late from non-owned (foreign) classes

VERSION

0.16

SYNOPSIS

    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;
    }

To combine this and a lazy use, write somthing like that:

    use Object::Lazy;

    my $foo = Object::Lazy->new(
        sub {
            # 3 lines instead of "use Foo 123"
            require Foo;
            Foo->import;
            Foo->VERSION('123');
            return Foo->new;
        },
    );

    # and so on

After a build object the scalar which hold the object will be updated too.

  $object->method;
  ^^^^^^^-------------- will update this scalar after a build

Read topic SUBROUTINES/METHODS to find the entended constructor and all the optional parameters.

EXAMPLE

Inside of this Distribution is a directory named example. Run this *.pl files.

DESCRIPTION

This module implements lazy evaluation and can create lazy objects from every class.

Creates a dummy object including a subroutine which knows how to build the real object.

Later, if a method of the object is called, the real object will be built.

Inherited methods from UNIVERSAL.pm are implemented and so overwritten. This are isa, DOES, can and VERSION.

SUBROUTINES/METHODS

method new

short constructor

    $object = Object::Lazy->new(
        sub {
            return RealClass->new(...);
        },
    );

extended constructor

    $object = Object::Lazy->new({
        build => sub {
            return RealClass->new(...);
        },
    });
  • optional parameter isa

    There are 3 ways to check the class or inheritance.

    If there is no parameter isa, the object must be built before.

    If the use RealClass; is outside of <build = sub {...}>> then the class method <RealClass-isa(...);>> checks the class or inheritance.

    Otherwise the isa parameter is a full notation of the class and possible of the inheritance.

        $object = Object::Lazy->new({
            ...
            isa => 'RealClass',
        });

    or

        $object = Object::Lazy->new({
            ...
            isa => [qw(RealClass BaseClassOfRealClass)],
        });
  • optional parameter DOES

    It is similar to parameter isa. But do not note the inheritance. Note the Rules here.

        $object = Object::Lazy->new({
            ...
            DOES => 'Role1',
        });

    or

        $object = Object::Lazy->new({
            ...
            DOES => [qw(Role1 Role2)],
        });
  • optional parameter VERSION

    For the VERSION method tell Object::Lazy which version shold be checked.

        $object = Object::Lazy->new({
            ...
            VERSION => '123',
        });

    or

        use version;
    
        $object = Object::Lazy->new({
            ...
            VERSION => qv('1.2.3'), # version object
        });
  • optional parameter version_from

    For the VERSION method tell Object::Lazy which class shold be version checked.

        $object = Object::Lazy->new({
            ...
            version_from => 'RealClass',
        });
  • optional parameter logger

    Optional notation of the logger code to show the build process.

        $object = Object::Lazy->new({
            ...
            logger => sub {
                my $at_stack = shift;
                print "RealClass $at_stack";
            },
        });
  • optional parameter ref

    Optional notation of the ref answer.

    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.

        use Object::Lazy::Ref; # overwrite CORE::GLOBAL::ref
    
        $object = Object::Lazy->new({
            ...
            ref => 'RealClass',
        });
    
        $boolean_true = ref $object eq 'RealClass';

method isa

If no isa parameter was given at method new, the object will build.

Otherwise the method isa checks by isa class method or only the given parameters.

    $boolean = $object->isa('RealClass');

or

    $boolean = $object->isa('BaseClassOfRealClass');

method DOES

If no isa or DOES parameter was given at method new, the object will build.

Otherwise the method DOES checks by DOES class method or only the given parameters isa and DOES.

    $boolean = $object->DOES('Role');

method can

The object will build. After that the can method checks the built object.

    $coderef_or_undef = $object->can('method');

method VERSION

If no VERSION or version_from parameter was given at method new, the object will build.

VERSION parameter set

The given version will be returnd or checked.

    $version = $object->VERSION;

or

    $object->VERSION($required_version);

version_from parameter set

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 VERSION instead.

    $version = $object->VERSION;

or

    $object->VERSION($required_version);

DIAGNOSTICS

The constructor can confess at false parameters.

UNIVERSAL 1.04 (Perl 5.10) required for method DOES.

CONFIGURATION AND ENVIRONMENT

nothing

DEPENDENCIES

Carp

Try::Tiny

Object::Lazy::Validate

INCOMPATIBILITIES

not known

BUGS AND LIMITATIONS

UNIVERSAL.pm 1.04 implements DOES first time. This version is part of the Perl 5.10 distribution.

SEE ALSO

UNIVERSAL

Data::Lazy The scalar will be built at my $scalar = shift; at first sub call.

Scalar::Defer The scalar will be built at my $scalar = shift; at first sub call.

Class::LazyObject No, I don't write my own class/package.

Object::Realize::Later No, I don't write my own class/package.

Class::Cache There are lazy parameters too.

Object::Trampoline This is nearly the same idea.

Objects::Collection::Object Object created at call of method isa.

AUTHOR

Steffen Winkler

LICENSE AND COPYRIGHT

Copyright (c) 2007 - 2020, Steffen Winkler <steffenw at cpan.org>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.