Merge pull request #4727 from Raku/librasteve-moreontraits

More Information on Attribute Traits

Author: librasteve

doc/Language/objects.rakudoc

@@ -271,6 +271,53 @@ attributes, it will only set attributes that have an accessor method.
 That is, even if you pass C«travelers => ["Alex", "Betty"]» to the
 default constructor, the attribute C<@!travelers> is not initialized.
 
+=head2 Traits
+
+Several traits are provided to modify the behavior of attributes.
+Attribute traits are introduced by the C<is> keyword after the attribute name.
+The following traits (and some others) are documented L<here|/type/Attribute#Traits>.
+
+=begin code
+class Journey {
+    # error if origin is not provided
+    has $.origin is required;
+    # reset to this default value if Nil is assigned
+    has $.destination is default('Orlando') is rw;
+    # private attribute
+    has @!travelers;
+    # is read/write
+    has $.notes is rw;
+    # is readonly
+    has $.agent is readonly = 'Acme Travel Inc.';
+    # private attribute can (only) be set via .new
+    has $!status is built;
+}
+=end code
+
+Here's how to construct and use this new version of Journey:
+
+=begin code :preamble<class Journey {}>
+# Create a new instance of the class.
+my $vacation = Journey.new(
+    origin      => 'Sweden',
+    status      => 'Requested'
+);
+
+# Use a setter accessor on a read/write attribute, then a getter to read it,
+# then assign Nil to reset the default.
+$vacation.destination = 'San Francisco';
+say $vacation.destination;    # OUTPUT: «San Francisco␤»
+$vacation.destination = Nil;
+say $vacation.destination;    # OUTPUT: «Orlando␤»
+
+# Try to change a built private attribute later.
+try { $vacation.status = 'Booked'; }  #ERROR
+=end code
+
+Note that C<is readonly> is the default for attributes that are not marked C<is rw>,
+so in this example it has no effect. An entire class can be marked C<is rw>, in which
+case the C<is readonly> is useful to opt out specific attributes.
+
 =head2 Methods
 
 Methods are declared with the C<method> keyword inside a class body.