diff --git a/.gitea/workflows/release.yaml b/.gitea/workflows/release.yaml index 7fb3d17..0e16251 100644 --- a/.gitea/workflows/release.yaml +++ b/.gitea/workflows/release.yaml @@ -20,7 +20,7 @@ jobs: with: go-version: '>=1.20.1' - name: Create zip file - run: zip -r YouTubeMusic.zip . -x .git*/ -x .vscode/ -x .git* -x repo.xml + run: zip -r YouTubeMusic.zip . -x ".git*" ".vscode/" repo.xml - name: Create repo.xml with sha run: | sha1=$(sha1sum YouTubeMusic.zip | cut -d ' ' -f1) && sed -i "s||$sha1|" repo.xml && echo "SHA: $sha1" diff --git a/CPAN/Moose.pm b/CPAN/Moose.pm new file mode 100644 index 0000000..c5c356d --- /dev/null +++ b/CPAN/Moose.pm @@ -0,0 +1,1268 @@ +use strict; +use warnings; +package Moose; # git description: 2.2206-2-ge01558bb6 +our $VERSION = '2.2207'; +our $AUTHORITY = 'cpan:STEVAN'; + +use 5.008003; + +use Scalar::Util (); +use Carp 'carp'; +use Module::Runtime 'module_notional_filename'; +use Class::Load 'is_class_loaded'; + +use Moose::Deprecated; +use Moose::Exporter; + +use Class::MOP; + +die "Class::MOP version $Moose::VERSION required--this is version $Class::MOP::VERSION" + if $Class::MOP::VERSION ne $Moose::VERSION; + +use Moose::Meta::Class; +use Moose::Meta::TypeConstraint; +use Moose::Meta::TypeCoercion; +use Moose::Meta::Attribute; +use Moose::Meta::Instance; + +use Moose::Object; + +use Moose::Meta::Role; +use Moose::Meta::Role::Composite; +use Moose::Meta::Role::Application; +use Moose::Meta::Role::Application::RoleSummation; +use Moose::Meta::Role::Application::ToClass; +use Moose::Meta::Role::Application::ToRole; +use Moose::Meta::Role::Application::ToInstance; + +use Moose::Util::TypeConstraints; +use Moose::Util 'throw_exception'; + +use Moose::Meta::Attribute::Native; + +sub extends { + my $meta = shift; + + unless ( @_ ) + { + throw_exception( ExtendsMissingArgs => class_name => $meta->name ); + } + # this checks the metaclass to make sure + # it is correct, sometimes it can get out + # of sync when the classes are being built + $meta->superclasses(@_); +} + +sub with { + Moose::Util::apply_all_roles(shift, @_); +} + +sub throw_error { + shift; + Class::MOP::Object->throw_error(@_); +} + +sub has { + my $meta = shift; + my $name = shift; + + my %context = Moose::Util::_caller_info; + $context{context} = 'has declaration'; + $context{type} = 'class'; + my @options = ( definition_context => \%context, @_ ); + my $attrs = ( ref($name) eq 'ARRAY' ) ? $name : [ ($name) ]; + $meta->add_attribute( $_, @options ) for @$attrs; +} + +sub before { + Moose::Util::add_method_modifier(shift, 'before', \@_); +} + +sub after { + Moose::Util::add_method_modifier(shift, 'after', \@_); +} + +sub around { + Moose::Util::add_method_modifier(shift, 'around', \@_); +} + +our $SUPER_PACKAGE; +our $SUPER_BODY; +our @SUPER_ARGS; + +sub super { + if (@_) { + carp 'Arguments passed to super() are ignored'; + } + + # This check avoids a recursion loop - see + # t/bugs/super_recursion.t + return if defined $SUPER_PACKAGE && $SUPER_PACKAGE ne caller(); + return unless $SUPER_BODY; $SUPER_BODY->(@SUPER_ARGS); +} + +sub override { + my $meta = shift; + my ( $name, $method ) = @_; + $meta->add_override_method_modifier( $name => $method ); +} + +sub inner { + my $pkg = caller(); + our ( %INNER_BODY, %INNER_ARGS ); + + if ( my $body = $INNER_BODY{$pkg} ) { + my @args = @{ $INNER_ARGS{$pkg} }; + local $INNER_ARGS{$pkg}; + local $INNER_BODY{$pkg}; + return $body->(@args); + } else { + return; + } +} + +sub augment { + my $meta = shift; + my ( $name, $method ) = @_; + $meta->add_augment_method_modifier( $name => $method ); +} + +Moose::Exporter->setup_import_methods( + with_meta => [ + qw( extends with has before after around override augment ) + ], + as_is => [ + qw( super inner ), + 'Carp::confess', + 'Scalar::Util::blessed', + ], +); + +sub init_meta { + shift; + my %args = @_; + + my $class = $args{for_class} + or throw_exception( InitMetaRequiresClass => params => \%args ); + + my $base_class = $args{base_class} || 'Moose::Object'; + my $metaclass = $args{metaclass} || 'Moose::Meta::Class'; + my $meta_name = exists $args{meta_name} ? $args{meta_name} : 'meta'; + + throw_exception( MetaclassNotLoaded => class_name => $metaclass ) + unless is_class_loaded($metaclass); + + throw_exception( MetaclassMustBeASubclassOfMooseMetaClass => class_name => $metaclass ) + unless $metaclass->isa('Moose::Meta::Class'); + + # make a subtype for each Moose class + class_type($class) + unless find_type_constraint($class); + + my $meta; + + if ( $meta = Class::MOP::get_metaclass_by_name($class) ) { + unless ( $meta->isa("Moose::Meta::Class") ) { + if ( $meta->isa('Moose::Meta::Role') ) { + throw_exception( MetaclassIsARoleNotASubclassOfGivenMetaclass => role_name => $class, + metaclass => $metaclass, + role => $meta + ); + } else { + throw_exception( MetaclassIsNotASubclassOfGivenMetaclass => class_name => $class, + metaclass => $metaclass, + class => $meta + ); + } + } + } else { + # no metaclass + + # now we check whether our ancestors have metaclass, and if so borrow that + my ( undef, @isa ) = @{ mro::get_linear_isa($class) }; + + foreach my $ancestor ( @isa ) { + my $ancestor_meta = Class::MOP::get_metaclass_by_name($ancestor) || next; + + my $ancestor_meta_class = $ancestor_meta->_real_ref_name; + + # if we have an ancestor metaclass that inherits $metaclass, we use + # that. This is like _fix_metaclass_incompatibility, but we can do it now. + + # the case of having an ancestry is not very common, but arises in + # e.g. Reaction + unless ( $metaclass->isa( $ancestor_meta_class ) ) { + if ( $ancestor_meta_class->isa($metaclass) ) { + $metaclass = $ancestor_meta_class; + } + } + } + + $meta = $metaclass->initialize($class); + my $filename = module_notional_filename($meta->name); + $INC{$filename} = '(set by Moose)' + unless exists $INC{$filename}; + } + + if (defined $meta_name) { + # also check for inherited non moose 'meta' method? + my $existing = $meta->get_method($meta_name); + if ($existing && !$existing->isa('Class::MOP::Method::Meta')) { + Carp::cluck "Moose is overwriting an existing method named " + . "$meta_name in class $class with a method " + . "which returns the class's metaclass. If this is " + . "actually what you want, you should remove the " + . "existing method, otherwise, you should rename or " + . "disable this generated method using the " + . "'-meta_name' option to 'use Moose'."; + } + $meta->_add_meta_method($meta_name); + } + + # make sure they inherit from Moose::Object + $meta->superclasses($base_class) + unless $meta->superclasses(); + + return $meta; +} + +# This may be used in some older MooseX extensions. +sub _get_caller { + goto &Moose::Exporter::_get_caller; +} + +## make 'em all immutable + +$_->make_immutable( + inline_constructor => 1, + constructor_name => "_new", + # these are Class::MOP accessors, so they need inlining + inline_accessors => 1 + ) for grep { $_->is_mutable } + map { $_->meta } + qw( + Moose::Meta::Attribute + Moose::Meta::Class + Moose::Meta::Instance + + Moose::Meta::TypeCoercion + Moose::Meta::TypeCoercion::Union + + Moose::Meta::Method + Moose::Meta::Method::Constructor + Moose::Meta::Method::Destructor + Moose::Meta::Method::Overridden + Moose::Meta::Method::Augmented + + Moose::Meta::Role + Moose::Meta::Role::Attribute + Moose::Meta::Role::Method + Moose::Meta::Role::Method::Required + Moose::Meta::Role::Method::Conflicting + + Moose::Meta::Role::Composite + + Moose::Meta::Role::Application + Moose::Meta::Role::Application::RoleSummation + Moose::Meta::Role::Application::ToClass + Moose::Meta::Role::Application::ToRole + Moose::Meta::Role::Application::ToInstance +); + +$_->make_immutable( + inline_constructor => 0, + constructor_name => undef, + # these are Class::MOP accessors, so they need inlining + inline_accessors => 1 + ) for grep { $_->is_mutable } + map { $_->meta } + qw( + Moose::Meta::Method::Accessor + Moose::Meta::Method::Delegation + Moose::Meta::Mixin::AttributeCore +); + +1; + +# ABSTRACT: A postmodern object system for Perl 5 + +__END__ + +=pod + +=encoding UTF-8 + +=head1 NAME + +Moose - A postmodern object system for Perl 5 + +=head1 VERSION + +version 2.2207 + +=head1 SYNOPSIS + + package Point; + use Moose; # automatically turns on strict and warnings + + has 'x' => (is => 'rw', isa => 'Int'); + has 'y' => (is => 'rw', isa => 'Int'); + + sub clear { + my $self = shift; + $self->x(0); + $self->y(0); + } + + package Point3D; + use Moose; + + extends 'Point'; + + has 'z' => (is => 'rw', isa => 'Int'); + + after 'clear' => sub { + my $self = shift; + $self->z(0); + }; + +=head1 DESCRIPTION + +Moose is an extension of the Perl 5 object system. + +The main goal of Moose is to make Perl 5 Object Oriented programming +easier, more consistent, and less tedious. With Moose you can think +more about what you want to do and less about the mechanics of OOP. + +Additionally, Moose is built on top of L, which is a +metaclass system for Perl 5. This means that Moose not only makes +building normal Perl 5 objects better, but it provides the power of +metaclass programming as well. + +=head2 New to Moose? + +If you're new to Moose, the best place to start is the +L docs, followed by the L. The intro +will show you what Moose is, and how it makes Perl 5 OO better. + +The cookbook recipes on Moose basics will get you up to speed with +many of Moose's features quickly. Once you have an idea of what Moose +can do, you can use the API documentation to get more detail on +features which interest you. + +=head2 Moose Extensions + +The C namespace is the official place to find Moose extensions. +These extensions can be found on the CPAN. The easiest way to find them +is to search for them (L), +or to examine L which aims to keep an up-to-date, easily +installable list of Moose extensions. + +=head1 TRANSLATIONS + +Much of the Moose documentation has been translated into other languages. + +=over 4 + +=item Japanese + +Japanese docs can be found at +L. The +source POD files can be found in GitHub: +L + +=back + +=head1 BUILDING CLASSES WITH MOOSE + +Moose makes every attempt to provide as much convenience as possible during +class construction/definition, but still stay out of your way if you want it +to. Here are a few items to note when building classes with Moose. + +When you C, Moose will set the class's parent class to +L, I the class using Moose already has a parent +class. In addition, specifying a parent with C will change the parent +class. + +Moose will also manage all attributes (including inherited ones) that are +defined with C. And (assuming you call C, which is inherited from +L) this includes properly initializing all instance slots, +setting defaults where appropriate, and performing any type constraint checking +or coercion. + +=head1 PROVIDED METHODS + +Moose provides a number of methods to all your classes, mostly through the +inheritance of L. There is however, one exception. By default, +Moose will install a method named C in any class which uses +C. This method returns the current class's metaclass. + +If you'd like to rename this method, you can do so by passing the +C<-meta_name> option when using Moose: + + use Moose -meta_name => 'my_meta'; + +However, the L class I provides a method named C +which does the same thing. If your class inherits from L (which +is the default), then you will still have a C method. However, if your +class inherits from a parent which provides a C method of its own, your +class will inherit that instead. + +If you'd like for Moose to not install a meta method at all, you can pass +C as the C<-meta_name> option: + + use Moose -meta_name => undef; + +Again, you will still inherit C from L in this case. + +=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. + +=head2 extends (@superclasses) + +This function will set the superclass(es) for the current class. If the parent +classes are not yet loaded, then C tries to load them. + +This approach is recommended instead of C>/C>, because +C actually Ces onto the class's C<@ISA>, whereas C will +replace it. This is important to ensure that classes which do not have +superclasses still properly inherit from L. + +Each superclass can be followed by a hash reference with options. Currently, +only L<-version|Class::MOP/Class Loading Options> is recognized: + + extends 'My::Parent' => { -version => 0.01 }, + 'My::OtherParent' => { -version => 0.03 }; + +An exception will be thrown if the version requirements are not +satisfied. + +=head2 with (@roles) + +This will apply a given set of C<@roles> to the local class. + +Like with C, each specified role can be followed by a hash +reference with a L<-version|Class::MOP/Class Loading Options> option: + + with 'My::Role' => { -version => 0.32 }, + 'My::Otherrole' => { -version => 0.23 }; + +The specified version requirements must be satisfied, otherwise an +exception will be thrown. + +If your role takes options or arguments, they can be passed along in the +hash reference as well. + +You should only use one C, even if you are consuming multiple roles. If +you consume roles using multiple C statements Moose cannot detect method +conflicts between those roles. + +=head2 has $name|@$names =E %options + +This will install an attribute of a given C<$name> into the current class. If +the first parameter is an array reference, it will create an attribute for +every C<$name> in the list. The C<%options> will be passed to the constructor +for L (which inherits from L), +so the full documentation for the valid options can be found there. These are +the most commonly used options: + +=over 4 + +=item I 'rw'|'ro'> + +The I option accepts either I (for read/write) or I (for read +only). These will create either a read/write accessor or a read-only +accessor respectively, using the same name as the C<$name> of the attribute. + +If you need more control over how your accessors are named, you can +use the L, +L and +L options inherited from +L, however if you use those, you won't need the +I option. + +=item I $type_name> + +The I option uses Moose's type constraint facilities to set up runtime +type checking for this attribute. Moose will perform the checks during class +construction, and within any accessors. The C<$type_name> argument must be a +string. The string may be either a class name or a type defined using +Moose's type definition features. (Refer to L +for information on how to define a new type, and how to retrieve type meta-data). + +=item I (1|0)> + +This will attempt to use coercion with the supplied type constraint to change +the value passed into any accessors or constructors. You B supply a type +constraint, and that type constraint B define a coercion. See +L for an example. + +=item I $role_name> + +This will accept the name of a role which the value stored in this attribute +is expected to have consumed. + +=item I (1|0)> + +This marks the attribute as being required. This means a value must be +supplied during class construction, I the attribute must be lazy +and have either a default or a builder. Note that C does not +say anything about the attribute's value, which can be C. + +=item I (1|0)> + +This will tell the class to store the value of this attribute as a weakened +reference. If an attribute is a weakened reference, it B also be +coerced. Note that when a weak ref expires, the attribute's value becomes +undefined, and is still considered to be set for purposes of predicate, +default, etc. + +=item I (1|0)> + +This will tell the class to not create this slot until absolutely necessary. +If an attribute is marked as lazy it B have a default or builder +supplied. + +=item I $code> + +The I option is a CODE reference which will be called after +the value of the attribute is set. The CODE ref is passed the +instance itself, the updated value, and the original value if the +attribute was already set. + +You B have a trigger on a read-only attribute. + +B Triggers will only fire when you B to the attribute, +either in the constructor, or using the writer. Default and built values will +B cause the trigger to be fired. + +=item I ARRAY | HASH | REGEXP | ROLE | ROLETYPE | DUCKTYPE | CODE> + +The I option provides Moose classes with automated delegation features. +This is a pretty complex and powerful option. It accepts many different option +formats, each with its own benefits and drawbacks. + +B 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. + +All I option formats share the following traits: + +You cannot override a locally defined method with a delegated method; an +exception will be thrown if you try. That is to say, if you define C in +your class, you cannot override it with a delegated C. This is almost never +something you would want to do, and if it is, you should do it by hand and not +use Moose. + +You cannot override any of the methods found in Moose::Object, or the C +and C methods. These will not throw an exception, but will silently +move on to the next method in the list. My reasoning for this is that you would +almost never want to do this, since it usually breaks your class. As with +overriding locally defined methods, if you do want to do this, you should do it +manually, not with Moose. + +You do not I to have a reader (or accessor) for the attribute in order +to delegate to it. Moose will create a means of accessing the value for you, +however this will be several times B efficient then if you had given +the attribute a reader (or accessor) to use. + +Below is the documentation for each option format: + +=over 4 + +=item C + +This is the most common usage for I. You basically pass a list of +method names to be delegated, and Moose will install a delegation method +for each one. + +=item C + +This is the second most common usage for I. Instead of a list of +method names, you pass a HASH ref where each key is the method name you +want installed locally, and its value is the name of the original method +in the class being delegated to. + +This can be very useful for recursive classes like trees. Here is a +quick example (soon to be expanded into a Moose::Cookbook recipe): + + package Tree; + use Moose; + + has 'node' => (is => 'rw', isa => 'Any'); + + has 'children' => ( + is => 'ro', + isa => 'ArrayRef', + default => sub { [] } + ); + + has 'parent' => ( + is => 'rw', + isa => 'Tree', + weak_ref => 1, + handles => { + parent_node => 'node', + siblings => 'children', + } + ); + +In this example, the Tree package gets C and C methods, +which delegate to the C and C methods (respectively) of the Tree +instance stored in the C slot. + +You may also use an array reference to curry arguments to the original method. + + has 'thing' => ( + ... + handles => { set_foo => [ set => 'foo' ] }, + ); + + # $self->set_foo(...) calls $self->thing->set('foo', ...) + +The first element of the array reference is the original method name, and the +rest is a list of curried arguments. + +=item C + +The regexp option works very similar to the ARRAY option, except that it builds +the list of methods for you. It starts by collecting all possible methods of the +class being delegated to, then filters that list using the regexp supplied here. + +B An I option is required when using the regexp option format. This +is so that we can determine (at compile time) the method list from the class. +Without an I this is just not possible. + +=item C or C + +With the role option, you specify the name of a role or a +L whose "interface" then becomes +the list of methods to handle. The "interface" can be defined as; the methods +of the role and any required methods of the role. It should be noted that this +does B include any method modifiers or generated attribute methods (which +is consistent with role composition). + +=item C + +With the duck type option, you pass a duck type object whose "interface" then +becomes the list of methods to handle. The "interface" can be defined as the +list of methods passed to C to create a duck type object. For more +information on C please check +L. + +=item C + +This is the option to use when you really want to do something funky. You should +only use it if you really know what you are doing, as it involves manual +metaclass twiddling. + +This takes a code reference, which should expect two arguments. The first is the +attribute meta-object this I is attached to. The second is the +metaclass of the class being delegated to. It expects you to return a hash (not +a HASH ref) of the methods you want mapped. + +=back + +=item I [ @role_names ]> + +This tells Moose to take the list of C<@role_names> and apply them to the +attribute meta-object. Custom attribute metaclass traits are useful for +extending the capabilities of the I 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 for details on how a trait name is +resolved to a role name. + +Also see L for a metaclass +trait example. + +=item I => Str + +The value of this key is the name of the method that will be called to obtain +the value used to initialize the attribute. See the L and/or +L for more +information. + +=item I => SCALAR | CODE + +The value of this key is the default value which will initialize the attribute. + +NOTE: If the value is a simple scalar (string or number), then it can +be just passed as is. However, if you wish to initialize it with a +HASH or ARRAY ref, then you need to wrap that inside a CODE reference. +See the L for more +information. + +=item I => Str + +Creates a method allowing you to clear the value. See the L for more +information. + +=item I => Str + +Creates a method to perform a basic test to see if a value has been set in the +attribute. See the L for more information. + +Note that the predicate will return true even for a C attribute +whose value has expired. + +=item I => $string + +An arbitrary string that can be retrieved later by calling C<< +$attr->documentation >>. + +=back + +=head2 has +$name =E %options + +This is variation on the normal attribute creator C which allows you to +clone and extend an attribute from a superclass or from a role. Here is an +example of the superclass usage: + + package Foo; + use Moose; + + has 'message' => ( + is => 'rw', + isa => 'Str', + default => 'Hello, I am a Foo' + ); + + package My::Foo; + use Moose; + + extends 'Foo'; + + has '+message' => (default => 'Hello I am My::Foo'); + +What is happening here is that B is cloning the C attribute +from its parent class B, retaining the C 'rw'> and C +'Str'> characteristics, but changing the value in C. + +Here is another example, but within the context of a role: + + package Foo::Role; + use Moose::Role; + + has 'message' => ( + is => 'rw', + isa => 'Str', + default => 'Hello, I am a Foo' + ); + + package My::Foo; + use Moose; + + with 'Foo::Role'; + + has '+message' => (default => 'Hello I am My::Foo'); + +In this case, we are basically taking the attribute which the role supplied +and altering it within the bounds of this feature. + +Note that you can only extend an attribute from either a superclass or a role, +you cannot extend an attribute in a role that composes over an attribute from +another role. + +Aside from where the attributes come from (one from superclass, the other +from a role), this feature works exactly the same. This feature is restricted +somewhat, so as to try and force at least I sanity into it. Most options work the same, but there are some exceptions: + +=over 4 + +=item I + +=item I + +=item I + +=item I + +=item I + +These options can be added, but cannot override a superclass definition. + +=item I + +You are allowed to B additional traits to the C definition. +These traits will be composed into the attribute, but preexisting traits +B overridden, or removed. + +=back + +=head2 before $name|@names|\@names|qr/.../ =E sub { ... } + +=head2 after $name|@names|\@names|qr/.../ =E sub { ... } + +=head2 around $name|@names|\@names|qr/.../ =E sub { ... } + +These three items are syntactic sugar for the before, after, and around method +modifier features that L provides. More information on these may be +found in L and the +L. + +=head2 override ($name, &sub) + +An C method is a way of explicitly saying "I am overriding this +method from my superclass". You can call C within this method, and +it will work as expected. The same thing I be accomplished with a normal +method call and the C pseudo-package; it is really your choice. + +=head2 super + +The keyword C is a no-op when called outside of an C method. In +the context of an C method, it will call the next most appropriate +superclass method with the same arguments as the original method. + +=head2 augment ($name, &sub) + +An C method, is a way of explicitly saying "I am augmenting this +method from my superclass". Once again, the details of how C and +C work is best described in the +L. + +=head2 inner + +The keyword C, much like C, is a no-op outside of the context of +an C method. You can think of C as being the inverse of +C; the details of how C and C work is best described in +the L. + +=head2 blessed + +This is the C function. It is highly recommended that +this is used instead of C anywhere you need to test for an object's class +name. + +=head2 confess + +This is the C function, and exported here for historical +reasons. + +=head1 METACLASS + +When you use Moose, you can specify traits which will be applied to your +metaclass: + + use Moose -traits => 'My::Trait'; + +This is very similar to the attribute traits feature. When you do +this, your class's C object will have the specified traits +applied to it. + +=head2 Metaclass and Trait Name Resolution + +By default, when given a trait name, Moose simply tries to load a +class of the same name. If such a class does not exist, it then looks +for a class matching +B. The C<$type> +variable here will be one of B or B, depending on +what the trait is being applied to. + +If a class with this long name exists, Moose checks to see if it has +the method C. This method is expected to +return the I class name of the trait. If there is no +C method, it will fall back to using +B as the trait name. + +The lookup method for metaclasses is the same, except that it looks +for a class matching B. + +If all this is confusing, take a look at +L, which demonstrates how to +create an attribute trait. + +=head1 UNIMPORTING FUNCTIONS + +=head2 B + +Moose offers a way to remove the keywords it exports, through the C +method. You simply have to say C at the bottom of your code for this +to work. Here is an example: + + package Person; + use Moose; + + has 'first_name' => (is => 'rw', isa => 'Str'); + has 'last_name' => (is => 'rw', isa => 'Str'); + + sub full_name { + my $self = shift; + $self->first_name . ' ' . $self->last_name + } + + no Moose; # keywords are removed from the Person package + +=head1 EXTENDING AND EMBEDDING MOOSE + +To learn more about extending Moose, we recommend checking out the +"Extending" recipes in the L, starting with +L, which provides an overview of +all the different ways you might extend Moose. L and +L are the modules which provide the majority of the +extension functionality, so reading their documentation should also be helpful. + +=head2 The MooseX:: namespace + +Generally if you're writing an extension I Moose itself you'll want +to put your extension in the C namespace. This namespace is +specifically for extensions that make Moose better or different in some +fundamental way. It is traditionally B for a package that just happens +to use Moose. This namespace follows from the examples of the C +and C namespaces that perform the same function for C and C +respectively. + +=head1 METACLASS COMPATIBILITY AND MOOSE + +Metaclass compatibility is a thorny subject. You should start by +reading the "About Metaclass compatibility" section in the +L docs. + +Moose will attempt to resolve a few cases of metaclass incompatibility +when you set the superclasses for a class, in addition to the cases that +L handles. + +Moose tries to determine if the metaclasses only "differ by roles". This +means that the parent and child's metaclass share a common ancestor in +their respective hierarchies, and that the subclasses under the common +ancestor are only different because of role applications. This case is +actually fairly common when you mix and match various C +modules, many of which apply roles to the metaclass. + +If the parent and child do differ by roles, Moose replaces the +metaclass in the child with a newly created metaclass. This metaclass +is a subclass of the parent's metaclass which does all of the roles that +the child's metaclass did before being replaced. Effectively, this +means the new metaclass does all of the roles done by both the +parent's and child's original metaclasses. + +Ultimately, this is all transparent to you except in the case of an +unresolvable conflict. + +=head1 CAVEATS + +It should be noted that C and C B be used in the same +method. However, they may be combined within the same class hierarchy; see +F for an example. + +The reason for this is that C is only valid within a method +with the C modifier, and C will never be valid within an +C method. In fact, C will skip over any C methods +when searching for its appropriate C. + +This might seem like a restriction, but I am of the opinion that keeping these +two features separate (yet interoperable) actually makes them easy to use, since +their behavior is then easier to predict. Time will tell whether I am right or +not (UPDATE: so far so good). + +=head1 GETTING HELP + +We offer both a mailing list and a very active IRC channel. + +The mailing list is L. You must be subscribed to send +a message. To subscribe, send an empty message to +L + +You can also visit us at C<#moose> on L +This channel is quite active, and questions at all levels (on Moose-related +topics ;) are welcome. + +=head1 WHAT DOES MOOSE STAND FOR? + +Moose doesn't stand for one thing in particular, however, if you want, here +are a few of our favorites. Feel free to contribute more! + +=over 4 + +=item * Make Other Object Systems Envious + +=item * Makes Object Orientation So Easy + +=item * Makes Object Orientation Spiffy- Er (sorry ingy) + +=item * Most Other Object Systems Emasculate + +=item * Moose Often Ovulate Sorta Early + +=item * Moose Offers Often Super Extensions + +=item * Meta Object Obligates Salivary Excitation + +=item * Meta Object Orientation Syntax Extensions + +=item * Moo, Only Overengineered, Slow, and Execrable (blame rjbs!) + +=item * Massive Object-Oriented Stacktrace Emitter + +=back + +=head1 ACKNOWLEDGEMENTS + +=over 4 + +=item I blame Sam Vilain for introducing me to the insanity that is meta-models. + +=item I blame Audrey Tang for then encouraging my meta-model habit in #perl6. + +=item Without Yuval "nothingmuch" Kogman this module would not be possible, +and it certainly wouldn't have this name ;P + +=item The basis of the TypeContraints module was Rob Kinyon's idea +originally, I just ran with it. + +=item Thanks to mst & chansen and the whole #moose posse for all the +early ideas/feature-requests/encouragement/bug-finding. + +=item Thanks to David "Theory" Wheeler for meta-discussions and spelling fixes. + +=back + +=head1 SEE ALSO + +=over 4 + +=item L + +This is the official web home of Moose. It contains links to our public git +repository, as well as links to a number of talks and articles on Moose and +Moose related technologies. + +=item the L + +This is an introduction to Moose which covers most of the basics. + +=item Modern Perl, by chromatic + +This is an introduction to modern Perl programming, which includes a section on +Moose. It is available in print and as a free download from +L. + +=item The Moose is flying, a tutorial by Randal Schwartz + +Part 1 - L + +Part 2 - L + +=item Several Moose extension modules in the C namespace. + +See L for extensions. + +=back + +=head2 Books + +=over 4 + +=item The Art of the MetaObject Protocol + +I mention this in the L docs too, as this book was critical in +the development of both modules and is highly recommended. + +=back + +=head2 Papers + +=over 4 + +=item L + +This paper (suggested by lbr on #moose) was what lead to the implementation +of the C/C and C/C features. If you really +want to understand them, I suggest you read this. + +=back + +=head1 BUGS + +All complex software has bugs lurking in it, and this module is no +exception. + +Please report any bugs to C, or through the web +interface at L. You can also submit a C test as a +pull request at L. + +You can also discuss feature requests or possible bugs on the Moose mailing +list (moose@perl.org) or on IRC at L. + +=head1 FEATURE REQUESTS + +We are very strict about what features we add to the Moose core, especially +the user-visible features. Instead we have made sure that the underlying +meta-system of Moose is as extensible as possible so that you can add your +own features easily. + +That said, occasionally there is a feature needed in the meta-system +to support your planned extension, in which case you should either +email the mailing list (moose@perl.org) or join us on IRC at +L to discuss. The +L has more detail about how and when you +can contribute. + +=head1 CABAL + +There are only a few people with the rights to release a new version +of Moose. The Moose Cabal are the people to go to with questions regarding +the wider purview of Moose. They help maintain not just the code +but the community as well. See the list below under L. + +=head1 CONTRIBUTORS + +Moose is a community project, and as such, involves the work of many, many +members of the community beyond just the members in the cabal. In particular: + +Dave (autarch) Rolsky wrote most of the documentation in L. + +John (jgoulah) Goulah wrote L. + +Jess (castaway) Robinson wrote L. + +Aran (bluefeet) Clary Deltac wrote +L. + +Anders (Debolaz) Nor Berle contributed L and L. + +Also, the code in L is based on code from the +L distribution, which had contributions from: + +Chris (perigrin) Prather + +Cory (gphat) Watson + +Evan Carroll + +Florian (rafl) Ragwitz + +Jason May + +Jay Hannah + +Jesse (doy) Luehrs + +Paul (frodwith) Driver + +Robert (rlb3) Boone + +Robert Buels + +Robert (phaylon) Sedlacek + +Shawn (Sartak) Moore + +Stevan Little + +Tom (dec) Lanyon + +Yuval Kogman + +Finally, these people also contributed various tests, bug fixes, +documentation, and features to the Moose codebase: + +Aankhen + +Adam (Alias) Kennedy + +Christian (chansen) Hansen + +Cory (gphat) Watson + +Dylan Hardison (doc fixes) + +Eric (ewilhelm) Wilhelm + +Evan Carroll + +Guillermo (groditi) Roditi + +Jason May + +Jay Hannah + +Jonathan (jrockway) Rockway + +Matt (mst) Trout + +Nathan (kolibrie) Gray + +Paul (frodwith) Driver + +Piotr (dexter) Roszatycki + +Robert Buels + +Robert (phaylon) Sedlacek + +Robert (rlb3) Boone + +Sam (mugwump) Vilain + +Scott (konobi) McWhirter + +Shlomi (rindolf) Fish + +Tom (dec) Lanyon + +Wallace (wreis) Reis + +... and many other #moose folks + +=head1 AUTHORS + +=over 4 + +=item * + +Stevan Little + +=item * + +Dave Rolsky + +=item * + +Jesse Luehrs + +=item * + +Shawn M Moore + +=item * + +יובל קוג'מן (Yuval Kogman) + +=item * + +Karen Etheridge + +=item * + +Florian Ragwitz + +=item * + +Hans Dieter Pearcey + +=item * + +Chris Prather + +=item * + +Matt S Trout + +=back + +=head1 COPYRIGHT AND LICENSE + +This software is copyright (c) 2006 by Infinity Interactive, Inc. + +This is free software; you can redistribute it and/or modify it under +the same terms as the Perl 5 programming language system itself. + +=cut diff --git a/CPAN/Moose/Conflicts.pm b/CPAN/Moose/Conflicts.pm new file mode 100644 index 0000000..011197d --- /dev/null +++ b/CPAN/Moose/Conflicts.pm @@ -0,0 +1,132 @@ +package # hide from PAUSE + Moose::Conflicts; + +use strict; +use warnings; + +# this module was generated with Dist::Zilla::Plugin::Conflicts 0.20 + +use Dist::CheckConflicts + -dist => 'Moose', + -conflicts => { + 'Catalyst' => '5.90049999', + 'Config::MVP' => '2.200004', + 'Devel::REPL' => '1.003020', + 'Dist::Zilla' => '5.043', + 'Dist::Zilla::Plugin::Git' => '2.016', + 'Fey' => '0.36', + 'Fey::ORM' => '0.42', + 'File::ChangeNotify' => '0.15', + 'HTTP::Throwable' => '0.017', + 'KiokuDB' => '0.51', + 'Markdent' => '0.16', + 'Mason' => '2.18', + 'Moose::Autobox' => '0.15', + 'MooseX::ABC' => '0.05', + 'MooseX::Aliases' => '0.08', + 'MooseX::AlwaysCoerce' => '0.13', + 'MooseX::App' => '1.22', + 'MooseX::Attribute::Deflator' => '2.1.7', + 'MooseX::Attribute::Dependent' => '1.1.3', + 'MooseX::Attribute::Prototype' => '0.10', + 'MooseX::AttributeHelpers' => '0.22', + 'MooseX::AttributeIndexes' => '1.0.0', + 'MooseX::AttributeInflate' => '0.02', + 'MooseX::CascadeClearing' => '0.03', + 'MooseX::ClassAttribute' => '0.26', + 'MooseX::Constructor::AllErrors' => '0.021', + 'MooseX::Declare' => '0.35', + 'MooseX::FollowPBP' => '0.02', + 'MooseX::Getopt' => '0.56', + 'MooseX::InstanceTracking' => '0.04', + 'MooseX::LazyRequire' => '0.06', + 'MooseX::Meta::Attribute::Index' => '0.04', + 'MooseX::Meta::Attribute::Lvalue' => '0.05', + 'MooseX::Method::Signatures' => '0.44', + 'MooseX::MethodAttributes' => '0.22', + 'MooseX::NonMoose' => '0.24', + 'MooseX::Object::Pluggable' => '0.0011', + 'MooseX::POE' => '0.214', + 'MooseX::Params::Validate' => '0.05', + 'MooseX::PrivateSetters' => '0.03', + 'MooseX::Role::Cmd' => '0.06', + 'MooseX::Role::Parameterized' => '1.00', + 'MooseX::Role::WithOverloading' => '0.14', + 'MooseX::Runnable' => '0.03', + 'MooseX::Scaffold' => '0.05', + 'MooseX::SemiAffordanceAccessor' => '0.05', + 'MooseX::SetOnce' => '0.100473', + 'MooseX::Singleton' => '0.25', + 'MooseX::SlurpyConstructor' => '1.1', + 'MooseX::Storage' => '0.42', + 'MooseX::StrictConstructor' => '0.12', + 'MooseX::Traits' => '0.11', + 'MooseX::Types' => '0.19', + 'MooseX::Types::Parameterizable' => '0.05', + 'MooseX::Types::Set::Object' => '0.03', + 'MooseX::Types::Signal' => '1.101930', + 'MooseX::UndefTolerant' => '0.11', + 'Net::Twitter' => '4.01041', + 'PRANG' => '0.14', + 'Pod::Elemental' => '0.093280', + 'Pod::Weaver' => '3.101638', + 'Reaction' => '0.002003', + 'Test::Able' => '0.10', + 'Test::CleanNamespaces' => '0.03', + 'Test::Moose::More' => '0.022', + 'Test::TempDir' => '0.05', + 'Throwable' => '0.102080', + 'namespace::autoclean' => '0.08', + }, + -also => [ qw( + Carp + Class::Load + Class::Load::XS + Data::OptList + Devel::GlobalDestruction + Devel::OverloadInfo + Devel::StackTrace + Dist::CheckConflicts + Eval::Closure + List::Util + MRO::Compat + Module::Runtime + Module::Runtime::Conflicts + Package::DeprecationManager + Package::Stash + Package::Stash::XS + Params::Util + Scalar::Util + Sub::Exporter + Sub::Util + Try::Tiny + parent + strict + warnings + ) ], + +; + +1; + +# ABSTRACT: Check for conflicts between Moose and installed packages +# Dist::Zilla: -PodWeaver + +__END__ + +=pod + +=for Pod::Coverage *EVERYTHING* + +=head1 NAME + +Moose::Conflicts - Check for conflicts between Moose and installed packages + +=head1 DESCRIPTION + +This module contains information about conflicts between this distribution and +other CPAN distributions. It does not have any user-facing parts. + +This module was generated by Dist::Zilla::Plugin::Conflicts 0.20. + +=cut diff --git a/CPAN/Moose/Cookbook.pod b/CPAN/Moose/Cookbook.pod new file mode 100644 index 0000000..9f669fc --- /dev/null +++ b/CPAN/Moose/Cookbook.pod @@ -0,0 +1,289 @@ +# PODNAME: Moose::Cookbook +# ABSTRACT: How to cook a Moose + +__END__ + +=pod + +=encoding UTF-8 + +=head1 NAME + +Moose::Cookbook - How to cook a Moose + +=head1 VERSION + +version 2.2207 + +=head1 DESCRIPTION + +The Moose cookbook is a series of recipes showing various Moose +features. Most recipes present some code demonstrating some feature, +and then explain the details of the code. + +You should probably read the L first. The manual +explains Moose concepts without being too code-heavy. + +=head1 RECIPES + +=head2 Basic Moose + +These recipes will give you a good overview of Moose's capabilities, starting +with simple attribute declaration, and moving on to more powerful features like +laziness, types, type coercion, method modifiers, and more. + +=over 4 + +=item L + +A simple Moose-based class. Demonstrates basic Moose attributes and subclassing. + +=item L + +A slightly more complex Moose class. Demonstrates using a method modifier in a +subclass. + +=item L + +Demonstrates several attribute features, including types, weak +references, predicates ("does this object have a foo?"), defaults, +laziness, and triggers. + +=item L + +Introduces the creation and use of custom types, a C method, and the +use of C in a subclass. This recipe also shows how to model a set of +classes that could be used to model companies, people, employees, etc. + +=item L + +This recipe covers more subtype creation, including the use of type coercions. + +=item L + +Making a class immutable greatly increases the speed of accessors and +object construction. + +=item L - Builder methods and lazy_build + +The builder feature provides an inheritable and role-composable way to +provide a default attribute value. + +=item L + +Demonstrates using operator overloading, coercion, and subtypes to +model how eye color is determined during reproduction. + +=item L + +This recipe demonstrates the use of C and C to hook +into object construction. + +=item L + +In this recipe, we make a Moose-based subclass of L, a +module which does not use Moose itself. + +=item L + +Demonstrates the use of C method modifiers, a way of turning +the usual method overriding style "inside-out". + +=back + +=head2 Moose Roles + +These recipes will show you how to use Moose roles. + +=over 4 + +=item L + +Demonstrates roles, which are also sometimes known as traits or +mix-ins. Roles provide a method of code re-use which is orthogonal to +subclassing. + +=item L + +Sometimes you just want to include part of a role in your +class. Sometimes you want the whole role but one of its methods +conflicts with one in your class. With method exclusion and aliasing, +you can work around these problems. + +=item L + +In this recipe, we apply a role to an existing object instance. + +=back + +=head2 Meta Moose + +These recipes show you how to write your own meta classes, which lets +you extend the object system provided by Moose. + +=over 4 + +=item L + +If you're wondering what all this "meta" stuff is, and why you should +care about it, read this "recipe". + +=item L + +Extending Moose's attribute metaclass is a great way to add +functionality. However, attributes can only have one metaclass. +Applying roles to the attribute metaclass lets you provide +composable attribute functionality. + +=item L + +This recipe takes the class metaclass we saw in the previous recipe +and reimplements it as a metaclass trait. + +=item L + +This recipe shows a custom method metaclass that implements making a +method private. + +=item L + +This recipe shows an example of how you create your own meta-instance +class. The meta-instance determines the internal structure of object +instances and provide access to attribute slots. + +In this particular instance, we use a blessed glob reference as the instance +instead of a blessed hash reference. + +=item Hooking into immutabilization (TODO) + +Moose has a feature known as "immutabilization". By calling C<< +__PACKAGE__->meta()->make_immutable() >> after defining your class +(attributes, roles, etc), you tell Moose to optimize things like +object creation, attribute access, and so on. + +If you are creating your own metaclasses, you may need to hook into +the immutabilization system. This cuts across a number of spots, +including the metaclass class, meta method classes, and possibly the +meta-instance class as well. + +This recipe shows you how to write extensions which immutabilize +properly. + +=back + +=head2 Extending Moose + +These recipes cover some more ways to extend Moose, and will be useful +if you plan to write your own C module. + +=over 4 + +=item L + +There are quite a few ways to extend Moose. This recipe provides an +overview of each method, and provides recommendations for when each is +appropriate. + +=item L + +Many base object class extensions can be implemented as roles. This +example shows how to provide a base object class debugging role that +is applied to any class that uses a notional C +module. + +=item L + +This recipe shows how to provide a replacement for C. You +may want to do this as part of the API for a C module, +especially if you want to default to a new metaclass class or base +object class. + +=back + +=head1 SNACKS + +=over 4 + +=item L + +=item L + +=back + +=head1 Legacy Recipes + +These cover topics that are no longer considered best practice. We've kept +them in case in you encounter these usages in the wild. + +=over 4 + +=item L + +=item L + +=item L + +=back + +=head1 SEE ALSO + +=over 4 + +=item L + +=back + +=head1 AUTHORS + +=over 4 + +=item * + +Stevan Little + +=item * + +Dave Rolsky + +=item * + +Jesse Luehrs + +=item * + +Shawn M Moore + +=item * + +יובל קוג'מן (Yuval Kogman) + +=item * + +Karen Etheridge + +=item * + +Florian Ragwitz + +=item * + +Hans Dieter Pearcey + +=item * + +Chris Prather + +=item * + +Matt S Trout + +=back + +=head1 COPYRIGHT AND LICENSE + +This software is copyright (c) 2006 by Infinity Interactive, Inc. + +This is free software; you can redistribute it and/or modify it under +the same terms as the Perl 5 programming language system itself. + +=cut diff --git a/CPAN/Moose/Cookbook/Basics/BankAccount_MethodModifiersAndSubclassing.pod b/CPAN/Moose/Cookbook/Basics/BankAccount_MethodModifiersAndSubclassing.pod new file mode 100644 index 0000000..6aa22dd --- /dev/null +++ b/CPAN/Moose/Cookbook/Basics/BankAccount_MethodModifiersAndSubclassing.pod @@ -0,0 +1,384 @@ +# PODNAME: Moose::Cookbook::Basics::BankAccount_MethodModifiersAndSubclassing +# ABSTRACT: Demonstrates the use of method modifiers in a subclass + +__END__ + +=pod + +=encoding UTF-8 + +=head1 NAME + +Moose::Cookbook::Basics::BankAccount_MethodModifiersAndSubclassing - Demonstrates the use of method modifiers in a subclass + +=head1 VERSION + +version 2.2207 + +=head1 SYNOPSIS + + package BankAccount; + use Moose; + + has 'balance' => ( isa => 'Int', is => 'rw', default => 0 ); + + sub deposit { + my ( $self, $amount ) = @_; + $self->balance( $self->balance + $amount ); + } + + sub withdraw { + my ( $self, $amount ) = @_; + my $current_balance = $self->balance(); + ( $current_balance >= $amount ) + || confess "Account overdrawn"; + $self->balance( $current_balance - $amount ); + } + + package CheckingAccount; + use Moose; + + extends 'BankAccount'; + + has 'overdraft_account' => ( isa => 'BankAccount', is => 'rw' ); + + before 'withdraw' => sub { + my ( $self, $amount ) = @_; + my $overdraft_amount = $amount - $self->balance(); + if ( $self->overdraft_account && $overdraft_amount > 0 ) { + $self->overdraft_account->withdraw($overdraft_amount); + $self->deposit($overdraft_amount); + } + }; + +=head1 DESCRIPTION + +The first recipe demonstrated how to build very basic Moose classes, +focusing on creating and manipulating attributes. The objects in that +recipe were very data-oriented, and did not have much in the way of +behavior (i.e. methods). In this recipe, we expand upon the concepts +from the first recipe to include some real behavior. In particular, we +show how you can use a method modifier to implement new behavior for a +method. + +The classes in the SYNOPSIS show two kinds of bank account. A simple +bank account has one attribute, the balance, and two behaviors, +depositing and withdrawing money. + +We then extend the basic bank account in the CheckingAccount +class. This class adds another attribute, an overdraft account. It +also adds overdraft protection to the withdraw method. If you try to +withdraw more than you have, the checking account attempts to +reconcile the difference by withdrawing money from the overdraft +account. (1) + +The first class, B, introduces a new attribute feature, a +default value: + + has 'balance' => ( isa => 'Int', is => 'rw', default => 0 ); + +This says that a B has a C attribute, which has +an C type constraint, a read/write accessor, and a default value +of C<0>. This means that every instance of B that is +created will have its C slot initialized to C<0>, unless some +other value is provided to the constructor. + +The C and C methods should be fairly +self-explanatory, as they are just plain old Perl 5 OO. (2) + +As you know from the first recipe, the keyword C sets a +class's superclass. Here we see that B C +B. The next line introduces yet another new attribute +feature, class-based type constraints: + + has 'overdraft_account' => ( isa => 'BankAccount', is => 'rw' ); + +Up until now, we have only seen the C type constraint, which (as +we saw in the first recipe) is a builtin type constraint. The +C type constraint is new, and was actually defined the +moment we created the B class itself. In fact, Moose +creates a corresponding type constraint for every class in your +program (3). + +This means that in the first recipe, constraints for both C and +C were created. In this recipe, both C and +C type constraints are created automatically. Moose +does this as a convenience so that your classes and type constraint +can be kept in sync with one another. In short, Moose makes sure that +it will just DWIM (4). + +In B, we see another method modifier, the C +modifier. + + before 'withdraw' => sub { + my ( $self, $amount ) = @_; + my $overdraft_amount = $amount - $self->balance(); + if ( $self->overdraft_account && $overdraft_amount > 0 ) { + $self->overdraft_account->withdraw($overdraft_amount); + $self->deposit($overdraft_amount); + } + }; + +Just as with the C modifier from the first recipe, Moose will +handle calling the superclass method (in this case C<< +BankAccount->withdraw >>). + +The C modifier will (obviously) run I the code from +the superclass is run. Here, C modifier implements overdraft +protection by first checking if there are available funds in the +checking account. If not (and if there is an overdraft account +available), it transfers the amount needed into the checking +account (5). + +As with the method modifier in the first recipe, we could use +C to get the same effect: + + sub withdraw { + my ( $self, $amount ) = @_; + my $overdraft_amount = $amount - $self->balance(); + if ( $self->overdraft_account && $overdraft_amount > 0 ) { + $self->overdraft_account->withdraw($overdraft_amount); + $self->deposit($overdraft_amount); + } + $self->SUPER::withdraw($amount); + } + +The benefit of taking the method modifier approach is we do not need +to remember to call C and pass it the C<$amount> +argument when writing C<< CheckingAccount->withdraw >>. + +This is actually more than just a convenience for forgetful +programmers. Using method modifiers helps isolate subclasses from +changes in the superclasses. For instance, if B<< +BankAccount->withdraw >> were to add an additional argument of some +kind, the version of B<< CheckingAccount->withdraw >> which uses +C would not pass that extra argument correctly, +whereas the method modifier version would automatically pass along all +arguments correctly. + +Just as with the first recipe, object instantiation uses the C +method, which accepts named parameters. + + my $savings_account = BankAccount->new( balance => 250 ); + + my $checking_account = CheckingAccount->new( + balance => 100, + overdraft_account => $savings_account, + ); + +And as with the first recipe, a more in-depth example can be found in +the F test file. + +=head1 CONCLUSION + +This recipe expanded on the basic concepts from the first recipe with +a more "real world" use case. + +=head1 FOOTNOTES + +=over 4 + +=item (1) + +If you're paying close attention, you might realize that there's a +circular loop waiting to happen here. A smarter example would have to +make sure that we don't accidentally create a loop between the +checking account and its overdraft account. + +=item (2) + +Note that for simple methods like these, which just manipulate some +single piece of data, it is often not necessary to write them at all. +For instance, C could be implemented via the C native +delegation for counters - see +L for more specifics, +and L for a broader overview. + +=item (3) + +In reality, this creation is sensitive to the order in which modules +are loaded. In more complicated cases, you may find that you need to +explicitly declare a class type before the corresponding class is +loaded. + +=item (4) + +Moose does not attempt to encode a class's is-a relationships within +the type constraint hierarchy. Instead, Moose just considers the class +type constraint to be a subtype of C, and specializes the +constraint check to allow for subclasses. This means that an instance +of B will pass a C type constraint +successfully. For more details, please refer to the +L documentation. + +=item (5) + +If the overdraft account does not have the amount needed, it will +throw an error. Of course, the overdraft account could also have +overdraft protection. See note 1. + +=back + +=head1 ACKNOWLEDGMENT + +The BankAccount example in this recipe is directly taken from the +examples in this chapter of "Practical Common Lisp": + +L + +=begin testing + +my $savings_account; + +{ + $savings_account = BankAccount->new( balance => 250 ); + isa_ok( $savings_account, 'BankAccount' ); + + is( $savings_account->balance, 250, '... got the right savings balance' ); + is( + exception { + $savings_account->withdraw(50); + }, + undef, + '... withdrew from savings successfully' + ); + is( $savings_account->balance, 200, + '... got the right savings balance after withdrawal' ); + + $savings_account->deposit(150); + is( $savings_account->balance, 350, + '... got the right savings balance after deposit' ); +} + +{ + my $checking_account = CheckingAccount->new( + balance => 100, + overdraft_account => $savings_account + ); + isa_ok( $checking_account, 'CheckingAccount' ); + isa_ok( $checking_account, 'BankAccount' ); + + is( $checking_account->overdraft_account, $savings_account, + '... got the right overdraft account' ); + + is( $checking_account->balance, 100, + '... got the right checkings balance' ); + + is( + exception { + $checking_account->withdraw(50); + }, + undef, + '... withdrew from checking successfully' + ); + is( $checking_account->balance, 50, + '... got the right checkings balance after withdrawal' ); + is( $savings_account->balance, 350, + '... got the right savings balance after checking withdrawal (no overdraft)' + ); + + is( + exception { + $checking_account->withdraw(200); + }, + undef, + '... withdrew from checking successfully' + ); + is( $checking_account->balance, 0, + '... got the right checkings balance after withdrawal' ); + is( $savings_account->balance, 200, + '... got the right savings balance after overdraft withdrawal' ); +} + +{ + my $checking_account = CheckingAccount->new( + balance => 100 + + # no overdraft account + ); + isa_ok( $checking_account, 'CheckingAccount' ); + isa_ok( $checking_account, 'BankAccount' ); + + is( $checking_account->overdraft_account, undef, + '... no overdraft account' ); + + is( $checking_account->balance, 100, + '... got the right checkings balance' ); + + is( + exception { + $checking_account->withdraw(50); + }, + undef, + '... withdrew from checking successfully' + ); + is( $checking_account->balance, 50, + '... got the right checkings balance after withdrawal' ); + + isnt( + exception { + $checking_account->withdraw(200); + }, + undef, + '... withdrawal failed due to attempted overdraft' + ); + is( $checking_account->balance, 50, + '... got the right checkings balance after withdrawal failure' ); +} + +=end testing + +=head1 AUTHORS + +=over 4 + +=item * + +Stevan Little + +=item * + +Dave Rolsky + +=item * + +Jesse Luehrs + +=item * + +Shawn M Moore + +=item * + +יובל קוג'מן (Yuval Kogman) + +=item * + +Karen Etheridge + +=item * + +Florian Ragwitz + +=item * + +Hans Dieter Pearcey + +=item * + +Chris Prather + +=item * + +Matt S Trout + +=back + +=head1 COPYRIGHT AND LICENSE + +This software is copyright (c) 2006 by Infinity Interactive, Inc. + +This is free software; you can redistribute it and/or modify it under +the same terms as the Perl 5 programming language system itself. + +=cut diff --git a/CPAN/Moose/Cookbook/Basics/BinaryTree_AttributeFeatures.pod b/CPAN/Moose/Cookbook/Basics/BinaryTree_AttributeFeatures.pod new file mode 100644 index 0000000..0cb2d29 --- /dev/null +++ b/CPAN/Moose/Cookbook/Basics/BinaryTree_AttributeFeatures.pod @@ -0,0 +1,397 @@ +# PODNAME: Moose::Cookbook::Basics::BinaryTree_AttributeFeatures +# ABSTRACT: Demonstrates various attribute features including lazy, predicates, weak refs, and more + +__END__ + +=pod + +=encoding UTF-8 + +=head1 NAME + +Moose::Cookbook::Basics::BinaryTree_AttributeFeatures - Demonstrates various attribute features including lazy, predicates, weak refs, and more + +=head1 VERSION + +version 2.2207 + +=head1 SYNOPSIS + + package BinaryTree; + use Moose; + + has 'node' => ( is => 'rw', isa => 'Any' ); + + has 'parent' => ( + is => 'rw', + isa => 'BinaryTree', + predicate => 'has_parent', + weak_ref => 1, + ); + + has 'left' => ( + is => 'rw', + isa => 'BinaryTree', + predicate => 'has_left', + lazy => 1, + default => sub { BinaryTree->new( parent => $_[0] ) }, + trigger => \&_set_parent_for_child + ); + + has 'right' => ( + is => 'rw', + isa => 'BinaryTree', + predicate => 'has_right', + lazy => 1, + default => sub { BinaryTree->new( parent => $_[0] ) }, + trigger => \&_set_parent_for_child + ); + + sub _set_parent_for_child { + my ( $self, $child ) = @_; + + confess "You cannot insert a tree which already has a parent" + if $child->has_parent; + + $child->parent($self); + } + +=head1 DESCRIPTION + +This recipe shows how various advanced attribute features can be used +to create complex and powerful behaviors. In particular, we introduce +a number of new attribute options, including C, C, +and C. + +The example class is a classic binary tree. Each node in the tree is +itself an instance of C. It has a C, which holds +some arbitrary value. It has C and C attributes, which +refer to its child trees, and a C. + +Let's take a look at the C attribute: + + has 'node' => ( is => 'rw', isa => 'Any' ); + +Moose generates a read-write accessor for this attribute. The type +constraint is C, which literally means it can contain anything. + +We could have left out the C option, but in this case, we are +including it for the benefit of other programmers, not the computer. + +Next, let's move on to the C attribute: + + has 'parent' => ( + is => 'rw', + isa => 'BinaryTree', + predicate => 'has_parent', + weak_ref => 1, + ); + +Again, we have a read-write accessor. This time, the C option +says that this attribute must always be an instance of +C. In the second recipe, we saw that every time we create +a Moose-based class, we also get a corresponding class type +constraint. + +The C option is new. It creates a method which can be used +to check whether or not a given attribute has been initialized. In +this case, the method is named C. + +This brings us to our last attribute option, C. Since +C is a circular reference (the tree in C should +already have a reference to this one, in its C or C +attribute), we want to make sure that we weaken the reference to avoid +memory leaks. If C is true, it alters the accessor function +so that the reference is weakened when it is set. + +Finally, we have the C and C attributes. They are +essentially identical except for their names, so we'll just look at +C: + + has 'left' => ( + is => 'rw', + isa => 'BinaryTree', + predicate => 'has_left', + lazy => 1, + default => sub { BinaryTree->new( parent => $_[0] ) }, + trigger => \&_set_parent_for_child + ); + +There are three new options here, C, C, and +C. The C and C options are linked. In fact, +you cannot have a C attribute unless it has a C +(or a C, but we'll cover that later). If you try to make an +attribute lazy without a default, class creation will fail with an +exception. (2) + +In the second recipe the B's C attribute had a +default value of C<0>. Given a non-reference, Perl copies the +I. However, given a reference, it does not do a deep clone, +instead simply copying the reference. If you just specified a simple +reference for a default, Perl would create it once and it would be +shared by all objects with that attribute. + +As a workaround, we use an anonymous subroutine to generate a new +reference every time the default is called. + + has 'foo' => ( is => 'rw', default => sub { [] } ); + +In fact, using a non-subroutine reference as a default is illegal in Moose. + + # will fail + has 'foo' => ( is => 'rw', default => [] ); + +This will blow up, so don't do it. + +You'll notice that we use C<$_[0]> in our default sub. When the +default subroutine is executed, it is called as a method on the +object. + +In our case, we're making a new C object in our default, +with the current tree as the parent. + +Normally, when an object is instantiated, any defaults are evaluated +immediately. With our C class, this would be a big +problem! We'd create the first object, which would immediately try to +populate its C and C attributes, which would create a new +C, which would populate I C and C +slots. Kaboom! + +By making our C and C attributes C, we avoid this +problem. If the attribute has a value when it is read, the default is +never executed at all. + +We still have one last bit of behavior to add. The autogenerated +C and C accessors are not quite correct. When one of +these is set, we want to make sure that we update the parent of the +C or C attribute's tree. + +We could write our own accessors, but then why use Moose at all? +Instead, we use a C. A C accepts a subroutine +reference, which will be called as a method whenever the attribute is +set. This can happen both during object construction or later by +passing a new object to the attribute's accessor method. However, it +is not called when a value is provided by a C or C. + + sub _set_parent_for_child { + my ( $self, $child ) = @_; + + confess "You cannot insert a tree which already has a parent" + if $child->has_parent; + + $child->parent($self); + } + +This trigger does two things. First, it ensures that the new child +node does not already have a parent. This is done for the sake of +simplifying the example. If we wanted to be more clever, we would +remove the child from its old parent tree and add it to the new one. + +If the child has no parent, we will add it to the current tree, and we +ensure that is has the correct value for its C attribute. + +As with all the other recipes, B can be used just like any +other Perl 5 class. A more detailed example of its usage can be found +in F. + +=head1 CONCLUSION + +This recipe introduced several of Moose's advanced features. We hope +that this inspires you to think of other ways these features can be +used to simplify your code. + +=head1 FOOTNOTES + +=over 4 + +=item (1) + +Weak references are tricky things, and should be used sparingly and +appropriately (such as in the case of circular refs). If you are not +careful, attribute values could disappear "mysteriously" because +Perl's reference counting garbage collector has gone and removed the +item you are weak-referencing. + +In short, don't use them unless you know what you are doing :) + +=item (2) + +You I use the C option without the C option if you +like, as we showed in the second recipe. + +Also, you can use C instead of C. See +L for details. + +=back + +=begin testing + +use Scalar::Util 'isweak'; + +my $root = BinaryTree->new(node => 'root'); +isa_ok($root, 'BinaryTree'); + +is($root->node, 'root', '... got the right node value'); + +ok(!$root->has_left, '... no left node yet'); +ok(!$root->has_right, '... no right node yet'); + +ok(!$root->has_parent, '... no parent for root node'); + +# make a left node + +my $left = $root->left; +isa_ok($left, 'BinaryTree'); + +is($root->left, $left, '... got the same node (and it is $left)'); +ok($root->has_left, '... we have a left node now'); + +ok($left->has_parent, '... lefts has a parent'); +is($left->parent, $root, '... lefts parent is the root'); + +ok(isweak($left->{parent}), '... parent is a weakened ref'); + +ok(!$left->has_left, '... $left no left node yet'); +ok(!$left->has_right, '... $left no right node yet'); + +is($left->node, undef, '... left has got no node value'); + +is( + exception { + $left->node('left'); + }, + undef, + '... assign to lefts node' +); + +is($left->node, 'left', '... left now has a node value'); + +# make a right node + +ok(!$root->has_right, '... still no right node yet'); + +is($root->right->node, undef, '... right has got no node value'); + +ok($root->has_right, '... now we have a right node'); + +my $right = $root->right; +isa_ok($right, 'BinaryTree'); + +is( + exception { + $right->node('right'); + }, + undef, + '... assign to rights node' +); + +is($right->node, 'right', '... left now has a node value'); + +is($root->right, $right, '... got the same node (and it is $right)'); +ok($root->has_right, '... we have a right node now'); + +ok($right->has_parent, '... rights has a parent'); +is($right->parent, $root, '... rights parent is the root'); + +ok(isweak($right->{parent}), '... parent is a weakened ref'); + +# make a left node of the left node + +my $left_left = $left->left; +isa_ok($left_left, 'BinaryTree'); + +ok($left_left->has_parent, '... left does have a parent'); + +is($left_left->parent, $left, '... got a parent node (and it is $left)'); +ok($left->has_left, '... we have a left node now'); +is($left->left, $left_left, '... got a left node (and it is $left_left)'); + +ok(isweak($left_left->{parent}), '... parent is a weakened ref'); + +# make a right node of the left node + +my $left_right = BinaryTree->new; +isa_ok($left_right, 'BinaryTree'); + +is( + exception { + $left->right($left_right); + }, + undef, + '... assign to rights node' +); + +ok($left_right->has_parent, '... left does have a parent'); + +is($left_right->parent, $left, '... got a parent node (and it is $left)'); +ok($left->has_right, '... we have a left node now'); +is($left->right, $left_right, '... got a left node (and it is $left_left)'); + +ok(isweak($left_right->{parent}), '... parent is a weakened ref'); + +# and check the error + +isnt( + exception { + $left_right->right($left_left); + }, + undef, + '... cannot assign a node which already has a parent' +); + +=end testing + +=head1 AUTHORS + +=over 4 + +=item * + +Stevan Little + +=item * + +Dave Rolsky + +=item * + +Jesse Luehrs + +=item * + +Shawn M Moore + +=item * + +יובל קוג'מן (Yuval Kogman) + +=item * + +Karen Etheridge + +=item * + +Florian Ragwitz + +=item * + +Hans Dieter Pearcey + +=item * + +Chris Prather + +=item * + +Matt S Trout + +=back + +=head1 COPYRIGHT AND LICENSE + +This software is copyright (c) 2006 by Infinity Interactive, Inc. + +This is free software; you can redistribute it and/or modify it under +the same terms as the Perl 5 programming language system itself. + +=cut diff --git a/CPAN/Moose/Cookbook/Basics/BinaryTree_BuilderAndLazyBuild.pod b/CPAN/Moose/Cookbook/Basics/BinaryTree_BuilderAndLazyBuild.pod new file mode 100644 index 0000000..8aba402 --- /dev/null +++ b/CPAN/Moose/Cookbook/Basics/BinaryTree_BuilderAndLazyBuild.pod @@ -0,0 +1,176 @@ +# PODNAME: Moose::Cookbook::Basics::BinaryTree_BuilderAndLazyBuild +# ABSTRACT: Builder methods and lazy_build + +__END__ + +=pod + +=encoding UTF-8 + +=head1 NAME + +Moose::Cookbook::Basics::BinaryTree_BuilderAndLazyBuild - Builder methods and lazy_build + +=head1 VERSION + +version 2.2207 + +=head1 SYNOPSIS + + package BinaryTree; + use Moose; + + has 'node' => (is => 'rw', isa => 'Any'); + + has 'parent' => ( + is => 'rw', + isa => 'BinaryTree', + predicate => 'has_parent', + weak_ref => 1, + ); + + has 'left' => ( + is => 'rw', + isa => 'BinaryTree', + predicate => 'has_left', + lazy => 1, + builder => '_build_child_tree', + ); + + has 'right' => ( + is => 'rw', + isa => 'BinaryTree', + predicate => 'has_right', + lazy => 1, + builder => '_build_child_tree', + ); + + before 'right', 'left' => sub { + my ($self, $tree) = @_; + $tree->parent($self) if defined $tree; + }; + + sub _build_child_tree { + my $self = shift; + + return BinaryTree->new( parent => $self ); + } + +=head1 DESCRIPTION + +If you've already read +L, then this example +should look very familiar. In fact, all we've done here is replace the +attribute's C parameter with a C. + +In this particular case, the C and C options act in +exactly the same way. When the C or C attribute is read, +Moose calls the builder method to initialize the attribute. + +Note that Moose calls the builder method I. Here's an example: + + my $tree = BinaryTree->new(); + + my $left = $tree->left(); + +When C<< $tree->left() >> is called, Moose calls C<< +$tree->_build_child_tree() >> in order to populate the C +attribute. If we had passed C to the original constructor, the +builder would not be called. + +There are some differences between C and C. Notably, +a builder is subclassable, and can be composed from a role. See +L for more details. + +=head2 The lazy_build shortcut + +The C attribute option can be used as sugar to specify +a whole set of attribute options at once: + + has 'animal' => ( + is => 'ro', + isa => 'Animal', + lazy_build => 1, + ); + +This is a shorthand for: + + has 'animal' => ( + is => 'ro', + isa => 'Animal', + required => 1, + lazy => 1, + builder => '_build_animal', + predicate => 'has_animal', + clearer => 'clear_animal', + ); + +If your attribute starts with an underscore, Moose is smart and will +do the right thing with the C and C, making them +both start with an underscore. The C method I starts +with an underscore. + +You can read more about C in L + +=head1 CONCLUSION + +The C option is a more OO-friendly version of the C +functionality. It also separates the default-generating code into a +well-defined method. Sprinkling your attribute definitions with +anonymous subroutines can be quite ugly and hard to follow. + +=head1 AUTHORS + +=over 4 + +=item * + +Stevan Little + +=item * + +Dave Rolsky + +=item * + +Jesse Luehrs + +=item * + +Shawn M Moore + +=item * + +יובל קוג'מן (Yuval Kogman) + +=item * + +Karen Etheridge + +=item * + +Florian Ragwitz + +=item * + +Hans Dieter Pearcey + +=item * + +Chris Prather + +=item * + +Matt S Trout + +=back + +=head1 COPYRIGHT AND LICENSE + +This software is copyright (c) 2006 by Infinity Interactive, Inc. + +This is free software; you can redistribute it and/or modify it under +the same terms as the Perl 5 programming language system itself. + +=cut diff --git a/CPAN/Moose/Cookbook/Basics/Company_Subtypes.pod b/CPAN/Moose/Cookbook/Basics/Company_Subtypes.pod new file mode 100644 index 0000000..562a648 --- /dev/null +++ b/CPAN/Moose/Cookbook/Basics/Company_Subtypes.pod @@ -0,0 +1,615 @@ +# PODNAME: Moose::Cookbook::Basics::Company_Subtypes +# ABSTRACT: Demonstrates the use of subtypes and how to model classes related to companies, people, employees, etc. + +__END__ + +=pod + +=encoding UTF-8 + +=head1 NAME + +Moose::Cookbook::Basics::Company_Subtypes - Demonstrates the use of subtypes and how to model classes related to companies, people, employees, etc. + +=head1 VERSION + +version 2.2207 + +=head1 SYNOPSIS + + package Address; + use Moose; + use Moose::Util::TypeConstraints; + + use Locale::US; + use Regexp::Common 'zip'; + + my $STATES = Locale::US->new; + subtype 'USState' + => as Str + => where { + ( exists $STATES->{code2state}{ uc($_) } + || exists $STATES->{state2code}{ uc($_) } ); + }; + + subtype 'USZipCode' + => as Value + => where { + /^$RE{zip}{US}{-extended => 'allow'}$/; + }; + + has 'street' => ( is => 'rw', isa => 'Str' ); + has 'city' => ( is => 'rw', isa => 'Str' ); + has 'state' => ( is => 'rw', isa => 'USState' ); + has 'zip_code' => ( is => 'rw', isa => 'USZipCode' ); + + package Company; + use Moose; + use Moose::Util::TypeConstraints; + + has 'name' => ( is => 'rw', isa => 'Str', required => 1 ); + has 'address' => ( is => 'rw', isa => 'Address' ); + has 'employees' => ( + is => 'rw', + isa => 'ArrayRef[Employee]', + default => sub { [] }, + ); + + sub BUILD { + my ( $self, $params ) = @_; + foreach my $employee ( @{ $self->employees } ) { + $employee->employer($self); + } + } + + after 'employees' => sub { + my ( $self, $employees ) = @_; + return unless $employees; + foreach my $employee ( @$employees ) { + $employee->employer($self); + } + }; + + package Person; + use Moose; + + has 'first_name' => ( is => 'rw', isa => 'Str', required => 1 ); + has 'last_name' => ( is => 'rw', isa => 'Str', required => 1 ); + has 'middle_initial' => ( + is => 'rw', isa => 'Str', + predicate => 'has_middle_initial' + ); + has 'address' => ( is => 'rw', isa => 'Address' ); + + sub full_name { + my $self = shift; + return $self->first_name + . ( + $self->has_middle_initial + ? ' ' . $self->middle_initial . '. ' + : ' ' + ) . $self->last_name; + } + + package Employee; + use Moose; + + extends 'Person'; + + has 'title' => ( is => 'rw', isa => 'Str', required => 1 ); + has 'employer' => ( is => 'rw', isa => 'Company', weak_ref => 1 ); + + override 'full_name' => sub { + my $self = shift; + super() . ', ' . $self->title; + }; + +=head1 DESCRIPTION + +This recipe introduces the C sugar function from +L. The C function lets you +declaratively create type constraints without building an entire +class. + +In the recipe we also make use of L and L +to build constraints, showing how constraints can make use of existing +CPAN tools for data validation. + +Finally, we introduce the C attribute option. + +In the C
class we define two subtypes. The first uses the +L module to check the validity of a state. It accepts +either a state abbreviation or full name. + +A state will be passed in as a string, so we make our C type +a subtype of Moose's builtin C type. This is done using the C +sugar. The actual constraint is defined using C. This function +accepts a single subroutine reference. That subroutine will be called +with the value to be checked in C<$_> (1). It is expected to return a +true or false value indicating whether the value is valid for the +type. + +We can now use the C type just like Moose's builtin types: + + has 'state' => ( is => 'rw', isa => 'USState' ); + +When the C attribute is set, the value is checked against the +C constraint. If the value is not valid, an exception will be +thrown. + +The next C, C, uses +L. L includes a regex for validating +US zip codes. We use this constraint for the C attribute. + + subtype 'USZipCode' + => as Value + => where { + /^$RE{zip}{US}{-extended => 'allow'}$/; + }; + +Using a subtype instead of requiring a class for each type greatly +simplifies the code. We don't really need a class for these types, as +they're just strings, but we do want to ensure that they're valid. + +The type constraints we created are reusable. Type constraints are +stored by name in a global registry, which means that we can refer to +them in other classes. Because the registry is global, we do recommend +that you use some sort of namespacing in real applications, +like C (just as you would do with class names). + +These two subtypes allow us to define a simple C
class. + +Then we define our C class, which has an address. As we saw +in earlier recipes, Moose automatically creates a type constraint for +each our classes, so we can use that for the C class's +C
attribute: + + has 'address' => ( is => 'rw', isa => 'Address' ); + +A company also needs a name: + + has 'name' => ( is => 'rw', isa => 'Str', required => 1 ); + +This introduces a new attribute option, C. If an attribute +is required, then it must be passed to the class's constructor, or an +exception will be thrown. It's important to understand that a +C attribute can still be false or C, if its type +constraint allows that. + +The next attribute, C, uses a I type +constraint: + + has 'employees' => ( + is => 'rw', + isa => 'ArrayRef[Employee]' + default => sub { [] }, + ); + +This constraint says that C must be an array reference +where each element of the array is an C object. It's worth +noting that an I array reference also satisfies this +constraint, such as the value given as the default here. + +Parameterizable type constraints (or "container types"), such as +C, can be made more specific with a type parameter. In +fact, we can arbitrarily nest these types, producing something like +C. However, you can also just use the type by +itself, so C is legal. (2) + +If you jump down to the definition of the C class, you will +see that it has an C attribute. + +When we set the C for a C we want to make sure +that each of these employee objects refers back to the right +C in its C attribute. + +To do that, we need to hook into object construction. Moose lets us do +this by writing a C method in our class. When your class +defines a C method, it will be called by the constructor +immediately after object construction, but before the object is returned +to the caller. Note that all C methods in your class hierarchy +will be called automatically; there is no need to (and you should not) +call the superclass C method. + +The C class uses the C method to ensure that each +employee of a company has the proper C object in its +C attribute: + + sub BUILD { + my ( $self, $params ) = @_; + foreach my $employee ( @{ $self->employees } ) { + $employee->employer($self); + } + } + +The C method is executed after type constraints are checked, so it is +safe to assume that if C<< $self->employees >> has a value, it will be an +array reference, and that the elements of that array reference will be +C objects. + +We also want to make sure that whenever the C attribute for +a C is changed, we also update the C for each +employee. + +To do this we can use an C modifier: + + after 'employees' => sub { + my ( $self, $employees ) = @_; + return unless $employees; + foreach my $employee ( @$employees ) { + $employee->employer($self); + } + }; + +Again, as with the C method, we know that the type constraint check has +already happened, so we know that if C<$employees> is defined it will contain +an array reference of C objects. + +Note that C is a read/write accessor, so we must return early if +it's called as a reader. + +The B class does not really demonstrate anything new. It has several +C attributes. It also has a C method, which we +first used in L. + +The only new feature in the C class is the C +method modifier: + + override 'full_name' => sub { + my $self = shift; + super() . ', ' . $self->title; + }; + +This is just a sugary alternative to Perl's built in C +feature. However, there is one difference. You cannot pass any +arguments to C. Instead, Moose simply passes the same +parameters that were passed to the method. + +A more detailed example of usage can be found in +F. + +=begin testing-SETUP + +# we have to do this silliness because Test::Inline already added a plan for us. +BEGIN { + if ("$]" <= '5.010') { + diag 'this test requires Regexp::Common (therefore perl 5.010)'; + pass; + exit 0; + } +} + +use Test::Needs { + 'Locale::US' => '0', + 'Regexp::Common' => '0', +}; + +=end testing-SETUP + +=head1 CONCLUSION + +This recipe was intentionally longer and more complex. It illustrates +how Moose classes can be used together with type constraints, as well +as the density of information that you can get out of a small amount +of typing when using Moose. + +This recipe also introduced the C function, the C +attribute, and the C method modifier. + +We will revisit type constraints in future recipes, and cover type +coercion as well. + +=head1 FOOTNOTES + +=over 4 + +=item (1) + +The value being checked is also passed as the first argument to +the C block, so it can be accessed as C<$_[0]>. + +=item (2) + +Note that C will not work. Moose will not parse this as a +container type, and instead you will have a new type named +"ArrayRef[]", which doesn't make any sense. + +=back + +=begin testing + +{ + package Company; + + sub get_employee_count { scalar @{(shift)->employees} } +} + +use Scalar::Util 'isweak'; + +my $ii; +is( + exception { + $ii = Company->new( + { + name => 'Infinity Interactive', + address => Address->new( + street => '565 Plandome Rd., Suite 307', + city => 'Manhasset', + state => 'NY', + zip_code => '11030' + ), + employees => [ + Employee->new( + first_name => 'Jeremy', + last_name => 'Shao', + title => 'President / Senior Consultant', + address => Address->new( + city => 'Manhasset', state => 'NY' + ) + ), + Employee->new( + first_name => 'Tommy', + last_name => 'Lee', + title => 'Vice President / Senior Developer', + address => + Address->new( city => 'New York', state => 'NY' ) + ), + Employee->new( + first_name => 'Stevan', + middle_initial => 'C', + last_name => 'Little', + title => 'Senior Developer', + address => + Address->new( city => 'Madison', state => 'CT' ) + ), + ] + } + ); + }, + undef, + '... created the entire company successfully' +); + +isa_ok( $ii, 'Company' ); + +is( $ii->name, 'Infinity Interactive', + '... got the right name for the company' ); + +isa_ok( $ii->address, 'Address' ); +is( $ii->address->street, '565 Plandome Rd., Suite 307', + '... got the right street address' ); +is( $ii->address->city, 'Manhasset', '... got the right city' ); +is( $ii->address->state, 'NY', '... got the right state' ); +is( $ii->address->zip_code, 11030, '... got the zip code' ); + +is( $ii->get_employee_count, 3, '... got the right employee count' ); + +# employee #1 + +isa_ok( $ii->employees->[0], 'Employee' ); +isa_ok( $ii->employees->[0], 'Person' ); + +is( $ii->employees->[0]->first_name, 'Jeremy', + '... got the right first name' ); +is( $ii->employees->[0]->last_name, 'Shao', '... got the right last name' ); +ok( !$ii->employees->[0]->has_middle_initial, '... no middle initial' ); +is( $ii->employees->[0]->middle_initial, undef, + '... got the right middle initial value' ); +is( $ii->employees->[0]->full_name, + 'Jeremy Shao, President / Senior Consultant', + '... got the right full name' ); +is( $ii->employees->[0]->title, 'President / Senior Consultant', + '... got the right title' ); +is( $ii->employees->[0]->employer, $ii, '... got the right company' ); +ok( isweak( $ii->employees->[0]->{employer} ), + '... the company is a weak-ref' ); + +isa_ok( $ii->employees->[0]->address, 'Address' ); +is( $ii->employees->[0]->address->city, 'Manhasset', + '... got the right city' ); +is( $ii->employees->[0]->address->state, 'NY', '... got the right state' ); + +# employee #2 + +isa_ok( $ii->employees->[1], 'Employee' ); +isa_ok( $ii->employees->[1], 'Person' ); + +is( $ii->employees->[1]->first_name, 'Tommy', + '... got the right first name' ); +is( $ii->employees->[1]->last_name, 'Lee', '... got the right last name' ); +ok( !$ii->employees->[1]->has_middle_initial, '... no middle initial' ); +is( $ii->employees->[1]->middle_initial, undef, + '... got the right middle initial value' ); +is( $ii->employees->[1]->full_name, + 'Tommy Lee, Vice President / Senior Developer', + '... got the right full name' ); +is( $ii->employees->[1]->title, 'Vice President / Senior Developer', + '... got the right title' ); +is( $ii->employees->[1]->employer, $ii, '... got the right company' ); +ok( isweak( $ii->employees->[1]->{employer} ), + '... the company is a weak-ref' ); + +isa_ok( $ii->employees->[1]->address, 'Address' ); +is( $ii->employees->[1]->address->city, 'New York', + '... got the right city' ); +is( $ii->employees->[1]->address->state, 'NY', '... got the right state' ); + +# employee #3 + +isa_ok( $ii->employees->[2], 'Employee' ); +isa_ok( $ii->employees->[2], 'Person' ); + +is( $ii->employees->[2]->first_name, 'Stevan', + '... got the right first name' ); +is( $ii->employees->[2]->last_name, 'Little', '... got the right last name' ); +ok( $ii->employees->[2]->has_middle_initial, '... got middle initial' ); +is( $ii->employees->[2]->middle_initial, 'C', + '... got the right middle initial value' ); +is( $ii->employees->[2]->full_name, 'Stevan C. Little, Senior Developer', + '... got the right full name' ); +is( $ii->employees->[2]->title, 'Senior Developer', + '... got the right title' ); +is( $ii->employees->[2]->employer, $ii, '... got the right company' ); +ok( isweak( $ii->employees->[2]->{employer} ), + '... the company is a weak-ref' ); + +isa_ok( $ii->employees->[2]->address, 'Address' ); +is( $ii->employees->[2]->address->city, 'Madison', '... got the right city' ); +is( $ii->employees->[2]->address->state, 'CT', '... got the right state' ); + +# create new company + +my $new_company + = Company->new( name => 'Infinity Interactive International' ); +isa_ok( $new_company, 'Company' ); + +my $ii_employees = $ii->employees; +foreach my $employee (@$ii_employees) { + is( $employee->employer, $ii, '... has the ii company' ); +} + +$new_company->employees($ii_employees); + +foreach my $employee ( @{ $new_company->employees } ) { + is( $employee->employer, $new_company, + '... has the different company now' ); +} + +## check some error conditions for the subtypes + +isnt( + exception { + Address->new( street => {} ),; + }, + undef, + '... we die correctly with bad args' +); + +isnt( + exception { + Address->new( city => {} ),; + }, + undef, + '... we die correctly with bad args' +); + +isnt( + exception { + Address->new( state => 'British Columbia' ),; + }, + undef, + '... we die correctly with bad args' +); + +is( + exception { + Address->new( state => 'Connecticut' ),; + }, + undef, + '... we live correctly with good args' +); + +isnt( + exception { + Address->new( zip_code => 'AF5J6$' ),; + }, + undef, + '... we die correctly with bad args' +); + +is( + exception { + Address->new( zip_code => '06443' ),; + }, + undef, + '... we live correctly with good args' +); + +isnt( + exception { + Company->new(),; + }, + undef, + '... we die correctly without good args' +); + +is( + exception { + Company->new( name => 'Foo' ),; + }, + undef, + '... we live correctly without good args' +); + +isnt( + exception { + Company->new( name => 'Foo', employees => [ Person->new ] ),; + }, + undef, + '... we die correctly with good args' +); + +is( + exception { + Company->new( name => 'Foo', employees => [] ),; + }, + undef, + '... we live correctly with good args' +); + +=end testing + +=head1 AUTHORS + +=over 4 + +=item * + +Stevan Little + +=item * + +Dave Rolsky + +=item * + +Jesse Luehrs + +=item * + +Shawn M Moore + +=item * + +יובל קוג'מן (Yuval Kogman) + +=item * + +Karen Etheridge + +=item * + +Florian Ragwitz + +=item * + +Hans Dieter Pearcey + +=item * + +Chris Prather + +=item * + +Matt S Trout + +=back + +=head1 COPYRIGHT AND LICENSE + +This software is copyright (c) 2006 by Infinity Interactive, Inc. + +This is free software; you can redistribute it and/or modify it under +the same terms as the Perl 5 programming language system itself. + +=cut diff --git a/CPAN/Moose/Cookbook/Basics/DateTime_ExtendingNonMooseParent.pod b/CPAN/Moose/Cookbook/Basics/DateTime_ExtendingNonMooseParent.pod new file mode 100644 index 0000000..e86e6d9 --- /dev/null +++ b/CPAN/Moose/Cookbook/Basics/DateTime_ExtendingNonMooseParent.pod @@ -0,0 +1,127 @@ +# PODNAME: Moose::Cookbook::Basics::DateTime_ExtendingNonMooseParent +# ABSTRACT: Extending a non-Moose parent class + +__END__ + +=pod + +=encoding UTF-8 + +=head1 NAME + +Moose::Cookbook::Basics::DateTime_ExtendingNonMooseParent - Extending a non-Moose parent class + +=head1 VERSION + +version 2.2207 + +=head1 SYNOPSIS + + package My::DateTime; + + use Moose; + use MooseX::NonMoose; + use DateTime::Calendar::Mayan; + extends qw( DateTime ); + + has 'mayan_date' => ( + is => 'ro', + isa => 'DateTime::Calendar::Mayan', + init_arg => undef, + lazy => 1, + builder => '_build_mayan_date', + clearer => '_clear_mayan_date', + predicate => 'has_mayan_date', + ); + + after 'set' => sub { + $_[0]->_clear_mayan_date; + }; + + sub _build_mayan_date { + DateTime::Calendar::Mayan->from_object( object => $_[0] ); + } + +=head1 DESCRIPTION + +This recipe demonstrates how to use Moose to subclass a parent which +is not Moose based. This recipe only works if the parent class uses a +blessed hash reference for object instances. If your parent is doing +something funkier, you should check out L and L. + +The meat of this recipe is contained in L, which does all +the grunt work for you. + +=for testing-SETUP use Test::Needs { + 'DateTime' => '0', + 'DateTime::Calendar::Mayan' => '0', + 'MooseX::NonMoose' => '0.25', +}; + +=begin testing + +my $dt = My::DateTime->new( year => 1970, month => 2, day => 24 ); + +can_ok( $dt, 'mayan_date' ); +isa_ok( $dt->mayan_date, 'DateTime::Calendar::Mayan' ); +is( $dt->mayan_date->date, '12.17.16.9.19', 'got expected mayan date' ); + +$dt->set( year => 2009 ); +ok( ! $dt->has_mayan_date, 'mayan_date is cleared after call to ->set' ); + +=end testing + +=head1 AUTHORS + +=over 4 + +=item * + +Stevan Little + +=item * + +Dave Rolsky + +=item * + +Jesse Luehrs + +=item * + +Shawn M Moore + +=item * + +יובל קוג'מן (Yuval Kogman) + +=item * + +Karen Etheridge + +=item * + +Florian Ragwitz + +=item * + +Hans Dieter Pearcey + +=item * + +Chris Prather + +=item * + +Matt S Trout + +=back + +=head1 COPYRIGHT AND LICENSE + +This software is copyright (c) 2006 by Infinity Interactive, Inc. + +This is free software; you can redistribute it and/or modify it under +the same terms as the Perl 5 programming language system itself. + +=cut diff --git a/CPAN/Moose/Cookbook/Basics/Document_AugmentAndInner.pod b/CPAN/Moose/Cookbook/Basics/Document_AugmentAndInner.pod new file mode 100644 index 0000000..f25d94a --- /dev/null +++ b/CPAN/Moose/Cookbook/Basics/Document_AugmentAndInner.pod @@ -0,0 +1,197 @@ +# PODNAME: Moose::Cookbook::Basics::Document_AugmentAndInner +# ABSTRACT: The augment modifier, which turns normal method overriding "inside-out" + +__END__ + +=pod + +=encoding UTF-8 + +=head1 NAME + +Moose::Cookbook::Basics::Document_AugmentAndInner - The augment modifier, which turns normal method overriding "inside-out" + +=head1 VERSION + +version 2.2207 + +=head1 SYNOPSIS + + package Document::Page; + use Moose; + + has 'body' => ( is => 'rw', isa => 'Str', default => sub {''} ); + + sub create { + my $self = shift; + $self->open_page; + inner(); + $self->close_page; + } + + sub append_body { + my ( $self, $appendage ) = @_; + $self->body( $self->body . $appendage ); + } + + sub open_page { (shift)->append_body('') } + sub close_page { (shift)->append_body('') } + + package Document::PageWithHeadersAndFooters; + use Moose; + + extends 'Document::Page'; + + augment 'create' => sub { + my $self = shift; + $self->create_header; + inner(); + $self->create_footer; + }; + + sub create_header { (shift)->append_body('
') } + sub create_footer { (shift)->append_body('