{
"mode": "perldoc",
"parameter": "Moose::Spec::Role",
"section": "",
"url": "https://www.chedong.com/phpMan.php/perldoc/Moose%3A%3ASpec%3A%3ARole/json",
"generated": "2026-10-05T19:28:52Z",
"sections": {
"NAME": {
"content": "Moose::Spec::Role - Formal spec for Role behavior\n",
"subsections": []
},
"VERSION": {
"content": "version 2.2207\n",
"subsections": []
},
"DESCRIPTION": {
"content": "NOTE: This document is currently incomplete.\n",
"subsections": [
{
"name": "Components of a Role",
"content": "Excluded Roles\nA role can have a list of excluded roles, these are basically roles that they shouldn't be\ncomposed with. This is not just direct composition either, but also \"inherited\" composition.\n\nThis feature was taken from the Fortress language and is really of most use when building a\nlarge set of role \"building blocks\" some of which should never be used together.\n\nAttributes\nA roles attributes are similar to those of a class, except that they are not actually\napplied. This means that methods that are generated by an attributes accessor will not be\ngenerated in the role, but only created once the role is applied to a class.\n\nMethods\nThese are the methods defined within the role. Simple as that.\n\nRequired Methods\nA role can require a consuming class (or role) to provide a given method. Failure to do so\nfor classes is a fatal error, while for roles it simply passes on the method requirement to\nthe consuming role.\n\nRequired Attributes\nJust as a role can require methods, it can also require attributes. The requirement\nfulfilling attribute must implement at least as much as is required. That means, for\ninstance, that if the role requires that the attribute be read-only, then it must at least\nhave a reader and can also have a writer. It means that if the role requires that the\nattribute be an ArrayRef, then it must either be an ArrayRef or a subtype of an ArrayRef.\n\nOverridden Methods\nThe \"override\" and \"super\" keywords are allowed in roles, but their behavior is different\nfrom that of its class counterparts. The \"super\" in a class refers directly to that class's\nsuperclass, while the \"super\" in a role is deferred and only has meaning once the role is\ncomposed into a class. Once that composition occurs, \"super\" then refers to that class's\nsuperclass.\n\nIt is key to remember that roles do not have hierarchy, so they can never have a *super*\nrole.\n\nMethod Modifiers\nThese are the \"before\", \"around\" and \"after\" modifiers provided in Moose classes. The\ndifference here is that the modifiers are not actually applied until the role is composed\ninto a class (this is just like attributes and the \"override\" keyword).\n"
},
{
"name": "Role Composition",
"content": "Composing into a Class\nExcluded Roles\nRequired Methods\nRequired Attributes\nAttributes\nMethods\nOverridden methods\nMethod Modifiers (before, around, after)\n\nComposing into a Instance\nComposing into a Role\nExcluded Roles\nRequired Methods\nRequired Attributes\nAttributes\nMethods\nOverridden methods\nMethod Modifiers (before, around, after)\n\nRole Summation\nWhen multiple roles are added to another role (using the \"with @roles\" keyword) the roles are\ncomposed symmetrically. The product of the composition is a composite role\n(Moose::Meta::Role::Composite).\n\nExcluded Roles\nRequired Methods\nRequired Attributes\nAttributes\nAttributes with the same name will conflict and are considered a unrecoverable error. No\nother aspect of the attribute is examined, it is enough that just the attribute names\nconflict.\n\nThe reason for such early and harsh conflicts with attributes is because there is so much\nroom for variance between two attributes that the problem quickly explodes and rules get\nvery complex. It is my opinion that this complexity is not worth the trouble.\n\nMethods\nMethods with the same name will conflict, but no error is thrown, instead the method name is\nadded to the list of *required* methods for the new composite role.\n\nTo look at this in terms of set theory, each role can be said to have a set of methods. The\nsymmetric difference of these two sets is the new set of methods for the composite role,\nwhile the intersection of these two sets are the conflicts. This can be illustrated like so:\n\nRole A has method set { a, b, c }\nRole B has method set { c, d, e }\n\nThe composite role (A,B) has\nmethod set { a, b, d, e }\nconflict set { c }\n\nOverridden methods\nAn overridden method can conflict in one of two ways.\n\nThe first way is with another overridden method of the same name, and this is considered an\nunrecoverable error. This is an obvious error since you cannot override a method twice in\nthe same class.\n\nThe second way for conflict is for an overridden method and a regular method to have the\nsame name. This is also an unrecoverable error since there is no way to combine these two,\nnor is it okay for both items to be composed into a single class at some point.\n\nThe use of override in roles can be tricky, but if used carefully they can be a very\npowerful tool.\n\nMethod Modifiers (before, around, after)\nMethod modifiers are the only place where the ordering of role composition matters. This is\ndue to the nature of method modifiers themselves.\n\nSince a method can have multiple method modifiers, these are just collected in order to be\nlater applied to the class in that same order.\n\nIn general, great care should be taken in using method modifiers in roles. The order\nsensitivity can possibly lead to subtle and difficult to find bugs if they are overused. As\nwith all good things in life, moderation is the key.\n\nComposition Edge Cases\nThis is a just a set of complex edge cases which can easily get confused. This attempts to\nclarify those cases and provide an explanation of what is going on in them.\n\nRole Method Overriding\nMany people want to \"override\" methods in roles they are consuming. This works fine for\nclasses, since the local class method is favored over the role method. However in roles it\nis trickier, this is because conflicts result in neither method being chosen and the method\nbeing \"required\" instead.\n\nHere is an example of this (incorrect) type of overriding.\n\npackage Role::Foo;\nuse Moose::Role;\n\nsub foo { ... }\n\npackage Role::FooBar;\nuse Moose::Role;\n\nwith 'Role::Foo';\n\nsub foo { ... }\nsub bar { ... }\n\nHere the \"foo\" methods conflict and the Role::FooBar now requires a class or role consuming\nit to implement \"foo\". This is very often not what the user wants.\n\nNow here is an example of the (correct) type of overriding, only it is not overriding at\nall, as is explained in the text below.\n\npackage Role::Foo;\nuse Moose::Role;\n\nsub foo { ... }\n\npackage Role::Bar;\nuse Moose::Role;\n\nsub foo { ... }\nsub bar { ... }\n\npackage Role::FooBar;\nuse Moose::Role;\n\nwith 'Role::Foo', 'Role::Bar';\n\nsub foo { ... }\n\nThis works because the combination of Role::Foo and Role::Bar produce a conflict with the\n\"foo\" method. This conflict results in the composite role (that was created by the\ncombination of Role::Foo and Role::Bar using the *with* keyword) having a method requirement\nof \"foo\". The Role::FooBar then fulfills this requirement.\n\nIt is important to note that Role::FooBar is simply fulfilling the required \"foo\" method,\nand NOT overriding \"foo\". This is an important distinction to make.\n\nNow here is another example of a (correct) type of overriding, this time using the\n*excludes* option.\n\npackage Role::Foo;\nuse Moose::Role;\n\nsub foo { ... }\n\npackage Role::FooBar;\nuse Moose::Role;\n\nwith 'Role::Foo' => { -excludes => 'foo' };\n\nsub foo { ... }\nsub bar { ... }\n\nBy specifically excluding the \"foo\" method during composition, we allow Role::FooBar to\ndefine its own version of \"foo\".\n"
}
]
},
"SEE ALSO": {
"content": "Traits\nRoles are based on Traits, which originated in the Smalltalk community.\n\n\nThis is the main site for the original Traits papers.\n\nClass::Trait\nI created this implementation of traits several years ago, after reading the papers\nlinked above. (This module is now maintained by Ovid and I am no longer involved with\nit).\n\nRoles\nSince they are relatively new, and the Moose implementation is probably the most mature out\nthere, roles don't have much to link to. However, here is some bits worth looking at (mostly\nrelated to Perl 6)\n\n\nThis is chromatic's take on roles, which is worth reading since he was/is one of the big\nproponents of them.\n\n\nThis is Synopsis 12, which is all about the Perl 6 Object System. Which, of course,\nincludes roles.\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::Spec::Role - Formal spec for Role behavior",
"flags": [],
"examples": [],
"see_also": []
}