=begin pod

=TITLE class Attribute

    class Attribute { }

In Perl 6 lingo, an I<attribute> refers to a per-instance/object storage slot.
An C<Attribute> is used to talk about classes' and roles' attributes on the
meta level.

Normal usage of attributes does not require the user to use class Attribute
explicitly.

The usual way to obtain an object of type C<Attribute> is by introspection:

    class Useless {
        has @!things;
    }
    my $a = Useless.^attributes(:local)[0];
    say $a.name;            # @!things
    say $a.package;         # Useless()
    say $a.has-accessor;    # False

    # modifying an attribute from the outside
    # this is usually not possible, but since Attribute
    # is at the level of the meta class, all is fair game
    my $instance = Useless.new;
    $a.set_value($instance, [1, 2, 3]);
    say $a.get_value($instance);        # 1 2 3

=head1 Methods

=head2 name

    method name(Attribute:D:) returns Str:D

Returns the name of the attribute. Note that this is always the private name,
so if an attribute is declared as C<has $.a>, the name returned is C<$!a>.

=head2 package

    method package(Attribute:D:) returns Mu:U

Returns the package (class/grammar/role) to which this attribute belongs.

=head2 has-accessor

    method has-accessor(Attribute:D:) returns Bool:D

Returns C<True> if the attribute has a public accessor method.

=head2 readonly

    method readonly(Attribute:D:) returns Bool:D

Returns C<True> for readonly attributes, which is the default.
Returns C<False> for attributes marked as C<is rw>.

=head2 get_value

    method get_value(Attribute:D: Mu $instance)

Returns the value stored in this attribute of object C<$instance>.

Note that this method violates encapsulation of the object, and should be
used with care. Here be dragons.

=head2 set_value

    method set_value(Attribute:D: Mu $instance, Mu \new_val)

Binds the value C<new_val> to this attribute of object C<$instance>.

Note that this method violates encapsulation of the object, and should be
used with care. Here be dragons.

=end pod