Some more work on S32/IO, WIP

Author: lizmat

S32-setting-library/IO.pod

@@ -20,35 +20,43 @@ increase the performance or maintainability.
 
 =head1 Functions
 
-=head2 print()
-X<print()>
+In alphabetical order.
 
-    sub print(*@text --> Bool) is export
+=head2 chdir()
+X<chdir()>
 
-Print the given text (as C<Str> objects) on $*OUT.  Return whether successful.
+  sub chdir(Str(Any) $dir, Str(Any) $CWD = $*CWD --> Bool) is export
 
-=head2 say()
-X<say()>
+Changes the current working directory to the given directory, for the scope in
+which C<$*CWD> is active.  Optionally takes a second positional parameter to
+indicate from which directory any relative path specified in the first
+positional parameter, should be taken.  Returns C<True> if successful, or an
+appropriate C<Failure>.
 
-    sub say(*@text --> Bool) is export
+Please note that this directory has B<no> connection with whatever the
+operating system thinks is the current working directory.  The value of
+C<$*CWD> just will always be prepended to any relative paths in any file
+operation in Perl 6.
 
-Print the given text, followed by a new line C<"\n"> on C<$*OUT>.  Before
-printing, call the C<.gist> method on any non-C<Str> objects.  Return whether
-successful.
+Normal usage:
 
-=head2 note()
-X<note()>
+  chdir("foo");
 
-    sub note(*@text --> Bool) is export
+A typically lexical scope bound use case:
 
-Print the given text, followed by a new line C<"\n"> on C<$*ERR>.  Before
-printing, call the C<.gist> method on any non-C<Str> objects. Return whether
-successful.
+  {
+      my $*CWD;
+      chdir("foo");
+      # working directory changed to "foo"
+  }
+  # restored to what it was
+
+But for the latter, you're probably better off using L</indir()>.
 
 =head2 dd()
 X<dd()>
 
-    sub dd(@vars --> Bool) is export
+  sub dd(@vars --> Bool) is export
 
 Tiny Data Dumper.  Takes the C<variables> specified and C<note>s them (on
 C<$*ERR>) in an easy to read format, along with the C<name> of the variable.
@@ -57,13 +65,92 @@ So:
   my $a = 42;
   dd($a);   # notes "$a = 42"
 
-=head2 prompt()
-X<prompt()>
+Returns C<True> (not that that will matter most of the time).
 
-    sub prompt($msg --> Bool) is export
+=head2 dir()
+X<dir()>
 
-Simple Prompter.  Print message (as C<Str> object) on C<$*OUT> and obtains a
-single line of input from C<$*IN>.
+  sub dir(
+    Str(Any) $dir   = $*CWD,
+    Str(Any) $from  = $*CWD,
+    Mu       :$test = (exclude . and ..),
+    Bool     :$Str  = False,
+    --> List ) is export
+
+Returns a lazy list of objects doing the C<IO::Pathy> role for the directory
+entries in the given the C<$dir>.  Optionally takes a second positional
+parameter to be used as the root for any relative path specified as the first
+positional.  Defaults to the directory pointed to by C<$*CWD>.
+If dir() fails, it returns an L<X::IO::Dir|S32::Exception/X::IO::Dir> failure.
+The following named parameters are optional:
+
+=over 4
+
+=item :test
+
+Expression against which to smart-match for inclusion in result list.  By
+default excludes C<"."> and C<".."> only.
+
+=item :Str
+
+Boolean indicating to return absolute C<Str>ings, rather than objects doing
+the C<IO::Pathy> role.  False by default.
+
+=back
+
+=head2 indir()
+X<indir()>
+
+  sub indir(Str(Any) $dir, &what, Str(Any) $CWD = $*CWD) is export
+
+Change to the directory indicated by the first positional, and execute the
+code given by the second positional.  Optionally specify the directory to
+which any relative dir should be applied.  Returns whatever the code returns.
+
+=head2 mkdir()
+X<mkdir()>
+
+  multi sub mkdir(Str(Any) $dir, Int $mode = 0o777 --> Bool)
+
+Create directory indicated by the first positional, with the (optional) mode
+as the second positional.  Return True if successful, or an appropriate
+C<Failure>.
+
+  multi sub mkdir(Int $mode, *@dir --> List)
+
+Use the first positional parameter C<Int> value as mode with which to create
+the directories specified with the other positional parameters.  Returns a
+C<List> with the directories that were successfully created.
+
+=head2 move()
+X<move()>
+
+  sub move(
+    Str(Any) $src,
+    Str(Any) $dest,
+    Bool     :$createonly,
+    --> Bool ) is export
+
+Moves a file, as indicate by the first positional parameter, by copying its
+contents to the destination specified, and then removing the file at the
+original location.  If the destination is a directory, moves the file into
+that directory.  If :createonly is set to True, the move fails if a
+directory entry already exists at the destination.  Returns C<True> upon
+success, or an appropriate C<Failure> if the operation could not be completed.
+
+Please use L</rename()> if a file can be moved by renaming (which is usually
+possible if the destination is on the same different physical storage device).
+Alternately, the C<move()> function is free to try the C<rename()> first,
+and if that (silently) fails, do it the hard way.
+
+=head2 note()
+X<note()>
+
+  sub note(*@text --> Bool) is export
+
+Print the given text, followed by a new line C<"\n"> on C<$*ERR>.  Before
+printing, call the C<.gist> method on any non-C<Str> objects. Return whether
+successful.
 
 =head2 open()
 X<open()>
