Doc for some of the new meta methods
[gitmo/Mouse.git] / lib / Mouse / Meta / Attribute.pm
index 2e626b0..af9e737 100644 (file)
@@ -10,27 +10,49 @@ sub new {
     my $class = shift;
     my %args  = @_;
 
-    $args{init_arg} = $args{name}
+    my $name = $args{name};
+
+    $args{init_arg} = $name
         unless exists $args{init_arg};
+
     $args{is} ||= '';
 
+    if ($args{lazy_build}) {
+        confess("You can not use lazy_build and default for the same attribute $name")
+            if exists $args{default};
+        $args{lazy}      = 1;
+        $args{required}  = 1;
+        $args{builder}   = "_build_${name}"
+            if !exists($args{builder});
+        if ($name =~ /^_/) {
+            $args{clearer}   = "_clear${name}" if !exists($args{clearer});
+            $args{predicate} = "_has${name}" if !exists($args{predicate});
+        }
+        else {
+            $args{clearer}   = "clear_${name}" if !exists($args{clearer});
+            $args{predicate} = "has_${name}" if !exists($args{predicate});
+        }
+    }
+
     bless \%args, $class;
 }
 
-sub name            { $_[0]->{name}            }
-sub class           { $_[0]->{class}           }
-sub _is_metadata    { $_[0]->{is}              }
-sub is_required     { $_[0]->{required}        }
-sub default         { $_[0]->{default}         }
-sub is_lazy         { $_[0]->{lazy}            }
-sub predicate       { $_[0]->{predicate}       }
-sub clearer         { $_[0]->{clearer}         }
-sub handles         { $_[0]->{handles}         }
-sub is_weak_ref     { $_[0]->{weak_ref}        }
-sub init_arg        { $_[0]->{init_arg}        }
-sub type_constraint { $_[0]->{type_constraint} }
-sub trigger         { $_[0]->{trigger}         }
-sub builder         { $_[0]->{builder}         }
+sub name              { $_[0]->{name}            }
+sub class             { $_[0]->{class}           }
+sub _is_metadata      { $_[0]->{is}              }
+sub is_required       { $_[0]->{required}        }
+sub default           { $_[0]->{default}         }
+sub is_lazy           { $_[0]->{lazy}            }
+sub is_lazy_build     { $_[0]->{lazy_build}      }
+sub predicate         { $_[0]->{predicate}       }
+sub clearer           { $_[0]->{clearer}         }
+sub handles           { $_[0]->{handles}         }
+sub is_weak_ref       { $_[0]->{weak_ref}        }
+sub init_arg          { $_[0]->{init_arg}        }
+sub type_constraint   { $_[0]->{type_constraint} }
+sub trigger           { $_[0]->{trigger}         }
+sub builder           { $_[0]->{builder}         }
+sub should_auto_deref { $_[0]->{auto_deref}      }
 
 sub has_default         { exists $_[0]->{default}         }
 sub has_predicate       { exists $_[0]->{predicate}       }
@@ -40,6 +62,11 @@ sub has_type_constraint { exists $_[0]->{type_constraint} }
 sub has_trigger         { exists $_[0]->{trigger}         }
 sub has_builder         { exists $_[0]->{builder}         }
 
+sub _create_args {
+    $_[0]->{_create_args} = $_[1] if @_ > 1;
+    $_[0]->{_create_args}
+}
+
 sub generate_accessor {
     my $attribute = shift;
 
@@ -93,7 +120,20 @@ sub generate_accessor {
         $accessor .= ' if !exists($self->{$key});';
     }
 
-    $accessor .= 'return $self->{$key}
+    if ($attribute->should_auto_deref) {
+        if ($attribute->type_constraint eq 'ArrayRef') {
+            $accessor .= 'if (wantarray) {
+                return @{ $self->{$key} || [] };
+            }';
+        }
+        else {
+            $accessor .= 'if (wantarray) {
+                return %{ $self->{$key} || {} };
+            }';
+        }
+    }
+
+    $accessor .= 'return $self->{$key};
     }';
 
     return eval $accessor;
@@ -141,17 +181,17 @@ sub generate_handles {
 sub create {
     my ($self, $class, $name, %args) = @_;
 
-    confess "You cannot have lazy attribute ($name) without specifying a default value for it"
-        if $args{lazy} && !exists($args{default}) && !exists($args{builder});
+    $args{name} = $name;
+    $args{class} = $class;
 
-    confess "References are not allowed as default values, you must wrap the default of '$name' in a CODE reference (ex: sub { [] } and not [])"
-        if ref($args{default})
-        && ref($args{default}) ne 'CODE';
+    $self->validate_args($name, %args);
 
     $args{type_constraint} = delete $args{isa}
         if exists $args{isa};
 
-    my $attribute = $self->new(%args, name => $name, class => $class);
+    my $attribute = $self->new(%args);
+    $attribute->_create_args(\%args);
+
     my $meta = $class->meta;
 
     $meta->add_attribute($attribute);
@@ -184,6 +224,29 @@ sub create {
     return $attribute;
 }
 
+sub validate_args {
+    my $self = shift;
+    my $name = shift;
+    my %args = @_;
+
+    confess "You cannot have lazy attribute ($name) without specifying a default value for it"
+        if $args{lazy} && !exists($args{default}) && !exists($args{builder});
+
+    confess "References are not allowed as default values, you must wrap the default of '$name' in a CODE reference (ex: sub { [] } and not [])"
+        if ref($args{default})
+        && ref($args{default}) ne 'CODE';
+
+    confess "You cannot auto-dereference without specifying a type constraint on attribute $name"
+        if $args{auto_deref} && !exists($args{isa});
+
+    confess "You cannot auto-dereference anything other than a ArrayRef or HashRef on attribute $name"
+        if $args{auto_deref}
+        && $args{isa} ne 'ArrayRef'
+        && $args{isa} ne 'HashRef';
+
+    return 1;
+}
+
 sub find_type_constraint {
     my $self = shift;
     my $type = $self->type_constraint;
@@ -226,6 +289,29 @@ sub _canonicalize_handles {
     }
 }
 
+sub clone_parent {
+    my $self  = shift;
+    my $class = shift;
+    my $name  = shift;
+    my %args  = ($self->get_parent_args($class, $name), @_);
+
+    $self->create($class, $name, %args);
+}
+
+sub get_parent_args {
+    my $self  = shift;
+    my $class = shift;
+    my $name  = shift;
+
+    for my $super ($class->meta->linearized_isa) {
+        my $super_attr = $super->can("meta") && $super->meta->get_attribute($name)
+            or next;
+        return %{ $super_attr->_create_args };
+    }
+
+    confess "Could not find an attribute by the name of '$name' to inherit from";
+}
+
 1;
 
 __END__
@@ -285,6 +371,10 @@ installed. Some error checking is done.
 
 =head2 has_builder -> Bool
 
+=head2 is_lazy_build => Bool
+
+=head2 should_auto_deref -> Bool
+
 Informational methods.
 
 =head2 generate_accessor -> CODE
@@ -313,5 +403,15 @@ this attribute's type constraint;
 Checks that the given value passes this attribute's type constraint. Returns 1
 on success, otherwise C<confess>es.
 
+=head2 clone_parent OwnerClass, AttributeName, %args -> Mouse::Meta::Attribute
+
+Creates a new attribute in OwnerClass, inheriting options from parent classes.
+Accessors and helper methods are installed. Some error checking is done.
+
+=head2 get_parent_args OwnerClass, AttributeName -> Hash
+
+Returns the options that the parent class of C<OwnerClass> used for attribute
+C<AttributeName>.
+
 =cut