Merge pull request #267 from gfldex/master

show of with Hyper Operators

doc/Language/operators.pod

@@ -166,7 +166,62 @@ with C<R>. Associativity of operands is reversed as well.
     say [R/] 2, 4, 16; # 2
 
 =head2 Hyper Operators
-TODO
+
+Hyper operators apply a given operator enclosed by C<«> and C<»> to one or two
+lists, returning the resulting list. The pointy part of C<«> or C<»> has to
+point to the shorter list. A list with just one element is fine too. If one of
+the lists is shorter then the other, the operator will cycle over the shorter
+list until all elements of the longer list are processed.
+
+    say (1,2,3) »*» 2;       # (2,4,6)
+    say (1,2,3,4) »~» <a b>; # (1a 2b 3a 4b)
+    say (1,2,3) »+« (4,5,6); # (5 7 9)
+
+Assignment meta operators can be hyped.
+
+    my @a = 1,2,3;
+    say @a »+=» 1; # [2 3 4]
+
+Hyper forms of unary opators have the pointy bit point to the operator and
+the blunt end at the list to be operated on.
+
+    my @wisdom = True, False, True;
+    say !« @wisdom; # [False True False]
+    
+    my @a = 1,2,3;
+    @a»++;          # (2,3,4)
+
+Hyper operators are defined recursivly on nested arrays.
+
+    say -« [[1, 2], 3]; # [[-1 -2] -3]
+
+Methods can be called too, in a out of order, cuncurrent fashion. The resulting
+list is in order. Please note that all hyper operators are candidates for
+autothreading and will cause tears if said methods have side effects. The
+optimizer has full reign over hyper operators, what is the reasion that they
+can not be defined by the user.
+
+    my CarefulClass @objs;
+    my @results = @objs».take-care();
+
+    my @slops; # May Contain Nuts
+    @slops».?this-method-may-not-exist();
+
+Hyper operatos can work with hashes. The pointy direction indicates if missing
+keys are to be ignored in the resulting hash. The enclosed operator operates on
+all values that have keys in both hashes.
+
+=begin table
+C<%foo «+» %bar;>       intersection of keys
+
+C<%foo »+« %bar;>       union of keys
+
+C<%outer »+» %inner;>   only keys of %inner that exist in %outer will occur in the result
+=end table
+
+    my %outer = 1,2,3 Z=> <a b c>; 
+    my %inner = 1,2 Z=> <x z>; 
+    say %outer «~» %inner; # {"1" => "ax", "2" => "bz"}
 
 =head2 Reduction Operators
 TODO