document Attribute

lib/Attribute.pod

@@ -0,0 +1,77 @@
+=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