Manually apply PR#3441

"Revise and add to Attribute's documentation"

RIP Kaiepi++

Author: coke

doc/Type/Attribute.rakudoc

@@ -10,8 +10,42 @@ In Raku lingo, an I<attribute> refers to a per-instance/object storage slot.
 An C<Attribute> is used to talk about classes' and roles' attributes at the
 metalevel.
 
-Normal usage of attributes does not require the user to use this class
-explicitly.
+C<Attribute> is typically useful when working with the L<MOP|/language/mop>.
+For instance, the attributes of any type that supports them can be
+introspected using the C<attributes> metamethod, which returns a list of
+C<Attribute> instances. Using these, we can inspect various properties of
+a type's attributes, such as their names:
+=begin code
+class WithAttributes {
+    has $.attribute;
+    has $.attribute-two-electric-boogaloo;
+    has $.yet-another-attribute;
+}
+.say for WithAttributes.^attributes(:local).map(*.name);
+# OUTPUT:
+# $!attribute
+# $!attribute-two-electric-boogaloo
+# $!yet-another-attribute
+=end code
+
+Because of C<Attribute>, a type containing attributes, such as this:
+
+=for code
+class WithAttribute {
+    has $.attribute;
+}
+
+Is not something only the compiler knows how to generate. This class in
+particular can be generated manually like so:
+
+=for code :solo
+BEGIN {
+    constant WithAttribute = Metamodel::ClassHOW.new_type: :name<WithAttribute>;
+    WithAttribute.^add_attribute: Attribute.new:
+        :name<$!attribute>, :type(Any), :package(WithAttribute),
+        :1has_accessor;
+    WithAttribute.^compose;
+}
 
 =head1 Traits
 
@@ -121,27 +155,31 @@ default accessor for the attribute will return a writable value.
 
     multi trait_mod:<is>(Attribute:D $a, :$built!)
 
-By default, this trait allows setting up a I«private attribute» during object
-construction via C«.new». The same trait can be used to prevent setting up a
-I«public attribute» via C«.new» by passing it the Boolean value C«False».
+By default, this trait allows setting up a I«private attribute» during
+object construction via C«.new». The same trait can be used to prevent
+setting up a I«public attribute» via C«.new» by passing it the Boolean
+value C«False». Setting up an attribute with its value is ordinarily
+handled by assigning the value, but if C<:bind> is passed, then it will
+be bound instead:
 
     class Foo {
         has $!bar is built; # same as `is built(True)`
         has $.baz is built(False);
+        has $!qux is built(:bind);
 
-        method bar {
-            $!bar
-        }
+        method bar(::?CLASS:D:) { $!bar }
+        method qux(::?CLASS:D:) { $!qux }
     }
 
-    my $foo = Foo.new(bar => 1, baz => 2);
-    say $foo.bar; # OUTPUT: «1␤»
-    say $foo.baz; # OUTPUT: «Any␤»
+    my Foo:D $foo .= new: :bar[], :baz[], :qux[];
+    say $foo.bar.raku; # OUTPUT: «$[]␤»
+    say $foo.baz.raku; # OUTPUT: «Any␤»
+    say $foo.qux.raku; # OUTPUT: «[]␤»
 
 The C<built> trait also allows named arguments to be specified.  Currently
 the C<:bind> named argument can be specified.  In that case, any (default)
 value will be B<bound> to the attribute, rather than assigned.  This allows
-for specifying a C<Proxy> to an attribute:
+for specifying a L<C<Proxy>|/type/Proxy> to an attribute:
 
     class Foo {
         has $!foo is built(:bind) = Proxy.new: :STORE{...}, :FETCH{...}
@@ -151,19 +189,26 @@ Available as of the 2020.01 release of the Rakudo compiler.
 
 =head1 Methods
 
-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.raku;            # OUTPUT: «Attribute.new␤»
-    say $a.name;            # OUTPUT: «@!things␤»
-    say $a.package;         # OUTPUT: «(Useless)␤»
-    say $a.has_accessor;    # OUTPUT: «False␤»
+=head2 method new
+
+=begin code :method
+method new(
+    Attribute:_:
+    :$name!,
+    :$type!,
+    :$package!,
+    :$inlined = 0,
+    :$has_accessor = 0,
+    :$is_built = $has_accessor,
+    :$is_bound = 0,
+    :$positional_delegate = 0,
+    :$associative_delegate = 0,
+    *%other
+)
+=end code
 
-Modifying a private attribute from the outside is usually not possible, but
-since Attribute is at the level of the metaclass, all is fair game.
+Creates a new attribute. The following named arguments are required:
+- C<$name> contains the attribute's name, which should always be a
 
 =head2 method name
 
@@ -283,7 +328,7 @@ Returns the value stored in this attribute of object C<$obj>.
     say $private.get_value(Violated.new); # OUTPUT: «5␤»
 
 Note that this method violates encapsulation of the object, and should be
-used with care.  Here be dragons.
+used with care.
 
 =head2 method set_value
 
@@ -323,6 +368,21 @@ say Hero.^attributes(:local)[0]; # OUTPUT: «Positional @!inventory␤»
 
 Since say implicitly calls C<.gist>, that is what produces the output here.
 
+=head2 method is_built
+
+    method is_built()
+
+Returns C<True> if the attribute had the L<C<is built>|#trait_is_built>
+trait applied to it, otherwise returns C<False>.
+
+=head2 method is_bound
+
+    method is_bound()
+
+Returns C<True> if the attribute had the L<C<is built>|#trait_is_built>
+trait applied to it with C<:bind> as an argument, otherwise returns
+C<False>.
+
 =head1 Optional introspection
 
 =head2 DEPRECATED

xt/pws/code.pws

@@ -100,6 +100,7 @@ bitrary
 bj
 bn
 bol
+boogaloo
 bq
 bracketleft
 bracketright
@@ -405,6 +406,7 @@ quant
 quietlevel
 quotedbl
 quotedstring
+qux
 qxelwq
 raker
 rakulambda
@@ -509,6 +511,8 @@ wday
 welp
 whatevera
 whateverable
+withattribute
+withattributes
 withoutlinenumber
 xa
 xab