[Moose-commits] r7451 - in Moose/trunk: . lib lib/Moose
lib/Moose/Manual lib/Moose/Util
autarch at code2.0beta.co.uk
autarch at code2.0beta.co.uk
Sat Jan 31 17:44:11 GMT 2009
Author: autarch
Date: 2009-01-31 09:44:11 -0800 (Sat, 31 Jan 2009)
New Revision: 7451
Added:
Moose/trunk/grant-description
Moose/trunk/lib/Moose/Manual.pod
Moose/trunk/lib/Moose/Manual/
Moose/trunk/lib/Moose/Manual/Attributes.pod
Moose/trunk/lib/Moose/Manual/BestPractices.pod
Moose/trunk/lib/Moose/Manual/Classes.pod
Moose/trunk/lib/Moose/Manual/Concepts.pod
Moose/trunk/lib/Moose/Manual/Construction.pod
Moose/trunk/lib/Moose/Manual/Delegation.pod
Moose/trunk/lib/Moose/Manual/MOP.pod
Moose/trunk/lib/Moose/Manual/MethodModifiers.pod
Moose/trunk/lib/Moose/Manual/MooseX.pod
Moose/trunk/lib/Moose/Manual/Roles.pod
Moose/trunk/lib/Moose/Manual/Types.pod
Modified:
Moose/trunk/
Moose/trunk/lib/Moose.pm
Moose/trunk/lib/Moose/Intro.pod
Moose/trunk/lib/Moose/Util/TypeConstraints.pm
Log:
merge moose-manual branch to trunk
Property changes on: Moose/trunk
___________________________________________________________________
Name: svk:merge
- 08e7d58d-de06-4458-8c15-335e402ab116:/local/Moose:77743
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/BUILDARGS:4770
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/Moose-dumb_roles:1727
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/Moose-moosex_compile_support:3337
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/Moose-real_class_meta_type_constraint:3322
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/deprototype:6072
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/inline_wrapped_constructor:3777
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/meta-role-helper:5585
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/method-changes:5953
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/moose-exporter:5196
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/parameterize_constructor_role:5927
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/parameterized_type_fixes:6365
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/predicate_fix:2940
48425d73-d564-4cf1-a4fc-b7d19ba782dc:/local/Moose:54077
f7901bf9-e7b5-442b-97a4-4d7fd5798e10:/local/moose/Moose:41354
+ 08e7d58d-de06-4458-8c15-335e402ab116:/local/Moose:77743
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/BUILDARGS:4770
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/Moose-dumb_roles:1727
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/Moose-moosex_compile_support:3337
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/Moose-real_class_meta_type_constraint:3322
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/deprototype:6072
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/inline_wrapped_constructor:3777
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/meta-role-helper:5585
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/method-changes:5953
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/moose-exporter:5196
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/moose-manual:7450
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/parameterize_constructor_role:5927
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/parameterized_type_fixes:6365
3efe9002-19ed-0310-8735-a98156148065:/Moose/branches/predicate_fix:2940
48425d73-d564-4cf1-a4fc-b7d19ba782dc:/local/Moose:54077
f7901bf9-e7b5-442b-97a4-4d7fd5798e10:/local/moose/Moose:41354
Added: Moose/trunk/grant-description
===================================================================
--- Moose/trunk/grant-description (rev 0)
+++ Moose/trunk/grant-description 2009-01-31 17:44:11 UTC (rev 7451)
@@ -0,0 +1,67 @@
+1. Write a set of Moose::Intro::* documentation. This would be a major
+expansion of the documentation currently in Moose::Intro. These docs
+will explain concepts in detail, and also explain why and when someone
+would choose to use a particular feature.
+
+This differs from the cookbook, which is primarily aimed at showing
+examples of features in code, and then walking through that code.
+
+The intro docs would include the following:
+
+ * Moose::Intro::Attributes - what are attributes and how are they
+ used? This piece of documentation would show all the different
+ features available for attributes, including the "initializer",
+ "clearer", "predicate", triggers, etc. It's likely that this
+ will end up being split into two or three separate documents,
+ since Moose has quite a lot of attribute-related features. For
+ example, delegation could easily be in its own document, and it
+ may make sense to split features into a "basic" and "advanced"
+ set.
+
+ * Moose::Intro::Subclassing - subclassing the Moose
+ way. Subclassing in Moose is very simple, but different from the
+ "old school" Perl 5 way.
+
+ * Moose::Intro::MethodModifiers - a detailed discussion of each
+ type of method modifier with explanations of when each is
+ appropriate.
+
+ * Moose::Intro::MooseObject - details of how Moose::Object works
+ and the features it provides for its subclasses. In particular,
+ this documentation would focus on how to use the BUILD,
+ BUILDARGS, and DEMOLISH methods.
+
+ * Moose::Intro::Roles - an explanation of what roles are and
+ discussion of when to use them. This document would discuss how
+ to apply multiple roles to classes, how to apply roles to other
+ roles, and also how to apply roles to an instantiated object.
+
+ * Moose::Intro::Types - an explanation of Moose's type
+ system. This will include information on how and when to create
+ your own types, and how to use coercion.
+
+ * Moose::Intro::Introspection - what are metaclasses,
+ meta-attributes, etc? This document will explain what the
+ metaclasses are, and talk about how they can be used for
+ introspection.
+
+ * Moose::Intro::MooseX - an overview of some useful MooseX
+ modules, specifically MooseX::AttributeHelpers,
+ MooseX::StrictConstructor, MooseX::Params::Validate, and
+ MooseX::Types.
+
+2. Revise all of the existing cookbook recipes for clarity and
+simplicity. I've already done this for a few recipes, but there are
+quite a few left to do.
+
+3. Write the recipes marked as TODO:
+
+ * Moose::Cookbook::Basics::Recipe8 - Managing complex relations with trigger
+ * Moose::Cookbook::Basics::Recipe11 - BUILD and BUILDARGS
+ * Moose::Cookbook::Roles::Recipe3 - Runtime Role Composition
+ * Moose::Cookbook::Meta::Recipe6 - Hooking into the immutabilization system
+ * Moose::Cookbook::Meta::Recipe7 - Custom meta-instances
+
+4. Complete API docs for all Moose and Class::MOP classes. Many of
+these classes have POD which simply lists their methods, without any
+explanation of what these methods do.
\ No newline at end of file
Modified: Moose/trunk/lib/Moose/Intro.pod
===================================================================
--- Moose/trunk/lib/Moose/Intro.pod 2009-01-31 17:42:48 UTC (rev 7450)
+++ Moose/trunk/lib/Moose/Intro.pod 2009-01-31 17:44:11 UTC (rev 7451)
@@ -2,549 +2,11 @@
=head1 NAME
-Moose::Intro - What is Moose, and how do I use it?
+Moose::Intro - Got renamed to Moose::Manual
-=head1 WHAT IS MOOSE?
+=head2 DESCRIPTION
-Moose is a I<complete> object system for Perl 5. If you've used a
-modern object-oriented language (which Perl 5 definitely isn't), you
-know they provide keywords for attribute declaration, object
-construction, and inheritance. These keywords are part of the
-language, and you don't care how they are implemented.
+Go read L<Moose::Manual>. This POD document still exists for the
+benefit of anyone out there who might've linked to it in the past.
-Moose aims to do the same thing for Perl 5 OO. We can't actually
-create new keywords, but we do offer "sugar" that looks a lot like
-them. More importantly, with Moose, you I<declaratively define> your
-class, without needing to know about blessed hashrefs, accessor
-methods, and so on.
-
-Moose lets you focus on the I<logical> structure of your classes, so
-you can focus on "what" rather than "how". With Moose, a class
-definition should read like a list of very concise English sentences.
-
-Moose is built in top of C<Class::MOP>, a meta-object protocol (aka
-MOP). Using the MOP, Moose provides complete introspection for all
-Moose-using classes. This means you can ask classes about their
-attributes, parents, children, methods, etc., all using a well-defined
-API. The MOP abstracts away tedious digging about in the Perl symbol
-table, looking at C<@ISA> vars, and all the other crufty Perl tricks
-we know and love (?).
-
-Moose is based in large part on the Perl 6 object system, as well as
-drawing on the best ideas from CLOS, Smalltalk, and many other
-languages.
-
-=head1 WHY MOOSE?
-
-Moose makes Perl 5 OO both simpler and more powerful. It encapsulates
-all the tricks of Perl 5 power users in high-level declarative APIs
-which are easy to use, and don't require any special knowledge of how
-Perl works under the hood.
-
-Moose makes Perl 5 OO fun, accessible, and powerful. And if you want
-to dig about in the guts, Moose lets you do that too, by using and
-extending its powerful introspection API.
-
-=head1 AN EXAMPLE
-
- package Person;
-
- use Moose;
-
- has 'first_name' => (
- is => 'rw',
- isa => 'Str',
- );
-
- has 'last_name' => (
- is => 'rw',
- isa => 'Str',
- );
-
-This is a I<complete and usable> class definition!
-
- package User;
-
- use DateTime;
- use Moose;
-
- extends 'Person';
-
- has 'password' => (
- is => 'rw',
- isa => 'Str',
- );
-
- has 'last_login' => (
- is => 'rw',
- isa => 'DateTime',
- handles => { 'date_of_last_login' => 'date' },
- );
-
- sub login {
- my $self = shift;
- my $pw = shift;
-
- return 0 if $pw ne $self->password;
-
- $self->last_login( DateTime->now() );
-
- return 1;
- }
-
-We'll leave the line-by-line explanation of this code to other
-documentation, but you can see how Moose reduces common OO idioms to
-simple declarative constructs.
-
-=head2 Where's the Constructor?
-
-One point of confusion that might come up with Moose is how it handles
-object construction. B<You should not define a C<new()> method for
-your classes!>
-
-Moose will provide one for you. It will accept a hash or hash
-reference of named parameters matching your attributes. This is just
-another way in which Moose keeps you from worrying I<how> classes are
-implemented. Simply define a class and you're ready to start creating
-objects!
-
-=head1 MOOSE CONCEPTS (VS "OLD SCHOOL" Perl)
-
-In the past, you may not have thought too much about the difference
-between packages and classes, attributes and methods, constructors and
-methods, etc. Part of what the MOP provides is well-defined
-introspection features for each of those things, and in turn Moose
-provides I<distinct> sugar for each of them. Moose also introduces
-concepts that are uncommon (or entirely new) like roles, method
-modifiers, and declarative delegation.
-
-Knowing what these concepts mean in Moose-speak, and how they used to
-be done in old school Perl 5 OO is a good way to start learning to use
-Moose.
-
-=head2 Class
-
-When you say "use Moose" in a package, you are defining your package
-as a class. At its simplest, a class will consist simply of attributes
-and/or methods. It can also include roles, method modifiers, and more.
-
-A class I<has> zero or more B<attributes>.
-
-A class I<has> zero or more B<methods>.
-
-A class I<has> zero or more superclasses (aka parent classes). A
-class inherits from its superclass(es).
-
-A class I<has> zero or more B<method modifiers>. These modifiers can
-apply to its own methods or methods that are inherited from its
-ancestors.
-
-A class may I<do> zero or more B<roles>.
-
-A class I<has> a B<constructor> and a B<destructor>. These are
-provided for you "for free" by Moose.
-
-The B<constructor> accepts named parameters corresponding to the
-class's attributes and uses them to initialize an B<object instance>.
-
-A class I<has> a B<metaclass>, which in turn has B<meta-attributes>,
-B<meta-methods>, and B<meta-roles>. This metaclass I<describes> the
-class.
-
-A class is usually analogous to a category of nouns, like "People" or
-"Users".
-
- package Person;
-
- use Moose;
- # now it's a Moose class!
-
-=head2 Attribute
-
-An attribute is a property of the class that defines it. It I<always>
-has a name, and it I<may have> a number of other defining
-characteristics.
-
-These characteristics may include a read/write flag, a B<type>,
-accessor method names, B<delegations>, a default value, and more.
-
-Attributes I<are not> methods, but defining them causes various
-accessor methods to be created. At a minimum, a normal attribute will
-always have a reader accessor method. Many attributes have things like
-a writer method, clearer method, and predicate method ("has it been
-set?").
-
-An attribute may also define B<delegation>s, which will create
-additional methods based on the delegation specification.
-
-By default, Moose stores attributes in the object instance, which is a
-hashref, I<but this is invisible to the author of a Moose-base class>!
-It is best to think of Moose attributes as "properties" of the
-I<opaque> B<object instance>. These properties are accessed through
-well-defined accessor methods.
-
-An attribute is usually analogous to a specific feature of something in
-the class's category. For example, People have first and last
-names. Users have passwords and last login datetimes.
-
- has 'first_name' => (
- is => 'rw',
- isa => 'Str',
- );
-
-=head2 Method
-
-A method is very straightforward. Any subroutine you define in your
-class is a method.
-
-Methods correspond to verbs, and are what your objects can do. For
-example, a User can login.
-
- sub login { ... }
-
-=head2 Roles
-
-A role is something that a class I<does>. For example, a Machine class
-might do the Breakable role, and so could a Bone class. A role is
-used to define some concept that cuts across multiple unrelated
-classes, like "breakability", or "has a color".
-
-A role I<has> zero or more B<attributes>.
-
-A role I<has> zero or more B<methods>.
-
-A role I<has> zero or more B<method modifiers>.
-
-A role I<has> zero or more B<required methods>.
-
-A required method is not implemented by the role. Instead, a required
-method says "to use this Role you must implement this method".
-
-Roles are I<composed> into classes (or other roles). When a role is
-composed into a class, its attributes and methods are "flattened" into
-the class. Roles I<do not> show up in the inheritance hierarchy. When
-a role is composed, its attributes and methods appear as if they were
-defined I<in the consuming class>.
-
-Role are somewhat like mixins or interfaces in other OO languages.
-
- package Breakable;
-
- use Moose::Role;
-
- has is_broken => (
- is => 'rw',
- isa => 'Bool',
- );
-
- requires 'break';
-
- before 'break' => {
- my $self = shift;
-
- $self->is_broken(1);
- };
-
-=head2 Method Modifiers
-
-A method modifier is a way of defining an action to be taken when a
-named method is called. Think of it as a hook on the named method. For
-example, you could say "before calling C<login()>, call this modifier
-first". Modifiers come in different flavors like "before", "after",
-"around", and "augment", and you can apply more than one modifier to
-a single method.
-
-Method modifiers are often used as an alternative to overriding a
-method in a parent class. They are also used in roles as a way of
-modifying methods in the consuming class.
-
-Under the hood, a method modifier is just a plain old Perl subroutine
-that gets called before or after (or around, etc.) some named method.
-
- before 'login' => sub {
- my $self = shift;
- my $pw = shift;
-
- warn "Called login() with $pw\n";
- };
-
-=head2 Type
-
-Moose also comes with a (miniature) type system. This allows you to
-define types for attributes. Moose has a set of built-in types based
-on what Perl provides, such as "Str", "Num", "Bool", "HashRef", etc.
-
-In addition, every class name in your application can also be used as
-a type name. We saw an example using "DateTime" earlier.
-
-Finally, you can define your own types, either as subtypes or entirely
-new types, with their own constraints. For example, you could define a
-type "PosInt", a subtype of "Int" which only allows positive numbers.
-
-=head2 Delegation
-
-Moose attributes provide declarative syntax for defining
-delegations. A delegation is a method which delegates the real work to
-some attribute of the class.
-
-You saw this in the User example, where we defined a delegation for
-the C<date_of_last_login()> method. Under the hood, this simple calls
-C<date()> on the User object's C<last_login> attribute.
-
-=head2 Constructor
-
-A constructor creates an B<object instance> for the class. In old
-school Perl, this was usually done by defining a method called
-C<new()> which in turn called C<bless> on a reference.
-
-With Moose, this C<new()> method is created for you, and it simply
-does the right thing. You should never need to define your own
-constructor!
-
-Sometimes you want to do something whenever an object is created. In
-those cases, you can provide a C<BUILD()> method in your class. Moose
-will call this for you after creating a new object.
-
-=head2 Destructor
-
-This is a special method called when an object instance goes out of
-scope. You can specialize what your class does in this method if you
-need to, but you usually don't.
-
-With old school Perl 5, this is the C<DESTROY()> method, but with
-Moose it is the C<DEMOLISH()> method.
-
-=head2 Object Instance
-
-An object instance is a specific noun in the class's "category". For
-example, one specific Person or User. An instance is created by the
-class's B<constructor>.
-
-An instance has values for its attributes. For example, a specific
-person has a first and last name.
-
-In old school Perl 5, this is often a blessed hash reference. With
-Moose, you should never need to know what your object instance
-actually is. (ok, it's usually a blessed hashref with Moose too)
-
-=head2 Moose VS Old School Summary
-
-=over 4
-
-=item * Class
-
-A package with no introspection other than mucking about in the symbol
-table.
-
-With Moose, you get well-defined declaration and introspection.
-
-=item * Attributes
-
-Hand-written accessor methods, symbol table hackery, or a helper
-module like C<Class::Accessor>.
-
-With Moose, these are declaratively defined, and distinct from
-methods.
-
-=item * Method
-
-These are pretty much the same in Moose as in old school Perl.
-
-=item * Roles
-
-C<Class::Trait> or C<Class::Role>, or maybe C<mixin.pm>.
-
-With Moose, they're part of the core feature set, and are
-introspectable like everything else.
-
-=item * Method Modifiers
-
-Could only be done through serious symbol table wizardry, and you
-probably never saw this before (at least in Perl 5).
-
-=item * Type
-
-Hand-written parameter checking in your C<new()> method and accessors.
-
-With Moose, you define types declaratively, and then use them by name
-in your attributes.
-
-=item * Delegation
-
-C<Class::Delegation> or C<Class::Delegator>, but probably even more
-hand-written code.
-
-With Moose, this is also declarative.
-
-=item * Constructor
-
-A C<new()> method which calls C<bless> on a reference.
-
-Comes for free when you define a class with Moose.
-
-=item * Destructor
-
-A C<DESTROY()> method.
-
-With Moose, this is called C<DEMOLISH()>.
-
-=item * Object Instance
-
-A blessed reference, usually a hash reference.
-
-With Moose, this is an opaque thing which has a bunch of attributes
-and methods, as defined by its class.
-
-=item * Immutabilization
-
-Moose comes with a feature called "immutabilization". When you make
-your class immutable, it means you're done adding methods, attributes,
-roles, etc. This lets Moose optimize your class with a bunch of
-extremely dirty in-place code generation tricks that speed up things
-like object construction and so on.
-
-=back
-
-=head1 META WHAT?
-
-A metaclass is a class that describes classes. With Moose, every class
-you define gets a C<meta()> method. It returns a L<Moose::Meta::Class>
-object, which has an introspection API that can tell you about the
-class it represents.
-
- my $meta = User->meta();
-
- for my $attribute ( $meta->compute_all_applicable_attributes ) {
- print $attribute->name(), "\n";
-
- if ( $attribute->has_type_constraint ) {
- print " type: ", $attribute->type_constraint->name, "\n";
- }
- }
-
- for my $method ( $meta->compute_all_applicable_methods ) {
- print $method->name, "\n";
- }
-
-Almost every concept we defined earlier has a meta class, so we have
-L<Moose::Meta::Class>, L<Moose::Meta::Attribute>,
-L<Moose::Meta::Method>, L<Moose::Meta::Role>,
-L<Moose::Meta::TypeConstraint>, L<Moose::Meta::Instance>, and so on.
-
-=head1 BUT I NEED TO DO IT MY WAY!
-
-One of the great things about Moose is that if you dig down and find
-that it does something the "wrong way", you can change it by extending
-a metaclass. For example, you can have arrayref based objects, you can
-make your constructors strict (no unknown params allowed!), you can
-define a naming scheme for attribute accessors, you can make a class a
-Singleton, and much, much more.
-
-Many of these extensions require surprisingly small amounts of code,
-and once you've done it once, you'll never have to hand-code "your way
-of doing things" again. Instead you'll just load your favorite
-extensions.
-
- package MyWay::User;
-
- use Moose;
- use MooseX::StrictConstructor
- use MooseX::MyWay;
-
- has ...;
-
-
-=head1 JUSTIFICATION
-
-If you're still still asking yourself "Why do I need this?", then this
-section is for you.
-
-=over 4
-
-=item Another object system!?!?
-
-Yes, I know there has been an explosion recently of new ways to
-build objects in Perl 5, most of them based on inside-out objects
-and other such things. Moose is different because it is not a new
-object system for Perl 5, but instead an extension of the existing
-object system.
-
-Moose is built on top of L<Class::MOP>, which is a metaclass system
-for Perl 5. This means that Moose not only makes building normal
-Perl 5 objects better, but it also provides the power of metaclass
-programming.
-
-=item Is this for real? Or is this just an experiment?
-
-Moose is I<based> on the prototypes and experiments Stevan did for the
-Perl 6 meta-model. However, Moose is B<NOT> an experiment or
-prototype; it is for B<real>.
-
-=item Is this ready for use in production?
-
-Yes.
-
-Moose has been used successfully in production environments by several
-people and companies. There are Moose applications which have been in
-production with little or no issue now for well over two years. We
-consider it highly stable and we are commited to keeping it stable.
-
-Of course, in the end, you need to make this call yourself. If you
-have any questions or concerns, please feel free to email Stevan, the
-moose at perl.org list, or just stop by irc.perl.org#moose and ask away.
-
-=item Is Moose just Perl 6 in Perl 5?
-
-No. While Moose is very much inspired by Perl 6, it is not itself Perl
-6. Instead, it is an OO system for Perl 5. Stevan built Moose because
-he was tired of writing the same old boring Perl 5 OO code, and
-drooling over Perl 6 OO. So instead of switching to Ruby, he wrote
-Moose :)
-
-=item Wait, I<post> modern, I thought it was just I<modern>?
-
-Stevan read Larry Wall's talk from the 1999 Linux World entitled
-"Perl, the first postmodern computer language" in which he talks about
-how he picked the features for Perl because he thought they were cool
-and he threw out the ones that he thought sucked. This got him
-thinking about how we have done the same thing in Moose. For Moose, we
-have "borrowed" features from Perl 6, CLOS (LISP), Smalltalk, Java,
-BETA, OCaml, Ruby and more, and the bits we didn't like (cause they
-sucked) we tossed aside. So for this reason (and a few others) Stevan
-has re-dubbed Moose a I<postmodern> object system.
-
-Nuff Said.
-
-=back
-
-=head1 WHAT NEXT?
-
-So you're sold on Moose. Time to learn how to really use it.
-
-We recommend that you start with the L<Moose::Cookbook>. If you work
-your way through all the recipes under the basics section, you should
-have a pretty good sense of how Moose works, and all of its basic OO
-features.
-
-After that, check out the Role recipes. If you're really curious, go
-on and read the Meta and Extending recipes, but those are mostly there
-for people who want to be Moose wizards and change how Moose works.
-
-If you want to see how Moose would translate directly old school Perl
-5 OO code, check out L<Moose::Unsweetened>.
-
-=head1 AUTHOR
-
-Dave Rolsky E<lt>autarch at urth.orgE<gt> and Stevan Little
-E<lt>stevan at iinteractive.comE<gt>
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 2008 by Infinity Interactive, Inc.
-
-L<http://www.iinteractive.com>
-
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
-
=cut
Added: Moose/trunk/lib/Moose/Manual/Attributes.pod
===================================================================
--- Moose/trunk/lib/Moose/Manual/Attributes.pod (rev 0)
+++ Moose/trunk/lib/Moose/Manual/Attributes.pod 2009-01-31 17:44:11 UTC (rev 7451)
@@ -0,0 +1,603 @@
+=pod
+
+=head1 NAME
+
+Moose::Manual::Attribute - Object attributes with Moose
+
+=head1 INTRODUCTION
+
+Moose has many attribute-related features, and attributes are probably
+the single most useful aspect of Moose. You can do a lot in a class
+just by declaring attributes. In fact, it's quite possible to have
+classes that consist solely of attribute declarations.
+
+An Attribute is a property that every member of a class has. For
+example, we might say that "every Person object has a first name and
+last name". Attributes can be optional, so that we can say "some Person
+objects have a social security number (and some don't)".
+
+At its simplest, an attribute can be thought of as a named value (as
+in a hash) that can be read and set. However, attributes can also have
+defaults, type constraints, delegation and much more.
+
+=head1 ATTRIBUTE OPTIONS
+
+Use the C<has> function to declare an attribute:
+
+ package Person;
+
+ use Moose;
+
+ has 'first_name' => ( is => 'rw' );
+
+This says that all person objects have an optional read-write
+"first_name" attribute.
+
+=head2 Read-write Vs Read-only
+
+The options passed to C<has> define the details of the
+attribute. There are a lot of options you can put here, but in the
+simplest form you just need to include C<is>, which can be either
+C<rw> (read-write) or C<ro> (read-only).
+
+(In fact, you could even omit C<is>, but that leaves you with an
+attribute that has no accessors, which is pointless unless you're
+doing some deep, dark magic).
+
+=head2 Accessor Methods
+
+Each attribute has one or more accessor methods. An accessor lets you
+read and write the value of that attribute for an object.
+
+By default, the accessor method has the same name as the attribute. If
+you declared your attribute as C<ro> then your accessor will be
+read-only. If you declared it read-write, you get a read-write
+accessor. Simple.
+
+Given our Person example above, we now have a single C<first_name>
+accessor that can read or write a person object's first name.
+
+If you want, you can also explicitly specify the method names to be
+used for reading and writing an attribute's value. This is
+particularly handy when you'd like an attribute to be publically
+readable, but only privately settable. For example:
+
+ has 'weight' => (
+ is => 'rw',
+ writer => '_set_weight',
+ );
+
+This might be useful if weight is calculated based on other methods,
+for example every time the C<eat> method is called, we might adjust
+weight. This lets us hide the implementation details of weight
+changes, but still provide the weight value to users of the class.
+
+Some people might prefer to have distinct methods for reading and
+writing. In I<Perl Best Practices>, Damian Conway recommends that
+reader methods start with "get_" and writer methods start with "set_".
+
+We can do exactly that by providing names for both the C<reader> and
+C<writer> methods:
+
+ has 'weight' => (
+ is => 'rw',
+ reader => 'get_weight',
+ writer => 'set_weight',
+ );
+
+If you're thinking that doing this over and over would be insanely
+tedious, you're right! Fortunately, Moose provides a powerful
+extension system that lets you do things like override the default
+accessor method conventions. See L<Moose::Manual::MooseX> for more
+details.
+
+=head2 Predicate and Clearer Methods
+
+Moose allows you to explicitly distinguish between a false or
+undefined attribute value and an attribute which is not set. If you
+want to be able access this information, you must define clearer and
+predicate methods for an attribute.
+
+A predicate method tells you whether or not a given attribute is
+currently set. Note that even if the attribute was explicitly set to
+undef or some other false value, the predicate will return true.
+
+The clearer method unsets the attribute. This is I<not> the
+same as setting the value to C<undef>, but you can only distinguish
+between them if you define a predicate method!
+
+Here's some code to illustrate the relationship between an accessor,
+predicate, and clearer method.
+
+ package Person;
+
+ use Moose;
+
+ has 'ssn' => (
+ is => 'rw',
+ clearer => 'clear_ssn',
+ predicate => 'has_ssn',
+ );
+
+ ...
+
+ my $person = Person->new();
+ $person->has_ssn; # false
+
+ $person->ssn(undef);
+ $person->ssn; # returns undef
+ $person->has_ssn; # true
+
+ $person->clear_ssn;
+ $person->ssn; # returns undef
+ $person->has_ssn; # false
+
+ $person->ssn('123-45-6789');
+ $person->ssn; # returns '123-45-6789'
+ $person->has_ssn; # true
+
+ my $person2 = Person->new( ssn => '111-22-3333');
+ $person2->has_ssn; # true
+
+By default, Moose does not make a predicate or clearer for you. You
+must explicitly provide method names for these options if you want
+them.
+
+=head2 Required or Not?
+
+By default, all attributes are optional, and do not need to be
+provided at object construction time. If you want to make an attribute
+required, simply set the C<required> option to true:
+
+ has 'name' => (
+ is => 'rw',
+ required => 1,
+ );
+
+There are a couple caveats worth mentioning in regards to what
+required actually means.
+
+Basically, all it says is that this attribute (name) must be provided
+to the constructor. It does not say anything about its value, so it
+could be C<undef>.
+
+If you define a clearer method on a required attribute, the clearer
+I<will> work, so even a required attribute can be unset after object
+construction.
+
+This means that if you do make an attribute required, providing a
+clearer doesn't make much sense. In some cases, it might be handy to
+have a I<private> C<clearer> and C<predicate> for a required
+attribute.
+
+=head2 Default and Builder Methods
+
+Attributes can have default values, and Moose provides two ways to
+specify that default.
+
+In the simplest form, you simply provide a non-reference scalar value
+for the C<default> option:
+
+ has 'size' => (
+ is => 'rw',
+ default => 'medium',
+ predicate => 'has_size',
+ );
+
+If the size attribute is not provided to the constructor, then it ends
+up being set to "medium":
+
+ my $person = Person->new();
+ $person->size; # medium
+ $person->has_size; # true
+
+You can also provide a subroutine reference for C<default>. This
+reference will be called a method on the object.
+
+ has 'size' => (
+ is => 'rw',
+ default =>
+ sub { ( 'small', 'medium', 'large' )[ int( rand 3 ) ] },
+ predicate => 'has_size',
+ );
+
+This is dumb example, but it illustrates the point that the subroutine
+will be called for every new object created.
+
+Of course, if it's called during object construction, it may be called
+before other attributes have been set. If your default is dependent on
+other parts of the object's state, you can make the default c<lazy>,
+which is covered in the next section.
+
+If you want to use a reference of any sort as the default value, you
+must return it from a subroutine. This is necessary because otherwise
+Perl would instantiate the reference exactly once, and it would be
+shared by all objects:
+
+ has 'mapping' => (
+ is => 'rw',
+ default => {}, # wrong!
+ );
+
+Moose will throw an error if you pass a bare non-subroutine reference
+as the default.
+
+If Moose allowed this then the default mapping attribute could easily
+end up shared across many objects. Instead, wrap it in a subroutine
+reference:
+
+ has 'mapping' => (
+ is => 'rw',
+ default => sub { {} }, # right!
+ );
+
+This is a bit awkward, but it's just the way Perl works.
+
+As an alternative to using a subroutine reference, you can instead
+supply a C<builder> method for your attribute:
+
+ has 'size' => (
+ is => 'rw',
+ builder => '_build_size',
+ predicate => 'has_size',
+ );
+
+ sub _build_size {
+ return ( 'small', 'medium', 'large' )[ int( rand 3 ) ];
+ }
+
+This has several advantages. First, it moves a chunk of code to its
+own named method, which improves readability and code
+organization. Second, the C<_build_size> method can be overridden in
+subclasses.
+
+We strongly recommend that you use a C<builder> instead of a
+C<default> for anything beyond the most trivial default.
+
+=head2 Laziness and lazy_build
+
+Moose lets you defer attribute population by making an attribute
+C<lazy>:
+
+ has 'size' => (
+ is => 'rw',
+ lazy => 1,
+ builder => '_build_size',
+ );
+
+When C<lazy> is true, the attribute is not populated until the reader
+method is called, rather than at object construction time. There are
+several reasons you might choose to do this.
+
+First, if the default value for this attribute depends on some other
+attributes, then the attribute I<must> be C<lazy>. During object
+construction, defaults are not generated in a predictable order, so
+you cannot count on some other attribute being populated in a non-lazy
+default subroutine.
+
+Second, there's often no reason to calculate a default before it's
+needed. Making an attribute C<lazy> lets you defer the cost until the
+attribute is needed. If the attribute is I<never> needed, you save
+some CPU time.
+
+We recommend that you make any attribute with a builder or non-trivial
+default C<lazy> as a matter of course.
+
+To facilitate this, you can simply specify the C<lazy_build> attribute
+option. This bundles up a number of options together:
+
+ has 'size' => (
+ is => 'rw',
+ lazy_build => 1,
+ );
+
+This is the same as specifying all of these options:
+
+ has 'size' => (
+ is => 'rw',
+ lazy => 1,
+ builder => '_build_size',
+ clearer => 'clear_size',
+ predicate => 'has_size',
+ );
+
+If your attribute name starts with an underscore (_), then the clearer
+and predicate will as well:
+
+ has '_size' => (
+ is => 'rw',
+ lazy_build => 1,
+ );
+
+becomes:
+
+ has '_size' => (
+ is => 'rw',
+ lazy => 1,
+ builder => '_build__size',
+ clearer => '_clear_size',
+ predicate => '_has_size',
+ );
+
+Note the doubled underscore in the builder name. Internally, Moose
+simply prepends the attribute name with "_build_" to come up with the
+builder name.
+
+If you don't like the names that C<lazy_build> generates, you can
+always provide your own:
+
+ has 'size' => (
+ is => 'rw',
+ lazy_build => 1,
+ clearer => '_clear_size',
+ );
+
+Options that you explicitly provide are always used in favor of
+Moose's internal defaults.
+
+=head2 Constructor Parameters (init_arg)
+
+By default, each attribute can be passed by name to the class's
+constructor. On occassion, you may want to use a different name for
+the constructor parameter. You may also want to make an attribute
+unsettable from the constructor.
+
+Both of these things can be done by providing a value for the
+C<init_arg> option:
+
+ has 'bigness' => (
+ is => 'rw',
+ init_arg => 'size',
+ );
+
+Now we have an attribute named bigness, but to set it during object
+construction we pass C<size> to the constructor.
+
+Even more useful is the ability to disable setting attribute. This is
+particularly handy for private attributes:
+
+ has '_genetic_code' => (
+ is => 'rw',
+ init_arg => undef,
+ );
+
+By setting the C<init_arg> to C<undef>, we make it impossible to set
+this attribute when creating a new object.
+
+=head2 Weak References
+
+Moose has built-in support for weak references. If you set the
+C<weak_ref> option to a true value, then it will call
+C<Scalar::Util::weaken> whenever the attribute is set:
+
+ has 'parent' => (
+ is => 'rw',
+ weak_ref => 1,
+ );
+
+ $node->parent($parent_node);
+
+This is very useful when you're building objects that may contain
+circular references.
+
+=head2 Triggers
+
+A C<trigger> is a subroutine that is called whenever the attribute is
+set:
+
+ has 'size' => (
+ is => 'rw',
+ trigger => \&_size_set,
+ );
+
+ sub _size_set {
+ my ( $self, $size, $meta_attr ) = @_;
+
+ warn $self->name, " size is now $size\n";
+ }
+
+The trigger is called as a method, and receives the new value as well
+as the L<Moose::Meta::Attribute> object for the attribute. The trigger
+is called I<after> the value is set.
+
+=head2 Attribute Types
+
+Attributes can be restricted to only accept certain types:
+
+ has 'first_name' => (
+ is => 'rw',
+ isa => 'Str',
+ );
+
+This says that the first_name attribute must be a string.
+
+Moose also provides a shortcut for specifying that an attribute only
+accepts objects that do a certain role:
+
+ has 'weapon' => (
+ is => 'rw',
+ does => 'MyApp::Weapon',
+ );
+
+See the L<Moose::Manual::Types> documentation for a complete
+discussion of Moose's type system.
+
+=head2 Delegation
+
+Attributes can define methods which simple delegate to their values:
+
+ has 'hair_color' => (
+ is => 'rw',
+ isa => 'Graphics::Color::RGB',
+ handles => { hair_color_hex => 'as_hex_string' },
+ );
+
+This adds a new method, C<hair_color_hex>. When someone calls
+C<hair_color_hex>, internally, the object just calls C<<
+$self->hair_color->as_hex_string >>.
+
+See L<Moose::Manual::Delegation> for more details on how to set up
+delegation methods.
+
+=head2 Metaclass and traits
+
+One of Moose's best features is that it can be extended in all sorts
+of ways through the use of custom metaclasses and metaclass traits.
+
+When declaring an attribute, you can declare a metaclass or a set of
+traits for the attribute:
+
+ use MooseX::AttributeHelpers;
+
+ has 'mapping' => (
+ metaclass => 'Collection::Hash',
+ is => 'ro',
+ default => sub { {} },
+ );
+
+In this case, the metaclass C<Collection::Hash> really refers to
+C<MooseX::AttributeHelpers::Collection::Hash>.
+
+You can also apply one or more traits to an attribute:
+
+ use MooseX::MetaDescription;
+
+ has 'size' => (
+ is => 'rw',
+ traits => ['MooseX::MetaDescription::Meta::Trait'],
+ description => {
+ html_widget => 'text_input',
+ serialize_as => 'element',
+ },
+ );
+
+The advantage of traits is that you can mix more than one of them
+together easily (in fact, a trait is just a role under the hood).
+
+There are a number of MooseX modules on CPAN which provide useful
+attribute metaclasses and traits. See L<Moose::Manual::MooseX> for
+some examples. You can also write your own metaclasses and traits. See
+the "Meta" and "Extending" recipes in L<Moose::Cookbook> for examples.
+
+=head1 ATTRIBUTE INHERITANCE
+
+By default, a child inherits all of its parent class(es)' attributes
+as-is. However, you can explicitly change some aspects of the
+inherited attribute in the child class.
+
+The options that can be overridden in a subclass are:
+
+=over 4
+
+=item * default
+
+=item * coerce
+
+=item * required
+
+=item * documentation
+
+=item * lazy
+
+=item * isa
+
+=item * handles
+
+=item * builder
+
+=item * metaclass
+
+=item * traits
+
+=back
+
+To override an attribute, you simply prepend its name with a plus sign
+(+):
+
+ package LazyPerson;
+
+ use Moose;
+
+ extends 'Person';
+
+ has '+first_name' => (
+ lazy => 1,
+ default => 'Bill',
+ );
+
+Now the C<first_name> attribute in C<LazyPerson> is lazy, and defaults
+to C<'Bill'>.
+
+We recommend that you exercise caution when changing the type (C<isa>)
+of an inherited attribute. It's best to only make the new type a
+subtype of the one accepted by the parent.
+
+=head1 MORE ON ATTRIBUTES
+
+Moose attributes are a big topic, and this document glosses over a few
+aspects of their aspects. We recommend that you read the
+L<Moose::Manual::Delegation> and L<Moose::Manual::Types> documents to
+get a more complete understanding of attribute features.
+
+=head1 A FEW MORE OPTIONS
+
+Moose has lots of attribute options. The ones listed below are
+superceded by some more modern features, but are covered for the sake
+of completeness.
+
+=head2 The C<documentation> option
+
+You can provide a piece of documentation as a string for an attribute:
+
+ has 'first_name' => (
+ is => 'rw',
+ documentation => q{The person's first (personal) name},
+ );
+
+Moose does absolutely nothing with this information other than store
+it.
+
+As an alternative, you might want to look at the
+C<MooseX::MetaDescription> module, which lets you attach a
+"description" to each attribute. This description is a hashref that
+can include meta-information intended for use in other code, as well
+as documentation information.
+
+=head2 The C<auto_deref> Option
+
+If your attribute is an array reference or hash reference, the
+C<auto_deref> option will make Moose de-reference the value when it is
+returned from the reader method:
+
+ my %map = $object->mapping;
+
+This option only works if your attribute is explicitly typed as an
+ArrayRef or HashRef.
+
+However, we recommend that you use C<MooseX::AttributeHelpers> for
+these types of attributes, which gives you much more control over how
+they are accessed and manipulated.
+
+=head2 Initializer
+
+Moose provides an attribute option called C<initializer>. This is
+similar to C<builder>, except that it is I<only> called during object
+construction.
+
+This option is inherited from C<Class::MOP>, but we recommend that you
+use a C<builder> (which is Moose-only) instead.
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch at urth.orgE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
Added: Moose/trunk/lib/Moose/Manual/BestPractices.pod
===================================================================
--- Moose/trunk/lib/Moose/Manual/BestPractices.pod (rev 0)
+++ Moose/trunk/lib/Moose/Manual/BestPractices.pod 2009-01-31 17:44:11 UTC (rev 7451)
@@ -0,0 +1,127 @@
+=pod
+
+=head1 RECOMMENDATIONS
+
+Moose has a lot of features, and there's definitely more than one way
+to do it. However, we think that picking a subset of these features
+and using them consistently makes everyone's life easier.
+
+Of course, as with any list of "best practices", these are really just
+opinions. Feel free to ignore us.
+
+=head2 "No Moose" and Immutabilize
+
+We recommend that you end your Moose class definitions by removing the
+Moose sugar and making your class immutable.
+
+ package Person;
+
+ use Moose;
+
+ # extends, roles, attributes, etc.
+
+ # methods
+
+ no Moose;
+
+ __PACKAGE__->meta->make_immutable;
+
+ 1;
+
+The "no Moose" bit is simply good code hygiene, and making classes
+immutable speeds up a lot of things, most notably object construction.
+
+=head2 Always call SUPER::BUILDARGS
+
+If you override the C<BUILDARGS> method in your class, make sure to
+play nice and call C<SUPER::BUILDARGS> to handle cases you're not
+checking for explicitly.q
+
+The default C<BUILDARGS> method in L<Moose::Object> handles both a
+list and hashref of named parameters correctly, and also checks for a
+I<non-hashref> single argument.
+
+=head2 Don't Use the initializer Feature
+
+Don't know what we're talking about? That's fine.
+
+=head2 Use builder Instead of default Most of the Time.
+
+Builders can be inherited, they have explicit names, and they're just
+plain cleaner.
+
+However, I<do> use a default when the default is a non-reference,
+I<or> when the default is simply an empty reference of some sort.
+
+Also, keep your builder methods private.
+
+=head2 Use lazy_build
+
+Lazy is good, and often solves initialization ordering problems. It's
+also good for deferring work that may never have to be done. If you're
+going to be lazy, use I<lazy_build> to save yourself some typing and
+standardize names.
+
+=head2 Consider Keeping clearers & predicates Private
+
+Does everyone I<really> need to be able to clear an attribute?
+Probably not. Don't expose this functionality outside your class
+by default.
+
+Predicates are less problematic, but there's no reason to make your
+public API bigger than it has to be.
+
+=head2 Default to read-only, and Consider Keeping writers Private
+
+Making attributes mutable just means more complexity to account for in
+your program. The alternative to mutable state is to encourage users
+of your class to simply make new objects as needed.
+
+If you I<must> make an attribute read-write, consider making the
+writer a separate private method. Narrower APIs are easy to maintain,
+and mutable state is trouble.
+
+=head2 Think Twice Before Changing an Attribute's Type in a Subclass
+
+Down this path lies great confusion. If the attribute is an object
+itself, at least make sure that it has the same interface as the type
+of object in the parent class.
+
+=head2 Use MooseX::AttributeHelpers Instead of auto_deref
+
+The C<auto_deref> feature is a big troublesome. Directly exposing a
+complex attribute is ugly. Instead, consider using
+C<MooseX::AttributeHelpers> to define an API that exposes those pieces
+of functionality that need exposing. Then you can expose just the
+functionality that you want.
+
+=head2 Namespace Your Types
+
+Use some sort of namespacing convention for type names. We recommend
+something like "MyApp.Type.Foo". I<Never> use "::" as the namespace
+separator, since that overlaps with actual class names.
+
+=head2 Coercion Instead of Unions
+
+Consider using a type coercion instead of a type union. This was
+covered at length in L<Moose::Manual::Types>.
+
+=head2 Define All Your Types in One Module
+
+Define all your types and coercions in one module. This was also
+covered in L<Moose::Manual::Types>.
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch at urth.orgE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
Added: Moose/trunk/lib/Moose/Manual/Classes.pod
===================================================================
--- Moose/trunk/lib/Moose/Manual/Classes.pod (rev 0)
+++ Moose/trunk/lib/Moose/Manual/Classes.pod 2009-01-31 17:44:11 UTC (rev 7451)
@@ -0,0 +1,121 @@
+=pod
+
+=head1 NAME
+
+Moose::Manual::Classes - Making your classes use Moose (and subclassing)
+
+=head1 USING MOOSE
+
+Using Moose is very simple, you just C<use Moose>:
+
+ package Person;
+
+ use Moose;
+
+That's it, you've now made a Moose-based class!
+
+There's actually a lot going on here under the hood, so let's step
+through it. The L<Moose> package does several things when you load it.
+
+When you load Moose, you get a bunch of sugar functions exported into
+your class. These include things like C<extends>, C<has>, C<with>, and
+more. These functions are what you use to define your class. For
+example, you might define an attribute ...
+
+ package Person;
+
+ use Moose;
+
+ has 'ssn' => ( is => 'rw' );
+
+Attributes are described in the L<Moose::Manual::Attributes>
+documentation.
+
+Loading Moose in your class also turns on the C<strict> and
+C<warnings> pragmas in your class for you.
+
+The metaclass object an introspection API for your class. It is also
+used by Moose itself under the hood to add attributes, define parent
+classes, and so on. In fact, all of Moose's sugar does the real work
+by calling methods on this metaclass object (and other meta level
+objects).
+
+When you load Moose, your class will become a subclass of
+L<Moose::Object>. The L<Moose::Object> class provides a default
+constructor, destructor, as well as object construction helper
+methods. You can read more about this in the
+L<Moose::Manual::Construction> document.
+
+As a convenience, Moose creates a new class type with the name of your
+class, by calling the C<class_type> function in
+L<Moose::Util::Constraints>. See the L<Moose::Manual::Types> document
+for more about types.
+
+It also creates a L<Moose::Meta::Class> object for your class. This
+metaclass object is now available by calling a C<meta> method on your
+class, for example C<< Person->meta >>.
+
+=head1 SUBCLASSING
+
+Moose provides a simple sugar function for declaring your parent
+classes, C<extends>:
+
+ package User;
+
+ use Moose;
+
+ extends 'Person';
+
+ has 'username' => ( is => 'rw' );
+
+When you call extends, Moose takes the class(es) you provide and makes
+those the parent of the current class. Note, that each call to
+C<extends> will I<reset> your parents, so for multiple inheritance you
+should provide all you parents at once, C<extends 'Foo', 'Bar'>.
+
+You can use Moose to extend a non-Moose parent. However, when you do
+this, you will inherit the parent class's constructor (assuming it is
+also called C<new>). In that case, you will have to take care of
+initializing attributes manually, either in the parent's constructor,
+or in your subclass, and you will generally lose a lot of Moose magic.
+
+=head1 NO MOOSE
+
+Moose also allows you to remove its sugar functions from your class's
+namespace. We recommend that you take advantage of this feature, since
+it just makes your classes "cleaner". You can do this by simply adding
+C<no Moose> at the end of your module file.
+
+What this does is delete the functions from your class's namespace, so
+that C<< Person->can('has') >> will no longer return true.
+
+=head1 MAKING IT FASTER
+
+Moose has a feature called "immutabilization" that you can use to
+greatly speed up your classes at runtime. However, using it does incur
+a cost when your class is first being loaded. When you make your class
+immutable you tell Moose that you will not be changing it,
+specifically not adding any attributes, methods, roles, etc.
+
+This allows Moose to generate code specific to your class for its
+constructor and other methods, making object construction much
+faster. It also makes some of the introspection methods faster as
+well.
+
+To make your class immutable you simply call C<make_immutable> on your
+class's metaclass object.
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch at urth.orgE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
Added: Moose/trunk/lib/Moose/Manual/Concepts.pod
===================================================================
--- Moose/trunk/lib/Moose/Manual/Concepts.pod (rev 0)
+++ Moose/trunk/lib/Moose/Manual/Concepts.pod 2009-01-31 17:44:11 UTC (rev 7451)
@@ -0,0 +1,382 @@
+
+
+=head1 NAME
+
+Moose::Manual::Concepts - Moose OO Concepts
+
+=head1 MOOSE CONCEPTS (VS "OLD SCHOOL" Perl)
+
+In the past, you may not have thought too much about the difference
+between packages and classes, attributes and methods, constructors and
+methods, etc. With Moose, these are all conceptually separate things,
+even though under the hood they're implemented with plain old Perl.
+
+Our meta-object protocol (aka MOP) provides a well-defined
+introspection features for each of those concepts, and Moose in turn
+provides I<distinct> sugar for each of them. Moose also introduces
+additional concepts such as roles, method modifiers, and declarative
+delegation.
+
+Knowing what these concepts mean in Moose-speak, and how they used to
+be done in old school Perl 5 OO is a good way to start learning to use
+Moose.
+
+=head2 Class
+
+When you say "use Moose" in a package, you are making your package a
+class. At its simplest, a class will consist simply of attributes
+and/or methods. It can also include roles, method modifiers, and more.
+
+A class I<has> zero or more B<attributes>.
+
+A class I<has> zero or more B<methods>.
+
+A class I<has> zero or more superclasses (aka parent classes). A
+class inherits from its superclass(es).
+
+A class I<has> zero or more B<method modifiers>. These modifiers can
+apply to its own methods or methods that are inherited from its
+ancestors.
+
+A class I<does> zero or more B<roles>.
+
+A class I<has> a B<constructor> and a B<destructor>. These are
+provided for you "for free" by Moose.
+
+The B<constructor> accepts named parameters corresponding to the
+class's attributes and uses them to initialize an B<object instance>.
+
+A class I<has> a B<metaclass>, which in turn has B<meta-attributes>,
+B<meta-methods>, and B<meta-roles>. This metaclass I<describes> the
+class.
+
+A class is usually analogous to a category of nouns, like "People" or
+"Users".
+
+ package Person;
+
+ use Moose;
+ # now it's a Moose class!
+
+=head2 Attribute
+
+An attribute is a property of the class that defines it. It I<always>
+has a name, and it I<may have> a number of other defining
+characteristics.
+
+These characteristics may include a read/write flag, a B<type>,
+accessor method names, B<delegations>, a default value, and more.
+
+Attributes I<are not> methods, but defining them causes various
+accessor methods to be created. At a minimum, a normal attribute will
+always have a reader accessor method. Many attributes have things like
+a writer method, clearer method, and predicate method ("has it been
+set?").
+
+An attribute may also define B<delegation>s, which will create
+additional methods based on the delegation specification.
+
+By default, Moose stores attributes in the object instance, which is a
+hashref, I<but this is invisible to the author of a Moose-base class>!
+It is best to think of Moose attributes as "properties" of the
+I<opaque> B<object instance>. These properties are accessed through
+well-defined accessor methods.
+
+An attribute is something that the class's members have. For example,
+People have first and last names. Users have passwords and last login
+datetimes.
+
+ has 'first_name' => (
+ is => 'rw',
+ isa => 'Str',
+ );
+
+=head2 Method
+
+A method is very straightforward. Any subroutine you define in your
+class is a method.
+
+Methods correspond to verbs, and are what your objects can do. For
+example, a User can login.
+
+ sub login { ... }
+
+=head2 Roles
+
+A role is something that a class I<does>. For example, a Machine class
+might do the Breakable role, and so could a Bone class. A role is
+used to define some concept that cuts across multiple unrelated
+classes, like "breakability", or "has a color".
+
+A role I<has> zero or more B<attributes>.
+
+A role I<has> zero or more B<methods>.
+
+A role I<has> zero or more B<method modifiers>.
+
+A role I<has> zero or more B<required methods>.
+
+A required method is not implemented by the role. Required methods say
+"to use this Role you must implement this method".
+
+Roles are I<composed> into classes (or other roles). When a role is
+composed into a class, its attributes and methods are "flattened" into
+the class. Roles I<do not> show up in the inheritance hierarchy. When
+a role is composed, its attributes and methods appear as if they were
+defined I<in the consuming class>.
+
+Role are somewhat like mixins or interfaces in other OO languages.
+
+ package Breakable;
+
+ use Moose::Role;
+
+ has is_broken => (
+ is => 'rw',
+ isa => 'Bool',
+ );
+
+ requires 'break';
+
+ before 'break' => {
+ my $self = shift;
+
+ $self->is_broken(1);
+ };
+
+=head2 Method Modifiers
+
+A method modifier is a hook that is called when a named method is
+called. For example, you could say "before calling C<login()>, call
+this modifier first". Modifiers come in different flavors like
+"before", "after", "around", and "augment", and you can apply more
+than one modifier to a single method.
+
+Method modifiers are often used as an alternative to overriding a
+method in a parent class. They are also used in roles as a way of
+modifying methods in the consuming class.
+
+Under the hood, a method modifier is just a plain old Perl subroutine
+that gets called before or after (or around, etc.) some named method.
+
+ before 'login' => sub {
+ my $self = shift;
+ my $pw = shift;
+
+ warn "Called login() with $pw\n";
+ };
+
+=head2 Type
+
+Moose also comes with a (miniature) type system. This allows you to
+define types for attributes. Moose has a set of built-in types based
+on what Perl provides, such as "Str", "Num", "Bool", "HashRef", etc.
+
+In addition, every class name in your application can also be used as
+a type name. We saw an example using "DateTime" earlier.
+
+Finally, you can define your own types, either as subtypes or entirely
+new types, with their own constraints. For example, you could define a
+type "PosInt", a subtype of "Int" which only allows positive numbers.
+
+=head2 Delegation
+
+Moose attributes provide declarative syntax for defining
+delegations. A delegation is a method which calls some method on an
+attribute to do its real work.
+
+=head2 Constructor
+
+A constructor creates an B<object instance> for the class. In old
+school Perl, this was usually done by defining a method called
+C<new()> which in turn called C<bless> on a reference.
+
+With Moose, this C<new()> method is created for you, and it simply
+does the right thing. You should never need to define your own
+constructor!
+
+Sometimes you want to do something whenever an object is created. In
+those cases, you can provide a C<BUILD()> method in your class. Moose
+will call this for you after creating a new object.
+
+=head2 Destructor
+
+This is a special method called when an object instance goes out of
+scope. You can specialize what your class does in this method if you
+need to, but you usually don't.
+
+With old school Perl 5, this is the C<DESTROY()> method, but with
+Moose it is the C<DEMOLISH()> method.
+
+=head2 Object Instance
+
+An object instance is a specific noun in the class's "category". For
+example, one specific Person or User. An instance is created by the
+class's B<constructor>.
+
+An instance has values for its attributes. For example, a specific
+person has a first and last name.
+
+In old school Perl 5, this is often a blessed hash reference. With
+Moose, you should never need to know what your object instance
+actually is. (ok, it's usually a blessed hashref with Moose too)
+
+=head2 Moose VS Old School Summary
+
+=over 4
+
+=item * Class
+
+A package with no introspection other than mucking about in the symbol
+table.
+
+With Moose, you get well-defined declaration and introspection.
+
+=item * Attributes
+
+Hand-written accessor methods, symbol table hackery, or a helper
+module like C<Class::Accessor>.
+
+With Moose, these are declaratively defined, and distinct from
+methods.
+
+=item * Method
+
+These are pretty much the same in Moose as in old school Perl.
+
+=item * Roles
+
+C<Class::Trait> or C<Class::Role>, or maybe C<mixin.pm>.
+
+With Moose, they're part of the core feature set, and are
+introspectable like everything else.
+
+=item * Method Modifiers
+
+Could only be done through serious symbol table wizardry, and you
+probably never saw this before (at least in Perl 5).
+
+=item * Type
+
+Hand-written parameter checking in your C<new()> method and accessors.
+
+With Moose, you define types declaratively, and then use them by name
+in your attributes.
+
+=item * Delegation
+
+C<Class::Delegation> or C<Class::Delegator>, but probably even more
+hand-written code.
+
+With Moose, this is also declarative.
+
+=item * Constructor
+
+A C<new()> method which calls C<bless> on a reference.
+
+Comes for free when you define a class with Moose.
+
+=item * Destructor
+
+A C<DESTROY()> method.
+
+With Moose, this is called C<DEMOLISH()>.
+
+=item * Object Instance
+
+A blessed reference, usually a hash reference.
+
+With Moose, this is an opaque thing which has a bunch of attributes
+and methods, as defined by its class.
+
+=item * Immutabilization
+
+Moose comes with a feature called "immutabilization". When you make
+your class immutable, it means you're done adding methods, attributes,
+roles, etc. This lets Moose optimize your class with a bunch of
+extremely dirty in-place code generation tricks that speed up things
+like object construction and so on.
+
+=back
+
+=head1 META WHAT?
+
+A metaclass is a class that describes classes. With Moose, every class
+you define gets a C<meta()> method. It returns a L<Moose::Meta::Class>
+object, which has an introspection API that can tell you about the
+class it represents.
+
+ my $meta = User->meta();
+
+ for my $attribute ( $meta->compute_all_applicable_attributes ) {
+ print $attribute->name(), "\n";
+
+ if ( $attribute->has_type_constraint ) {
+ print " type: ", $attribute->type_constraint->name, "\n";
+ }
+ }
+
+ for my $method ( $meta->compute_all_applicable_methods ) {
+ print $method->name, "\n";
+ }
+
+Almost every concept we defined earlier has a meta class, so we have
+L<Moose::Meta::Class>, L<Moose::Meta::Attribute>,
+L<Moose::Meta::Method>, L<Moose::Meta::Role>,
+L<Moose::Meta::TypeConstraint>, L<Moose::Meta::Instance>, and so on.
+
+=head1 BUT I NEED TO DO IT MY WAY!
+
+One of the great things about Moose is that if you dig down and find
+that it does something the "wrong way", you can change it by extending
+a metaclass. For example, you can have arrayref based objects, you can
+make your constructors strict (no unknown params allowed!), you can
+define a naming scheme for attribute accessors, you can make a class a
+Singleton, and much, much more.
+
+Many of these extensions require surprisingly small amounts of code,
+and once you've done it once, you'll never have to hand-code "your way
+of doing things" again. Instead you'll just load your favorite
+extensions.
+
+ package MyWay::User;
+
+ use Moose;
+ use MooseX::StrictConstructor
+ use MooseX::MyWay;
+
+ has ...;
+
+=head1 WHAT NEXT?
+
+So you're sold on Moose. Time to learn how to really use it.
+
+If you want to see how Moose would translate directly old school Perl
+5 OO code, check out L<Moose::Unsweetened>. This might be helpful for
+quickly wrapping your brain around some aspects of "the Moose way".
+
+Obviously, the next thing to read is the rest of the L<Moose::Manual>.
+
+After that we recommend that you start with the L<Moose::Cookbook>. If
+you work your way through all the recipes under the basics section,
+you should have a pretty good sense of how Moose works, and all of its
+basic OO features.
+
+After that, check out the Role recipes. If you're really curious, go
+on and read the Meta and Extending recipes, but those are mostly there
+for people who want to be Moose wizards and change how Moose works.
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch at urth.orgE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
Added: Moose/trunk/lib/Moose/Manual/Construction.pod
===================================================================
--- Moose/trunk/lib/Moose/Manual/Construction.pod (rev 0)
+++ Moose/trunk/lib/Moose/Manual/Construction.pod 2009-01-31 17:44:11 UTC (rev 7451)
@@ -0,0 +1,133 @@
+=pod
+
+=head1 NAME
+
+Moose::Manual::Classes - Object construction (and destruction) with Moose
+
+=head1 WHERE'S THE CONSTRUCTOR?
+
+B<You do not need to define a C<new()> method for your classes!>
+
+When you C<use Moose> in your class, you will become a subclass of
+C<Moose::Object>, which provides a C<new> method for you. And if you
+follow our recommendations in L<Moose::Manual::BestPractices> and make
+your class immutable, then you actually get a class-specific C<new>
+method genreated in your class.
+
+=head1 OBJECT CONSTRUCTION AND ATTRIBUTES
+
+The Moose-provided constructor accepts a hash or hash reference of
+named parameters matching your attributes (actually, matching their
+C<init_arg>s). This is just another way in which Moose keeps you from
+worrying I<how> classes are implemented. Simply define a class and
+you're ready to start creating objects!
+
+=head1 OBJECT CONSTRUCTION HOOKS
+
+Sometimes you need to hook into object construction. Some common needs
+are validating an object's state, logging, and allowing non-hash(ref)
+constructor arguments. Moose provides hooks for these needs with the
+C<BUILD> and C<BUILDARGS> methods.
+
+If these are defined in your class, then Moose will arrange for them
+to be called as part of the object construction process.
+
+=head2 BUILDARGS
+
+The C<BUILDARGS> method is called I<before> an object is created, and
+is therefore called as a class method. It will receive all of the
+arguments that were passed to C<new> I<as-is>. Your C<BUILDARGS>
+method must then return a hash reference. This hash reference will be
+used to construct the object, so it should contain keys matching your
+attributes' names (well, C<init_arg>s).
+
+One common use for C<BUILDARGS> is to accomodate a non-hash(ref)
+calling style. For example, we might want to allow our Person class to
+be called with a single argument of a social security number, C<<
+Person->new($ssn) >>.
+
+Without a C<BUILDARGS> method, Moose will complain, because it expects
+a hash or hash reference. We can use the C<BUILDARGS> method to
+accomodate this calling style:
+
+ sub BUILDARGS {
+ my $class = shift;
+
+ if ( @_ == 1 && ! ref $_[0] ) {
+ return { ssn => $_[0] };
+ }
+ else {
+ return $class->SUPER::BUILDARGS(@_);
+ }
+ }
+
+Note the call to C<SUPER::BUILDARGS>. This will call the default
+C<BUILDARGS> in C<Moose::Object>. This method handles distinguishing
+between a hash reference and a plain hash, so you don't have to.
+
+=head2 BUILD
+
+The C<BUILD> method is called I<after> an object is created. There are
+many potential uses for a C<BUILD> method. One of the most common is
+to check that the object state makes sense. While we can validate
+individual attributes through the use of types, we can't validate the
+state of a whole object that way.
+
+ sub BUILD {
+ my $self = shift;
+
+ if ( $self->country_of_residence eq 'USA' ) {
+ die 'All US residents must have an SSN'
+ unless $self->has_ssn;
+ }
+ }
+
+Another use of a C<BUILD> method could be for logging or tracking
+object creation.
+
+ sub BUILD {
+ my $self = shift;
+
+ debug( 'Made a new person - SSN = ', $self->ssn, );
+ }
+
+=head3 BUILD and Parent Classes
+
+The interaction between multiple C<BUILD> methods in an inheritance
+hierarchy is different from normal Perl methods. B<You should never
+call C<< $self->SUPER::BUILD >>.>
+
+Moose arranges to have all of the C<BUILD> methods in a hierarchy
+called when an object is constructed, I<from parents to
+children>. This might be surprising at first, because it reverses the
+normal order of method inheritance.
+
+The theory behind this is that C<BUILD> methods can only be used for
+increasing specialization of a class's constraints, so it makes sense
+to call the least specific first (also, this is how Perl 6 does it).
+
+=head1 OBJECT DESTRUCTION
+
+Moose provides a hook for object destruction with the C<DEMOLISH>
+method. As with C<BUILD>, you should never explicitly call C<<
+$self->SUPER::DEMOLISH >>. Moose will arrange for all of the
+C<DEMOLISH> methods in your hierarchy to be called, from most to least
+specific.
+
+In most cases, Perl's built-in garbage collection is sufficient, and
+you won't need ot provide a C<DEMOLISH> method.
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch at urth.orgE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
Added: Moose/trunk/lib/Moose/Manual/Delegation.pod
===================================================================
--- Moose/trunk/lib/Moose/Manual/Delegation.pod (rev 0)
+++ Moose/trunk/lib/Moose/Manual/Delegation.pod 2009-01-31 17:44:11 UTC (rev 7451)
@@ -0,0 +1,116 @@
+=pod
+
+=head1 NAME
+
+Moose::Manual::Attribute - Attribute Delegation
+
+=head1 WHAT IS DELEGATION?
+
+Moose's delegation feature lets you create "shadow" methods that do
+nothing more than call some other method on an attribute. This is
+quite handy since it lets you simplify a complex set of "has-a"
+relationships and present a single unified API from one class.
+
+This means that consumers of a class don't need to know about all the
+objects it contains, and it simplifies their code.
+
+Delegations are defined as a mapping between one or more methods
+provided by the "real" class (the delegatee), and a set of
+corresponding methods in the delegating class. The delegating class
+can re-use the method names provided by the delegatee, or provide its
+own names.
+
+Delegation is also a great way to wrap an existing class, especially a
+non-Moose class or one that is somehow hard (or impossible) to
+subclass.
+
+=head1 DEFINING A MAPPING
+
+Moose offers a number of options for defining a delegation's mapping,
+ranging from simple to complex.
+
+The simplest form is to simply specify a list of methods:
+
+ package Website;
+
+ use Moose;
+
+ has 'uri' => (
+ is => 'ro',
+ isa => 'URI',
+ handles => [qw( host path )],
+ );
+
+With this definition, we can call C<< $website->host >> and it "just
+works". Under the hood, Moose will call C<< $website->uri->host >> for
+you.
+
+We can also define a mapping as a hash reference. This allows you to
+rename methods as part of the mapping:
+
+ package Website;
+
+ use Moose;
+
+ has 'uri' => (
+ is => 'ro',
+ isa => 'URI',
+ handles => {
+ hostname => 'host',
+ path => 'path',
+ },
+ );
+
+In this example, we've created a C<< $website->hostname >> method,
+rather than using C<URI.pm>'s name, C<host>.
+
+These two mapping forms are the ones you will use most often. The
+remainder are a bit more complex, and less common.
+
+ has 'uri' => (
+ is => 'ro',
+ isa => 'URI',
+ handles => qr/^(?:host|path|query.*)/,
+ );
+
+This is similar to the array version, except it uses the regex to
+match against all the methods provided by the delegatee. In order for
+this to work, you must provide an C<isa> parameter for the attribute,
+and it must be a class. Moose uses this to introspect the delegatee
+class and determine what methods it provides.
+
+You can use a role name as the value of C<handles>:
+
+ has 'uri' => (
+ is => 'ro',
+ isa => 'URI',
+ handles => 'HasURI',
+ );
+
+Moose will introspect the role to determine what methods it provides
+and create a mapping for each of those methods.
+
+Finally, you can also provide a sub reference to I<generate> a
+mapping. You probably won't need this version often (if ever). See the
+L<Moose> docs for more details on exactly how this works.
+
+=head1 MISSING ATTRIBUTES
+
+It is perfectly valid to delegate methods to an attribute which is not
+required, or can be undefined. In that case, Moose will throw a
+runtime error when a delegated method is called.
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch at urth.orgE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
Added: Moose/trunk/lib/Moose/Manual/MOP.pod
===================================================================
--- Moose/trunk/lib/Moose/Manual/MOP.pod (rev 0)
+++ Moose/trunk/lib/Moose/Manual/MOP.pod 2009-01-31 17:44:11 UTC (rev 7451)
@@ -0,0 +1,171 @@
+=pod
+
+=head1 NAME
+
+Moose::Manual::MOP - The Moose (and Class::MOP) Meta API
+
+=head1 INTRODUCTION
+
+Moose provides a powerful introspection API by building on top of
+C<Class::MOP>. "MOP" stands for Meta-Object Protocol. In plainer
+english, a MOP is an API for examing classes, attributes, methods, and
+so on.
+
+In fact, it is C<Class::MOP> that provides many of Moose's core
+features, including attributes, before/after/around method modifiers,
+and immutability. In most cases, Moose subclasses an existing
+C<Class::MOP> class to extend. Moose also adds some entirely new
+features, including roles, method augmentation, and types.
+
+It's important to know about C<Class::MOP> so you know what docs to
+read. Often times, the introspection method that you're looking for is
+defined in a C<Class::MOP> class, rather than Moose itself.
+
+The MOP provides more than just I<read-only> introspection. It also
+lets you add attributes, method, apply roles, and much more. In fact,
+all of the declarative Moose sugar is simply a thin layer on top of
+the MOP API.
+
+The meta API is useful for a lot of things. If you want to write Moose
+extensions, you'll definitely need to learn about the meta API. The
+introspection methods are also handy if you want to do something like
+generate docs or inheritance graphs, or do some other sort of runtime
+reflection.
+
+This document is not a complete reference for the meta API. We're just
+going to cover some of the highlights, and give you a sense of how it
+all works. To really understand it, you'll have to read a lot of other
+docs, and possibly even dig into the Moose guts a bit.
+
+=head1 GETTING STARTED
+
+The typical entry point to the meta API is a class's metaclass object,
+which is a L<Moose::Meta::Class>. This is available by calling the
+C<meta> method on a class or object:
+
+ package User;
+
+ use Moose;
+
+ my $meta = __PACKAGE__->meta;
+
+The C<meta> method is added to a class when it uses Moose.
+
+You can also use C<Class::MOP::get_metaclass_by_name($name)> to get a
+metaclass object for any class. This is safer than calling C<<
+$class->meta >> when you're not sure that the class has a meta method.
+
+If you want a metaclass object for a class that I<isn't> using Moose,
+a good idiom to use is:
+
+ my $meta = Class::MOP::Class->initialize($class_name);
+
+The C<< Class::MOP::Class->initialize >> will return an existing
+metaclass if one has already been created (via Moose or some other
+means). If it hasn't, it will return a new C<Class::MOP::Class>
+object. This will work for classes that use Moose, meta API classes,
+and classes which don't use Moose at all.
+
+=head1 USING THE METACLASS OBJECT
+
+The metaclass object can tell you about a class's attributes, methods,
+roles, parents, and more. For example, to look at all of the class's
+attributes:
+
+ for my $attr ( $meta->get_all_attributes ) {
+ print $attr->name, "\n";
+ }
+
+The C<get_all_attributes> method is documented in
+C<Class::MOP::Class>. It returns a list of L<Moose::Meta::Attribute>
+objects for attributes defined in the class and its parents.
+
+You can also get a list of methods:
+
+ for my $method ( $meta->get_all_methods ) {
+ print $meth->fully_qualified_name, "\n";
+ }
+
+Now we're looping over a list of L<Moose::Meta::Method> objects. Note
+that some of these objects may actually be a subclass of
+L<Moose::Meta::Method>, as Moose uses different classes to represent
+wrapped methods, delegation methods, constructors, etc.
+
+We can look at a class's parent classes and subclasses:
+
+ for my $class ( $meta->linearized_isa ) {
+ print "$class\n";
+ }
+
+ for my $subclass ( $meta->subclasses ) {
+ print "$subclass\n";
+ }
+
+Note that both these methods return class I<names>, not metaclass
+objects.
+
+=head1 CHANGING THE OBJECT
+
+You can also use the metaclass object to change the class directly, by
+adding attributes, methods, etc.
+
+You might remember that we've talked about making classes immutable
+elsewhere in the manual. This is a good practice. However, once a
+class is immutable, calling any of these update methods will throw an
+exception.
+
+You can make a class mutable again simply by calling C<<
+$metaclass->make_mutable >>. Once you're done changing it, you can
+restore immutability by calling C<< $metaclass->make_immutable >>.
+
+However, the most common use for this part of of the meta API is as
+part of Moose extensions. These extensions should assume that they are
+being run before you make a class immutable.
+
+As an example, we can add a method to a class:
+
+ $meta->add_method( 'say' => sub { print @_, "\n" } );
+
+Or an attribute:
+
+ $meta->add_attribute(
+ name => 'size',
+ is => 'rw',
+ isa => 'Int',
+ );
+
+Obviously, this is much more cumbersome than the normal way of
+defining methods and attributes, but being able to do this via an API
+makes for very powerful extensions.
+
+=head1 GOING FURTHER
+
+We recommend that you take a look at all of the "Meta" and "Extending"
+recipes in the L<Moose::Cookbook>. These show various practical
+applications of the MOP.
+
+If you'd like to write your own extensions, one of the best ways to
+learn more about this is to look at other similar extensions to see
+how they work. You'll probably also need to read various API docs,
+including the docs for the various Moose::Meta::* classes and the
+C<Class::MOP> distribution.
+
+Finally, we welcome questions on the Moose mailing list and
+IRC. Information on the mailing list, IRC, and more references can be
+found in the L<Moose.pm docs|Moose/GETTING HELP>.
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch at urth.orgE<gt> and Stevan Little
+E<lt>stevan at iinteractive.comE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
Added: Moose/trunk/lib/Moose/Manual/MethodModifiers.pod
===================================================================
--- Moose/trunk/lib/Moose/Manual/MethodModifiers.pod (rev 0)
+++ Moose/trunk/lib/Moose/Manual/MethodModifiers.pod 2009-01-31 17:44:11 UTC (rev 7451)
@@ -0,0 +1,273 @@
+=pod
+
+=head1 NAME
+
+Moose::Manual::Attribute - Moose's Method Modifiers
+
+=head1 WHAT IS A METHOD MODIFIER?
+
+Moose provides a feature called "method modifiers". Another word for
+this feature might be "hooks" or "advice".
+
+It's probably easiest to understand this feature with a few examples:
+
+ package Example;
+
+ use Moose;
+
+ sub foo {
+ print "foo\n";
+ }
+
+ before 'foo' => sub { print "about to call foo\n"; };
+ after 'foo' => sub { print "just called foo\n"; };
+
+ around 'foo' => sub {
+ my $orig = shift;
+ my $self = shift;
+
+ print "I'm around foo\n";
+
+ $self->$orig(@_);
+
+ print "I'm still around foo\n";
+ };
+
+Now if I call C<< Example->new->foo >> I'll get the following output:
+
+ about to call foo
+ I'm around foo
+ foo
+ I'm still around foo
+ just called foo
+
+You probably could have figured that out from the names "before",
+"after", and "around".
+
+Also, as you can see, the before modifiers come before around
+modifiers, and after modifiers come last.
+
+When there are multiple modifiers of the same type, the before and
+around modifiers run from the last added to the first, and after
+modifiers run from first added to last:
+
+ before 2
+ before 1
+ around 2
+ around 1
+ primary
+ around 1
+ around 2
+ after 1
+ after 2
+
+=head1 WHY USE THEM?
+
+Method modifiers have many uses. One very common use is in roles. This
+lets roles alter the behavior of methods in the classes that use
+them. See L<Moose::Manual::Roles> for more about roles.
+
+Modifiers really are at their most useful in roles, so some of the
+examples below are a bit artificial. They're intended to give you an
+idea of how modifiers work, but may not be the most natural usages.
+
+=head1 BEFORE, AFTER, AND AROUND
+
+Method modifiers can also be used to add behavior to a method that
+Moose generates for you, such as an attribute accessor:
+
+ has 'size' => ( is => 'rw' );
+
+ before 'size' => sub {
+ my $self = shift;
+
+ if (@_) {
+ Carp::cluck('Someone is setting size');
+ }
+ };
+
+Another use for the before modifier would be to do some sort of
+pre-checking on a method call. For example:
+
+ before 'size' => sub {
+ my $self = shift;
+
+ die 'Cannot set size while the person is growing'
+ if @_ && $self->is_growing;
+ };
+
+This lets us implement logical checks that don't fit well into
+constraints.
+
+Similarly, an after modifier could be used for logging an action that
+was taken.
+
+Note that the return values of both before and after modifiers are
+ignored.
+
+An around modifier is a bit more powerful than either a before or
+after modifier. First, it is easy to modify the arguments being passed
+onto the original method in an around modifier. Second, you can decide
+to simply not call the original method at all, unlike with other
+modifiers. Finally, you can modify the return value with an around
+modifier.
+
+An around modifier receives the original method as its first argument,
+I<then> the object, and finally any arguments passed to the method.
+
+ around 'size' => sub {
+ my $orig = shift;
+ my $self = shift;
+
+ return $self->$orig()
+ unless @_;
+
+ my $size = shift;
+ $size = $size / 2
+ if $self->likes_small_things();
+
+ return $self->$orig($size);
+ };
+
+=head1 INNER AND AUGMENT
+
+Augment and inner are two halves of the same feature. The augment
+modifier provides a sort of inverted subclassing. You provide part of
+the implementation in a superclass, and then document that subclasses
+are expected to provide the rest.
+
+The superclass calls C<inner()>, which then calls the C<augment>
+modifier in the subclass:
+
+ package Document;
+
+ use Moose;
+
+ sub as_xml {
+ my $self = shift;
+
+ my $xml = "<document>\n";
+ $xml .= inner();
+ $xml .= "</document>\n";
+
+ return $xml;
+ }
+
+Using C<inner()> in this method makes it possible for one or more
+subclasses to then augment this method with their own specific
+implementation:
+
+ package Report;
+
+ use Moose;
+
+ extends 'Document';
+
+ augment 'as_xml' => sub {
+ my $self = shift;
+
+ my $xml = "<report>\n";
+ $xml .= inner();
+ $xml .= "</report>\n";
+
+ return $xml;
+ };
+
+When we call C<as_xml> on a Report object, we get something like this:
+
+ <document>
+ <report>
+ </report>
+ </document>
+
+But we also called C<inner()> in C<Report>, so we can continue
+subclassing and adding more content inside the document:
+
+ package Report::IncomeAndExpenses;
+
+ use Moose;
+
+ extends 'Report';
+
+ augment 'as_xml' => sub {
+ my $self = shift;
+
+ my $xml = '<income>' . $self->income . '</income>';
+ $xml .= "\n";
+ my $xml = '<expenses>' . $self->expenses . '</expenses>';
+ $xml .= "\n";
+
+ $xml .= inner() || q{};
+
+ return $xml;
+ };
+
+Now our report has some content:
+
+ <document>
+ <report>
+ <income>$10</income>
+ <expenses>$8</expenses>
+ </report>
+ </document>
+
+What makes this combination of C<augment> and C<inner()> special is
+that it allows us to have methods which are called from I<parent
+(least specific) to child (most specific). This inverts the normal
+order, where the child's method is called first, and it in turn will
+call C<< $self->SUPER::method >> to call the parent.
+
+Note that in C<Report::IncomeAndExpenses> we call C<inner()> again. If
+the object is an instance of C<Report::IncomeAndExpenses> then this
+call is a no-op, and just returns false.
+
+=head1 OVERRIDE AND SUPER
+
+Finally, Moose provides some simple sugar for Perl's built-in method
+overriding scheme. If you want to override a method from a parent
+class, you can do this with C<override>:
+
+ package Employee;
+
+ use Moose;
+
+ extends 'Person';
+
+ has 'job_title' => ( is => 'rw' );
+
+ override 'display_name' => sub {
+ my $self = shift;
+
+ return super() . q{, } . $self->title();
+ };
+
+The call to C<super()> is almost the same as calling C<<
+$self->SUPER::display_name >>. The difference is that the arguments
+passed to the superclass's method will always be the same as the ones
+passed to the method modifier, and cannot be changed.
+
+All arguments passed to C<super()> are ignored, as are any changes
+made to C<@_> before C<super()> is called.
+
+=head1 SEMI-COLONS
+
+Because all of these method modifiers are implemented as Perl
+functions, you must always end the modifier declaration with a
+semi-colon:
+
+ after 'foo' => sub { };
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch at urth.orgE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
Added: Moose/trunk/lib/Moose/Manual/MooseX.pod
===================================================================
--- Moose/trunk/lib/Moose/Manual/MooseX.pod (rev 0)
+++ Moose/trunk/lib/Moose/Manual/MooseX.pod 2009-01-31 17:44:11 UTC (rev 7451)
@@ -0,0 +1,245 @@
+=pod
+
+=head1 NAME
+
+Moose::Manual::MooseX - Recommended Moose Extensions
+
+=head1 MooseX?
+
+One of the great things about Moose is that it is easy to extend and
+override. You can use the meta-model API to do things your own way,
+add new features, and generally customize your Moose.
+
+Writing your own extensions does require a good understanding of the
+meta-model. You can start learning about thiswith the
+L<Moose::Manual::Introspection> docs. There are also several extensions
+recipes in the L<Moose::Cookbook>.
+
+Explaining how to write extensions is beyond the scope of this
+manual. Fortunately, lots of people have already written extensions
+and put them on CPAN for you.
+
+This document covers a few of the ones we like best.
+
+=head1 MooseX::AttributeHelpers
+
+If you only look at one extension, it should be this one. The name
+isn't the best, but what it does it provide the equivalent of
+delegation for all of Perl's native data types, such as array
+reference, hash references, numbers, strings, etc.
+
+This lets you create I<much> cleaner and fluent APIs.
+
+ package User;
+
+ use Moose;
+ use MooseX::AttributeHelpers;
+
+ has '_orders' => (
+ metaclass => 'Collection::Array',
+ is => 'ro',
+ isa => 'ArrayRef',
+ default => sub { [] },
+ provides => {
+ push => 'add_order',
+ shift => 'next_order',
+ elements => 'orders',
+ },
+ );
+
+Instead of directly exposing an array reference, we have three
+well-named, easy to use methods.
+
+=head1 MooseX::StrictConstructor
+
+By default, Moose lets you pass any old junk into a class's
+constructor. If you load C<MooseX::StrictConstructor>, your class will
+throw an error if it sees something it doesn't recognize;
+
+ package User;
+
+ use Moose;
+ use MooseX::StrictConstructor;
+
+ has 'name';
+ has 'email';
+
+ User->new( name => 'Bob', emali => 'bob at example.com' );
+
+With C<MooseX::StrictConstructor>, that typo ("emali") will cause a
+runtime error. Otherwise, the "emali" attribute would just be silently
+ignored.
+
+=head1 MooseX::Params::Validate
+
+We have high hopes for the future of C<MooseX::Method::Signatures> and
+C<MooseX::Declare>. However, for now we recommend the decidely more
+clunky (but also faster and simpler) C<MooseX::Params::Validate>. This
+module lets you apply Moose types and coercions to any method
+arguments.
+
+ package User;
+
+ use Moose;
+ use MooseX::Params::Validate qw( validatep );
+
+ sub login {
+ my $self = shift;
+ my ($password)
+ = validatep( \@_, password => { isa => 'Str', required => 1 } );
+
+ ...
+ }
+
+=head1 MooseX::Getopt
+
+This is a role which adds a C<new_with_options> method to your
+class. This is a constructor that takes the command line options and
+uses them to populate attributes.
+
+Thia makes writing a command-line application as a module trivially
+simple:
+
+ package App::Foo;
+
+ use Moose;
+ with 'MooseX::Getopt';
+
+ has 'input' => (
+ is => 'ro',
+ isa => 'Str',
+ required => 1
+ );
+
+ has 'output' => (
+ is => 'ro',
+ isa => 'Str',
+ required => 1
+ );
+
+ sub run { ... }
+
+Then in the script that gets run we have:
+
+ use App::Foo;
+
+ App::Foo->new_with_options->run;
+
+=head1 MooseX::Singleton
+
+To be honest, using a singleton is often a hack, but it sure is a
+handy hack. C<MooseX::Singleton> lets you have a Moose class that's a
+singleton:
+
+ package Config;
+
+ use MooseX::Singleton; # instead of Moose
+
+ has 'cache_dir' => ( ... );
+
+It's that simple.
+
+=head1 EXTENSIONS TO CONSIDER
+
+There are literally dozens of other extensions on CPAN. These are a
+few to consider. We're not quite ready to recommend them outright,
+though. There's a couple reasons for this. One, they may be very
+specialized. Two, they may be immature. Three, they may not be quite
+right yet. Four, we may not all agree they're such a great idea.
+
+=head2 MooseX::Declare
+
+Extends Perl with Moose-based keywords using C<Devel::Declare>. Very
+cool, but still new and experimental.
+
+ class User {
+
+ has 'name' => ( ... );
+ has 'email' => ( ... );
+
+ method login (Str $password) { ... }
+ }
+
+=head2 MooseX::Types
+
+This extension helps you build a type library for your application. It
+also lets you pre-declare type names and use them as barewords.
+
+ use MooseX::Types -declare => ['PosInt'];
+ use MooseX::Types::Moose 'Int';
+
+ subtype PositiveInt
+ => as Int,
+ => where { $_ > 0 }
+ => message {"Int is not larger than 0"};
+
+One nice feature is the those bareword names are actually namespaces
+in Moose's type registry, so multiple applications can use the same
+bareword names, even if the type definitions differ.
+
+=head2 MooseX::Types::Structured
+
+This extension builds on top of C<MooseX::Types> to let you declare
+complex data structure types.
+
+ use MooseX::Types -declare => [ qw( Name Color ) ];
+ use MooseX::Types::Moose qw(Str Int);
+ use MooseX::Types::Structured qw(Dict Tuple Optional);
+
+ subtype Name
+ => as Dict[ first => Str, middle => Optional[Str], last => Str ];
+
+ subtype Color
+ => as Tuple[ Int, Int, Int, Optional[Int] ];
+
+Of course, you could always use objects to represent these sorts of
+things too.
+
+=head2 MooseX::ClassAttribute
+
+This extension provides class attributes for Moose classes. The
+declared class attributes are introspectable just like regular Moose
+attributes.
+
+ package User;
+
+ use Moose;
+ use MooseX::ClassAttribute;
+
+ has 'name' => ( ... );
+
+ class_has 'Cache' => ( ... );
+
+=head2 MooseX::Daemonize
+
+This is a role that provides a number of methods useful for creating a
+daemon, including methods for starting and stopping, managing a PID
+file, and signal handling.
+
+=head2 MooseX::Role::Parameterized
+
+If you find yourself wanting a role that customizes itself for each
+consumer, this is the tool for you. With this module, you can create a
+role that accepts parameters and generates attributes, methods, etc on
+a customized basis for each consumer.
+
+=head2 MooseX::POE
+
+This is a small wrapper that ties together a Moose class with
+C<POE::Session>, and gives you an C<event> sugar function to declare
+event handlers.
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch at urth.orgE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
Added: Moose/trunk/lib/Moose/Manual/Roles.pod
===================================================================
--- Moose/trunk/lib/Moose/Manual/Roles.pod (rev 0)
+++ Moose/trunk/lib/Moose/Manual/Roles.pod 2009-01-31 17:44:11 UTC (rev 7451)
@@ -0,0 +1,250 @@
+=pod
+
+=head1 NAME
+
+Moose::Manual::Roles - Roles, an Alternative to Deep Hierarchies and Base Classes
+
+=head1 WHAT IS A ROLE?
+
+A role is something that classes do. Usually, a role encapsulates some
+piece of behavior or state that can be shared between classes. It is
+important to understand that I<roles are not classes>. Roles do not
+participate in inheritance, and a role cannot be instantiated.
+
+Instead, a role is I<composed> into a class. In practical terms, this
+means that all of the methods and attributes defined in a role are
+added directly to (we sometimes say ("flattened into") the class that
+consumes the role. These attributes and methods then show up in the
+class as if they were defined directly in the class.
+
+Moose roles are similar to mixins or interfaces in other languages.
+
+Besides defining their own methods and attributes, roles can also
+require that the consuming class define certain methods of its
+own. You could have a role that consisted only of a list of required
+methods, in which case the role would be very much like a Java
+interface.
+
+=head1 A SIMPLE ROLE
+
+Creating a role looks a lot like creating a Moose class:
+
+ package Breakable;
+
+ use Moose::Role;
+
+ has 'is_broken' => (
+ is => 'rw',
+ isa => 'Bool',
+ );
+
+ sub break {
+ my $self = shift;
+
+ print "I broke\n";
+
+ $self->is_broken(1);
+ }
+
+Except for our use of C<Moose::Role>, this looks just like a class
+definition with Moose. However, this is not a class, and it cannot be
+instantiated.
+
+Instead, its attributes and methods will be composed into classes
+which use the role:
+
+ package Car;
+
+ use Moose;
+
+ with 'Breakable';
+
+ has 'engine' => (
+ is => 'ro',
+ isa => 'Engine',
+ );
+
+The C<with> function composes roles into a class. Once that is done,
+the C<Car> class has an C<is_broken> attribute and a C<break>
+method. The C<Car> class also C<does('Breakable')>:
+
+ my $car = Car->new( engine => Engine->new );
+
+ print $car->is_broken ? 'Still working' : 'Busted';
+ $car->break;
+ print $car->is_broken ? 'Still working' : 'Busted';
+
+ $car->does('Breakable'); # true
+
+This prints:
+
+ Still working
+ I broke
+ Busted
+
+We could use this same role in a C<Bone> class:
+
+ package Bone;
+
+ use Moose;
+
+ with 'Breakable';
+
+ has 'marrow' => (
+ is => 'ro',
+ isa => 'Marrow',
+ );
+
+=head1 REQUIRED METHODS
+
+As mentioned previously, a role can require that consuming classes
+provide one or more methods. Using our C<Breakable> example, let's
+make it require that consuming classes implement their own C<break>
+methods:
+
+ package Breakable;
+
+ use Moose::Role;
+
+ requires 'break';
+
+ has 'is_broken' => (
+ is => 'rw',
+ isa => 'Bool',
+ );
+
+ after 'break' => sub {
+ my $self = shift;
+
+ $self->is_broken(1);
+ };
+
+If we try to consume this role in a class that does not have a
+C<break> method, we will get an exception.
+
+Note that attribute-generated accessors do not satisfy the requirement
+that the named method exists. Similarly, a method modifier does not
+satisfy this requirement either. This may change in the future.
+
+You can also see that we added a method modifier on
+C<break>. Basically, we want consuming classes to implement their own
+logic for breaking, but we make sure that the C<is_broken> attribute
+is always set to true when C<break> is called.
+
+ package Car
+
+ use Moose;
+
+ with 'Breakable';
+
+ has 'engine' => (
+ is => 'ro',
+ isa => 'Engine',
+ );
+
+ sub break {
+ my $self = shift;
+
+ if ( $self->is_moving ) {
+ $self->stop;
+ }
+ }
+
+=head1 USING METHOD MODIFIERS
+
+Method modifiers and roles are a very powerful combination. Often, a
+role will combine method modifiers and required methods. We already
+saw one example with our C<Breakable> example.
+
+Method modifiers increase the complexity of roles, because they make
+the role application order relevant. If a class uses multiple roles,
+each of which modify the same method, those modifiers will be applied
+in the same order as the roles are used:
+
+ package MovieCar;
+
+ use Moose;
+
+ extends 'Car';
+
+ with 'Breakable', 'ExplodesOnBreakage';
+
+Assuming that the new C<ExplodesOnBreakage> method I<also> has an
+C<after> modifier on C<break>, the C<after> modifiers will run one
+after the other. The modifier from C<Breakable> will run first, then
+the one from C<ExplodesOnBreakage>.
+
+=head1 METHOD CONFLICTS
+
+If a class composes multiple roles, and those roles have methods of
+the same name, we will have a conflict. In that case, the composing
+class is required to provide its I<own> method of the same name.
+
+ package Breakdances;
+
+ use Moose::Role
+
+ sub break {
+
+ }
+
+If we compose both C<Breakable> and C<Breakdancer> in a class, we must
+provide our own C<break> method:
+
+ package FragileDancer;
+
+ use Moose;
+
+ with 'Breakable', 'Breakdancer';
+
+ sub break { ... }
+
+=head1 METHOD EXCLUSION AND ALIASING
+
+If we want our C<FragileDancer> class to be able to call the methods
+from both its roles, we can alias the methods:
+
+ package FragileDancer;
+
+ use Moose;
+
+ with 'Breakable' => { alias => { break => 'break_bone' } },
+ 'Breakdancer' => { alias => { break => 'break_dance' } };
+
+However, aliasing a method simply makes a I<copy> of the method with
+the new name. We also need to exclude the original name:
+
+ with 'Breakable' => {
+ alias => { break => 'break_bone' },
+ exclude => 'break',
+ },
+ 'Breakdancer' => {
+ alias => { break => 'break_dance' },
+ exclude => 'break',
+ };
+
+The exclude parameter prevents the C<break> method from being composed
+into the C<FragileDancer> class, so we don't have a conflict. This
+means that C<FragileDancer> does not need to implement its own
+C<break> method.
+
+This is useful, but it's worth noting that this breaks the contract
+implicit in consuming a role. Our C<FragileDancer> class does both the
+C<Breakable> and C<BreakDancer>, but does not provide a C<break>
+method. If some API expects an object that does one of those roles, it
+probably expects it to implement that method.
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch at urth.orgE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
Added: Moose/trunk/lib/Moose/Manual/Types.pod
===================================================================
--- Moose/trunk/lib/Moose/Manual/Types.pod (rev 0)
+++ Moose/trunk/lib/Moose/Manual/Types.pod 2009-01-31 17:44:11 UTC (rev 7451)
@@ -0,0 +1,431 @@
+=pod
+
+=head1 NAME
+
+Moose::Manual::Types - Moose's Type System
+
+=head1 TYPES IN PERL?
+
+Moose provides its own type system for your class's attributes. You
+can also use these types to validate method parameters with the help
+of some MooseX modules.
+
+Moose's type system is based on a combination of Perl 5's own
+I<implicit> types, and some Perl 6 concepts as well. But most
+importantly, you can easily create your own subtypes with custom
+constraints, making it easy to express any sort of validation.
+
+You can also name types and re-use them by name, making it easy to
+share types throughout a large application.
+
+Let us be clear that is not a "real" type system. Moose does not
+magically make Perl start associating types with variables. In many
+ways, this is really an advanced parameter checking system which
+allows you to associate a name with a constraintq.
+
+That said, it's still pretty damn useful, and we think it's one of the
+things that makes Moose both fun and powerful. Taking advantage of the
+type system makes it much easier to ensure that you are getting valid
+data, and it also contributes greatly to code maintainability.
+
+=head1 THE TYPES
+
+The basic Moose type hierarchy looks like this
+
+ Any
+ Item
+ Bool
+ Maybe[`a]
+ Undef
+ Defined
+ Value
+ Num
+ Int
+ Str
+ ClassName
+ Ref
+ ScalarRef
+ ArrayRef[`a]
+ HashRef[`a]
+ CodeRef
+ RegexpRef
+ GlobRef
+ FileHandle
+ Object
+ Role
+
+In practice, the only difference between C<Any> and C<Item> is
+conceptual. C<Item> is used as the top-level type in the hierarchy.
+
+The rest of these types correspond to existing Perl concepts. For
+example, a C<Num> is anything that Perl thinks looks like a number. An
+C<Object> is a blessed reference, etc.
+
+The types followed by "[`a]" can be parameterized. So instead of just
+plain C<ArrayRef> we can say that we want C<ArrayRef[Int]> instead. We
+can even do something like C<HashRef[ArrayRef[Str]]>.
+
+The C<Maybe[`a]> type deserves a special mention. Used by itself, it
+doesn't really mean anything (and is equivalent to C<Item>). When it
+is parameterized, it means that the value is either C<undef> or the
+parameterized type. So C<Maybe[Int]> means an integer or C<undef>
+
+For more details on the type hierarchy, see
+L<Moose::Util::TypeConstraints>.
+
+=head1 WHAT IS A TYPE?
+
+It's important to realize that types are not classes (or
+packages). Types are just objects (L<Moose::Meta::TypeConstraint>
+objects, to be exact) with a name. Moose maintains a global type
+registry that lets it convert names like "Num" into the appropriuate
+object.
+
+However, class names I<can be> type names. When you define a new class
+using Moose, it defines an associated type name behind the scenes:
+
+ package MyApp::User;
+
+ use Moose;
+
+Now you can use C<'MyApp::User'> as a type name:
+
+ has creator => (
+ is => 'rw',
+ isa => 'MyApp::User',
+ );
+
+However, for non-Moose classes there's no magic. You may have to
+explicitly declare the class type. This is a bit muddled because Moose
+assumes that any unknown type name passed as the C<isa> value for an
+attribute is a class. So this works:
+
+ has 'birth_date' => (
+ is => 'rw',
+ isa => 'DateTime',
+ );
+
+In general, when Moose is presented with an unknown name, it assumes
+that the name is a class:
+
+ subtype 'ModernDateTime'
+ => as 'DateTime'
+ => where { $_->year() >= 1980 }
+ => message { 'The date you provided is not modern enough' };
+
+ has 'valid_dates' => (
+ is => 'ro',
+ isa => 'ArrayRef[DateTime]',
+ );
+
+Moose will assume that "DateTime" is a class name and create a type
+accordingly.
+
+=head1 SUBTYPES
+
+Moose uses subtypes in its built-in hierarchy. C<Int> is a child of
+C<Num> for example.
+
+A subtype is defined in terms of a parent type and a constraint. Any
+constraints defined by the parent(s) will be checked first, and then
+the subtype's constraint is checked. A value must pass I<all> of these
+checks to be valid for the subtype.
+
+Generally, a subtype takes the parent's constraint and makes it more
+specific.
+
+A subtype can also define its own constraint failure message. This
+lets you do things like have an error "The value you provided (20),
+was not a valid rating, which must be a number from 1-10." This is
+much friendlier than the default error, which just says that the value
+failed a validation check for the type.
+
+Here's a simple (and useful) subtype example:
+
+ subtype 'PositiveInt'
+ => as 'Int'
+ => where { $_ > 0 }
+ => message { "The number you provided, $_, was not a positive number" }
+
+Note that the sugar functions for working with types are all exported
+by L<Moose::Util::TypeConstraints>.
+
+=head2 Creating a New Type (That Isn't a Subtype)
+
+You can also create new top-level types:
+
+ type 'FourCharacters' => where { defined $_ && length $_ == 4 };
+
+In practice, this example is pretty much the same as doing the same
+thing as a subtype of C<Str>, except you have to check defined-ness
+yourself.
+
+It's hard to find a case where you wouldn't want to subtype a very
+broad type like C<Defined>, C<Ref> or C<Object>.
+
+In practice, defining a new top-level type is conceptually the same as
+subtyping C<Item>.
+
+=head1 TYPE NAMES
+
+Type names are global throughout the current Perl
+interpreter. Internally, Moose maps names to type objects via
+L<Moose::Meta::TypeConstraint::Registry|registry> singleton.
+
+If you have multiple apps or libraries all using Moose in the same
+process, you could have problems with collisions. We recommend that
+you prefix names with some sort of namespace indicator to prevent
+these sorts of collisions.
+
+For example, instead of calling a type "PositiveInt", call it
+"MyApp.Type.PositiveInt".
+
+Type names are just strings, and can contain any character you
+want. We recommend that you I<do not> use "::" as a separator in type
+names. This can be very confusing, because class names are I<also>
+valid type names! Using something else, like a period, makes it clear
+that "MyApp::User" is a class and "MyApp.Type.PositiveInt" is a Moose
+type defined by your application.
+
+The C<MooseX::Types> module lets you create bareword aliases to longer
+names (really, the barewords are functions).
+
+=head1 COERCION
+
+One of the most powerful features of Moose's type system is its
+coercions. A coercion is a mapping between two types.
+
+ subtype 'ArrayRefOfInts'
+ => as 'ArrayRef[Int]';
+
+ coerce 'ArrayRefOfInts'
+ => from 'Int'
+ => via { [ $_ ] };
+
+You'll note that we had to create a subtype rather than coercing
+C<ArrayRef[Int]> directly. This is just a quirk of how Moose
+works.
+
+Coercions, like type names, are global. This is I<another> reason why
+it is good to namespace your types. Moose will I<never> try to coerce
+a value unless you explicitly ask for it. This is done by setting the
+C<coerce> attribute parameter to a true value:
+
+ package Foo;
+
+ has 'sizes' => (
+ is => 'rw',
+ isa => 'ArrayRefOfInts',
+ coerce => 1,
+ );
+
+ Foo->new( sizes => 42 );
+
+This code example will do the right thing, and the newly created
+object will have C<[ 42 ]> as its C<sizes> attribute.
+
+=head2 Deep Coercion
+
+Deep coercion is the coercion of type parameters for parameterized
+types. Let's take these types as an example:
+
+ subtype 'HexNum'
+ => as 'Str'
+ => where { /[a-f0-9]/i };
+
+ coerce 'Int'
+ => from 'HexNum'
+ => via { hex $_ };
+
+ has 'sizes' => (
+ is => 'rw',
+ isa => 'ArrayRef[Int]',
+ coerce => 1,
+ );
+
+If we try passing an array reference of hex numbers for the C<sizes>
+attribute, Moose will not do any coercion. The reason for this is that
+it gets very complicate very fast.
+
+However, if you want to, you can define a set of subtypes to enable
+coercion between two parameterized types.
+
+ subtype 'ArrayRefOfHexNums'
+ => as 'ArrayRef[HexNum]';
+
+ subtype 'ArrayRefOfInts'
+ => as 'ArrayRef[Int]';
+
+ coerce 'ArrayRefOfInts'
+ => from 'ArrayRefOfHexNums'
+ => via { [ map { hex } @{$_} ] };
+
+ Foo->new( sizes => [ 'a1', 'ff', '22' ] );
+
+Now Moose will coerce the hex numbers to integers.
+
+However, Moose does not attempt to chain coercions, so we cannot pass
+a single hex number. If we want to make that possible as well, we need
+to define yet another coercion:
+
+ coerce 'ArrayRefOfInts'
+ => from 'HexNum'
+ => via { [ hex $_ ] };
+
+Yes, this can all get verbose, but coercion is tricky magic, and we
+think it's best to make it as explicit as possible.
+
+=head1 TYPE UNIONS
+
+Moose allows you to say that an attribute can be of two or more
+disparate types. For example, we might allow an C<Object> or
+C<FileHandle>:
+
+ has 'output' => (
+ is => 'rw',
+ isa => 'Object | FileHandle',
+ );
+
+Moose actually parses that string and recognizes that you are creating
+a type union. The C<output> attribute will accept any sort of object,
+as well as an unblessed file handle. It is up to you to do the right
+thing for each of them in your code.
+
+Whenever you consider using a type union, you should think about
+whether or not coercion might be a better answer.
+
+For our example above, we might want to be more specific, and insist
+that output be an object with a C<print> method:
+
+ subtype 'CanPrint'
+ => as 'Object'
+ => where { $_->can('print') };
+
+We can coerce file handles to an object that satisfies this condition
+with a simple wrapper class:
+
+ package FHWrapper;
+
+ use Moose;
+
+ has 'handle' => (
+ is => 'ro',
+ isa => 'FileHandle',
+ );
+
+ sub print {
+ my $self = shift;
+ my $fh = $self->handle();
+
+ print $fh @_;
+ }
+
+Now we can define a coercion from C<FileHandle> to our wrapper class:
+
+ coerce 'FHWrapper'
+ => from 'FileHandle'
+ => via { FHWrapper->new( handle => $_ ) };
+
+ has 'output' => (
+ is => 'rw',
+ isa => 'CanPrint',
+ coerce => 1,
+ );
+
+This pattern, using a coercion instead of a type union, can help
+simplify the use of the attribute, and should be considered whenever
+you have a type union.
+
+=head1 TYPE CREATION HELPERS
+
+The L<Moose::Util::TypeConstraints> module exports a number of helper
+functions for creating specific kinds of types. These include
+C<class_type>, C<role_type>, and C<maybe_type>. See the docs for
+details.
+
+One helper worth noting is C<enum>, which allows you to create a
+subtype of C<Str> that only allows the specified values:
+
+ enum 'RGB' => qw( red green blue );
+
+This creates a type named C<RGB>
+
+=head1 ANONYMOUS TYPES
+
+All of the type creation functions return a type object. This type
+object can be used wherever you would use a type name, as a parent
+type, or as the value for an attribute's C<isa> parameter:
+
+ has 'size' => (
+ is => 'rw',
+ isa => subtype 'Int' => where { $_ > 0 },
+ );
+
+This is handy when you want to create a one-off type and don't want to
+"pollute" the global namespace registry.
+
+=head1 VALIDATING METHOD PARAMETERS
+
+Moose does not provide any means of validating method
+parameters. However, there are several MooseX extensions on CPAN which
+let you do this.
+
+The simplest and least sugary is C<MooseX::Params::Validate>. This
+lets you validate a set of named parameters using Moose types:
+
+ use Moose;
+ use MooseX::Params::Validate;
+
+ sub foo {
+ my $self = shift;
+ my %params = validate(
+ \@_,
+ bar => { isa => 'Str', default => 'Moose' },
+ );
+ ...
+ }
+
+C<MooseX::Params::Validate> also supports coercions.
+
+There are several more powerful extensions that support method
+parameter validation using Moose types, including
+C<MooseX::Method::Signatures>, which gives you a full-blown C<method>
+keyword.
+
+ method morning (Str $name) {
+ $self->say("Good morning ${name}!");
+ }
+
+=head1 LOAD ORDER ISSUES
+
+Because Moose types are defined at runtime, you can sometimes run into
+issues with load order. In particular, you may sometimes want to use a
+class's type constraint before it exists.
+
+We recommend several things. First, define I<all> of your custom types
+in one module, C<MyApp::Types>. Second, load this module in all of
+your other modules.
+
+If you are still having load order problems, you can make use of the
+C<find_type_constraint> function exported by
+L<Moose::Util::TypeConstraints>:
+
+ my $type = find_type_constraint('MyApp::User') || class_type('MyApp::User');
+
+This sort of "find or create" logic is simple to write, and will let
+you work around load order issues.
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch at urth.orgE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
Copied: Moose/trunk/lib/Moose/Manual.pod (from rev 6991, Moose/trunk/lib/Moose/Intro.pod)
===================================================================
--- Moose/trunk/lib/Moose/Manual.pod (rev 0)
+++ Moose/trunk/lib/Moose/Manual.pod 2009-01-31 17:44:11 UTC (rev 7451)
@@ -0,0 +1,238 @@
+=pod
+
+=head1 NAME
+
+Moose::Manual - What is Moose, and how do I use it?
+
+=head2 DESCRIPTION
+
+Go read L<Moose::Manual>. This POD document still exists for the
+benefit of anyone out there who might've linked to it in the past.
+
+Moose aims to do the same thing for Perl 5 OO. We can't actually
+create new keywords, but we do offer "sugar" that looks a lot like
+them. More importantly, with Moose, you I<declaratively define> your
+class, without needing to know about blessed hashrefs, accessor
+methods, and so on.
+
+Moose helps you define the I<logical> structure of your classes, so
+you can focus on "what" rather than "how". With Moose, a class
+definition reads like a list of very concise English sentences.
+
+Moose is built in top of C<Class::MOP>, a meta-object protocol (aka
+MOP). Using the MOP, Moose provides complete introspection for all
+Moose-using classes. This means you can ask classes about their
+attributes, parents, children, methods, etc., all using a well-defined
+API. The MOP abstracts away tedious digging about in the Perl symbol
+table, looking at C<@ISA> vars, and all the other crufty Perl tricks
+we know and love(?).
+
+Moose is based in large part on the Perl 6 object system, as well as
+drawing on the best ideas from CLOS, Smalltalk, and many other
+languages.
+
+=head1 WHY MOOSE?
+
+Moose makes Perl 5 OO both simpler and more powerful. It encapsulates
+all the tricks of Perl 5 power users in high-level declarative APIs
+which are easy to use, and doesn't require any special knowledge of
+how Perl works under the hood.
+
+If you want to dig about in the guts, Moose lets you do that too, by
+using and extending its powerful introspection API.
+
+=head1 AN EXAMPLE
+
+ package Person;
+
+ use Moose;
+
+ has 'first_name' => (
+ is => 'rw',
+ isa => 'Str',
+ );
+
+ has 'last_name' => (
+ is => 'rw',
+ isa => 'Str',
+ );
+
+ no Moose;
+ __PACKAGE__->meta->make_immutable;
+
+This is a I<complete and usable> class definition!
+
+ package User;
+
+ use DateTime;
+ use Moose;
+
+ extends 'Person';
+
+ has 'password' => (
+ is => 'rw',
+ isa => 'Str',
+ );
+
+ has 'last_login' => (
+ is => 'rw',
+ isa => 'DateTime',
+ handles => { 'date_of_last_login' => 'date' },
+ );
+
+ sub login {
+ my $self = shift;
+ my $pw = shift;
+
+ return 0 if $pw ne $self->password;
+
+ $self->last_login( DateTime->now() );
+
+ return 1;
+ }
+
+ no Moose;
+ __PACKAGE__->meta->make_immutable;
+
+We'll leave the line-by-line explanation of this code to other
+documentation, but you can see how Moose reduces common OO idioms to
+simple declarative constructs.
+
+=head2 TABLE OF CONTENTS
+
+This manual consists of a number of documents.
+
+=over 4
+
+=item L<Moose::Manual::Concepts>
+
+Introduces Moose concepts, and contrasts them against "old school"
+Perl 5 OO.
+
+=item L<Moose::Manual::Classes>
+
+How do you make use of Moose in your classes? Now that I'm a Moose,
+how do I subclass something?
+
+=item L<Moose::Manual::Attributes>
+
+Attributes are a core part of the Moose OO system. An attribute is a
+piece of data that an object has. Moose has a lot of attribute-related
+features!
+
+=item L<Moose::Manual::Delegation>
+
+Delegation is a powerful way to make use of attribute which are
+themselves objects.
+
+=item L<Moose::Manual::Construction>
+
+Learn how objects are built in Moose, and in particular about the
+C<BUILD>, C<BUILDARGS> methods. Also covers object destruction
+with C<DEMOLISH>.
+
+=item L<Moose::Manual::MethodModifiers>
+
+A method modifier lets you say "before calling method X, do this
+first", or "wrap method X in this code". Method modifiers are
+particularly handy in roles and with attribute accessors.
+
+=item L<Moose::Manual::Roles>
+
+A role is something a class does (like "Debuggable" or
+"Printable"). Roles provide a way of adding behavior to classes that
+is orthogonal to inheritance.
+
+=item L<Moose::Manual::Types>
+
+Moose's type system lets you strictly define what values an attribute
+can contain.
+
+=item L<Moose::Manual::MOP>
+
+Moose's meta API system lets you ask classes about their parents,
+children, methods, attributes, etc.
+
+=item L<Moose::Manual::MooseX>
+
+This document shows a few of the most useful Moose extensions on CPAN.
+
+=back
+
+=head1 JUSTIFICATION
+
+If you're still still asking yourself "Why do I need this?", then this
+section is for you.
+
+=over 4
+
+=item Another object system!?!?
+
+Yes, I know there are many, many ways to build objects in Perl 5, many
+of them based on inside-out objects and other such things. Moose is
+different because it is not a new object system for Perl 5, but
+instead an extension of the existing object system.
+
+Moose is built on top of L<Class::MOP>, which is a metaclass system
+for Perl 5. This means that Moose not only makes building normal
+Perl 5 objects better, but it also provides the power of metaclass
+programming.
+
+=item Is this for real? Or is this just an experiment?
+
+Moose is I<based> on the prototypes and experiments Stevan did for the
+Perl 6 meta-model. However, Moose is B<NOT> an experiment or
+prototype; it is for B<real>.
+
+=item Is this ready for use in production?
+
+Yes.
+
+Moose has been used successfully in production environments by many
+people and companies. There are Moose applications which have been in
+production with little or no issue now for well years. We consider it
+highly stable and we are commited to keeping it stable.
+
+Of course, in the end, you need to make this call yourself. If you
+have any questions or concerns, please feel free to email Stevan, the
+moose at perl.org list, or just stop by irc.perl.org#moose and ask away.
+
+=item Is Moose just Perl 6 in Perl 5?
+
+No. While Moose is very much inspired by Perl 6, it is not itself Perl
+6. Instead, it is an OO system for Perl 5. Stevan built Moose because
+he was tired of writing the same old boring Perl 5 OO code, and
+drooling over Perl 6 OO. So instead of switching to Ruby, he wrote
+Moose :)
+
+=item Wait, I<post> modern, I thought it was just I<modern>?
+
+Stevan read Larry Wall's talk from the 1999 Linux World entitled
+"Perl, the first postmodern computer language" in which he talks about
+how he picked the features for Perl because he thought they were cool
+and he threw out the ones that he thought sucked. This got him
+thinking about how we have done the same thing in Moose. For Moose, we
+have "borrowed" features from Perl 6, CLOS (LISP), Smalltalk, Java,
+BETA, OCaml, Ruby and more, and the bits we didn't like (cause they
+sucked) we tossed aside. So for this reason (and a few others) Stevan
+has re-dubbed Moose a I<postmodern> object system.
+
+Nuff Said.
+
+=back
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch at urth.orgE<gt> and Stevan Little
+E<lt>stevan at iinteractive.comE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
Modified: Moose/trunk/lib/Moose/Util/TypeConstraints.pm
===================================================================
--- Moose/trunk/lib/Moose/Util/TypeConstraints.pm 2009-01-31 17:42:48 UTC (rev 7450)
+++ Moose/trunk/lib/Moose/Util/TypeConstraints.pm 2009-01-31 17:44:11 UTC (rev 7451)
@@ -754,7 +754,7 @@
GlobRef
FileHandle
Object
- Role
+ Role
B<NOTE:> Any type followed by a type parameter C<[`a]> can be
parameterized, this means you can say:
@@ -785,7 +785,7 @@
Since the types created by this module are global, it is suggested
that you namespace your types just as you would namespace your
modules. So instead of creating a I<Color> type for your B<My::Graphics>
-module, you would call the type I<My::Graphics::Color> instead.
+module, you would call the type I<My.Graphics.Color> instead.
=head2 Use with Other Constraint Modules
Modified: Moose/trunk/lib/Moose.pm
===================================================================
--- Moose/trunk/lib/Moose.pm 2009-01-31 17:42:48 UTC (rev 7450)
+++ Moose/trunk/lib/Moose.pm 2009-01-31 17:44:11 UTC (rev 7451)
@@ -632,16 +632,6 @@
Class::MOP::Attribute|Class::MOP::Attribute/default> for more
information.
-=item I<initializer> => Str
-
-This may be a method name (referring to a method on the class with
-this attribute) or a CODE ref. The initializer is used to set the
-attribute value on an instance when the attribute is set during
-instance initialization (but not when the value is being assigned
-to). See the L<initializer option docs in
-Class::MOP::Attribute|Class::MOP::Attribute/initializer> for more
-information.
-
=item I<clearer> => Str
Allows you to clear the value, see the L<clearer option docs in
@@ -660,7 +650,16 @@
Automatically define lazy => 1 as well as builder => "_build_$attr", clearer =>
"clear_$attr', predicate => 'has_$attr' unless they are already defined.
+=item I<initializer> => Str
+This may be a method name (referring to a method on the class with
+this attribute) or a CODE ref. The initializer is used to set the
+attribute value on an instance when the attribute is set during
+instance initialization (but not when the value is being assigned
+to). See the L<initializer option docs in
+Class::MOP::Attribute|Class::MOP::Attribute/initializer> for more
+information.
+
=back
=item B<has +$name =E<gt> %options>
@@ -978,6 +977,18 @@
=back
+=head1 GETTING HELP
+
+We offer both a mailing list and a very active IRC channel.
+
+The mailing list is L<moose at perl.org>. You must be subscribed to send
+a message. To subscribe, send an empty message to
+L<moose-subscribe at perl.org>
+
+You can also visit us at L<#moose on
+irc.perl.org|irc://irc.perl.org/#moose>. This channel is quite active,
+and questions at all levels (on Moose-related topics ;) are welcome.
+
=head1 ACKNOWLEDGEMENTS
=over 4
@@ -1009,28 +1020,18 @@
as well as links to a number of talks and articles on Moose and Moose related
technologies.
-=item L<Moose::Cookbook> - How to cook a Moose
-
=item The Moose is flying, a tutorial by Randal Schwartz
Part 1 - L<http://www.stonehenge.com/merlyn/LinuxMag/col94.html>
Part 2 - L<http://www.stonehenge.com/merlyn/LinuxMag/col95.html>
-=item L<Class::MOP> documentation
+=item Several Moose extension modules in the C<MooseX::> namespace.
-=item L<Moose::Util::TypeConstraints> for information about type constraints.
+See L<http://search.cpan.org/search?query=MooseX::> for extensions.
-=item The #moose channel on irc.perl.org
-
-=item The Moose mailing list - moose at perl.org
-
=item Moose stats on ohloh.net - L<http://www.ohloh.net/projects/moose>
-=item Several Moose extension modules in the C<MooseX::> namespace.
-
-See L<http://search.cpan.org/search?query=MooseX::> for extensions.
-
=back
=head2 Books
More information about the Moose-commits
mailing list