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

Author: szabgab

README

@@ -41,6 +41,11 @@ A: Several reasons:
       3.  A separate repo in the perl6 Github account invites
           more potential contributors and editors.
 
+Q: Should I include methods from superclasses or roles
+A: No. In time we'll develop a mechanism to extract those
+   automatically. Including all inherited methods manually
+   simply doesn't scale.
+
 Q: Which license is this stuff under?
 A: Both code and documentation are available under the Artistic License 2.0
    as published by The Perl Foundation. See the 'LICENSE' file for the full

TODO

@@ -0,0 +1,31 @@
+Known missing stuff
+
+Types:
+    Associative
+    Positional
+    Callable
+
+    Date        # probably possible to steal much from S32::Temporal
+    DateTime    # probably possible to steal much from S32::Temporal
+    Instant
+    Duration
+
+    Backtrace
+    Backtrace::Frame
+
+    Bag
+    Set
+    KeyBag
+    KeySet
+
+    Order (enum)
+
+    Signature
+    Parameter
+
+    Junction
+
+    ObjAt
+
+    Regex
+    Routine

htmlify.pl

@@ -1,6 +1,7 @@
 #!/usr/bin/env perl6
 use v6;
 use Pod::To::HTML;
+use URI::Escape;
 
 # this script isn't in bin/ because it's not meant
 # to be installed.
@@ -9,18 +10,33 @@
 my %types;
 my %routines;
 
+sub recursive-dir($dir) {
+    my @todo = $dir;
+    gather while @todo {
+        my $d = @todo.shift;
+        for dir($d) -> $f {
+            if $f.f {
+                take $f;
+            }
+            else {
+                @todo.push($f.path);
+            }
+        }
+    }
+}
+
 sub MAIN($out_dir = 'html') {
     for ('', <type language routine>) {
         mkdir "$out_dir/$_" unless "$out_dir/$_".IO ~~ :e;
     }
 
     # TODO:  be recursive instead
-    my @source = dir('lib').grep(*.f).grep(rx{\.pod$});
+    my @source := recursive-dir('lib').grep(*.f).grep(rx{\.pod$});
 
     my $tempfile = join '-', "tempfile", $*PID, (1..1000).pick ~ '.temp';
 
     for (@source) {
-        my $podname = .basename.subst(rx{\.pod$}, '').subst(:g, '/', '::');
+        my $podname = .path.subst('lib/', '').subst(rx{\.pod$}, '').subst(:g, '/', '::');
         my $what = $podname ~~ /^<[A..Z]> | '::'/  ?? 'type' !! 'language';
         say "$_.path() => $what/$podname";
         %names{$podname}{$what}.push: "/$what/$podname";
@@ -38,9 +54,9 @@ ($out_dir = 'html')
         for @chunks -> $chunk {
             my $name = $chunk[0].content[0].content[0];
             next if $name ~~ /\s/;
-            %names{$name}<routine>.push: "/type/$podname.html#$name";
-            %routines{$name}.push: $podname => $chunk;
-            %types<routine>{$name} = "/routine/$name";
+            %names{$name}<routine>.push: "/type/$podname.html#" ~ uri_escape($name);
+                %routines{$name}.push: $podname => $chunk;
+            %types<routine>{$name} = "/routine/" ~ uri_escape( $name );
         }
         unlink $tempfile;
     }
@@ -81,7 +97,7 @@ ($out_dir = 'html')
                     )
                 )
             ),
-            @blocks,
+            @blocks.flat,
         ]
     );
 }
