Adds numeric context

Refs #1225 and #124

Author: JJ

doc/Language/contexts.pod6

@@ -19,6 +19,34 @@ You can force that sink context on L<Iterator>s, by using the L<C<sink-all>|/rou
 
 In general, blocks will warn if evaluated in sink context; however, L<gather/take blocks|/language/control#Flow%29_gather_take> are explicitly evaluated in sink context, with values returned explicitly using C<take>.
 
+=head1 Number
+
+This context, and probably all of them except sink above, are I<conversion> or I<interpretation> contexts in the sense that they take an untyped or typed variable and duck-type it to whatever is needed to perform the operation. In some cases that will imply a conversion (from L<Str> to L<Int>, for instance); in other cases simply an interpretation (L<IntStr> will be interpreted as L<Int> or as L<Str>).
+
+I<Number context> is called whenever we need to apply a numerical operation on a variable.
+
+=begin code
+my $not-a-string="1                 ";
+my $neither-a-string="3                        ";
+say $not-a-string+$neither-a-string; # OUTPUT: «4␤»
+=end code
+
+In the code above, strings will be interpreted in numeric context as long as there is only some numbers and no other characters. It can have any number of leading or trailing whitespace, however.
+
+Numeric context can be forced by using arithmetic operators such as C<+> or C<->. In that context, the L<C<Numeric>|/routine/Numeric> method will be called if available and the value returned used as the numeric value of the object.
+
+=begin code
+my $t = True;
+my $f = False;
+say $t+$f;      # OUTPUT: «1␤»
+say $t.Numeric; # OUTPUT: «1␤»
+say $f.Numeric; # OUTPUT: «0␤»
+my $list= <a b c>;
+say True+$list; # OUTPUT: «4␤»
+=end code
+
+In the case of I<listy> things, the numeric value will be in general equivalent to C<.elems>; in some cases, like L<Thread|/Numeric#(Thread)_method_Numeric> it will return an unique thread identifier.
+
 =end pod
 
 # vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6