--- name: "Bread::Board::Container" section: "3pm" platform: "linux" package: "libbread-board-perl" version: "0.37-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Bread::Board::Container" --- # Bread::Board::Container(3pm) A container for services and other containers ## NAME Bread::Board::Container - A container for services and other containers ## VERSION version 0.37 ## SYNOPSIS ``` use Bread::Board; my $c = container MCP => as { container Users => as { service flynn => ...; service bradley => ...; service dillinger => ...; }; container Programs => as { container Rebels => as { service tron => ...; service yori => ...; alias flynn => '/Users/flynn'; }; # nested container container Slaves => as { service sark => ...; service crom => ...; }; }; }; # OR directly... my $guardians => Bread::Board::Container->new( name => 'Guardians' ); $guardians->add_service( Bread::Board::ConstructorInjection->new( name => 'dumont', ..., ) ); $c->get_sub_container('Programs')->add_sub_container($guardians); ``` ## DESCRIPTION This class implements the container for Bread::Board: a container is a thing that contains services and other containers. Each container and service has a name, so you end up with a tree of named nodes, just like files and directories in a filesystem: each item can be referenced using a path (see Bread::Board::Traversable for the details). ## ATTRIBUTES ### "name" Read/write string, required. Every container needs a name, by which it can be referenced when fetching it. ### "services" Hashref, constrained by `"Bread::Board::Container::ServiceList"`, mapping names to services directly contained in this container. Every service added here will have its `"parent"` set to this container. You can pass an arrayref of services instead of a hashref, the keys will be the names of the services. You should probably use "add\_service" and "get\_service" to manipulate this attribute, instead of modifying it directly. ### "sub\_containers" Hashref, constrained by `"Bread::Board::Container::SubContainerList"`, mapping names to containers directly contained in this container. Every container added here will have its `"parent"` set to this container. You can pass an arrayref of containers instead of a hashref, the keys will be the names of the containers. You should probably use "add\_sub\_container" and "get\_sub\_container" to manipulate this attribute, instead of modifying it directly. Containers added here can either be normal Bread::Board::Container or Bread::Board::Container::Parameterized. ## METHODS ### "add\_service" ``` $container->add_service($service); ``` Adds a service into the "services" map, using its name as the key. ### "get\_service" ``` my $service = $container->get_service($name); ``` Returns a service by name, or `"undef"` if there's no such service in the "services" map. ### "has\_service" ``` if ($container->has_service($name)) { ... } ``` Returns true if a service with the given name name exists in the "services" map, false otherwise. ### "has\_services" ``` if ($container->has_services) { ... } ``` Returns true if the "services" map contains any services, false if it's empty. ### "get\_service\_list" ``` my @service_names = $container->get_service_list(); ``` Returns the names off all services present in the "services" map. ### "add\_sub\_container" ``` $container->add_sub_container($container); ``` Adds a container into the "sub\_containers" map, using its name as the key. ### "get\_sub\_container" ``` my $container = $container->get_sub_container($name); ``` Returns a container by name, or `"undef"` if there's no such container in the "sub\_containers" map. ### "has\_sub\_container" ``` if ($container->has_sub_container($name)) { ... } ``` Returns true if a container with the given name name exists in the "sub\_containers" map, false otherwise. ### "has\_sub\_containers" ``` if ($container->has_sub_containers) { ... } ``` Returns true if the "sub\_containers" map contains any contains, false if it's empty. ### "get\_sub\_container\_list" ``` my @container_names = $container->get_sub_container_list(); ``` Returns the names off all containers present in the "sub\_containers" map. ### "add\_type\_mapping\_for" ``` $containers->add_type_mapping_for( $type_name, $service ); ``` Adds a mapping from a Moose type to a service: whenever we try to "resolve" that type, we'll use that service to instantiate it. ### "get\_type\_mapping\_for" ``` my $service = $container->get_type_mapping_for( $type_name ); ``` Returns the service to use to instantiate the given type name. Important: if a mapping for the exact type can't be found, but a mapping for a *subtype* of it can, you'll get the latter instead: ``` package Superclass { use Moose }; package Subclass { use Moose; exends 'Superclass' }; $c->add_type_mapping_for( 'Subclass', Bread::Board::ConstructorInjection->new(name=>'sc',class=>'Subclass'), ); my $o = $c->get_type_mapping_for('Superclass')->get; ``` `$o` is an instance of `"Subclass"`. If there are more than one sub-type mapped, you get a random one. This is probably a bad idea. ### "has\_type\_mapping\_for" ``` if ($container->has_type_mapping_for( $type_name )) { ... } ``` Returns true if we have a service defined to instantiate the given type name, but see the note on "get\_type\_mapping\_for" about subtype mapping. ### "resolve" ``` my $object = $container->resolve(service=>$service_name); my $object = $container->resolve(service=>$service_name,parameters=>\%p); ``` When given a service name, this method will fetch the service, then call `"get"` on it, optionally passing the given parameters. ``` my $object = $container->resolve(type=>$type); my $object = $container->resolve(type=>$type,parameters=>\%p); ``` When given a type name, this method will use "get\_type\_mapping\_for" to get the service, then call `"get"` on it, optionally passing the given parameters. If the instance is not of the expected type, the method will die. ## AUTHOR Stevan Little \ ## BUGS Please report any bugs or feature requests on the bugtracker website https://github.com/stevan/BreadBoard/issues When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. ## COPYRIGHT AND LICENSE This software is copyright (c) 2019, 2017, 2016, 2015, 2014, 2013, 2011, 2009 by Infinity Interactive. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.