{ "content": [ { "type": "text", "text": "# Class::MOP::Attribute (perldoc)\n\n## NAME\n\nClass::MOP::Attribute - Attribute Meta Object\n\n## SYNOPSIS\n\nClass::MOP::Attribute->new(\nfoo => (\naccessor => 'foo', # dual purpose get/set accessor\npredicate => 'hasfoo', # predicate check for defined-ness\ninitarg => '-foo', # class->new will look for a -foo key\ndefault => 'BAR IS BAZ!' # if no -foo key is provided, use this\n)\n);\nClass::MOP::Attribute->new(\nbar => (\nreader => 'bar', # getter\nwriter => 'setbar', # setter\npredicate => 'hasbar', # predicate check for defined-ness\ninitarg => ':bar', # class->new will look for a :bar key\n# no default value means it is undef\n)\n);\n\n## DESCRIPTION\n\nThe Attribute Protocol is almost entirely an invention of \"Class::MOP\". Perl 5 does not have a\nconsistent notion of attributes. There are so many ways in which this is done, and very few (if\nany) are easily discoverable by this module.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS** (7 subsections)\n- **AUTHORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Class::MOP::Attribute", "section": "", "mode": "perldoc", "summary": "Class::MOP::Attribute - Attribute Meta Object", "synopsis": "Class::MOP::Attribute->new(\nfoo => (\naccessor => 'foo', # dual purpose get/set accessor\npredicate => 'hasfoo', # predicate check for defined-ness\ninitarg => '-foo', # class->new will look for a -foo key\ndefault => 'BAR IS BAZ!' # if no -foo key is provided, use this\n)\n);\nClass::MOP::Attribute->new(\nbar => (\nreader => 'bar', # getter\nwriter => 'setbar', # setter\npredicate => 'hasbar', # predicate check for defined-ness\ninitarg => ':bar', # class->new will look for a :bar key\n# no default value means it is undef\n)\n);", "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": "SYNOPSIS", "lines": 19, "subsections": [] }, { "name": "DESCRIPTION", "lines": 7, "subsections": [] }, { "name": "METHODS", "lines": 1, "subsections": [ { "name": "Creation", "lines": 187 }, { "name": "Informational", "lines": 57 }, { "name": "Informational predicates", "lines": 19 }, { "name": "Value management", "lines": 46 }, { "name": "Class association", "lines": 22 }, { "name": "Attribute Accessor generation", "lines": 29 }, { "name": "Introspection", "lines": 6 } ] }, { "name": "AUTHORS", "lines": 20, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "Class::MOP::Attribute - Attribute Meta Object\n", "subsections": [] }, "VERSION": { "content": "version 2.2200\n", "subsections": [] }, "SYNOPSIS": { "content": "Class::MOP::Attribute->new(\nfoo => (\naccessor => 'foo', # dual purpose get/set accessor\npredicate => 'hasfoo', # predicate check for defined-ness\ninitarg => '-foo', # class->new will look for a -foo key\ndefault => 'BAR IS BAZ!' # if no -foo key is provided, use this\n)\n);\n\nClass::MOP::Attribute->new(\nbar => (\nreader => 'bar', # getter\nwriter => 'setbar', # setter\npredicate => 'hasbar', # predicate check for defined-ness\ninitarg => ':bar', # class->new will look for a :bar key\n# no default value means it is undef\n)\n);\n", "subsections": [] }, "DESCRIPTION": { "content": "The Attribute Protocol is almost entirely an invention of \"Class::MOP\". Perl 5 does not have a\nconsistent notion of attributes. There are so many ways in which this is done, and very few (if\nany) are easily discoverable by this module.\n\nWith that said, this module attempts to inject some order into this chaos, by introducing a\nconsistent API which can be used to create object attributes.\n", "subsections": [] }, "METHODS": { "content": "", "subsections": [ { "name": "Creation", "content": "Class::MOP::Attribute->new($name, ?%options)\nAn attribute must (at the very least), have a $name. All other %options are added as\nkey-value pairs.\n\n* initarg\n\nThis is a string value representing the expected key in an initialization hash. For\ninstance, if we have an \"initarg\" value of \"-foo\", then the following code will\nJust Work.\n\nMyClass->meta->newobject( -foo => 'Hello There' );\n\nIf an initarg is not assigned, it will automatically use the attribute's name. If\n\"initarg\" is explicitly set to \"undef\", the attribute cannot be specified during\ninitialization.\n\n* builder\n\nThis provides the name of a method that will be called to initialize the attribute.\nThis method will be called on the object after it is constructed. It is expected to\nreturn a valid value for the attribute.\n\n* default\n\nThis can be used to provide an explicit default for initializing the attribute. If\nthe default you provide is a subroutine reference, then this reference will be\ncalled *as a method* on the object.\n\nIf the value is a simple scalar (string or number), then it can be just passed as\nis. However, if you wish to initialize it with a HASH or ARRAY ref, then you need to\nwrap that inside a subroutine reference:\n\nClass::MOP::Attribute->new(\n'foo' => (\ndefault => sub { [] },\n)\n);\n\n# or ...\n\nClass::MOP::Attribute->new(\n'foo' => (\ndefault => sub { {} },\n)\n);\n\nIf you wish to initialize an attribute with a subroutine reference itself, then you\nneed to wrap that in a subroutine as well:\n\nClass::MOP::Attribute->new(\n'foo' => (\ndefault => sub {\nsub { print \"Hello World\" }\n},\n)\n);\n\nAnd lastly, if the value of your attribute is dependent upon some other aspect of\nthe instance structure, then you can take advantage of the fact that when the\n\"default\" value is called as a method:\n\nClass::MOP::Attribute->new(\n'objectidentity' => (\ndefault => sub { Scalar::Util::refaddr( $[0] ) },\n)\n);\n\nNote that there is no guarantee that attributes are initialized in any particular\norder, so you cannot rely on the value of some other attribute when generating the\ndefault.\n\n* initializer\n\nThis option can be either a method name or a subroutine reference. This method will\nbe called when setting the attribute's value in the constructor. Unlike \"default\"\nand \"builder\", the initializer is only called when a value is provided to the\nconstructor. The initializer allows you to munge this value during object\nconstruction.\n\nThe initializer is called as a method with three arguments. The first is the value\nthat was passed to the constructor. The second is a subroutine reference that can be\ncalled to actually set the attribute's value, and the last is the associated\n\"Class::MOP::Attribute\" object.\n\nThis contrived example shows an initializer that sets the attribute to twice the\ngiven value.\n\nClass::MOP::Attribute->new(\n'doubled' => (\ninitializer => sub {\nmy ( $self, $value, $set, $attr ) = @;\n$set->( $value * 2 );\n},\n)\n);\n\nSince an initializer can be a method name, you can easily make attribute\ninitialization use the writer:\n\nClass::MOP::Attribute->new(\n'someattr' => (\nwriter => 'someattr',\ninitializer => 'someattr',\n)\n);\n\nYour writer (actually, a wrapper around the writer, using method modifications) will\nneed to examine @ and determine under which context it is being called:\n\naround 'someattr' => sub {\nmy $orig = shift;\nmy $self = shift;\n# $value is not defined if being called as a reader\n# $setter and $attr are only defined if being called as an initializer\nmy ($value, $setter, $attr) = @;\n\n# the reader behaves normally\nreturn $self->$orig if not @;\n\n# mutate $value as desired\n# $value = ($row) if $setter;\n\n# otherwise, call the real writer with the new value\n$self->$orig($row);\n};\n\nThe \"accessor\", \"reader\", \"writer\", \"predicate\" and \"clearer\" options all accept the same\nparameters. You can provide the name of the method, in which case an appropriate default\nmethod will be generated for you. Or instead you can also provide hash reference containing\nexactly one key (the method name) and one value. The value should be a subroutine reference,\nwhich will be installed as the method itself.\n\n* accessor\n\nAn \"accessor\" is a standard Perl-style read/write accessor. It will return the value\nof the attribute, and if a value is passed as an argument, it will assign that value\nto the attribute.\n\nNote that \"undef\" is a legitimate value, so this will work:\n\n$object->setsomething(undef);\n\n* reader\n\nThis is a basic read-only accessor. It returns the value of the attribute.\n\n* writer\n\nThis is a basic write accessor, it accepts a single argument, and assigns that value\nto the attribute.\n\nNote that \"undef\" is a legitimate value, so this will work:\n\n$object->setsomething(undef);\n\n* predicate\n\nThe predicate method returns a boolean indicating whether or not the attribute has\nbeen explicitly set.\n\nNote that the predicate returns true even if the attribute was set to a false value\n(0 or \"undef\").\n\n* clearer\n\nThis method will uninitialize the attribute. After an attribute is cleared, its\n\"predicate\" will return false.\n\n* definitioncontext\n\nMostly, this exists as a hook for the benefit of Moose.\n\nThis option should be a hash reference containing several keys which will be used\nwhen inlining the attribute's accessors. The keys should include \"line\", the line\nnumber where the attribute was created, and either \"file\" or \"description\".\n\nThis information will ultimately be used when eval'ing inlined accessor code so that\nerror messages report a useful line and file name.\n\n$attr->clone(%options)\nThis clones the attribute. Any options you provide will override the settings of the\noriginal attribute. You can change the name of the new attribute by passing a \"name\" key in\n%options.\n" }, { "name": "Informational", "content": "These are all basic read-only accessors for the values passed into the constructor.\n\n$attr->name\nReturns the attribute's name.\n\n$attr->accessor\n$attr->reader\n$attr->writer\n$attr->predicate\n$attr->clearer\nThe \"accessor\", \"reader\", \"writer\", \"predicate\", and \"clearer\" methods all return exactly\nwhat was passed to the constructor, so it can be either a string containing a method name,\nor a hash reference.\n\n$attr->initializer\nReturns the initializer as passed to the constructor, so this may be either a method name or\na subroutine reference.\n\n$attr->initarg\n$attr->isdefaultacoderef\n$attr->builder\n$attr->default($instance)\nThe $instance argument is optional. If you don't pass it, the return value for this method\nis exactly what was passed to the constructor, either a simple scalar or a subroutine\nreference.\n\nIf you *do* pass an $instance and the default is a subroutine reference, then the reference\nis called as a method on the $instance and the generated value is returned.\n\n$attr->slots\nReturn a list of slots required by the attribute. This is usually just one, the name of the\nattribute.\n\nA slot is the name of the hash key used to store the attribute in an object instance.\n\n$attr->getreadmethod\n$attr->getwritemethod\nReturns the name of a method suitable for reading or writing the value of the attribute in\nthe associated class.\n\nIf an attribute is read- or write-only, then these methods can return \"undef\" as\nappropriate.\n\n$attr->hasreadmethod\n$attr->haswritemethod\nThis returns a boolean indicating whether the attribute has a *named* read or write method.\n\n$attr->getreadmethodref\n$attr->getwritemethodref\nReturns the subroutine reference of a method suitable for reading or writing the attribute's\nvalue in the associated class. These methods always return a subroutine reference,\nregardless of whether or not the attribute is read- or write-only.\n\n$attr->insertionorder\nIf this attribute has been inserted into a class, this returns a zero based index regarding\nthe order of insertion.\n" }, { "name": "Informational predicates", "content": "These are all basic predicate methods for the values passed into \"new\".\n\n$attr->hasaccessor\n$attr->hasreader\n$attr->haswriter\n$attr->haspredicate\n$attr->hasclearer\n$attr->hasinitializer\n$attr->hasinitarg\nThis will be *false* if the \"initarg\" was set to \"undef\".\n\n$attr->hasdefault\nThis will be *false* if the \"default\" was set to \"undef\", since \"undef\" is the default\n\"default\" anyway.\n\n$attr->hasbuilder\n$attr->hasinsertionorder\nThis will be *false* if this attribute has not be inserted into a class\n" }, { "name": "Value management", "content": "These methods are basically \"back doors\" to the instance, and can be used to bypass the regular\naccessors, but still stay within the MOP.\n\nThese methods are not for general use, and should only be used if you really know what you are\ndoing.\n\n$attr->initializeinstanceslot($metainstance, $instance, $params)\nThis method is used internally to initialize the attribute's slot in the object $instance.\n\nThe $params is a hash reference of the values passed to the object constructor.\n\nIt's unlikely that you'll need to call this method yourself.\n\n$attr->setvalue($instance, $value)\nSets the value without going through the accessor. Note that this works even with read-only\nattributes.\n\n$attr->setrawvalue($instance, $value)\nSets the value with no side effects such as a trigger.\n\nThis doesn't actually apply to Class::MOP attributes, only to subclasses.\n\n$attr->setinitialvalue($instance, $value)\nSets the value without going through the accessor. This method is only called when the\ninstance is first being initialized.\n\n$attr->getvalue($instance)\nReturns the value without going through the accessor. Note that this works even with\nwrite-only accessors.\n\n$attr->getrawvalue($instance)\nReturns the value without any side effects such as lazy attributes.\n\nDoesn't actually apply to Class::MOP attributes, only to subclasses.\n\n$attr->hasvalue($instance)\nReturn a boolean indicating whether the attribute has been set in $instance. This how the\ndefault \"predicate\" method works.\n\n$attr->clearvalue($instance)\nThis will clear the attribute's value in $instance. This is what the default \"clearer\"\ncalls.\n\nNote that this works even if the attribute does not have any associated read, write or clear\nmethods.\n" }, { "name": "Class association", "content": "These methods allow you to manage the attributes association with the class that contains it.\nThese methods should not be used lightly, nor are they very magical, they are mostly used\ninternally and by metaclass instances.\n\n$attr->associatedclass\nThis returns the Class::MOP::Class with which this attribute is associated, if any.\n\n$attr->attachtoclass($metaclass)\nThis method stores a weakened reference to the $metaclass object internally.\n\nThis method does not remove the attribute from its old class, nor does it create any\naccessors in the new class.\n\nIt is probably best to use the Class::MOP::Class \"addattribute\" method instead.\n\n$attr->detachfromclass\nThis method removes the associate metaclass object from the attribute it has one.\n\nThis method does not remove the attribute itself from the class, or remove its accessors.\n\nIt is probably best to use the Class::MOP::Class \"removeattribute\" method instead.\n" }, { "name": "Attribute Accessor generation", "content": "$attr->accessormetaclass\nAccessor methods are generated using an accessor metaclass. By default, this is\nClass::MOP::Method::Accessor. This method returns the name of the accessor metaclass that\nthis attribute uses.\n\n$attr->associatemethod($method)\nThis associates a Class::MOP::Method object with the attribute. Typically, this is called\ninternally when an attribute generates its accessors.\n\n$attr->associatedmethods\nThis returns the list of methods which have been associated with the attribute.\n\n$attr->installaccessors\nThis method generates and installs code for the attribute's accessors. It is typically\ncalled from the Class::MOP::Class \"addattribute\" method.\n\n$attr->removeaccessors\nThis method removes all of the accessors associated with the attribute.\n\nThis does not currently remove methods from the list returned by \"associatedmethods\".\n\n$attr->inlineget\n$attr->inlineset\n$attr->inlinehas\n$attr->inlineclear\nThese methods return a code snippet suitable for inlining the relevant operation. They\nexpect strings containing variable names to be used in the inlining, like '$self' or\n'$[1]'.\n" }, { "name": "Introspection", "content": "Class::MOP::Attribute->meta\nThis will return a Class::MOP::Class instance for this class.\n\nIt should also be noted that Class::MOP will actually bootstrap this module by installing a\nnumber of attribute meta-objects into its metaclass.\n" } ] }, "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": [] } } } }