Some formatting adjustments

Author: Jan-Olof Hendig

doc/Type/IO/Handle.pod6

@@ -13,13 +13,13 @@
 Defined as:
 
 =for code :skip-test
-    method open(IO::Handle:D:
-        :$bin, :$enc, :$chomp, :$nl-in, Str:D :$nl-out,
-        Str :$mode,
-        :$r, :$w, :$a, :$x, :$update, :$rw, :$rx, :$ra,
-        :$create, :$append, :$truncate, :$exclusive,
-        --> IO::Handle:D
-    )
+method open(IO::Handle:D:
+    :$bin, :$enc, :$chomp, :$nl-in, Str:D :$nl-out,
+    Str :$mode,
+    :$r, :$w, :$a, :$x, :$update, :$rw, :$rx, :$ra,
+    :$create, :$append, :$truncate, :$exclusive,
+    --> IO::Handle:D
+)
 
 Opens the handle in one of the modes. L<Fails|/routine/fail> with appropriate
 exception if the open fails.
@@ -40,16 +40,16 @@ The open mode defaults to non-exclusive, read only (same as specifying
 C<:r>) and can be controlled by a mix of the following arguments:
 
 =begin code :skip-test :allow< B R >
-    :r      same as specifying   :mode<ro>
+:r      same as specifying   :mode<ro>
 
-    :w      same as specifying   :mode<wo>, :create, :truncate
-    :a      same as specifying   :mode<wo>, :create, :append
-    :x      same as specifying   :mode<wo>, :create, :exclusive
+:w      same as specifying   :mode<wo>, :create, :truncate
+:a      same as specifying   :mode<wo>, :create, :append
+:x      same as specifying   :mode<wo>, :create, :exclusive
 
-    :update same as specifying   :mode<rw>
-    :rw     same as specifying   :mode<rw>, :create
-    :ra     same as specifying   :mode<rw>, :create, :append
-    :rx     same as specifying   :mode<rw>, :create, :exclusive
+:update same as specifying   :mode<rw>
+:rw     same as specifying   :mode<rw>, :create
+:ra     same as specifying   :mode<rw>, :create, :append
+:rx     same as specifying   :mode<rw>, :create, :exclusive
 =end code
 
 Support for combinations of modes I<other> than what is listed above
@@ -61,14 +61,14 @@ to implode, depending on a particular implementation.
 The mode details are:
 
 =begin code :skip-test :allow< B R >
-    :mode<ro>  means "read only"
-    :mode<wo>  means "write only"
-    :mode<rw>  means "read and write"
-
-    :create    means the file will be created, if it does not exist
-    :truncate  means the file will be emptied, if it exists
-    :exclusive means .open will fail if the file already exists
-    :append    means writes will be done at the end of file's current contents
+:mode<ro>  means "read only"
+:mode<wo>  means "write only"
+:mode<rw>  means "read and write"
+
+:create    means the file will be created, if it does not exist
+:truncate  means the file will be emptied, if it exists
+:exclusive means .open will fail if the file already exists
+:append    means writes will be done at the end of file's current contents
 =end code
 
 Attempts to open a directory, write to a handle opened in read-only mode
@@ -135,13 +135,13 @@ L<in binary mode|/type/IO::Handle#method_encoding> will result in
 C<X::IO::BinaryMode> exception being thrown.
 
 =begin code
-    $*IN.get.say;              # Read one line from the standard input
+$*IN.get.say;              # Read one line from the standard input
 
-    my $fh = open 'filename';
-    $fh.get.say;               # Read one line from a file
-    $fh.close;
+my $fh = open 'filename';
+$fh.get.say;               # Read one line from a file
+$fh.close;
 
-    say get;                   # Read one line from $*ARGFILES
+say get;                   # Read one line from $*ARGFILES
 =end code
 
 =head2 routine getc
@@ -200,8 +200,8 @@ L«C<.path>|/type/IO::Handle#method_path», if any, the handle is created for
 and whether it is L«C<.opened>|/type/IO::Handle#method_opened».
 
 =begin code
-    say IO::Handle.new; # IO::Handle<(Any)>(closed)
-    say "foo".IO.open;  # IO::Handle<"foo".IO>(opened)
+say IO::Handle.new; # IO::Handle<(Any)>(closed)
+say "foo".IO.open;  # IO::Handle<"foo".IO>(opened)
 =end code
 
 =head2 method eof
