Merge pull request #2818 from taboege/update-2019-03

Update for 2019.03

doc/Language/exceptions.pod6

@@ -385,13 +385,14 @@ printing a backtrace along with the message:
 
 =head1 Control exceptions
 
-Control exceptions are thrown by certain L<keywords|/language/phasers#CONTROL>
-and are handled either automatically or by the appropriate
-L<phaser|/language/phasers#Loop_phasers>. Any unhandled control exception is
-converted to a normal exception.
+Control exceptions are raised when throwing an Exception which does the
+L<X::Control|/type/X::Control> role (since Rakudo 2019.03). They are
+usually thrown by certain L<keywords|/language/phasers#CONTROL> and are
+handled either automatically or by the appropriate L<phaser|/language/phasers#Loop_phasers>.
+Any unhandled control exception is converted to a normal exception.
 
 =begin code
-{ return; CATCH { default { $*ERR.say: .^name, ': ',.Str } } }
+{ return; CATCH { default { $*ERR.say: .^name, ': ', .Str } } }
 # OUTPUT: «X::ControlFlow::Return: Attempt to return outside of any Routine␤»
 # was CX::Return
 =end code

doc/Language/pragmas.pod6

@@ -74,6 +74,35 @@ pragmas, currently the three above; thus, it would be equivalent to
     use MONKEY-SEE-NO-EVAL;
     use MONKEY-GUTS;
 
+X<dynamic-scope, pragma>
+=head2 dynamic-scope
+
+Applies the L<is dynamic|/type/Variable#trait_is_dynamic> trait to variables
+in the pragma's lexical scope. The effect can be restricted to a subset of
+variables by listing their names as arguments. By default applies to I<all>
+variables.
+
+=begin code :allow<C>
+# Apply C<is dynamic> only to $x, but not to $y
+use dynamic-scope <$x>;
+
+sub poke {
+    say $CALLER::x;
+    say $CALLER::y;
+}
+
+my $x = 23;
+my $y = 34;
+poke;
+
+# OUTPUT:
+# 23
+# Cannot access '$y' through CALLER, because it is not declared as dynamic
+=end code
+
+This pragma is not currently part of any Perl 6 specification and was added
+in Rakudo 2019.03.
+
 X<|experimental, pragma>
 =head2 experimental
 

doc/Type/Bag.pod6

@@ -77,7 +77,7 @@ Of course, you can also create a C<Bag> with the C<.new> method.
 
     my $breakfast = Bag.new( <spam eggs spam spam bacon spam> );
 
-Since 6.d (2019.01 and later) you can also use this syntax for parameterization
+Since 6.d (2019.03 and later) you can also use this syntax for parameterization
 of the C<Bag>, to specify which type of values are acceptable:
 
     # only allow strings (Str) in the Bag
@@ -93,7 +93,7 @@ Finally, you can create Bag masquerading as a hash by using the C<is> trait:
     say %b<a>;  # True
     say %b<d>;  # False
 
-Since 6.d (2019.01 and later), this syntax also allows you to specify the
+Since 6.d (2019.03 and later), this syntax also allows you to specify the
 type of values you would like to allow:
 
     # limit to strings

doc/Type/BagHash.pod6

@@ -81,7 +81,7 @@ You can also create C<BagHash> masquerading as a hash by using the C<is> trait:
     say %bh<b>;  # 2
     say %bh<d>;  # 0
 
-Since 6.d (2019.01 and later) it is also possible to specify the type of values
+Since 6.d (2019.03 and later) it is also possible to specify the type of values
 you would like to allow in a C<BagHash>.  This can either be done when calling
 C<.new>:
 

doc/Type/Blob.pod6

@@ -402,7 +402,7 @@ Defined as:
 Returns a native C<num> value for the B<eight> bytes starting at the given
 position.
 
-=head1 Methods on blob8 only (6.d, 2019.01 and later)
+=head1 Methods on blob8 only (6.d, 2019.03 and later)
 
 =head2 method read-ubits
 

doc/Type/Buf.pod6

@@ -316,13 +316,13 @@ Writes a native C<num64> IEEE floating point value at the given position with
 the given endianness.
 
 
-=head1 Methods on blob8 only (6.d, 2019.01 and later)
+=head1 Methods on buf8 only (6.d, 2019.03 and later)
 
 =head2 method write-ubits
 
 Defined as:
 
-    method write-ubits(blob8:D: uint $pos, uint $bits, UInt:D $value --> Nil)
+    method write-ubits(buf8:D: uint $pos, uint $bits, UInt:D $value --> Nil)
 
 Writes an unsigned integer value to the B<bits> from the given B<bit> offset
 and given number of bits.  The endianness of the bits is assumed to be
@@ -332,7 +332,7 @@ C<BigEndian>.  Always returns Nil.
 
 Defined as:
 
-    method write-bits(blob8:D: uint $pos, uint $bits, Int:D $value --> Nil)
+    method write-bits(buf8:D: uint $pos, uint $bits, Int:D $value --> Nil)
 
 Writes a signed integer value for the B<bits> from the given B<bit> offset
 and given number of bits.  The endianness of the bits is assumed to be

