gistfile1.txt

S02-bits.pod
1263-The final element of an array is subscripted as C<@a[*-1]>,
1264-which means that when the subscripting operation discovers a C<Code:($)>
1265-object for a subscript, it calls it and supplies an argument indicating
1266-the number of elements in (that dimension of) the array.  See S09.
1267-
1268:=head3 The C<HyperWhatever> Type
1269-
1270:A variant of C<*> is the C<**> term, which is of type C<HyperWhatever>.
1271-It is generally understood to be a multidimension form of C<*> when
1272-that makes sense.  When modified by an operator that would turn C<*>
1273:into a function of one argument, C<WhateverCode:($)>, C<**> instead turns into
1274-a function with one slurpy argument, C<Code(*@)>, such that multiple
1275-arguments are distributed to some number of internal whatevers.
1276-That is:
1277-
1278-    * - 1    means                -> $x { $x - 1 }
1279:    ** - 1   means   -> *@x { map -> $x { $x - 1 }, @x }
1280-
1281:Therefore C<@array[^**]> represents C<< @array[{ map { ^* }, @_ }] >>,
1282-that is to say, every element of the array, no matter how many dimensions.
1283:(However, C<@array[**]> means the same thing because (as with C<...>
1284:above), the subscript operator will interpret bare C<**> as meaning
1285-all the subscripts, not the list of dimension sizes.  The meaning of
1286-C<Whatever> is always controlled by the first context it is bound into.)
1287-
1288:Other uses for C<*> and C<**> will doubtless suggest themselves
1289-over time.  These can be given meaning via the MMD system, if not
1290-the compiler.  In general a C<Whatever> should be interpreted as
1291-maximizing the degrees of freedom in a dwimmy way, not as a nihilistic
1292-"don't care anymore--just shoot me".
1293-
--
2249-and slice parameters are argumentative and call C<.getarg> on the internal
2250-iterator and just return the next syntactic argument (parcel or other object)
2251-without flattening.  (A slice differs from an ordinary positional parameter
2252-in being "slurpy", that is, it is intended to fetch multiple values from
2253-the variadic region of the surrounding capture.  Slurpy contexts come in
2254:both flattening (C<*> parameters) and slicing (C<**> parameters) forms.)
2255-
2256-The fact that a parameter is being bound implies that there is an outer
2257-capture being bound to a signature.  The capture's iterator provides
2258-a C<.get> and a C<.getarg> method to tell the iterator what context to
2259-bind in.  For positional/slice parameters, the C<.getarg> method returns
2260-the entire next argument from the iterator. It returns other objects unchanged.
2261-In contrast, flat parameters call C<.get> on the capture's iterator, which
2262-flattens any subparcels before pulling out the next item.  In either case,
2263-no bare parcel object is seen as a normal bound argument.  (There is a way to
2264-bind the underlying parcel using backslash, however.  This is how internal
2265-routines can deal with parcels as real objects.)
2266-
2267-In contrast to parameter binding, if a C<Parcel> is bound to an entire
2268-signature (typically as part of a function or method call), it will be transformed
2269-first into a capture object, which is much like a parcel but has its
--
4735-    $p.tree(*.item)        # force level 1 parcels to item
4736-    $p.tree(1)             # same thing
4737-    $p.tree(*.item,*.list) # force level 1 parcels to item, level 2 to list
4738-    $p.tree(*.Array,*)     # Turn all subparcels into item recursively
4739-
4740:When bound to a slice parameter (indicated with C<**>), a capture reforms the rest of its
4741-positional arguments with one level of "treeness", equivalent to
4742-C<@args.tree(1)>, that is, a list of lists, or C<LoL>.  The sublists are not
4743-automatically flattened; that is, if a sublist is a C<Parcel>, it
4744-remains a list until subsequent processing decides how flat or
4745-treelike the sublist should be.
4746-
4747-To force a non-flattening item context, use the "C<item>" operator.
4748-
4749-=head2 Forcing capture context
4750-
4751-The C<|> prefix operator may be used to force "capture" context on its
4752-argument and I<also> defeat any scalar argument checking imposed by
4753-subroutine signature declarations.  Any resulting list arguments are
4754-then evaluated lazily.
4755-

