{ "content": [ { "type": "text", "text": "# Moose::Manual::FAQ (perldoc)\n\n## NAME\n\nMoose::Manual::FAQ - Frequently asked questions about Moose\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **FREQUENTLY ASKED QUESTIONS** (7 subsections)\n- **AUTHORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Moose::Manual::FAQ", "section": "", "mode": "perldoc", "summary": "Moose::Manual::FAQ - Frequently asked questions about Moose", "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": "FREQUENTLY ASKED QUESTIONS", "lines": 1, "subsections": [ { "name": "Module Stability", "lines": 32 }, { "name": "Constructors", "lines": 33 }, { "name": "Accessors", "lines": 74 }, { "name": "Method Modifiers", "lines": 52 }, { "name": "Type Constraints", "lines": 32 }, { "name": "Roles", "lines": 75 }, { "name": "Moose and Subroutine Attributes", "lines": 12 } ] }, { "name": "AUTHORS", "lines": 20, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "Moose::Manual::FAQ - Frequently asked questions about Moose\n", "subsections": [] }, "VERSION": { "content": "version 2.2200\n", "subsections": [] }, "FREQUENTLY ASKED QUESTIONS": { "content": "", "subsections": [ { "name": "Module Stability", "content": "Is Moose \"production ready\"?\nYes! Many sites with household names are using Moose to build high-traffic services. Countless\nothers are using Moose in production. See\n for a partial list.\n\nAs of this writing, Moose is a dependency of several hundred CPAN modules.\n\n\nIs Moose's API stable?\nYes. The sugary API, the one 95% of users will interact with, is very stable. Any changes will\nbe 100% backwards compatible.\n\nThe meta API is less set in stone. We reserve the right to tweak parts of it to improve\nefficiency or consistency. This will not be done lightly. We do perform deprecation cycles. We\n*really* do not like making ourselves look bad by breaking your code. Submitting test cases is\nthe best way to ensure that your code is not inadvertently broken by refactoring.\n\nI heard Moose is slow, is this true?\nAgain, this one is tricky, so Yes *and* No.\n\nFirstly, *nothing* in life is free, and some Moose features do cost more than others. It is also\nthe policy of Moose to only charge you for the features you use, and to do our absolute best to\nnot place any extra burdens on the execution of your code for features you are not using. Of\ncourse using Moose itself does involve some overhead, but it is mostly compile time. At this\npoint we do have some options available for getting the speed you need.\n\nCurrently we provide the option of making your classes immutable as a means of boosting speed.\nThis will mean a slightly larger compile time cost, but the runtime speed increase (especially\nin object construction) is pretty significant. This can be done with the following code:\n\nMyClass->meta->makeimmutable();\n" }, { "name": "Constructors", "content": "How do I write custom constructors with Moose?\nIdeally, you should never write your own \"new\" method, and should use Moose's other features to\nhandle your specific object construction needs. Here are a few scenarios, and the Moose way to\nsolve them;\n\nIf you need to call initialization code post instance construction, then use the \"BUILD\" method.\nThis feature is taken directly from Perl 6. Every \"BUILD\" method in your inheritance chain is\ncalled (in the correct order) immediately after the instance is constructed. This allows you to\nensure that all your superclasses are initialized properly as well. This is the best approach to\ntake (when possible) because it makes subclassing your class much easier.\n\nIf you need to affect the constructor's parameters prior to the instance actually being\nconstructed, you have a number of options.\n\nTo change the parameter processing as a whole, you can use the \"BUILDARGS\" method. The default\nimplementation accepts key/value pairs or a hash reference. You can override it to take\npositional args, or any other format\n\nTo change the handling of individual parameters, there are *coercions* (See the\nMoose::Cookbook::Basics::HTTPSubtypesAndCoercion for a complete example and explanation of\ncoercions). With coercions it is possible to morph argument values into the correct expected\ntypes. This approach is the most flexible and robust, but does have a slightly higher learning\ncurve.\n\nHow do I make non-Moose constructors work with Moose?\nUsually the correct approach to subclassing a non-Moose class is delegation. Moose makes this\neasy using the \"handles\" keyword, coercions, and \"lazybuild\", so subclassing is often not the\nideal route.\n\nThat said, if you really need to inherit from a non-Moose class, see\nMoose::Cookbook::Basics::DateTimeExtendingNonMooseParent for an example of how to do it, or\ntake a look at \"MooseX::NonMoose\" in Moose::Manual::MooseX.\n" }, { "name": "Accessors", "content": "How do I tell Moose to use get/set accessors?\nThe easiest way to accomplish this is to use the \"reader\" and \"writer\" attribute options:\n\nhas 'bar' => (\nisa => 'Baz',\nreader => 'getbar',\nwriter => 'setbar',\n);\n\nMoose will still take advantage of type constraints, triggers, etc. when creating these methods.\n\nIf you do not like this much typing, and wish it to be a default for your classes, please see\nMooseX::FollowPBP. This extension will allow you to write:\n\nhas 'bar' => (\nisa => 'Baz',\nis => 'rw',\n);\n\nMoose will create separate \"getbar\" and \"setbar\" methods instead of a single \"bar\" method.\n\nIf you like \"bar\" and \"setbar\", see MooseX::SemiAffordanceAccessor.\n\nNOTE: This cannot be set globally in Moose, as that would break other classes which are built\nwith Moose. You can still save on typing by defining a new \"MyApp::Moose\" that exports Moose's\nsugar and then turns on MooseX::FollowPBP. See Moose::Cookbook::Extending::MooseishMooseSugar.\n\nHow can I inflate/deflate values in accessors?\nWell, the first question to ask is if you actually need both inflate and deflate.\n\nIf you only need to inflate, then we suggest using coercions. Here is some basic sample code for\ninflating a DateTime object:\n\nclasstype 'DateTime';\n\ncoerce 'DateTime'\n=> from 'Str'\n=> via { DateTime::Format::MySQL->parsedatetime($) };\n\nhas 'timestamp' => (is => 'rw', isa => 'DateTime', coerce => 1);\n\nThis creates a custom type for DateTime objects, then attaches a coercion to that type. The\n\"timestamp\" attribute is then told to expect a \"DateTime\" type, and to try to coerce it. When a\n\"Str\" type is given to the \"timestamp\" accessor, it will attempt to coerce the value into a\n\"DateTime\" object using the code in found in the \"via\" block.\n\nFor a more comprehensive example of using coercions, see the\nMoose::Cookbook::Basics::HTTPSubtypesAndCoercion.\n\nIf you need to deflate your attribute's value, the current best practice is to add an \"around\"\nmodifier to your accessor:\n\n# a timestamp which stores as\n# seconds from the epoch\nhas 'timestamp' => (is => 'rw', isa => 'Int');\n\naround 'timestamp' => sub {\nmy $next = shift;\nmy $self = shift;\n\nreturn $self->$next unless @;\n\n# assume we get a DateTime object ...\nmy $timestamp = shift;\nreturn $self->$next( $timestamp->epoch );\n};\n\nIt is also possible to do deflation using coercion, but this tends to get quite complex and\nrequire many subtypes. An example of this is outside the scope of this document, ask on #moose\nor send a mail to the list.\n\nStill another option is to write a custom attribute metaclass, which is also outside the scope\nof this document, but we would be happy to explain it on #moose or the mailing list.\n" }, { "name": "Method Modifiers", "content": "How can I affect the values in @ using \"before\"?\nYou can't, actually: \"before\" only runs before the main method, and it cannot easily affect the\nmethod's execution.\n\nYou similarly can't use \"after\" to affect the return value of a method.\n\nWe limit \"before\" and \"after\" because this lets you write more concise code. You do not have to\nworry about passing @ to the original method, or forwarding its return value (being careful to\npreserve context).\n\nThe \"around\" method modifier has neither of these limitations, but is a little more verbose.\n\nAlternatively, the MooseX::Mangle extension provides the \"mangleargs\" function, which does\nallow you to affect @.\n\nCan I use \"before\" to stop execution of a method?\nYes, but only if you throw an exception. If this is too drastic a measure then we suggest using\n\"around\" instead. The \"around\" method modifier is the only modifier which can gracefully prevent\nexecution of the main method. Here is an example:\n\naround 'baz' => sub {\nmy $next = shift;\nmy ($self, %options) = @;\nunless ($options->{bar} eq 'foo') {\nreturn 'bar';\n}\n$self->$next(%options);\n};\n\nBy choosing not to call the $next method, you can stop the execution of the main method.\n\nAlternatively, the MooseX::Mangle extension provides the \"guard\" function, which will\nconditionally prevent execution of the original method.\n\nWhy can't I see return values in an \"after\" modifier?\nAs with the \"before\" modifier, the \"after\" modifier is simply called *after* the main method. It\nis passed the original contents of @ and not the return values of the main method.\n\nAgain, the arguments are too lengthy as to why this has to be. And as with \"before\" I recommend\nusing an \"around\" modifier instead. Here is some sample code:\n\naround 'foo' => sub {\nmy $next = shift;\nmy ($self, @args) = @;\nmy @rv = $next->($self, @args);\n# do something silly with the return values\nreturn reverse @rv;\n};\n\nAlternatively, the MooseX::Mangle extension provides the \"manglereturn\" function, which allows\nmodifying the return values of the original method.\n" }, { "name": "Type Constraints", "content": "How can I provide a custom error message for a type constraint?\nUse the \"message\" option when building the subtype:\n\nsubtype 'NaturalLessThanTen'\n=> as 'Natural'\n=> where { $ < 10 }\n=> message { \"This number ($) is not less than ten!\" };\n\nThis \"message\" block will be called when a value fails to pass the \"NaturalLessThanTen\"\nconstraint check.\n\nCan I turn off type constraint checking?\nThere's no support for it in the core of Moose yet. This option may come in a future release.\n\nMeanwhile there's a MooseX extension that allows you to do this on a per-attribute basis, and if\nit doesn't do what you it's easy to write one that fits your use case.\n\nMy coercions stopped working with recent Moose, why did you break it?\nMoose 0.76 fixed a case where coercions were being applied even if the original constraint\npassed. This has caused some edge cases to fail where people were doing something like\n\nsubtype 'Address', as 'Str';\ncoerce 'Address', from 'Str', via { getaddress($) };\n\nThis is not what they intended, because the type constraint \"Address\" is too loose in this case.\nIt is saying that all strings are Addresses, which is obviously not the case. The solution is to\nprovide a \"where\" clause that properly restricts the type constraint:\n\nsubtype 'Address', as 'Str', where { lookslikeaddress($) };\n\nThis will allow the coercion to apply only to strings that fail to look like an Address.\n" }, { "name": "Roles", "content": "Why is BUILD not called for my composed roles?\n\"BUILD\" is never called in composed roles. The primary reason is that roles are not order\nsensitive. Roles are composed in such a way that the order of composition does not matter (for\ninformation on the deeper theory of this read the original traits papers here\n).\n\nBecause roles are essentially unordered, it would be impossible to determine the order in which\nto execute the \"BUILD\" methods.\n\nAs for alternate solutions, there are a couple.\n\n* Using a combination of lazy and default in your attributes to defer initialization (see the\nBinary Tree example in the cookbook for a good example of lazy/default usage\nMoose::Cookbook::Basics::BinaryTreeAttributeFeatures)\n\n* Use attribute triggers, which fire after an attribute is set, to facilitate initialization.\nThese are described in the Moose docs, and examples can be found in the test suite.\n\nIn general, roles should not *require* initialization; they should either provide sane defaults\nor should be documented as needing specific initialization. One such way to \"document\" this is\nto have a separate attribute initializer which is required for the role. Here is an example of\nhow to do this:\n\npackage My::Role;\nuse Moose::Role;\n\nhas 'height' => (\nis => 'rw',\nisa => 'Int',\nlazy => 1,\ndefault => sub {\nmy $self = shift;\n$self->initheight;\n}\n);\n\nrequires 'initheight';\n\nIn this example, the role will not compose successfully unless the class provides a\n\"initheight\" method.\n\nIf none of those solutions work, then it is possible that a role is not the best tool for the\njob, and you really should be using classes. Or, at the very least, you should reduce the amount\nof functionality in your role so that it does not require initialization.\n\nWhat are traits, and how are they different from roles?\nIn Moose, a trait is almost exactly the same thing as a role, except that traits typically\nregister themselves, which allows you to refer to them by a short name (\"Big\" vs\n\"MyApp::Role::Big\").\n\nIn Moose-speak, a *Role* is usually composed into a *class* at compile time, whereas a *Trait*\nis usually composed into an instance of a class at runtime to add or modify the behavior of just\nthat instance.\n\nOutside the context of Moose, traits and roles generally mean exactly the same thing. The\noriginal paper called them traits, but Perl 6 will call them roles.\n\nCan an attribute-generated method (e.g. an accessor) satisfy requires?\nYes, just be sure to consume the role *after* declaring your attribute. \"Required Attributes\" in\nMoose::Manual::Roles provides an example:\n\npackage Breakable;\nuse Moose::Role;\nrequires 'stress';\n\npackage Car;\nuse Moose;\nhas 'stress' => ( is => 'rw', isa => 'Int' );\nwith 'Breakable';\n\nIf you mistakenly consume the \"Breakable\" role before declaring your \"stress\" attribute, you\nwould see an error like this:\n\n'Breakable' requires the method 'stress' to be implemented by 'Car' at...\n" }, { "name": "Moose and Subroutine Attributes", "content": "Why don't subroutine attributes I inherited from a superclass work?\nCurrently when subclassing a module is done at runtime with the \"extends\" keyword, but\nattributes are checked at compile time by Perl. To make attributes work, you must place\n\"extends\" in a \"BEGIN\" block so that the attribute handlers will be available at compile time,\nlike this:\n\nBEGIN { extends qw/Foo/ }\n\nNote that we're talking about Perl's subroutine attributes here, not Moose attributes:\n\nsub foo : Bar(27) { ... }\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": [] } } } }