doc/Type/Mix.pod6

@@ -70,7 +70,7 @@ declare them; in that case, we can employ C<is> to declare their type:
     say %n.^name; # OUTPUT: «Mix␤»
     say %n;       # OUTPUT: «Mix(a(2), c(3.14))␤»
 
-Since 6.d (2019.01 and later) it is also possible to specify the type of values
+Since 6.d (2019.03 and later) it is also possible to specify the type of values
 you would like to allow in a C<Mix>.  This can either be done when calling
 C<.new>:
 

doc/Type/MixHash.pod6

@@ -66,7 +66,7 @@ the mix, and the (cumulative) values become the associated numeric weights:
     say $n.keys.map(&WHAT);  # OUTPUT: «((Str) (Str))␤»
     say $n.pairs;            # OUTPUT: «(a => 2 c => 3.14)␤»
 
-Since 6.d (2019.01 and later) it is also possible to specify the type of values
+Since 6.d (2019.03 and later) it is also possible to specify the type of values
 you would like to allow in a C<MixHash>.  This can either be done when calling
 C<.new>:
 

doc/Type/Parameter.pod6

@@ -286,7 +286,7 @@ If the parameter has a
 L<sub-signature|/type/Signature#Destructuring_Parameters>,
 returns a C<Signature> object for it.  Otherwise returns C<Any>.
 
-=head1 Runtime creation of Parameter objects (6.d, 2019.01 and later)
+=head1 Runtime creation of Parameter objects (6.d, 2019.03 and later)
 
    Parameter.new( ... )
 

doc/Type/Set.pod6

@@ -61,7 +61,7 @@ Of course, you can also create a C<Set> with the C<.new> method.
 
     my $fruits = Set.new( <peach apple orange apple apple> );
 
-Since 6.d (2019.01 and later) you can also use this syntax for parameterization
+Since 6.d (2019.03 and later) you can also use this syntax for parameterization
 of the C<Set>, to specify which type of values are acceptable:
 
     # only allow strings (Str) in the Set
@@ -77,7 +77,7 @@ Finally, you can create Set masquerading as a hash by using the C<is> trait:
     say %s<a>;  # True
     say %s<d>;  # False
 
-Since 6.d (2019.01 and later), this syntax also allows you to specify the
+Since 6.d (2019.03 and later), this syntax also allows you to specify the
 type of values you would like to allow:
 
     # limit to strings

doc/Type/SetHash.pod6

@@ -92,7 +92,7 @@ You can also create C<SetHash> masquerading as a hash by using the C<is> trait:
     say %sh<a>;  # True
     say %sh<d>;  # False
 
-Since 6.d (2019.01 and later) it is also possible to specify the type of values
+Since 6.d (2019.03 and later) it is also possible to specify the type of values
 you would like to allow in a C<SetHash>.  This can either be done when calling
 C<.new>:
 

doc/Type/Signature.pod6

@@ -1078,7 +1078,7 @@ Defined as:
 
 Throws C<X::Cannot::Capture>.
 
-=head1 Runtime creation of Signature objects (6.d, 2019.01 and later)
+=head1 Runtime creation of Signature objects (6.d, 2019.03 and later)
 
 =for code :preamble<role Type {}>
 Signature.new(params => (...), returns => Type, arity => 1, count => 1)

doc/Type/X/Control.pod6

@@ -0,0 +1,38 @@
+=begin pod
+
+=TITLE role X::Control
+
+=SUBTITLE Role for control exceptions
+
+    role X::Control is Exception { }
+
+This role turns an exception into a L<control exception|/language/exceptions#Control_exceptions>,
+like C<CX::Next>, C<CX::Take>, etc.
+
+Since Rakudo 2019.03, C<throw>ing an C<X::Control> object raises a control
+exception which is caught by the L<CONTROL phaser|/language/phasers#CONTROL>
+instead of L<CATCH|/language/phasers#CATCH>. This allows to define custom
+control exceptions.
+
+For example
+
+=begin code
+class CX::Oops does X::Control {
+    has $.message
+}
+
+sub oops ($message = 'oops') {
+    CX::Oops.new(:$message).throw
+}
+
+oops "I messed up!";
+
+CONTROL {
+    default {
+        say "Controlled { .^name }: { .message }"
+    }
+}
+# OUTPUT: «Controlled CX::Oops: I messed up!␤»
+=end code
+
+=end pod

doc/Type/X/Method/NotFound.pod6

@@ -28,7 +28,7 @@ Returns the method name that was invoked.
 
 =head2 method typename
 
-    method typename returns Str:D
+    method typename(--> Str:D)
 
 Returns the name of the invocant type.
 
@@ -38,4 +38,12 @@ Returns the name of the invocant type.
 
 Returns C<True> for private methods, and C<False> for public methods.
 
+=head2 method addendum
+
+    method addendum(--> Str:D)
+
+Returns additional explanations or hints.
+
+I<Note>: C<addendum> was introduced in Rakudo 2019.03.
+
 =end pod