{ "mode": "perldoc", "parameter": "Moose::Manual::Delegation", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/Moose%3A%3AManual%3A%3ADelegation/json", "generated": "2026-06-16T03:40:14Z", "sections": { "NAME": { "content": "Moose::Manual::Delegation - Attribute delegation\n", "subsections": [] }, "VERSION": { "content": "version 2.2200\n\nWHAT IS DELEGATION?\nDelegation is a feature that lets you create \"proxy\" methods that do nothing more than call some\nother method on an attribute. This lets you simplify a complex set of \"has-a\" relationships and\npresent a single unified API from one class.\n\nWith delegation, consumers of a class don't need to know about all the objects it contains,\nreducing the amount of API they need to learn.\n\nDelegations are defined as a mapping between one or more methods provided by the \"real\" class\n(the delegatee), and a set of corresponding methods in the delegating class. The delegating\nclass can re-use the method names provided by the delegatee or provide its own names.\n\nDelegation is also a great way to wrap an existing class, especially a non-Moose class or one\nthat is somehow hard (or impossible) to subclass.\n", "subsections": [] }, "DEFINING A MAPPING": { "content": "Moose offers a number of options for defining a delegation's mapping, ranging from simple to\ncomplex.\n\nThe simplest form is to simply specify a list of methods:\n\npackage Website;\n\nuse Moose;\n\nhas 'uri' => (\nis => 'ro',\nisa => 'URI',\nhandles => [qw( host path )],\n);\n\nUsing an arrayref tells Moose to create methods in your class that match the method names in the\ndelegated class.\n\nWith this definition, we can call \"$website->host\" and it \"just works\". Under the hood, Moose\nwill call \"$website->uri->host\" for you. Note that $website is *not* automatically passed to the\n\"host\" method; the invocant is \"$website->uri\".\n\nWe can also define a mapping as a hash reference. This allows you to rename methods as part of\nthe mapping:\n\npackage Website;\n\nuse Moose;\n\nhas 'uri' => (\nis => 'ro',\nisa => 'URI',\nhandles => {\nhostname => 'host',\npath => 'path',\n},\n);\n\nUsing a hash tells Moose to create method names (specified on the left) which invoke the\ndelegated class methods (specified on the right).\n\nIn this example, we've created a \"$website->hostname\" method, rather than simply using\n\"URI.pm\"'s name, \"host\" in the Website class.\n\nThese two mapping forms are the ones you will use most often. The remaining methods are a bit\nmore complex.\n\nhas 'uri' => (\nis => 'ro',\nisa => 'URI',\nhandles => qr/^(?:host|path|query.*)/,\n);\n\nThis is similar to the array version, except it uses the regex to match against all the methods\nprovided by the delegatee. In order for this to work, you must provide an \"isa\" parameter for\nthe attribute, and it must be a class. Moose uses this to introspect the delegatee class and\ndetermine what methods it provides.\n\nYou can use a role name as the value of \"handles\":\n\nhas 'uri' => (\nis => 'ro',\nisa => 'URI',\nhandles => 'HasURI',\n);\n\nMoose will introspect the role to determine what methods it provides and create a name-for-name\nmapping for each of those methods.\n\nFinally, you can provide a sub reference to *generate* a mapping that behaves like the hash\nexample above. You probably won't need this version often (if ever). See the Moose docs for more\ndetails on exactly how this works.\n", "subsections": [] }, "NATIVE DELEGATION": { "content": "Native delegations allow you to delegate to standard Perl data structures as if they were\nobjects.\n\nhas 'queue' => (\ntraits => ['Array'],\nisa => 'ArrayRef[Item]',\ndefault => sub { [ ] },\nhandles => {\nadditem => 'push',\nnextitem => 'shift',\n},\n)\n\nThe \"Array\" trait in the \"traits\" parameter tells Moose that you would like to use the set of\nArray helpers. Moose will then create \"additem\" and \"nextitem\" methods that \"just work\".\nBehind the scenes \"additem\" is something like\n\nsub additem {\nmy ($self, @items) = @;\n\nfor my $item (@items) {\n$ItemTC->validate($item);\n}\n\npush @{ $self->queue }, @items;\n}\n\nFor example, you might use Array helpers to add \"addtask\" and \"addappointment\" methods to a\nCalendar class:\n\nhas 'tasks' => (\ntraits => ['Array'],\nisa => 'ArrayRef[Task]',\ndefault => sub { [ ] },\nhandles => {\naddtask => 'push',\nnexttask => 'shift',\n},\n);\n\nhas 'appointments' => (\ntraits => ['Array'],\nisa => 'ArrayRef[Appointment]',\ndefault => sub { [ ] },\nhandles => {\naddappointment => 'push',\nnextappointment => 'shift',\n},\n);\n\nWhich you would call as:\n\n$calendar->addtask( $taskobj );\n$calendar->addappointment( $appointmentobj );\n\nAs mentioned above, each trait provides a number of methods which are summarized below. For more\ninformation about each of these provided methods see the documentation for that specific trait.\n\nMoose includes the following traits for native delegation.\n\n* Array\n\nThe following methods are provided by the native Array trait:\n\ncount, isempty, elements, get, pop, push, shift, unshift, splice, first, firstindex, grep,\nmap, reduce, sort, sortinplace, shuffle, uniq, join, set, delete, insert, clear, accessor,\nnatatime, shallowclone\n\n* Bool\n\nThe following methods are provided by the native Bool trait:\n\nset, unset, toggle, not\n\n* Code\n\nThe following methods are provided by the native Code trait:\n\nexecute, executemethod\n\n* Counter\n\nThe following methods are provided by the native Counter trait:\n\nset, inc, dec, reset\n\n* Hash\n\nThe following methods are provided by the native Hash trait:\n\nget, set, delete, keys, exists, defined, values, kv, elements, clear, count, isempty,\naccessor, shallowclone\n\n* Number\n\nThe following methods are provided by the native Number trait:\n\nadd, sub, mul, div, mod, abs\n\n* String\n\nThe following methods are provided by the native String trait:\n\ninc, append, prepend, replace, match, chop, chomp, clear, length, substr\n", "subsections": [] }, "CURRYING": { "content": "Currying allows you to create a method with some pre-set parameters. You can create a curried\ndelegation method:\n\npackage Spider;\nuse Moose;\n\nhas request => (\nis => 'ro'\nisa => 'HTTP::Request',\nhandles => {\nsetuseragent => [ header => 'UserAgent' ],\n},\n)\n\nWith this definition, calling \"$spider->setuseragent('MyClient')\" will call\n\"$spider->request->header('UserAgent', 'MyClient')\" behind the scenes.\n\nNote that with currying, the currying always starts with the first parameter to a method\n($[0]). Any arguments you pass to the delegation come after the curried arguments.\n", "subsections": [] }, "MISSING ATTRIBUTES": { "content": "It is perfectly valid to delegate methods to an attribute which is not required or can be\nundefined. When a delegated method is called, Moose will throw a runtime error if the attribute\ndoes not contain an object.\n", "subsections": [] }, "AUTHORS": { "content": "* Stevan Little \n\n* Dave Rolsky \n\n* Jesse Luehrs \n\n* Shawn M Moore \n\n* יובל קוג'מן (Yuval Kogman) \n\n* Karen Etheridge \n\n* Florian Ragwitz \n\n* Hans Dieter Pearcey \n\n* Chris Prather \n\n* Matt S Trout \n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "This software is copyright (c) 2006 by Infinity Interactive, Inc.\n\nThis is free software; you can redistribute it and/or modify it under the same terms as the Perl\n5 programming language system itself.\n", "subsections": [] } }, "summary": "Moose::Manual::Delegation - Attribute delegation", "flags": [], "examples": [], "see_also": [] }