[operators] start with Nonchaining Binary Precedence

Author: moritz

lib/operators.pod

@@ -499,4 +499,56 @@ except that C<temp> does not reset the value).
 Hypothetical reset: if the current scope is exited either through an exception
 or C<fail()>, the old value is restored.
 
+=head1 Nonchaining Binary Precedence
+
+=head2 infix does
+
+    sub infix:<does>(Mu $obj, Mu $role)
+
+Mixes C<$role> into C<$obj> at run time. Requires C<$obj> to be mutable.
+
+C<$role> doesn't need to a be a role, it can be something that knows how
+to act like a role, for example enum values.
+
+=head2 infix but
+
+    sub infix:<but>(Mu $obj, Mu $role)
+
+Creates a copy of C<$obj> with C<$role> mixed in. Since C<$obj> is not
+modified, C<but> can be used to created immutable values with mixins.
+
+C<$role> doesn't need to a be a role, it can be something that knows how
+to act like a role, for example enum values.
+
+=head2 infix cmp
+
+    multi sub infix:<cmp>($a, $b) returns Order:D
+
+Generic, "smart" three-way comparator.
+
+Compares strings with string semantics, numbers
+with number semantics, L<Pair> objects first by key and then by value etc.
+
+if C<$a eqv $b>, then C<$a cmp $b> always returns C<Order::Same>.
+
+    say (a => 3) cmp (a => 4);      # Increase
+    say 4        cmp 4.0;           # Same
+    say 'b'      cmp 'a';           # Decrease
+
+=head2 infix leg
+
+    multi sub infix:<leg>($a, $b) returns Order:D
+
+String three-way comparator.
+
+Coerces both arguments to L<Str>, and then does a lexicographic comparison.
+
+=head2 infix <=>
+
+    multi sub infix:«<=>»($a, $b) returns Order:D
+
+Numeric three-way comparator.
+
+Coerces both arguments to L<Real>, and then does a numeric comparison.
+
 =end pod