Merge branch 'master' of github.com:perl6/doc

Author: JJ

doc/Language/containers.pod6

@@ -324,17 +324,31 @@ last resort, you can use Promises to L<handle|/type/Promise#method_in> timeouts.
 Any container can have a type constraint in the form of
 a L<type object|/language/typesystem#Type_objects> or a L<subset|/language/typesystem#subset>.
 Both can be placed between a declarator and the variable name or after the trait L<of|/type/Variable#trait_is_dynamic>.
-The constraint is a property of the container, not the variable. Any (re-)binding may change the
-type constraint or remove the constraint altogether if bound to a value instead of a container.
-Introspection of type constraints on containers is provided by C<.VAR.of>.
-
-    EVAL ‚my Int $i = 42; $i := "forty plus two";‘;
-    CATCH { default { say .^name, ' ', .Str } }
-    # OUTPUT: «Type check failed in binding; expected Int but got Str ("forty plus two")␤…»
-
-The default type constraint of a C<Scalar> container is Any. For &-sigiled
-containers it's C<Callable> and @-sigiled containers are of type C<Array>. Please
-note that binding can change the type constraint.
+The constraint is a property of the container, not the variable.
+
+Variables may have no container in them, yet still offer the ability to
+re-bind and typecheck that rebind. The reason for that is in such cases the
+binding operator L<:=|/operators#infix_:=> performs the typecheck:
+
+    my Int \z = 42;
+    z := 100; # OK
+    z := "x"; # Typecheck failure
+
+The same isn't the case when, say, binding to a L<Hash> key, as there the
+binding is handled by a method call (even though the syntax remains the same,
+using C<:=> operator).
+
+The default type constraint of a C<Scalar> container is L<Mu>.
+Introspection of type constraints on containers is provided by C<.VAR.of>
+method, which for C<@> and C<%> sigiled variables gives the constraint for
+values:
+
+    my Str $x;
+    say $x.VAR.of;  # OUTPUT: «(Str)␤»
+    my Num @a;
+    say @a.VAR.of;  # OUTPUT: «(Num)␤»
+    my Int %h;
+    say %h.VAR.of;  # OUTPUT: «(Int)␤»
 
 =head1 Custom containers
 

doc/Language/modules.pod6

@@ -592,7 +592,7 @@ lib
     library files and their installed location can be determined through the
     C<%?RESOURCES> Hash indexed on the name provided. C<tags> is also optional, but is used to describe the module in the Perl6 ecosystem.
 
-    C<depends>, C<build-depends> and C<test-depends> include different modules that are used in those phases of the of installation. The last two are optional, but convenient. 
+    C<depends>, C<build-depends> and C<test-depends> include different modules that are used in those phases of the of installation. The last two are optional, but convenient.
 
     The L<Test::META module | https://github.com/jonathanstowe/Test-META/>
     can help you check the correctness of the META6.json file.

doc/Language/operators.pod6

@@ -2290,6 +2290,9 @@ different.
 This will output 43, since C<$b> and C<$a> both represented the same
 object.
 
+If type constrains on variables or containers are present a type check will be
+performed at runtime. On failure C<X::TypeCheck::BindingType> will be thrown.
+
 Please note that C<:=> is a compile time construct. As such it can not be
 referred to at runtime and thus can't be used as an argument to meta operators.
 

doc/Language/traps.pod6

@@ -1391,30 +1391,52 @@ beware unintentional combination of C<LEAVE> phasers and C<exit> calls.
 
 =head2 C<LEAVE> phaser may run sooner than you think
 
-You should always expect the C<LEAVE> phaser to be executed before
-I<anything> else in the block.
+Parameter binding is executed when we're "inside" the routine's block,
+which means C<LEAVE> phaser would run when we leave that block if parameter
+binding fails when wrong arguments are given:
 
-Here is an example:
+=begin code
+sub foo(Int) {
+    my $x = 42;
+    LEAVE say $x.Int; # ← WRONG; assumes that $x is set
+}
+say foo rand; # OUTPUT: «No such method 'Int' for invocant of type 'Any'␤»
+=end code
+
+A simple way to avoid this issue is to declare your sub or method a multi,
+so the candidate is eliminated during dispatch and the code never gets to
+binding anything inside the sub, thus never entering the routine's body:
 
 =begin code
-sub foo($ where ‘abc’) {
+multi foo(Int) {
     my $x = 42;
-    LEAVE say $x.Int; # ← WRONG; assumes that $x is not Nil
+    LEAVE say $x.Int;
 }
-say foo ‘hello’; # OUTPUT: «No such method 'Int' for invocant of type 'Any'␤»
+say foo rand; # OUTPUT: «Cannot resolve caller foo(Num); none of these signatures match: (Int)␤»
 =end code
 
-You may think that there is no way C<my $x = 42> can fail, and
-therefore C<$x> will always be defined in the C<LEAVE> block. But that
-is simply not the case. There is no guarantee that anything will be
-executed at all, which is what happens when type constraints are
-involved.
+Another alternative is placing the C<LEAVE> into another block (assuming it's
+appropriate for it to be executed when I<that> block is left, not the
+routine's body:
+
+=begin code
+sub foo(Int) {
+    my $x = 42;
+    { LEAVE say $x.Int; }
+}
+say foo rand; # OUTPUT: «Type check failed in binding to parameter '<anon>'; expected Int but got Num (0.7289418947969465e0)␤»
+=end code
 
-The right way to do it is to I<always> check that whatever you use in
-your C<LEAVE> block is defined:
+You can also ensure C<LEAVE> can be executed even if the routine is left
+due to failed argument binding. In our example, we check C<$x>
+L<is defined|/routine/andthen> before doing anything with it.
 
-=begin code :skip-test
-LEAVE say .Int with $x
+=begin code
+sub foo(Int) {
+    my $x = 42;
+    LEAVE $x andthen .Int.say;
+}
+say foo rand; # OUTPUT: «Type check failed in binding to parameter '<anon>'; expected Int but got Num (0.8517160389079508e0)␤»
 =end code
 
 =head1 Grammars

xt/words.pws

@@ -112,6 +112,7 @@ bigrat
 bindkey
 bindoruse
 binmode
+bitbucket
 bitwise
 bom
 bool
@@ -1054,6 +1055,7 @@ smartmatching
 smtp
 socketpair
 solitaryquantifier
+someauthor
 sourcecode
 spdx
 spectest