@@ -142,12 +158,13 @@ ($out_dir = 'html')
     say "Writing $out_dir/routine/$name.html";
     my $pod = pod-with-title("Documentation for routine $name",
         pod-block("Documentation for routine $name, assembled from the
-            following types:"));
-    $pod.content.push: @chunks.map(-> Pair (:key($type), :value($chunk)) {
+            following types:"),
+        @chunks.map(-> Pair (:key($type), :value($chunk)) {
             pod-heading($type),
             pod-block("From ", pod-link($type, "/type/{$type}#$name")),
             @$chunk
-        });
+        })
+    );
     my $file = open :w, "$out_dir/routine/$name.html";
     $file.print: pod2html($pod);
     $file.close;

lib/IO.pod

@@ -10,7 +10,7 @@
 
     sub dir Cool $path = '.', Mu :$test = none('.', '..')
 
-Returns a list if L<IO::File> and L<IO::Dir> objects for the
+Returns a list of L<IO::File> and L<IO::Dir> objects for the
 files and directories found in the $path. If $path is not given
 in lists the entries in the current directory.
 
@@ -30,7 +30,7 @@ To include all the entries (including . and ..) write:
 
     dir(test => all())
 
-To include only the files with .pl extension write
+To include only the entries with .pl extension write
 
     dir(test => /.pl$/)
 

lib/Mu.pod

@@ -28,6 +28,31 @@ Returns C<False> on the type object, and C<True> otherwise
 
 Returns C<False> on the type object, and C<True> otherwise
 
+=head2 Str
+
+    multi method Str()   returns Str
+
+Returns a string representation of the invocant, inteded to be machine
+readable.
+
+=head2 gist
+
+    multi sub    gist(Mu) returns Str
+    multi method gist()   returns Str
+
+Returns a string representation of the invocant, optimized for
+fast recognition by humans.
+
+The default C<gist> method in C<Mu> re-dispatches to the C<perl> method,
+but many built-in classes override it to something more specific.
+
+=head2 perl
+
+    multi sub    perl(Mu) returns Str
+    multi method perl()   returns Str
+
+Returns parsable string which generates current class.
+
 =head2 clone
 
     method clone(*%twiddles)
@@ -51,13 +76,15 @@ their own C<new> method to override this default.
 
     multi method print() returns Bool:D
 
-Prints value to C<$*OUT> without newline at end.
+Prints value to C<$*OUT> after stringification using C<.Str> method without
+newline at end.
 
 =head2 say
 
     multi method say() returns Bool:D
 
-Prints value to C<$*OUT> with newline at end.
+Prints value to C<$*OUT> after stringification using C<.gist> method with
+newline at end.
 
 =head2 ACCEPTS
 

lib/Parcel.pod

@@ -0,0 +1,30 @@
+=begin pod
+
+=TITLE class Parcel
+
+    class Parcel is Cool does Positional { }
+
+I<Parcel> stands for I<Par>enthesis I<cel>l, ie an expression
+surrounded by parenthesis. Though with the exception of the empty parcel,
+C<()>, it is really the comma that create a Parcel.
+
+    ()      # empty Parcel
+    (1 + 2) # not a Parcel
+    (1, 2)  # Parcel with two elements
+
+Parcels are immutable, but can contain mutable containers.
+
+    my $x;
+    my $p = (0, $x, 2); # can assign to $p[1], but not
+                        # to any other element of $p
+
+Word-quoting constructs such as C<< <...> >> also create parcels:
+
+    <a b c> # 3-element Parcel
+
+In flattening list context, parcels are flattened out and disappear:
+
+    my @flat = <a b>, <c, d>;
+    say @flat.elems;            # 4
+
+=end pod

lib/X/AdHoc.pod

@@ -0,0 +1,33 @@
+=begin pod
+
+=TITLE class X::AdHoc
+
+    class X::AdHoc is Exception { ... }
+
+C<X::AdHoc> is the type into which objects are wrapped if they are
+thrown as exceptions, but don't inherit from L<Exception>.
+
+Its benefit over returning non-C<Exception> objects is that it gives
+access to all the methods from class L<Exception>, like C<backtrace>
+and C<rethrow>.
+
+You can obtain the original object with the C<payload> method.
+
+    try {
+        die [404, 'File not found']; # throw non-exception object
+    }
+    say "Got HTTP code ",
+        $!.payload[0],          # 404
+        " and backtrace ",
+        $!.backtrace;
+
+=head1 METHODS
+
+=head2 payload
+
+    method payload(X::AdHoc:D)
+
+Returns the original object which was passed to C<die>.
+
+=end pod
+