Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Moose::Manual::DelegatUser3Contributed Perl DocumeMoose::Manual::Delegation(3)

NAME
       Moose::Manual::Delegation - Attribute delegation

VERSION
       version 2.2013

WHAT IS	DELEGATION?
       Delegation is a feature that lets you create "proxy" methods that do
       nothing more than call some other method	on an attribute. This lets you
       simplify	a complex set of "has-a" relationships and present a single
       unified API from	one class.

       With delegation,	consumers of a class don't need	to know	about all the
       objects it contains, reducing the amount	of API they need to learn.

       Delegations are defined as a mapping between one	or more	methods
       provided	by the "real" class (the delegatee), and a set of
       corresponding methods in	the delegating class. The delegating class can
       re-use the method names provided	by the delegatee or provide its	own
       names.

       Delegation is also a great way to wrap an existing class, especially a
       non-Moose class or one that is somehow hard (or impossible) to
       subclass.

DEFINING A MAPPING
       Moose offers a number of	options	for defining a delegation's mapping,
       ranging from simple to complex.

       The simplest form is to simply specify a	list of	methods:

	 package Website;

	 use Moose;

	 has 'uri' => (
	     is	     =>	'ro',
	     isa     =>	'URI',
	     handles =>	[qw( host path )],
	 );

       Using an	arrayref tells Moose to	create methods in your class that
       match the method	names in the delegated class.

       With this definition, we	can call "$website->host" and it "just works".
       Under the hood, Moose will call "$website->uri->host" for you. Note
       that $website is	not automatically passed to the	"host" method; the
       invocant	is "$website->uri".

       We can also define a mapping as a hash reference. This allows you to
       rename methods as part of the mapping:

	 package Website;

	 use Moose;

	 has 'uri' => (
	     is	     =>	'ro',
	     isa     =>	'URI',
	     handles =>	{
		 hostname => 'host',
		 path	  => 'path',
	     },
	 );

       Using a hash tells Moose	to create method names (specified on the left)
       which invoke the	delegated class	methods	(specified on the right).

       In this example,	we've created a	"$website->hostname" method, rather
       than simply using "URI.pm"'s name, "host" in the	Website	class.

       These two mapping forms are the ones you	will use most often. The
       remaining methods are a bit more	complex.

	 has 'uri' => (
	     is	     =>	'ro',
	     isa     =>	'URI',
	     handles =>	qr/^(?:host|path|query.*)/,
	 );

       This is similar to the array version, except it uses the	regex to match
       against all the methods provided	by the delegatee. In order for this to
       work, you must provide an "isa" parameter for the attribute, and	it
       must be a class.	Moose uses this	to introspect the delegatee class and
       determine what methods it provides.

       You can use a role name as the value of "handles":

	 has 'uri' => (
	     is	     =>	'ro',
	     isa     =>	'URI',
	     handles =>	'HasURI',
	 );

       Moose will introspect the role to determine what	methods	it provides
       and create a name-for-name mapping for each of those methods.

       Finally,	you can	provide	a sub reference	to generate a mapping that
       behaves like the	hash example above. You	probably won't need this
       version often (if ever).	See the	Moose docs for more details on exactly
       how this	works.