@@ -136,46 +223,38 @@ C<.lines> and C<.get>.  Defaults to C<True>.
 
 =back
 
-=head2 dir()
-X<dir()>
-
-    sub dir($directory as Str = $*CWD,
-        Mu   :$test = (exclude . and ..)
-        Bool :$Str = False,
-             :$CWD = $*CWD.Str,
-        --> List ) is export
-
-Returns a lazy list directory entries in given the C<$directory> as objects
-doing the C<IO::Pathy> role.   Defualts to the directory pointed to by C<$*CWD>.
-If dir() fails, it returns an L<X::IO::Dir|S32::Exception/X::IO::Dir> failure.
-The following named parameters are optional:
+=head2 print()
+X<print()>
 
-=over 4
+  sub print(*@text --> Bool) is export
 
-=item :test
+Print the given text (as C<Str> objects) on $*OUT.  Return whether successful.
 
-Expression against which to smart-match for inclusion in result list.  By
-default excludes C<"."> and C<".."> only.
+=head2 prompt()
+X<prompt()>
 
-=item :Str
+  sub prompt(Str(Any) $msg --> Str) is export
 
-Boolean indicating to return absolute C<Str>ings, rather than objects doing
-the C<IO::Path> role.  False by default.
+Simple Prompter.  Print message (as C<Str> object) on C<$*OUT> and obtains a
+single line of input from C<$*IN>, which is returned.
 
-=item :CWD
+=head2 say()
+X<say()>
 
-The directory to pre-pend to C<$directory> if specified as a relative path.
-Defaults to C<$*CWD>.
+  sub say(*@text --> Bool) is export
 
-=back
+Print the given text, followed by a new line C<"\n"> on C<$*OUT>.  Before
+printing, call the C<.gist> method on any non-C<Str> objects.  Return whether
+successful.
 
 =head2 slurp()
 X<slurp()>
 
-    sub slurp ($what = $*ARGFILES,
-        Bool :$bin = False,
-        Str  :$enc = "Unicode",
-        --> Str|Buf ) is export
+  sub slurp(
+    $what      = $*ARGFILES,  # XXX need to generalize $*ARGFILES behaviour
+    Bool :$bin = False,
+    Str  :$enc = "Unicode",
+    --> Str|Buf ) is export
 
 Slurps the contents of the entire file into a C<Str> (or C<Buf> if C<:bin>).
 Accepts C<:bin> and C<:enc> optional named parameters, with the same meaning
@@ -185,11 +264,11 @@ directory.
 =head2 spurt()
 X<spurt()>
 