@@ -231,12 +231,12 @@ vary by implementation and backend. On Rakudo MoarVM the following are
 supported:
 
 =for code :skip-test
-  utf8
-  utf16
-  utf8-c8
-  iso-8859-1
-  windows-1252
-  ascii
+utf8
+utf16
+utf8-c8
+iso-8859-1
+windows-1252
+ascii
 
 The default encoding is utf8, which undergoes normalization into Unicode B<NFC>
 (normalization form canonical). In some cases you may want to ensure no
@@ -249,13 +249,13 @@ allows aliases C<latin-1> for C<iso-8859-1> encoding and dashed utf versions:
 C<utf-8> and C<utf-16>.
 
 =begin code
-    with 'foo'.IO {
-        .spurt: "First line is text, then:\nBinary";
-        my $fh will leave {.close} = .open;
-        $fh.get.say;         # OUTPUT: «First line is text, then:␤»
-        $fh.encoding: Nil;
-        $fh.slurp.say;       # OUTPUT: «Buf[uint8]:0x<42 69 6e 61 72 79>␤»
-    }
+with 'foo'.IO {
+    .spurt: "First line is text, then:\nBinary";
+    my $fh will leave {.close} = .open;
+    $fh.get.say;         # OUTPUT: «First line is text, then:␤»
+    $fh.encoding: Nil;
+    $fh.slurp.say;       # OUTPUT: «Buf[uint8]:0x<42 69 6e 61 72 79>␤»
+}
 =end code
 
 =head2 routine lines
@@ -288,10 +288,10 @@ when you close the handle or attempt to use any other methods that change the
 file position.
 
 =begin code
-    say "The file contains ",
-      '50GB-file'.IO.open.lines.grep(*.contains: 'Perl').elems,
-      " lines that mention Perl";
-    # OUTPUT: «The file contains 72 lines that mention Perl␤»
+say "The file contains ",
+  '50GB-file'.IO.open.lines.grep(*.contains: 'Perl').elems,
+  " lines that mention Perl";
+# OUTPUT: «The file contains 72 lines that mention Perl␤»
 =end code
 
 =head2 method lock
@@ -515,11 +515,11 @@ This method can be called even when the handle is not
 L<in binary mode|/type/IO::Handle#method_encoding>.
 
 =begin code
-    (my $file = 'foo'.IO).spurt: 'I ♥ Perl';
-    given $file.open {
-        say .read: 6; # OUTPUT: «Buf[uint8]:0x<49 20 e2 99 a5 20>␤»
-        .close;
-    }
+(my $file = 'foo'.IO).spurt: 'I ♥ Perl';
+given $file.open {
+    say .read: 6; # OUTPUT: «Buf[uint8]:0x<49 20 e2 99 a5 20>␤»
+    .close;
+}
 =end code
 
 =head2 method readchars
@@ -536,11 +536,11 @@ L<in binary mode|/type/IO::Handle#method_encoding> will result in
 C<X::IO::BinaryMode> exception being thrown.
 
 =begin code
-    (my $file = 'foo'.IO).spurt: 'I ♥ Perl';
-    given $file.open {
-        say .readchars: 5; # OUTPUT: «I ♥ P␤»
-        .close;
-    }
+(my $file = 'foo'.IO).spurt: 'I ♥ Perl';
+given $file.open {
+    say .readchars: 5; # OUTPUT: «I ♥ P␤»
+    .close;
+}
 =end code
 
 =head2 method write
@@ -628,15 +628,15 @@ parameter and C<65536> bytes in binary mode or C<65536> characters in non-binary
 mode.
 
 =for code
-    "foo".IO.open(:bin).Supply(:size<10>).tap: *.perl.say;
-    # OUTPUT:
-    # Buf[uint8].new(73,32,226,153,165,32,80,101,114,108)
-    # Buf[uint8].new(32,54,33,10)
+"foo".IO.open(:bin).Supply(:size<10>).tap: *.perl.say;
+# OUTPUT:
+# Buf[uint8].new(73,32,226,153,165,32,80,101,114,108)
+# Buf[uint8].new(32,54,33,10)
 
-    "foo".IO.open.Supply(:size<10>).tap: *.perl.say;
-    # OUTPUT:
-    # "I ♥ Perl 6"
-    # "!\n"
+"foo".IO.open.Supply(:size<10>).tap: *.perl.say;
+# OUTPUT:
+# "I ♥ Perl 6"
+# "!\n"
 
 
 =head2 method path
