Merge pull request #3300 from Kaiepi/sigiled-methods

Document sigiled method calls

Author: JJ

doc/Language/objects.pod6

@@ -319,6 +319,30 @@ separated by a colon, the arguments: C<method invocant: arguments>. We can use
 this syntax whenever it feels more natural than the classical
 period-and-parentheses one. It works exactly in the same way.
 
+Note how the call to the C<notes> method in the C<Str> method is made on
+C<self>. Writing method calls this way will leave the return value of
+the method as is with regards to containers. To containerize return
+values, you can make method calls on a sigil instead of C<self>. This
+calls various methods on the return value of the method depending on the
+sigil used to containerize it:
+
+=begin table
+Sigil | Method
+==============
+ $    | item
+ @    | list
+ %    | hash
+ &    | item
+=end table
+
+For example, the C<Str> method of C<Journey> can be rewritten not to use
+the C<~> operator by embedding a sigiled method call in the string it
+returns:
+
+=begin code :skip-test<demonstrates another way of writing a method>
+method Str { ⤷ $!origin\n$ⲧ$.notes()$!destination ⤶\n" }
+=end code
+
 Method names can be resolved at runtime with the C<.""> operator.
 
 =begin code

xt/words.pws

@@ -293,6 +293,7 @@ deopts
 deparse
 deprecations
 deps
+dequeue
 deref
 dereference
 dereferenced
@@ -353,6 +354,7 @@ endnetent
 endprotoent
 endpwent
 endservent
+enqueue
 enqueues
 entrapments
 ents