-    sub spurt ($where, $what,
-        Str  :$enc        = $*ENC,
-        Bool :append      = False,
-        Bool :$createonly = False,
-        --> Bool ) is export
+  sub spurt ($where, $what,
+    Str  :$enc        = $*ENC,
+    Bool :$append     = False,
+    Bool :$createonly = False,
+    --> Bool ) is export
 
 Writes the indicated contents (2nd positional parameter) to the location
 indicated by the first positional parameter (which can either be a string,
@@ -219,21 +298,6 @@ C<False>.
 
 =back
 
-=head2 mkdir()
-X<mkdir()>
-
-    multi sub mkdir($dir, Int $mode = 0o777 --> Bool)
-
-Create directory indicated by the first positional, with the (optional) mode
-as the second positional.  Return True if successful, or an appropriate
-C<Failure>.
-
-    multi sub mkdir(Int $mode, *@dir --> List)
-
-Use the first positional parameter C<Int> value as mode with which to create
-the directories specified with the other positional parameters.  Returns a
-C<List> with the directories that were successfully created.
-
 =head2 rmdir()
 X<rmdir()>
 
@@ -242,48 +306,16 @@ X<rmdir()>
 Removes the (empty) directory as indicated by the positional parameter.
 Returns C<True> on success or an appropriate C<Failure>.
 
-=head2 chdir()
-X<chdir()>
-
-    sub chdir($dir as IO, $CWD = $*CWD,
-        :$test = <d r>
-        --> Bool) is export
-
-Changes the current working directory to the given directory, for the scope in
-which C<$*CWD> is active (if no second positional parameter is given) or for
-the scope of the indicated localized C<$*CWD>.  A typical use case:
-
-  {
-      chdir("foo", my $*CWD);
-      # working directory changed to "foo"
-  }
-  # restored to what it was
-
-Returns C<True> if successful, or an appropriate C<Failure>, e.g if the
-directory does not exist, or is not a directory, or is not readable.
-
-Please note that this directory has B<no> connection with whatever the
-operating system thinks is the current working directory.  The value of
-C<$*CWD> just will always be prepended to any relative paths in any file
-operation in Perl 6.
-
-Also note that you can use C<chdir> to set similar dynamic variables, like
-C<$*TMPDIR> and C<$*HOME> this way:
-
-  chdir("bar", my $*TMPDIR);   # set $*TMPDIR in this scope
-  chdir("bar", my $*HOME);     # set $*HOME in this scope
-
 =head2 copy()
 X<copy()>
 
-    sub copy ($source as IO, $dest as IO,
-        :$createonly = False,
-        --> Bool ) is export
+    sub copy(Str(Any) $src, Str(Any) $dst, :$createonly --> Bool) is export
 
 Copies a file, as indicate by the first positional parameter, to the
-destination specified.  If :createonly is set to True, copy fails if a file
-already exists in the destination.  Returns C<True> upon success, or an
-appropriate C<Failure> if the operation could not be completed.
+destination specified.  Optionally takes a named parameter C<:createonly>:
+if set to True, the copy will fail if a directory entry already exists at the
+destination.  Returns C<True> upon success, or an appropriate C<Failure> if
+the operation could not be completed.
 
 =head2 rename()
 X<rename()>
@@ -300,23 +332,13 @@ an appropriate C<Failure> if the operation could not be completed.
 Please use L</move()> if a file could not be moved by renaming (usually because
 the destination is on a different physical storage device).
 
-=head2 move()
-X<move()>
+=head2 tmpdir()
+X<tmpdir()>
 
-    sub move ($source as IO, $dest as IO,
-        :$createonly = False,
-        --> Bool ) is export
-
-Moves a file, as indicate by the first positional parameter, by copying its
-contents to the destination specified, and then removing the file at the
-original location.  If :createonly is set to True, the move fails if a file
-already exists in the destination.  Returns C<True> upon success, or an
-appropriate C<Failure> if the operation could not be completed.
+  sub tmpdir(Str(Any) $dir, Str(Any) $CWD = $*CWD --> Bool) is export
 
-Please use L</rename()> if a file can be moved by renaming (which is usually
-possible if the destination is on the same different physical storage device).
-Alternately, the C<move()> function is free to try the C<rename()> first,
-and if that (silently) fails, do it the hard way.
+Similar in functionality to L</chdir()>, but instead sets the dynamic
+variable C<$*TMPDIR> (rather than $*CWD).
 
 =head2 unlink()
 X<unlink()>