{ "content": [ { "type": "text", "text": "# Moose::Meta::Attribute (perldoc)\n\n## NAME\n\nMoose::Meta::Attribute - The Moose attribute metaclass\n\n## DESCRIPTION\n\nThis class is a subclass of Class::MOP::Attribute that provides additional Moose-specific\nfunctionality.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **DESCRIPTION**\n- **INHERITANCE**\n- **METHODS** (4 subsections)\n- **BUGS**\n- **AUTHORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Moose::Meta::Attribute", "section": "", "mode": "perldoc", "summary": "Moose::Meta::Attribute - The Moose attribute metaclass", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 7, "subsections": [] }, { "name": "INHERITANCE", "lines": 2, "subsections": [] }, { "name": "METHODS", "lines": 3, "subsections": [ { "name": "Creation", "lines": 135 }, { "name": "Value management", "lines": 25 }, { "name": "Attribute Accessor generation", "lines": 27 }, { "name": "Additional Moose features", "lines": 93 } ] }, { "name": "BUGS", "lines": 2, "subsections": [] }, { "name": "AUTHORS", "lines": 20, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "Moose::Meta::Attribute - The Moose attribute metaclass\n", "subsections": [] }, "VERSION": { "content": "version 2.2200\n", "subsections": [] }, "DESCRIPTION": { "content": "This class is a subclass of Class::MOP::Attribute that provides additional Moose-specific\nfunctionality.\n\nTo really understand this class, you will need to start with the Class::MOP::Attribute\ndocumentation. This class can be understood as a set of additional features on top of the basic\nfeature provided by that parent class.\n", "subsections": [] }, "INHERITANCE": { "content": "\"Moose::Meta::Attribute\" is a subclass of Class::MOP::Attribute.\n", "subsections": [] }, "METHODS": { "content": "Many of the documented below override methods in Class::MOP::Attribute and add Moose specific\nfeatures.\n", "subsections": [ { "name": "Creation", "content": "Moose::Meta::Attribute->new($name, %options)\nThis method overrides the Class::MOP::Attribute constructor.\n\nMany of the options below are described in more detail in the Moose::Manual::Attributes\ndocument.\n\nIt adds the following options to the constructor:\n\n* is => 'ro', 'rw', 'bare'\n\nThis provides a shorthand for specifying the \"reader\", \"writer\", or \"accessor\"\nnames. If the attribute is read-only ('ro') then it will have a \"reader\" method with\nthe same attribute as the name.\n\nIf it is read-write ('rw') then it will have an \"accessor\" method with the same\nname. If you provide an explicit \"writer\" for a read-write attribute, then you will\nhave a \"reader\" with the same name as the attribute, and a \"writer\" with the name\nyou provided.\n\nUse 'bare' when you are deliberately not installing any methods (accessor, reader,\netc.) associated with this attribute; otherwise, Moose will issue a warning when\nthis attribute is added to a metaclass.\n\n* isa => $type\n\nThis option accepts a type. The type can be a string, which should be a type name.\nIf the type name is unknown, it is assumed to be a class name.\n\nThis option can also accept a Moose::Meta::TypeConstraint object.\n\nIf you *also* provide a \"does\" option, then your \"isa\" option must be a class name,\nand that class must do the role specified with \"does\".\n\n* does => $role\n\nThis is short-hand for saying that the attribute's type must be an object which does\nthe named role.\n\n* coerce => $bool\n\nThis option is only valid for objects with a type constraint (\"isa\") that defined a\ncoercion. If this is true, then coercions will be applied whenever this attribute is\nset.\n\nYou cannot make both this and the \"weakref\" option true.\n\n* trigger => $sub\n\nThis option accepts a subroutine reference, which will be called after the attribute\nis set.\n\n* required => $bool\n\nAn attribute which is required must be provided to the constructor. An attribute\nwhich is required can also have a \"default\" or \"builder\", which will satisfy its\nrequired-ness.\n\nA required attribute must have a \"default\", \"builder\" or a non-\"undef\" \"initarg\"\n\n* lazy => $bool\n\nA lazy attribute must have a \"default\" or \"builder\". When an attribute is lazy, the\ndefault value will not be calculated until the attribute is read.\n\n* weakref => $bool\n\nIf this is true, the attribute's value will be stored as a weak reference.\n\n* documentation\n\nAn arbitrary string that can be retrieved later by calling \"$attr->documentation\".\n\n* autoderef => $bool\n\nNote that in cases where you want this feature you are often better served by using\na Moose::Meta::Attribute::Native trait instead.\n\nIf this is true, then the reader will dereference the value when it is called. The\nattribute must have a type constraint which defines the attribute as an array or\nhash reference.\n\n* lazybuild => $bool\n\nNote that use of this feature is strongly discouraged. Some documentation used to\nencourage use of this feature as a best practice, but we have changed our minds.\n\nSetting this to true makes the attribute lazy and provides a number of default\nmethods.\n\nhas 'size' => (\nis => 'ro',\nlazybuild => 1,\n);\n\nis equivalent to this:\n\nhas 'size' => (\nis => 'ro',\nlazy => 1,\nbuilder => 'buildsize',\nclearer => 'clearsize',\npredicate => 'hassize',\n);\n\nIf your attribute name starts with an underscore (\"\"), then the clearer and\npredicate will as well:\n\nhas 'size' => (\nis => 'ro',\nlazybuild => 1,\n);\n\nbecomes:\n\nhas 'size' => (\nis => 'ro',\nlazy => 1,\nbuilder => 'buildsize',\nclearer => 'clearsize',\npredicate => 'hassize',\n);\n\nNote the doubled underscore in the builder name. Internally, Moose simply prepends\nthe attribute name with \"build\" to come up with the builder name.\n\n* roleattribute => $roleattribute\n\nIf provided, this should be a Moose::Meta::Role::Attribute object.\n\n$attr->clone(%options)\nThis creates a new attribute based on attribute being cloned. You must supply a \"name\"\noption to provide a new name for the attribute.\n\nThe %options can only specify options handled by Class::MOP::Attribute.\n" }, { "name": "Value management", "content": "$attr->initializeinstanceslot($metainstance, $instance, $params)\nThis method is used internally to initialize the attribute's slot in the object $instance.\n\nThis overrides the Class::MOP::Attribute method to handle lazy attributes, weak references,\nand type constraints.\n\ngetvalue\nsetvalue\neval { $point->meta->getattribute('x')->setvalue($point, 'forty-two') };\nif($@) {\nprint \"Oops: $@\\n\";\n}\n\n*Attribute (x) does not pass the type constraint (Int) with 'forty-two'*\n\nBefore setting the value, a check is made on the type constraint of the attribute, if it has\none, to see if the value passes it. If the value fails to pass, the set operation dies.\n\nAny coercion to convert values is done before checking the type constraint.\n\nTo check a value against a type constraint before setting it, fetch the attribute instance\nusing \"findattributebyname\" in Class::MOP::Class, fetch the typeconstraint from the\nattribute using \"typeconstraint\" in Moose::Meta::Attribute and call \"check\" in\nMoose::Meta::TypeConstraint. See Moose::Cookbook::Basics::CompanySubtypes for an example.\n" }, { "name": "Attribute Accessor generation", "content": "$attr->installaccessors\nThis method overrides the parent to also install delegation methods.\n\nIf, after installing all methods, the attribute object has no associated methods, it throws\nan error unless \"is => 'bare'\" was passed to the attribute constructor. (Trying to add an\nattribute that has no associated methods is almost always an error.)\n\n$attr->removeaccessors\nThis method overrides the parent to also remove delegation methods.\n\n$attr->inlineset($instancevar, $valuevar)\nThis method return a code snippet suitable for inlining the relevant operation. It expect\nstrings containing variable names to be used in the inlining, like '$self' or '$[1]'.\n\n$attr->installdelegation\nThis method adds its delegation methods to the attribute's associated class, if it has any\nto add.\n\n$attr->removedelegation\nThis method remove its delegation methods from the attribute's associated class.\n\n$attr->accessormetaclass\nReturns the accessor metaclass name, which defaults to Moose::Meta::Method::Accessor.\n\n$attr->delegationmetaclass\nReturns the delegation metaclass name, which defaults to Moose::Meta::Method::Delegation.\n" }, { "name": "Additional Moose features", "content": "These methods are not found in the superclass. They support features provided by Moose.\n\n$attr->does($role)\nThis indicates whether the *attribute itself* does the given role. The role can be given as\na full class name, or as a resolvable trait name.\n\nNote that this checks the attribute itself, not its type constraint, so it is checking the\nattribute's metaclass and any traits applied to the attribute.\n\nMoose::Meta::Class->interpolateclassandnew($name, %options)\nThis is an alternate constructor that handles the \"metaclass\" and \"traits\" options.\n\nEffectively, this method is a factory that finds or creates the appropriate class for the\ngiven \"metaclass\" and/or \"traits\".\n\nOnce it has the appropriate class, it will call \"$class->new($name, %options)\" on that\nclass.\n\n$attr->cloneandinheritoptions(%options)\nThis method supports the \"has '+foo'\" feature. It does various bits of processing on the\nsupplied %options before ultimately calling the \"clone\" method.\n\nOne of its main tasks is to make sure that the %options provided does not include the\noptions returned by the \"illegaloptionsforinheritance\" method.\n\n$attr->illegaloptionsforinheritance\nThis returns a blacklist of options that can not be overridden in a subclass's attribute\ndefinition.\n\nThis exists to allow a custom metaclass to change or add to the list of options which can\nnot be changed.\n\n$attr->typeconstraint\nReturns the Moose::Meta::TypeConstraint object for this attribute, if it has one.\n\n$attr->hastypeconstraint\nReturns true if this attribute has a type constraint.\n\n$attr->verifyagainsttypeconstraint($value)\nGiven a value, this method returns true if the value is valid for the attribute's type\nconstraint. If the value is not valid, it throws an error.\n\n$attr->handles\nThis returns the value of the \"handles\" option passed to the constructor.\n\n$attr->hashandles\nReturns true if this attribute performs delegation.\n\n$attr->isweakref\nReturns true if this attribute stores its value as a weak reference.\n\n$attr->isrequired\nReturns true if this attribute is required to have a value.\n\n$attr->islazy\nReturns true if this attribute is lazy.\n\n$attr->islazybuild\nReturns true if the \"lazybuild\" option was true when passed to the constructor.\n\n$attr->shouldcoerce\nReturns true if the \"coerce\" option passed to the constructor was true.\n\n$attr->shouldautoderef\nReturns true if the \"autoderef\" option passed to the constructor was true.\n\n$attr->trigger\nThis is the subroutine reference that was in the \"trigger\" option passed to the constructor,\nif any.\n\n$attr->hastrigger\nReturns true if this attribute has a trigger set.\n\n$attr->documentation\nReturns the value that was in the \"documentation\" option passed to the constructor, if any.\n\n$attr->hasdocumentation\nReturns true if this attribute has any documentation.\n\n$attr->roleattribute\nReturns the Moose::Meta::Role::Attribute object from which this attribute was created, if\nany. This may return \"undef\".\n\n$attr->hasroleattribute\nReturns true if this attribute has an associated role attribute.\n\n$attr->appliedtraits\nThis returns an array reference of all the traits which were applied to this attribute. If\nnone were applied, this returns \"undef\".\n\n$attr->hasappliedtraits\nReturns true if this attribute has any traits applied.\n" } ] }, "BUGS": { "content": "See \"BUGS\" in Moose for details on reporting bugs.\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": [] } } } }