@@ -666,7 +666,7 @@ Returns the value of L«C<.path>|/type/IO::Handle#method_path», coerced
 to L<Str>.
 
 =for code
-    say "foo".IO.open.path; # OUTPUT: «"foo".IO␤»
+say "foo".IO.open.path; # OUTPUT: «"foo".IO␤»
 
 =head2 routine close
 
@@ -683,26 +683,26 @@ closing the handles, which ensures the handle is closed regardless of how the
 block is left.
 
 =begin code :skip-test
-    if $do-stuff-with-the-file {
-        my $fh = open "path-to-file";
-        LEAVE close $fh;
-        # ... do stuff with the file
-    }
+if $do-stuff-with-the-file {
+    my $fh = open "path-to-file";
+    LEAVE close $fh;
+    # ... do stuff with the file
+}
 
-    sub do-stuff-with-the-file (IO $path-to-file)
-      my $fh = $path-to-file.open;
+sub do-stuff-with-the-file (IO $path-to-file)
+  my $fh = $path-to-file.open;
 
-      # stick a `try` on it, since this will get run even when the sub is
-      # called with wrong arguments, in which case the `$fh` will be an `Any`
-      LEAVE try close $fh;
+  # stick a `try` on it, since this will get run even when the sub is
+  # called with wrong arguments, in which case the `$fh` will be an `Any`
+  LEAVE try close $fh;
 
-      # ... do stuff with the file
-    }
+  # ... do stuff with the file
+}
 
-    given "foo/bar".IO.open(:w) {
-        .spurt: "I ♥ Perl 6!";
-        .close;
-    }
+given "foo/bar".IO.open(:w) {
+    .spurt: "I ♥ Perl 6!";
+    .close;
+}
 =end code
 
 B<Note:> unlike some other languages, Perl 6 does not use reference counting,
@@ -729,13 +729,13 @@ Will flush the handle, writing any of the buffered data. Returns C<True>
 on success; otherwise, L<fails|/routine/fail> with C<X::IO::Flush>.
 
 =begin code :skip-test
-    given "foo".IO.open: :w {
-        LEAVE .close;
-        $fh.print: 'something';
-        'foo'.IO.slurp.say; # (if the data got buffered) OUTPUT: «␤»
-        $fh.flush;          # flush the handle
-        'foo'.IO.slurp.say; # OUTPUT: «something␤»
-    }
+given "foo".IO.open: :w {
+    LEAVE .close;
+    $fh.print: 'something';
+    'foo'.IO.slurp.say; # (if the data got buffered) OUTPUT: «␤»
+    $fh.flush;          # flush the handle
+    'foo'.IO.slurp.say; # OUTPUT: «something␤»
+}
 =end code
 
 =head2 method native-descriptor
@@ -762,12 +762,12 @@ in routines that C<chomp>, such as L«C<get>|/routine/get» and
 L«C<lines>|/routine/lines».
 
 =begin code
-    with 'test'.IO {
-        .spurt: '1foo2bar3foo'; # write some data into our test file
-        my $fh will leave {.close} = .open; # can also set .nl-in via .open arg
-        $fh.nl-in = [<foo bar>]; # set two possible line endings to use;
-        $fh.lines.say; # OUTPUT: ("1", "2", "3").Seq
-    }
+with 'test'.IO {
+    .spurt: '1foo2bar3foo'; # write some data into our test file
+    my $fh will leave {.close} = .open; # can also set .nl-in via .open arg
+    $fh.nl-in = [<foo bar>]; # set two possible line endings to use;
+    $fh.lines.say; # OUTPUT: ("1", "2", "3").Seq
+}
 =end code
 
 =head2 method nl-out
@@ -782,15 +782,15 @@ handle, to be used by methods L«C<.put>|/type/IO::Handle#method_put»
 and L«C<.say>|/type/IO::Handle#method_say».
 
 =begin code
-    with 'test'.IO {
-        given .open: :w {
-            .put: 42;
-            .nl-out = 'foo';
-            .put: 42;
-            .close;
-        }
-        .slurp.perl.say; # OUTPUT: «"42\n42foo"»
+with 'test'.IO {
+    given .open: :w {
+        .put: 42;
+        .nl-out = 'foo';
+        .put: 42;
+        .close;
     }
+    .slurp.perl.say; # OUTPUT: «"42\n42foo"»
+}
 =end code
 
 =head2 method opened