NAME

MooX::Attributes::Shadow::Role - enumerate shadowable attributes in a contained class

VERSION

version 0.05

SYNOPSIS

  # in the contained class
  package Foo;
  use Moo;
  with 'MooX::Attributes::Shadow::Role';

  shadowable_attrs 'x', 'y';

  has x => ( is => 'ro' );
  has y => ( is => 'ro' );


  # in the container class

  package Bar;

  use Moo;
  use Foo;

  # create accessors with a prefix to avoid collisions; no need to
  # specify which ones
  Foo->shadow_attrs( fmt => sub { 'pfx_' . shift } );

  # create an attribute which holds the contained oject, and
  # delegate the shadowed accessors to it.
  has foo   => ( is => 'ro',
                 lazy => 1,
                 default => sub { Foo->new_from_attrs( shift ) },
                 handles => Foo->shadowed_attrs,
               );

DESCRIPTION

MooX::Attributes::Shadow::Role provides a means for a class to identify attributes which should be shadowed to classes which contain it. (See MooX::Attributes::Shadow for more on what this means). A class containing a class composed with this role need know nothing about the attributes which will be shadowed, and can use the class methods to integrate the shadowable attributes into their interface.

INTERFACE

Contained class functions

shadowable_attrs

  shadowable_attrs @attrs;

This is called by the contained class to identify which attributes are available for shadowing. It does not create them, it merely records them.

Subsequent calls will return the names of the attributes which may be shadowed as an array:

   Class->shadowable_attrs( qw[ a b c ] );
   @attrs = Class->shadowable_attrs;

Class methods for use by the Container Classes

shadow_attrs

   ContainedClass->shadow_attrs( %options );

This method creates read-only attributes shadowing the ContainedClass's shadowable attributes in the class which calls it.

It takes the following options:

fmt

This is a reference to a subroutine which should return a modified attribute name (e.g. to prevent attribute collisions). It is passed the attribute name as its first parameter.

instance

In the case where more than one instance of an object is contained, this (string) is used to identify an individual instance.

private

If true, the actual attribute name is mangled; the attribute initialization name is left untouched (see the init_arg option to the Moo has subroutine). This defaults to true.

shadowed_attrs

  $attrs = ContainedClass->( [$container,] \%options );

Return a hash of attributes shadowed into $container. If $container is provided it may be either a class name or an object. If it is not provided, the package name of the calling routine is used.

It takes the following options:

instance

In the case where more than one instance of an object is contained, this (string) is used to identify an individual instance.

The keys in the returned hash are the attribute initialization names (not the mangled ones) in the container class; the hash values are the attribute names in the contained class. This makes it easy to delegate accessors to the contained class:

  has foo   => ( is => 'ro',
                 lazy => 1,
                 default => sub { Foo->new( Foo->xtract_attrs( shift ) ) },
                 handles => Foo->shadowed_attrs,
               );

xtract_attrs

  %attrs = ContainedClass->xtract_attrs( $container_obj, \%options );

After the container class is instantiated, xtract_attrs is used to extract attributes for the contained object from the container object.

It takes the following options:

instance

In the case where more than one instance of an object is contained, this (string) is used to identify an individual instance.

new_from_attrs

  $obj = ContainedClass->new_from_attrs( $container_obj );
  $obj = ContainedClass->new_from_attrs( $container_obj, %attr );
  $obj = ContainedClass->new_from_attrs( $container_obj, \%options );
  $obj = ContainedClass->new_from_attrs( $container_obj, \%options, \%attr );
  $obj = ContainedClass->new_from_attrs( $container_obj, \%options,  %attr );

Create a new contained object from the attributes shadowed in the container object. Additional attributes and values may be passed.

It takes the following options:

instance

In the case where more than one instance of an object is contained, this (string) is used to identify an individual instance.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=MooX-Attributes-Shadow or by email to bug-MooX-Attributes-Shadow@rt.cpan.org.

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.

SOURCE

The development version is on github at https://github.com/djerius/moox-attributes-shadow and may be cloned from git://github.com/djerius/moox-attributes-shadow.git

SEE ALSO

Please see those modules/websites for more information related to this module.

• MooX::Attributes::Shadow

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018 by Smithsonian Astrophysical Observatory.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007