[operators] describe some circumfix and postcircumfixes

Author: moritz

lib/operators.pod

@@ -101,8 +101,114 @@ term or as a prefix. Subroutine calls are the most common listops. Other
 cases include meta-reduced infix operators (C<[+]| 1, 2, 3>) and the
 L<#prefix ...> etc. stub operators.
 
+(Niecza currently turns postcircumfix operators in a subroutine call,
+while Rakudo interprets them as methods).
 
-=head1 Method Postfix
+=head1 Term Precedence
+
+=head2 circumfix < >
+
+The quote-words construct. Breaks up the contents on whitespace, and returns
+a C<Parcel> of the words. If a word
+looks like a number literal or a C<Pair> literal, it is converted the
+appropriate number.
+
+    say <a b c>[1];     # b
+
+(Rakudo currently always returns a parcel of strings).
+
+=head2 circumfix ( )
+
+The grouping operator.
+
+An empty group C<()> creates an empty L<Parcel>.
+Parens around non-empty expressions simply structure the expression, but
+not have additional semantics.
+
+In an argument list, putting parenthesis around an argument prevents it from
+being interpreted as a named argument.
+
+    multi sub p(:$a!) { say 'named'      }
+    multi sub p($a)   { say 'positional' }
+    p a => 1;       # named
+    p (a => 1);     # positional
+
+=head2 circumfix { }
+
+Block or L<Hash> constructor.
+
+If the contents looks like a list of pairs and does not use L<$_> or other
+placeholder parameters, returns an itemized L<Hash>.
+
+Otherwise it contructs a L<Block>.
+
+Note that this construct does not reparse the contents; rather the
+contents are always parsed as a statement list (i.e. like a block),
+and if the later analysis shows that it needs to be interpreted as a hash,
+the block is executed and coerced to L<Hash>.
+
+=head2 circumfix [ ]
+
+The L<Array> constructor. Returns an itemized L<Array> which does not flatten
+in list context.
+
+=head1 Method Postfix Precedence
+
+=head2 postcircumfix { }
+
+The hash indexing postcircumfix. Fail on type L<Any>, and on L<EnumMap>,
+L<Hash> and related types it allows lookup of hash elements by key.
+
+    my %h = a => 1, b => 2;
+    say %h{'a'};        # 1
+    say %h{'a', 'b'};   # 1, 2
+
+=head2 postcircumfix < >
+
+The hash indexing quote-words operator. Interprets the argument list
+as a list of words, just like C<< circumfix < > >>, and then calls
+C<< postcircumfix:<{ }> >>, i.e. the hash indexing operator.
+
+Thus you can write
+
+    my %h = a => 1, b => 2;
+    say %h<a>;          # 1
+    say %h<b a>;        # 2, 1
+
+=head2 postcircumfix ( )
+
+The call operator. Treats the invocant as a L<Callable> and invokes it,
+using the expression between the parens as arguments.
+
+Note that an identifier followed by a pair of parens is always parsed as a
+subroutine call.
+
+If you want your objects to respond to the call operator, you need to
+implement a C<< method postcircumfix:<( )> >>.
+
+=head2 postcircumfix [ ]
+
+The array indexing operator. Treats the invocant as a L<Positional> and
+indexes it by position.
+
+    my @a = 'a' .. 'z';
+    say @a[0];                      # a
+
+Lists of indexes produce list of results as if they were all indexed
+separetely.
+
+    my @a = 'a' .. 'z';
+    say @a[15, 4, 17, 11].join;     # perl
+
+L<Callable> indexes are invoked with the number of elements as arguments.
+
+This lets you write
+
+    my @a[*-1];                     # z
+
+to index lists and arrays from the end.
+
+Non-L<Positional> invocants are interpreted as a one-list element of the object.
 
 =head2 postfix .