S03-operators.pod
686-
687-Interpolates the elements of the C<Parcel> (or any other ordered value)
688-into the current argument list as if they had been specified literally,
689-separated by semicolons, that is, at the multi-dimensional level.
690-It is an error to use this operator outside of a lol context; in
691:other words it must be bound into a C<**> (slice) parameter rather
692-than a C<*> (slurpy) parameter.
693-
694-=item *
695-
696-C<< prefix:<+^> >>, numeric bitwise negation
697-
698-    +^$x
699-
700-Coerces to C<Int> and then does bitwise negation on the number, returning an C<Int>.
701-(In order not to have to represent an infinitude of 1's, it represents
702-that value as some negative in 2's complement form.)
703-
704-=item *
705-
706-C<< prefix:<~^> >>, string bitwise negation
--
2643-    source() ==> filter() ==> sink()
2644-
2645-The forms with the double angle append rather than clobber the sink's
2646-todo list.  The C<<< ==>> >>> form always looks ahead for an appropriate
2647-target to append to, either the final sink in the chain, or the next
2648:filter stage with an explicit C<@(*)> or C<@(**)> target.  This means
2649-you can stack multiple feeds onto one filter command:
2650-
2651-    source1() ==>>
2652-    source2() ==>>
2653-    source3() ==>>
2654-    filter(@(*)) ==> sink()
2655-
2656-Similar semantics apply to C<<< <<== >>> except it looks backward for
2657-an appropriate target to append to.
2658-
2659-=item *
2660-
2661-Control block: <ws>{...}
2662-
2663-When a block occurs after whitespace where an infix is expected, it is
--
4545-
4546-or you can let the system autogenerate one for you based on the
4547-corresponding infix operator, probably by priming:
4548-
4549-    &prefix:<[*]> ::= &reduce.assuming(&infix:<*>, 1);
4550:    &prefix:<[**]> ::= &reducerev.assuming(&infix:<**>);
4551-
4552-If the reduction operator is defined separately from the infix operator,
4553-it must associate the same way as the operator used:
4554-
4555-    [-] 4, 3, 2;      # 4-3-2 = (4-3)-2 = -1
4556:    [**] 4, 3, 2;     # 4**3**2 = 4**(3**2) = 262144
4557-
4558-For list-associative operator (the ones with X in the precedence table), the
4559-implementation must take into account the listiness of the arguments; that is,
4560-if repeatedly applying a binary version of the operator would produce the
4561-wrong results, then it cannot be implemented that way.  For instance:
4562-
4563-    [^^] $a, $b, $c;  # means ($a ^^ $b ^^ $c), NOT (($a ^^ $b) ^^ $c)
4564-
4565-For chain-associative operators (like C<< < >>), all arguments are taken
4566-together, just as if you had written it out explicitly:
4567-
4568-    [<] 1, 3, 5;      # 1 < 3 < 5
4569-
4570-For list infix operators, flattening is not done on the input list, so
4571-that multiple parcels may be passed in as comma-separated arguments:

S06-routines.pod
1325-
1326-Some functions take more than one list of positional and/or named arguments,
1327-that they wish not to be flattened into one list.  For instance, C<zip()> wants
1328-to iterate several lists in parallel, while array and hash subscripts want to
1329-process a multidimensional slice.  The set of underlying argument lists may be
1330:bound to a single array parameter declared with a double C<**> marker:
1331-
1332:    sub foo (**@slice) { ... }
1333-
1334-Note that this is different from
1335-
1336-    sub foo (|slice) { ... }
1337-
1338-insofar as C<|slice> is bound to a single argument-list object that
1339-makes no commitment to processing its structure (and maybe doesn't
1340:even know its own structure yet), while C<**@slice> has to create
1341-an array that binds the incoming dimensional lists to the array's
1342-dimensions, and make that commitment visible to the rest of the scope
1343-via the sigil so that constructs expecting multidimensional lists
1344-know that multidimensionality is the intention.
1345-
1346-It is allowed to specify a return type:
1347-
1348:    sub foo (**@slice --> Num) { ... }
1349-
1350-The invocant does not participate in multi-dimensional argument lists,
1351:so C<self> is not present in the C<**@slice> below:
1352-
1353:    method foo (**@slice) { ... }
1354-
1355:The C<**> marker is just a variant of the C<*> marker that ends up
1356-requesting parcels when binding (underlyingly calling C<.getarg>) rather
1357-than requesting individual elements as the flattening C<*> does (underlyingly
1358-calling C<.get>).
1359-
1360-=head2 Zero-dimensional argument list
1361-
1362-If you call a function without parens and supply no arguments, the
1363-argument list becomes a zero-dimensional slice.  It differs from
1364-C<\()> in several ways:
1365-
1366:    sub foo (**@slice) {...}
1367-    foo;        # +@slice == 0
1368-    foo();      # +@slice == 1
1369-
1370-    sub bar (|args = \(1,2,3)) {...}
1371-    bar;        # $args === \(1,2,3)
1372-    bar();      # $args === \()
1373-
1374-=head2 Feed operators
1375-
1376-The variadic list of a subroutine call can be passed in separately from
1377-the normal argument list, by using either of the I<feed> operators:
1378-C<< <== >> or C<< ==> >>.  Syntactically, feed operators expect to find a
1379-statement on either end.  Any statement can occur on the source end;
1380-however not all statements are suitable for use on the sink end of a feed.
1381-

S09-data.pod
397-
398-is really short for something like:
399-
400-    @array.postcircumfix:<[ ]>( (0..10), (42), (@x) );
401-
402:The method's internal C<**@slices> parameter turns the subscripts into three
403-independent C<Parcel> lists, which can be read lazily independently of one other.
404-(Though a subscripter will typically use them left-to-right as it slices each
405- dimension in turn.)
406-
407-Note that:
408-
409-    @array[@x,@y]
410-
411-is always interpreted as a one-dimensional slice in the outermost
412-dimension, which is the same as:
413-
414-    @array[@x,@y;]
415-
416-or more verbosely:
417-
--
440-
441-    my @calendar[12;*;24];          # day-of-month dimension unlimited/ragged
442-    @calendar[1;42;8] = 'meeting'   # See you on January 42nd
443-
444-It is also possible to specify that an array has an arbitrary number
445:of dimensions, using a "hyperwhatever" (C<**>) at the end of the
446-dimensional specification:
447-
448:    my @grid[**];                      # Any number of dimensions
449:    my @spacetime[*;*;*;**];           # Three or more dimensions
450:    my @coordinates[100;100;100;**];   # Three or more dimensions
451-
452:Note that C<**> is a shorthand for something that means C<||(* xx *)>, so the extra
453-dimensions are all of arbitrary size. To specify an arbitrary number
454-of fixed-size dimensions, write:
455-
456-    my @coordinates[ ||(100 xx *) ];
457-
458-This syntax is also convenient if you need to define a large number of
459-consistently sized dimensions:
460-
461-    my @string_theory[ ||(100 xx 11) ];    # 11-dimensional
462-
463-=head1 User-defined array indexing
464-
465-Any array may also be given a second set of user-defined indices, which
466-need not be zero-based, monotonic, or even integers. Whereas standard array
467-indices always start at zero, user-defined indices may start at any
--
715-    @calendar{Dec; *; *[0..2]}
716-
717-    # Last three business hours of first three days in July...
718-    @calendar[*{July}; 0..2; *-3..*-1]
719-
720:Extending this feature, you can use C<**> within an indexing operation
721-as if it were a multidimensional array of I<all> the indices of a fixed
722-number of dimensions of the indexed array:
723-
724-    # Last three business hours of first three days in July...
725:    @calendar{ July; **[0..2; *-3..*-1] }
726-
727-    # Same...
728:    @calendar[ **{July; 1..3}; *-3..*-1]
729-
730-It is also possible to stack subscript declarations of various
731-types, including a final normal signature to specify named args
732-and return type:
733-
734-    my @array[10]{'a'..'z'}(:$sparse --> MyType);
735-
736-[Note: the final signature syntax is merely reserved for now, and
737-not expected to work until we figure out what it really means, if
738-it means anything.]
739-
740-=head1 PDL support
741-
742-An array C<@array> can be tied to a PDL at declaration time:
743-
--
854-
855-    @nums[0,1,2;*;*]
856-
857-But you should maybe write the last form anyway just for good
858-documentation, unless you don't actually know how many more dimensions
859:there are.  For that case use C<**>:
860-
861:    @nums[0,1,2;**]
862-
863-If you wanted that C<0..2> range to mean
864-
865-    @nums[0;1;2]
866-
867-it is not good enough to use the C<|> prefix operator, because
868-that interpolates at the comma level, so:
869-
870-    @nums[ |(0,1,2) ]
871-
872-just means
873-
874-    @nums[ 0,1,2 ];
875-
876-Instead, to interpolate at the semicolon level, you need to use the C<||> prefix operator:
--
1176-    my %hash{Any};
1177-    my %hash{*};
1178-
1179-A hash of indeterminate dimensionality is:
1180-
1181:    my %hash{**};
1182-
1183-You can limit the keys to objects of particular types:
1184-
1185-    my Fight %hash{Dog; Squirrel where {!.scared}};
1186-
1187-The standard Hash:
1188-
1189-    my %hash;
1190-
1191-is really short for:
1192-
1193-    my Mu %hash{Str(Any)};
1194-
1195-Note that any type used as a key must be intrinsically immutable,
1196-or it has to be able to make a copy that functions as an immutable key,

S12-objects.pod
1490-via the delegate.  (This allows you to call a C<FALLBACK> routine
1491-of your own if the delegation would fail, since your own C<FALLBACK>
1492-always runs after delegation, even wildcard delegation.)  If instead
1493-you want to delegate completely and utterly, including a search of
1494-the delegate for its own fallback methods, with abject failure if
1495:the delegate can't handle it, then use the "HyperWhatever" instead:
1496-
1497:    has $the_real_me handles **;
1498-
1499-If, where you would ordinarily specify a string, you put a pair, then
1500-the pair maps the method name in this class to the method name in the
1501-other class.  If you put a hash, each key/value pair is treated as
1502-such a mapping.  Such mappings are not considered wildcards.
1503-
1504-    has $.fur handles { :shakefur<shake>, :scratch<get_fleas> };
1505-
1506-You I<can> do a wildcard renaming, but not with pairs.  Instead do smartmatch
1507-with a substitution:
1508-
1509-    has $.fur handles (s/^furget_/get_/);
1510-
1511-Ordinarily delegation is based on an attribute holding an object, but it can
1512-also be based on the return value of a method:

S13-overloading.pod
136-
137-A class may define methods that allow it to respond as if it were a
138-routine, array, or hash.  The long forms are as follows:
139-
140-    method postcircumfix:<( )> (|capture) {...}
141:    method postcircumfix:<[ ]> (**@slice) {...}
142:    method postcircumfix:<{ }> (**@slice) {...}
143-
144-Those are a bit unwieldy, so you may also use these short forms:
145-
146-    method &.( |capture ) {...}
147:    method @.[ **@slice ] {...}
148:    method %.{ **@slice } {...}
149-
150-The sigil-dot sequence in these short forms autogenerates the
151-corresponding public operators, in exactly the same way that
152-the sigil-dot in:
153-
154-    has $.action;
155-    has @.sequence;
156-    has %.mapping;
157-
158-autogenerates public accessor methods.
159-
160-And because it uses the same method-autogeneration mechanism, the
161-specific sigil used to specify a short-form postcircumfix operator
162-doesn't actually matter...as long as it's followed by a dot and the
163-bracket pair containing the signature. (Though it's probably kinder

S29-functions.pod
408-Forces flat context on its arguments, and returns them.
409-The heavy work is done by the C<*@> binding.
410-
411-=item lol
412-
413: multi lol ( **@list --> List )
414-
415-Forces the argument list to be evaluated in lol ("list of lists") context.
416-(Subscripts treat such a list of lists as a multidimensional slice.)
417-Any C<Parcel> within the top level of the outer list will be transformed into an item (Scalar).
418:The work is actually done by the binding to the C<**@> parameter.
419-See also the more general C<.tree> method, which defaults to itemizing every level.
420-
421-=item hash
422-
423-The C<hash> contextualizer
424-
425- multi hash ( *@list --> Hash )
426-
427-Forces the argument list to be evaluated in hash context.
428-The expression is evaluated in list context (flattening any C<Capture>s),
429-then a hash will be created from the list, taken as a list of C<Pair>s.
430-(Any element in the list that is not a C<Pair> will pretend to be a key
431-and grab the next value in the list as its value.)  Equivalent to
432-C<%()> (except that empty C<%()> means C<%($/)>, while
433-empty C<hash()> means an empty hash).

S32-setting-library/Containers.pod
42-
43-=over
44-
45-=item cat
46-
47: multi cat( **@list --> Cat )
48-
49-C<cat> reads arrays serially rather than in parallel as C<zip> does. It
50-returns all of the elements of the containers that were passed to it
51-like so:
52-
53- cat(@a;@b;@c);
54-
55-Typically, you could just write C<(@a,@b,@c)>, but sometimes
56-it's nice to be explicit about that:
57-
58- @foo := [[1,2,3],[4,5,6]]; say cat(||@foo); # 1,2,3,4,5,6
59-
60-In addition, a C<Cat> in item context emulates the C<Str> interface lazily.
61-
62-[Conjecture: Cats should maybe just do the lazy strings, and leave flattening
63-to other operators.]
64-
65-=item roundrobin
66-
67: multi roundrobin( **@list --> Parcel )
68-
69-C<roundrobin> is very similar to C<zip>.  The difference is that
70-C<roundrobin> will not stop on lists that run out of elements but
71-simply skip any undefined value:
72-
73- my @a = 1;
74- my @b = 1..2;
75- my @c = 1..3;
76- for roundrobin( @a; @b; @c ) -> $x { ... }
77-
78-will get the following values for C<$x>: C<1, 1, 1, 2, 2, 3>
79-
80-=item zip
81-
82: multi zip ( **@list --> Parcel of Parcel )
83: multi infix:<Z> ( **@list --> Parcel of Parcel )
84-
85-zip takes any number of arrays and returns one tuple for every index.
86-This is easier to read in an example:
87-
88- for zip(@a;@b;@c) -> $nth_a, $nth_b, $nth_c {
89-   ...
90- }
91-
92-Mnemonic: the input arrays are "zipped" up like a zipper.
93-
94-The C<zip> function defaults to stopping as soon as any of its lists
95-is exhausted.  This behavior may be modified by conceptually extending
96-any short list using C<*>, which replicates the final element.
97-
98-If all lists are potentially infinite, an evaluation in C<eager>