Describe postcircumfix:<[ ]> in much greater detail

Author: moritz

lib/Language/operators.pod

@@ -178,6 +178,9 @@ Thus you can write
     say %h<a>;          # 1
     say %h<b a>;        # 2, 1
 
+This is not a real operator, just a syntactic desugaring to the C<{ }>
+postcircumfix operator
+
 =head2 postcircumfix C«( )»
 
 The call operator. Treats the invocant as a L<Callable> and invokes it,
@@ -213,6 +216,10 @@ to index lists and arrays from the end.
 
 Non-L<Positional> invocants are interpreted as a one-list element of the object.
 
+See L<Positional|/type/Positional> for a more detailed description, and a list
+of low-level methods that this operator calls, and wihch types that want to
+offer an API similar to the built-in types can implement.
+
 =head2 postfix C«.»
 
 The operator for calling one method, C<$invocant.method>.

lib/Type/Positional.pod

@@ -19,4 +19,74 @@ include L<Parcel>, L<List>, L<Array>, L<Range>, and L<Buf>.
 Returns the type constraint for elements of the positional container. Defaults
 to L<Mu>.
 
+=head2 sub postcircumfix:<[ ]>
+
+    sub postcircumfix:<[ ]>(@container, *@index, :$k, :$v, :$kv, :$p, :$exists, :$delete)
+
+Universal interface for positional access to zero or more elements of the
+C<@container>. Elements can be accessed by zero-based
+L<integers|/type/Int>, or by C<callable objects|/type/Callable>, which will be
+passed the number of elements in the container, making indexing from the end
+esay:
+
+    my @a = <a b c>;
+    say @a[0];                      # a
+    say @a[*-1];                    # c
+    say @a[ sub $x { $x - 1 }];     # c
+
+If more than one index is given, a list of elements is returned:
+
+    my @a = <a b c>;
+    say @a[0, 2];                   # a c
+
+Different access mode (integers vs. callables) can be mixed inside a single
+positional access:
+
+    my @a = <a b c>;
+    say @a[*-1, 0];                 # c a
+
+Each access of a single element goes through a method called C<AT-POS>, which
+derivative types can override.
+
+Accesses with positive integers beyond the end of the container are allowed
+for mutable data structures (such as L<Array>), and return a L<Scalar>
+container that, on assignment, autovivifies the accessed array element:
+
+    my @a = <a b>;
+    @a[2] = 'c';
+    say @a;                         # a b c
+
+Where detected at compile time, assignment to a positional index can be
+short-circuted through a method called C<ASSIGN-POS>.
+
+The adverb C<:delete> deletes the specified indexes, and returns the deleted
+values:
+
+    my @a = <a b c>;
+    say @a[2]:delete;               # c
+    say @a;                         # a b
+
+Deletion of elements is impelemented in the C<DELETE-POS> method, which
+derivative types can override.
+
+The adverb C<:exists> make the positional accesses return a L<Bool> for each
+index, indicating whether the container has a value at the index:
+
+    my @a = 1, Any;
+
+    say @a[0, 1, 2]:exists;         # True True False
+
+The adverbs C<:k> (for I<key>), C<:v> (for I<value>), C<:kv> (for
+I<key/value>) and C<:p> (for L<Pair|/type/Pair>) are mutually exclusive, and
+control the format of the return value. C<:k> only returns the key (which is
+always the index on Positional types), C<:v> only the value (the default),
+C<:kv> a L<Parcel> of key and value, and C<:p> a L<Pair|/type/Pair> with the
+key being the index, and the value being the value stored in the container
+
+    for <a b c>.kv -> $k, $v {
+        say "$k: $v";               # 0: a
+                                    # 1: b
+                                    # 2: c
+    }
+
 =end pod