Revision history for Perl extension Moose
0.41
+ ~~ numerous documentation updates ~~
+
** IMPORTANT NOTE **
- the make_immutable keyword is now deprecated, don't
use it in any new code and please fix your old code
setting defaults where appropriate, and performing any type constraint checking
or coercion.
-=head1 EXPORTED FUNCTIONS
+=head1 PROVIDED METHODS
-Moose will export a number of functions into the class's namespace which
-may then be used to set up the class. These functions all work directly
-on the current class.
+Moose provides a number of methods to all your classes, mostly through the
+inheritance of L<Moose::Object>. There is however, one exception.
=over 4
This is a method which provides access to the current class's metaclass.
+=back
+
+=head1 EXPORTED FUNCTIONS
+
+Moose will export a number of functions into the class's namespace which
+may then be used to set up the class. These functions all work directly
+on the current class.
+
+=over 4
+
=item B<extends (@superclasses)>
This function will set the superclass(es) for the current class.
=item B<with (@roles)>
-This will apply a given set of C<@roles> to the local class. Role support
-is currently under heavy development; see L<Moose::Role> for more details.
+This will apply a given set of C<@roles> to the local class.
=item B<has $name =E<gt> %options>
If you need more control over how your accessors are named, you can use the
I<reader>, I<writer> and I<accessor> options inherited from
-L<Class::MOP::Attribute>.
+L<Class::MOP::Attribute>, however if you use those, you won't need the I<is>
+option.
=item I<isa =E<gt> $type_name>
This tells the accessor whether to automatically dereference the value returned.
This is only legal if your C<isa> option is either C<ArrayRef> or C<HashRef>.
-=item I<metaclass =E<gt> $metaclass_name>
-
-This tells the class to use a custom attribute metaclass for this particular
-attribute. Custom attribute metaclasses are useful for extending the
-capabilities of the I<has> keyword: they are the simplest way to extend the MOP,
-but they are still a fairly advanced topic and too much to cover here. I will
-try and write a recipe on them soon.
-
-The default behavior here is to just load C<$metaclass_name>; however, we also
-have a way to alias to a shorter name. This will first look to see if
-B<Moose::Meta::Attribute::Custom::$metaclass_name> exists. If it does, Moose
-will then check to see if that has the method C<register_implementation>, which
-should return the actual name of the custom attribute metaclass. If there is no
-C<register_implementation> method, it will fall back to using
-B<Moose::Meta::Attribute::Custom::$metaclass_name> as the metaclass name.
-
=item I<trigger =E<gt> $code>
The I<trigger> option is a CODE reference which will be called after the value of
This is a pretty complex and powerful option. It accepts many different option
formats, each with its own benefits and drawbacks.
-B<NOTE:> This feature is no longer experimental, but it may still have subtle
-bugs lurking in the deeper corners. If you think you have found a bug, you
-probably have, so please report it to me right away.
-
B<NOTE:> The class being delegated to does not need to be a Moose based class,
which is why this feature is especially useful when wrapping non-Moose classes.
=back
+=item I<metaclass =E<gt> $metaclass_name>
+
+This tells the class to use a custom attribute metaclass for this particular
+attribute. Custom attribute metaclasses are useful for extending the
+capabilities of the I<has> keyword: they are the simplest way to extend the MOP,
+but they are still a fairly advanced topic and too much to cover here, see
+L<Moose::Cookbook::Recipe11> for more information.
+
+The default behavior here is to just load C<$metaclass_name>; however, we also
+have a way to alias to a shorter name. This will first look to see if
+B<Moose::Meta::Attribute::Custom::$metaclass_name> exists. If it does, Moose
+will then check to see if that has the method C<register_implementation>, which
+should return the actual name of the custom attribute metaclass. If there is no
+C<register_implementation> method, it will fall back to using
+B<Moose::Meta::Attribute::Custom::$metaclass_name> as the metaclass name.
+
+=item I<traits =E<gt> [ @role_names ]>
+
+This tells Moose to take the list of C<@role_names> and apply them to the
+attribute meta-object. This is very similar to the I<metaclass> option, but
+allows you to use more than one extension at a time. This too is an advanced
+topic, we don't yet have a cookbook for it though.
+
+As with I<metaclass>, the default behavior is to just load C<$role_name>; however,
+we also have a way to alias to a shorter name. This will first look to see if
+B<Moose::Meta::Attribute::Custom::Trait::$role_name> exists. If it does, Moose
+will then check to see if that has the method C<register_implementation>, which
+should return the actual name of the custom attribute trait. If there is no
+C<register_implementation> method, it will fall back to using
+B<Moose::Meta::Attribute::Custom::Trait::$metaclass_name> as the trait name.
+
=back
=item B<has +$name =E<gt> %options>
The keyword C<inner>, much like C<super>, is a no-op outside of the context of
an C<augment> method. You can think of C<inner> as being the inverse of
C<super>; the details of how C<inner> and C<augment> work is best described in
-the L<Moose::Cookbook>.
+the L<Moose::Cookbook::Recipe7>.
=item B<augment ($name, &sub)>
An C<augment> method, is a way of explicitly saying "I am augmenting this
method from my superclass". Once again, the details of how C<inner> and
-C<augment> work is best described in the L<Moose::Cookbook>.
+C<augment> work is best described in the L<Moose::Cookbook::Recipe7>.
=item B<confess>
This is the C<Carp::confess> function, and exported here because I use it
-all the time. This feature may change in the future, so you have been warned.
+all the time.
=item B<blessed>
their behavior is then easier to predict. Time will tell whether I am right or
not (UPDATE: so far so good).
+=item *
+
+It is important to note that we currently have no simple way of combining
+multiple extended versions of Moose (see L<EXTENDING AND EMBEDDING MOOSE> above),
+and that in many cases they will conflict with one another. We are working on
+developing a way around this issue, but in the meantime, you have been warned.
+
=back
=head1 ACKNOWLEDGEMENTS
=back
+=head2 Books
+
+=over 4
+
+=item The Art of the MetaObject Protocol
+
+I mention this in the L<Class::MOP> docs too, this book was critical in
+the development of both modules and is highly recommended.
+
+=back
+
=head2 Papers
=over 4
=head3 Is Moose "production ready"?
-Yes. I have three medium-to-large-ish web applications in
+Yes. I have several medium-to-large-ish web applications in
production using Moose, they have been running without
-issue now for almost a year.
+issue now for well over a year.
-At $work we are re-writing our core offering to use Moose,
+At C<$work> we are re-writing our core offering to use Moose,
so it's continued development is assured.
Several other people on #moose either have apps in production
available for getting the speed you need.
Currently we have the option of making your classes immutable
-as a means of boosting speed. This will mean a larger compile
+as a means of boosting speed. This will mean a slightly larger compile
time cost, but the runtime speed increase (especially in object
construction) is pretty significant. This is not very well
documented yet, so please ask on the list or on #moose for more
=head3 When will Moose 1.0 be ready?
-It is right now, I just haven't bumped the version number up yet.
-
-I still have some more internal TODO items I would like to complete
-before I would even consider bumping it to 1.0.
+It is right now, I declared 0.18 to be "ready to use".
=head2 Constructors
sub create_tps_report {
(shift)->append_body('<report type="tps"/>')
}
+
+ print TPSReport->new->create # <page><header/><report type="tps"/><footer/></page>
=head1 DESCRIPTION
=head1 DESCRIPTION
+B<NOTE:> This document is currently incomplete.
+
=head2 Components of a Role
=over 4
required C<foo> method, and **NOT** overriding C<foo>. This is an
important distinction to make.
+Now here is another example of a (correct) type of overriding, this
+time using the I<excludes> option.
+
+ package Role::Foo;
+ use Moose::Role;
+
+ sub foo { ... }
+
+ package Role::FooBar;
+ use Moose::Role;
+
+ with 'Role::Foo' => { excludes => 'foo' };
+
+ sub foo { ... }
+ sub bar { ... }
+
+By specifically excluding the C<foo> method during composition,
+we allow B<Role::FooBar> to define it's own version of C<foo>.
+
=back
=head1 SEE ALSO
=head1 DESCRIPTION
-This is a set of utility functions to help working with Moose classes. This
-is an experimental module, and it's not 100% clear what purpose it will serve.
-That said, ideas, suggestions and contributions to this collection are most
-welcome. See the L<TODO> section below for a list of ideas for possible
-functions to write.
+This is a set of utility functions to help working with Moose classes, and
+is used internally by Moose itself. The goal is to provide useful functions
+that for both Moose users and Moose extenders (MooseX:: authors).
+
+This is a relatively new addition to the Moose toolchest, so ideas,
+suggestions and contributions to this collection are most welcome.
+See the L<TODO> section below for a list of ideas for possible functions
+to write.
=head1 EXPORTED FUNCTIONS
inference is performed, expression are not typed, etc. etc. etc.
This is simply a means of creating small constraint functions which
-can be used to simplify your own type-checking code.
+can be used to simplify your own type-checking code, with the added
+side benefit of making your intentions clearer through self-documentation.
=head2 Slightly Less Important Caveat
-It is almost always a good idea to quote your type and subtype names.
+It is B<always> a good idea to quote your type and subtype names.
+
This is to prevent perl from trying to execute the call as an indirect
object call. This issue only seems to come up when you have a subtype
the same name as a valid class, but when the issue does arise it tends
=head2 Default Type Constraints
-This module also provides a simple hierarchy for Perl 5 types, this
-could probably use some work, but it works for me at the moment.
+This module also provides a simple hierarchy for Perl 5 types, here is
+that hierarchy represented visually.
Any
Item
Object
Role
-Suggestions for improvement are welcome.
-
B<NOTE:> Any type followed by a type parameter C<[`a]> can be
parameterized, this means you can say:
this type constraint to pass. I know this is not ideal for all,
but it is a saner restriction than most others.
+=head2 Type Constraint Naming
+
+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.
+
=head2 Use with Other Constraint Modules
This module should play fairly nicely with other constraint
modules with only some slight tweaking. The C<where> clause
in types is expected to be a C<CODE> reference which checks
-it's first argument and returns a bool. Since most constraint
+it's first argument and returns a boolean. Since most constraint
modules work in a similar way, it should be simple to adapt
them to work with Moose.
-keys => HasLength,
-values => IsArrayRef( IsObject ));
-For more examples see the F<t/204_example_w_DCS.t> test file.
+For more examples see the F<t/200_examples/204_example_w_DCS.t>
+test file.
Here is an example of using L<Test::Deep> and it's non-test
related C<eq_deeply> function.
})))
};
-For a complete example see the F<t/205_example_w_TestDeep.t>
-test file.
+For a complete example see the
+F<t/200_examples/205_example_w_TestDeep.t> test file.
=head1 FUNCTIONS
-=head2 Type Constraint Construction & Locating
-
-=over 4
-
-=item B<create_type_constraint_union ($pipe_seperated_types | @type_constraint_names)>
-
-Given string with C<$pipe_seperated_types> or a list of C<@type_constraint_names>,
-this will return a L<Moose::Meta::TypeConstraint::Union> instance.
-
-=item B<create_parameterized_type_constraint ($type_name)>
-
-Given a C<$type_name> in the form of:
-
- BaseType[ContainerType]
-
-this will extract the base type and container type and build an instance of
-L<Moose::Meta::TypeConstraint::Parameterized> for it.
-
-=item B<create_class_type_constraint ($class, ?$message)>
-
-Given a class name it will create a new L<Moose::Meta::TypeConstraint::Class>
-object for that class name.
-
-=item B<find_or_create_type_constraint ($type_name, ?$options_for_anon_type)>
-
-This will attempt to find or create a type constraint given the a C<$type_name>.
-If it cannot find it in the registry, it will see if it should be a union or
-container type an create one if appropriate, and lastly if nothing can be
-found or created that way, it will create an anon-type using the
-C<$options_for_anon_type> HASH ref to populate it. If the C<$options_for_anon_type>
-is not specified (it is C<undef>), then it will not create anything and simply
-return.
-
-=item B<find_type_constraint ($type_name)>
-
-This function can be used to locate a specific type constraint
-meta-object, of the class L<Moose::Meta::TypeConstraint> or a
-derivative. What you do with it from there is up to you :)
-
-=item B<register_type_constraint ($type_object)>
-
-This function will register a named type constraint with the type registry.
-
-=item B<get_type_constraint_registry>
-
-Fetch the L<Moose::Meta::TypeConstraint::Registry> object which
-keeps track of all type constraints.
-
-=item B<list_all_type_constraints>
-
-This will return a list of type constraint names, you can then
-fetch them using C<find_type_constraint ($type_name)> if you
-want to.
-
-=item B<list_all_builtin_type_constraints>
-
-This will return a list of builtin type constraints, meaning,
-those which are defined in this module. See the section
-labeled L<Default Type Constraints> for a complete list.
-
-=item B<export_type_constraints_as_functions>
-
-This will export all the current type constraints as functions
-into the caller's namespace. Right now, this is mostly used for
-testing, but it might prove useful to others.
-
-=item B<get_all_parameterizable_types>
-
-This returns all the parameterizable types that have been registered.
-
-=item B<add_parameterizable_type ($type)>
-
-Adds C<$type> to the list of parameterizable types
-
-=back
-
=head2 Type Constraint Constructors
The following functions are used to create type constraints.
=back
+=head2 Type Constraint Construction & Locating
+
+=over 4
+
+=item B<create_type_constraint_union ($pipe_seperated_types | @type_constraint_names)>
+
+Given string with C<$pipe_seperated_types> or a list of C<@type_constraint_names>,
+this will return a L<Moose::Meta::TypeConstraint::Union> instance.
+
+=item B<create_parameterized_type_constraint ($type_name)>
+
+Given a C<$type_name> in the form of:
+
+ BaseType[ContainerType]
+
+this will extract the base type and container type and build an instance of
+L<Moose::Meta::TypeConstraint::Parameterized> for it.
+
+=item B<create_class_type_constraint ($class, ?$message)>
+
+Given a class name it will create a new L<Moose::Meta::TypeConstraint::Class>
+object for that class name.
+
+=item B<find_or_create_type_constraint ($type_name, ?$options_for_anon_type)>
+
+This will attempt to find or create a type constraint given the a C<$type_name>.
+If it cannot find it in the registry, it will see if it should be a union or
+container type an create one if appropriate, and lastly if nothing can be
+found or created that way, it will create an anon-type using the
+C<$options_for_anon_type> HASH ref to populate it. If the C<$options_for_anon_type>
+is not specified (it is C<undef>), then it will not create anything and simply
+return.
+
+=item B<find_type_constraint ($type_name)>
+
+This function can be used to locate a specific type constraint
+meta-object, of the class L<Moose::Meta::TypeConstraint> or a
+derivative. What you do with it from there is up to you :)
+
+=item B<register_type_constraint ($type_object)>
+
+This function will register a named type constraint with the type registry.
+
+=item B<get_type_constraint_registry>
+
+Fetch the L<Moose::Meta::TypeConstraint::Registry> object which
+keeps track of all type constraints.
+
+=item B<list_all_type_constraints>
+
+This will return a list of type constraint names, you can then
+fetch them using C<find_type_constraint ($type_name)> if you
+want to.
+
+=item B<list_all_builtin_type_constraints>
+
+This will return a list of builtin type constraints, meaning,
+those which are defined in this module. See the section
+labeled L<Default Type Constraints> for a complete list.
+
+=item B<export_type_constraints_as_functions>
+
+This will export all the current type constraints as functions
+into the caller's namespace. Right now, this is mostly used for
+testing, but it might prove useful to others.
+
+=item B<get_all_parameterizable_types>
+
+This returns all the parameterizable types that have been registered.
+
+=item B<add_parameterizable_type ($type)>
+
+Adds C<$type> to the list of parameterizable types
+
+=back
+
=head2 Namespace Management
=over 4
=head1 DESCRIPTION
-This file contains the hand optimized versions of Moose type constraints.
+This file contains the hand optimized versions of Moose type constraints,
+no user serviceable parts inside.
=head1 FUNCTIONS
=head1 COPYRIGHT AND LICENSE
-Copyright 2006-2008 by Infinity Interactive, Inc.
+Copyright 2007-2008 by Infinity Interactive, Inc.
L<http://www.iinteractive.com>
use Sub::Exporter;
use Test::Builder;
+
use Moose::Util 'does_role', 'find_meta';
our $VERSION = '0.01';
=head1 COPYRIGHT AND LICENSE
-Copyright 2007 by Infinity Interactive, Inc.
+Copyright 2007-2008 by Infinity Interactive, Inc.
L<http://www.iinteractive.com>
package oose;
+
use strict;
use warnings;
projects / gitmo/Moose.git / commitdiff