NATIVE DELEGATION
       Native delegations allow	you to delegate	to standard Perl data
       structures as if	they were objects.

	 has 'queue' =>	(
	     traits  =>	['Array'],
	     isa     =>	'ArrayRef[Item]',
	     default =>	sub { [	] },
	     handles =>	{
		 add_item  => 'push',
		 next_item => 'shift',
	     },
	 )

       The "Array" trait in the	"traits" parameter tells Moose that you	would
       like to use the set of Array helpers. Moose will	then create "add_item"
       and "next_item" methods that "just work". Behind	the scenes "add_item"
       is something like

	 sub add_item {
	     my	($self,	@items)	= @_;

	     for my $item (@items) {
		 $Item_TC->validate($item);
	     }

	     push @{ $self->queue }, @items;
	 }

       For example, you	might use Array	helpers	to add "add_task" and
       "add_appointment" methods to a Calendar class:

	 has 'tasks' =>	(
	     traits => ['Array'],
	     isa => 'ArrayRef[Task]',
	     default =>	sub { [	] },
	     handles =>	{
		 add_task  => 'push',
		 next_task => 'shift',
	     },
	 );

	 has 'appointments' => (
	     traits  =>	['Array'],
	     isa => 'ArrayRef[Appointment]',
	     default =>	sub { [	] },
	     handles =>	{
		 add_appointment  => 'push',
		 next_appointment => 'shift',
	     },
	 );

       Which you would call as:

	 $calendar->add_task( $task_obj	);
	 $calendar->add_appointment( $appointment_obj );

       As mentioned above, each	trait provides a number	of methods which are
       summarized below. For more information about each of these provided
       methods see the documentation for that specific trait.

       Moose includes the following traits for native delegation.

       o   Array

	   The following methods are provided by the native Array trait:

	   count, is_empty, elements, get, pop,	push, shift, unshift, splice,
	   first, first_index, grep, map, reduce, sort,	sort_in_place,
	   shuffle, uniq, join,	set, delete, insert, clear, accessor,
	   natatime, shallow_clone

       o   Bool

	   The following methods are provided by the native Bool trait:

	   set,	unset, toggle, not

       o   Code

	   The following methods are provided by the native Code trait:

	   execute, execute_method

       o   Counter

	   The following methods are provided by the native Counter trait:

	   set,	inc, dec, reset

       o   Hash

	   The following methods are provided by the native Hash trait:

	   get,	set, delete, keys, exists, defined, values, kv,	elements,
	   clear, count, is_empty, accessor, shallow_clone

       o   Number

	   The following methods are provided by the native Number trait:

	   add,	sub, mul, div, mod, abs

       o   String

	   The following methods are provided by the native String trait:

	   inc,	append,	prepend, replace, match, chop, chomp, clear, length,
	   substr

CURRYING
       Currying	allows you to create a method with some	pre-set	parameters.
       You can create a	curried	delegation method:

	   package Spider;
	   use Moose;

	   has request => (
	       is      => 'ro'
	       isa     => 'HTTP::Request',
	       handles => {
		   set_user_agent => [ header => 'UserAgent' ],
	       },
	   )

       With this definition, calling "$spider->set_user_agent('MyClient')"
       will call "$spider->request->header('UserAgent',	'MyClient')" behind
       the scenes.

       Note that with currying,	the currying always starts with	the first
       parameter to a method ($_[0]). Any arguments you	pass to	the delegation
       come after the curried arguments.

MISSING	ATTRIBUTES
       It is perfectly valid to	delegate methods to an attribute which is not
       required	or can be undefined. When a delegated method is	called,	Moose
       will throw a runtime error if the attribute does	not contain an object.

AUTHORS
       o   Stevan Little <stevan.little@iinteractive.com>

       o   Dave	Rolsky <autarch@urth.org>

       o   Jesse Luehrs	<doy@tozt.net>

       o   Shawn M Moore <code@sartak.org>

       o   xxxx	x<section>xx'xx	(Yuval Kogman) <nothingmuch@woobling.org>

       o   Karen Etheridge <ether@cpan.org>

       o   Florian Ragwitz <rafl@debian.org>

       o   Hans	Dieter Pearcey <hdp@weftsoar.net>

       o   Chris Prather <chris@prather.org>

       o   Matt	S Trout	<mst@shadowcat.co.uk>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2006 by Infinity Interactive, Inc.

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

perl v5.32.0			  2020-07-21	  Moose::Manual::Delegation(3)

NAME | VERSION | WHAT IS DELEGATION? | DEFINING A MAPPING | NATIVE DELEGATION | CURRYING | MISSING ATTRIBUTES | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Moose::Manual::Delegation&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help