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

Author: paultcochrane

CREDITS

@@ -11,7 +11,7 @@
 
         Thanks,
 
-        The Rakudo Team
+        The perl6/doc Team
         PS: Yes, this looks remarkably like the Linux CREDITS format
         PPS: This file is encoded in UTF-8
 

lib/Type/Any.pod

@@ -46,6 +46,9 @@ Interprets the invocant as a list, and returns that list.
 
 Interprets the invocant as a list, flattens it, and returns that list.
 
+    say ((1, 2), (3)).elems;        # 2
+    say ((1, 2), (3)).flat.elems;   # 3
+
 =head2 method eager
 
 Interprets the invocant as a list, evaluates it eagerly, and returns that

lib/Type/Mu.pod

@@ -137,4 +137,15 @@ Returns an object of type L<ObjAt> which uniquely identifies the object.
 Value types override this method which makes sure that two equivalent objects
 return the same return value from C<WHICH>.
 
+=head2 trait is export
+
+    multi sub trait_mod:<is>(Mu:U \type, :$export!)
+
+Marks a type as being exported, that is, available to external users.
+
+    my class SomeClass is export { }
+
+A user of a module or class automatically gets all the symbols imported that
+are marked as C<is export>.
+
 =end pod

lib/Type/Parameter.pod

@@ -70,13 +70,17 @@ L<rw|#rw>-parameter which can only bind to variables, never to values.
 
 =head2 method capture
 
-Returns C<True> for parameters that capture the rest of the argument list.
+Returns C<True> for parameters that capture the rest of the argument list into
+a single object of L<type Capture|/type/Capture>.
 
-    sub f(\capture) { }
+    sub f(|capture) { }
+    say &f.signature.params[0].capture;     # True
 
 Capture parameters do not force any context on the values passed bound
 to them, which is why they cannot have sigils.
 
+
+
 =head2 method rw
 
 Returns C<True> for C<is rw> parameters.

lib/Type/Routine.pod

@@ -142,9 +142,31 @@ produces
 Note that C<return> marks return values as read only; if you need an early
 exit from an C<is rw> routine, you have to use C<return-rw> instead.
 
+=head2 trait is export
+
+    multi sub trait_mod:<is>(Routine $r, :$export!)
+
+Marks a routine as exported to the rest of the world
+
+=begin code :allow<B>
+module Foo {
+    sub double($x) B<is export> {
+        2 * $x
+    }
+}
+
+import Foo;         # makes sub double available
+say double 21;      # 42
+=end code
+
+From inside another file you'd say C<use Foo;> to load a module and import the
+exported functions.
+
+
 =begin comment
 
-TODO: traits hidden_from_backtrace, export, DEPRECATED
+TODO: explain export tags
+TODO: traits hidden_from_backtrace, DEPRECATED
 
 =end comment
 

lib/Type/Signature.pod

@@ -146,7 +146,7 @@ say limit-lines "a \n b \n c", Int; # "a \n b \n c"
 For explicitly indicating the normal behaviour, C<:_> can be used, but this is
 unnecessary. C<:(Num:_ $)> is the same as C<:(Num $)>.
 
-=head2 Slurpy (A.K.A. Variadic) Parameters
+=head2 X<Slurpy (A.K.A. Variadic) Parameters|parameter,*@;parameter,*%>
 
 An array or hash parameter can be marked as I<slurpy> by a leading asterisk,
 which means it can bind to an arbitrary amount of arguments (zero or more).
@@ -265,7 +265,7 @@ However, this unpacking of objects as their attributes is only the default
 behavior. To make an object get destructured differently, change its
 L<C<Capture>> method.
 
-=head2 Capture Parameters
+=head2 X<Capture Parameters|parameter,|>
 
 Prefixing a parameter with a vertical bar C<|> makes the parameter a
 L<C<Capture>>, using up all the remaining positional and named
@@ -275,7 +275,7 @@ This is often used in L<C<proto> definitions|proto> (like C<proto foo (|) {*}>)
 to indicate that the routine's L<C<multi> definitions|multi> can have any
 L<type constraints|#Type_Constraints>.
 
-=head2 Parameter Traits and Modifiers
+=head2 X<Parameter Traits and Modifiers|trait,is copy;trait,is rw>
 
 By default, parameters are bound to their argument and marked as
 read-only. One can change that with traits on the parameter.

lib/Type/WhateverCode.pod

@@ -9,4 +9,53 @@
 C<WhateverCode> objects are the result of L<Whatever>-currying. See the
 L<Whatever> documentation for details.
 
+When you wish to control how a method or function interprets any
+I<Whatever stars>, you may use multi dispatch with C<Whatever> and
+C<WhateverCode> parameters to do so, as in the following example:
+
+    class Cycle {
+          has $.pos;
+          has @.vals;
+    }
+    
+    multi sub get_val(Cycle $c, Int $idx) {
+          $c.vals[$idx % $c.vals.elems]
+    }
+    
+    # Define what to do with a stand-alone * as the second argument
+    multi sub get_val(Cycle $c, Whatever $idx) {
+        get_val($c, $c.pos);
+    }
+    
+    # Define what to do with a * in an expression
+    multi sub get_val(Cycle $c, WhateverCode $idx) {
+        get_val($c, $idx($c.pos));
+    }
+    
+    my Cycle $c .= new(:pos(2),:vals(0..^10));
+    
+    say get_val($c, 3);   # 3
+    say get_val($c, *);   # 2
+    say get_val($c, *-1); # 1
+
+Since C<WhateverCode> objects are C<Callable> you may use introspection
+to create as fancy a behavior as you wish.  Continuing the following
+example we may add handling for two I<Whatever stars>:
+
+    # Define what to do with two * in an expression
+    multi sub get_val(Cycle $c, WhateverCode $idx where { .arity == 2 }) {
+        get_val($c, $idx($c.pos, $c.vals.elems));
+    }
+    
+    say get_val($c, * + * div 2); # 2 + 10/2 = 7
+
+Note, though, that subexpressions may impose their own I<Whatever star>
+rules:
+
+    my @a = (0,1,2);
+    say get_val($c, @a[*-1]) # 2, because the star belongs to the Array class
+
+This can make the ownership of I<Whatever stars> become confusing rather
+quickly, so be careful not to overdo it.
+
 =end pod

t/typegraph.t

@@ -3,6 +3,13 @@ use Test;
 use lib 'lib';
 use Perl6::TypeGraph;
 
+plan 8;
+
+if $*VM.name eq 'parrot' {
+    skip_rest 'segfaults on parrot';
+    exit;
+}
+
 my $t = Perl6::TypeGraph.new-from-file('type-graph.txt');
 ok $t, 'Could parse the file';
 ok $t.types<Array>, 'has type Array';

sync renamed to util/sync

@@ -0,0 +1,2 @@
+#!/bin/sh
+rsync -az --delete html/build-log/ doc.perl6.org@www.p6c.org:/var/www/doc.perl6.org/build-log/