NAME

Bread::Board::LazyLoader - loads lazily Bread::Board containers from files

VERSION

version 0.14

SYNOPSIS

    use Bread::Board::LazyLoader qw(load_container);

    # having files defining Bread Board containers

    # ./ioc/Root.ioc
    # ./ioc/Database.ioc
    # ./ioc/Webapp/Rating.ioc

    # we can load them with

    my $root
        = load_container( root_dir => './ioc', filename_extension => '.ioc', );

    # then $root container is defined by file Root.ioc
    # $root->fetch('Database') is defined by file Database.ioc
    # $root->fetch('Webapp/Rating.ioc') is defined by

    # but all files except of Root.ioc are loaded lazily when the respective
    # container is needed (usually when a service from the container is
    # resolved by a dependency) 

DESCRIPTION

Bread::Board::LazyLoader loads a Bread::Board container from a directory (directories) with files defining the container.

The container returned can also loads lazily its sub containers from the same directories.

FUNCTIONS

All functions are imported on demand.

load_container(%params)

Loads the container. The parameters are:

root_dir

The directory (directories) to be traversed for container definition files. Either string or an arrayref of strings. Mandatory parameter.

filename_extension

The extension of files (without dot) which are searched for container definitions. Mandatory parameter.

container_name

The name of created container. Also the basename of the file which contains it. "Root" by default.

container_factory

An anonymous subroutine used to create "intermediate" containers for directories - the ones having no definition files. By default it is:

    sub {
        my ($name) = @_;
        return Bread::Board::Container->new(name => $name);
    }

load_container searches under supplied root directories for plain files with the extension. Found files found are used to build root container or its subcontainers. The position of container in the hierarchy of the containers is same as the relative path of the file (minus extension) under root directory.

The exception is the file Root.extension which defines the root container itself, not its subcontainer called Root.

The container is built from its first definition file (the files are ordered according their appropriate root in root_dir parameter).

Definition file for a container is a perl code file returning (its last expression is) an anonymous subroutine - a container builder.

The container builder is called like:

    my $container = $builder->($name, $next);

First argument to builder is a container name (the basename of the file found), the second an anonymous subroutine creating the container via next definition file (if any) or by calling the container factory.

The definition file may look like:

    use strict;
    use Bread::Board;

    sub {
        my $name = shift;
        return container $name => as {
                service psgi => (...);
        }
    };

Wwhen there is more than one root directory, the most specific should be mentioned first and their would look like:

    use strict;
    use Bread::Board;

    sub {
        my ($name, $next) = @_;

        my $c = $next->();
        return container $c => as {
            # modifying container specified by more generic files
                service psgi => (...);
        }
    };

The builder must return a Bread::Board container (an instance of Bread::Board::Container or its subclass) with name $name.

Every file is evaluated in a "sandbox", i.e. artificially created package, thus all imports and sub definitions in the file are private and not shared.

The root container is built immediately, the subcontainers (their files) are built lazily, typically when a service from them is needed.

AUTHOR

Roman Daniel <roman@daniel.cz>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Roman Daniel.

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

cpanm Bread::Board::LazyLoader

perl -MCPAN -e shell
install Bread::Board::LazyLoader