[io grant] Document &indir

Author: zoffixznet

doc/Type/IO.pod6

@@ -63,6 +63,40 @@ to specify which file tests to perform.
     &*chdir('/tmp');  # change $*CWD and process's current directory to '/tmp'
     &*chdir('/not-there'); # returns Failure
 
+=head2 sub indir
+
+Defined as:
+
+    sub indir(IO() $path, &code, :$d = True, :$r, :$w, :$x --> Mu)
+
+Takes L«C<Callable>|/type/Callable» C<&code> and executes it after locally (to
+C<&code>) changing C<$*CWD> variable to C<$path>, optionally ensuring
+the new path passes several file tests. B<NOTE:> that this routine does I<NOT>
+alter the process's current directory (see
+L«C<&*chdir>|/routine/$AMPERSAND*chdir»). The C<$*CWD> outside of the C<&code>
+is not affected, even if C<&code> explicitly assignes a new value to C<$*CWD>.
+
+Returns the return value of C<&code> on success. On failure to successfully
+change C<$*CWD>, returns L«C<Failure>|/type/Failure».
+The C<$path> can be any object with an IO method that returns an
+L«C<IO::Path>|/type/IO::Path» object. The available file tests are:
+
+=item C<:d> — check L«C<.d>|/routine/d» returns C<True>
+
+=item C<:r> — check L«C<.r>|/routine/d» returns C<True>
+
+=item C<:w> — check L«C<.w>|/routine/d» returns C<True>
+
+=item C<:x> — check L«C<.x>|/routine/d» returns C<True>
+
+By default, only C<:d> test is performed.
+
+    say $*CWD;                   # OUTPUT: «"/home/camelia".IO␤»
+    indir '/tmp', { say $*CWD }; # OUTPUT: «"/tmp".IO␤»
+    say $*CWD;                   # OUTPUT: «"/home/camelia".IO␤»
+
+    indir '/not-there', {;};     # returns Failure; path does not exist
+
 =head2 sub print
 
 Print the given text on C<$*OUT> (standard output), e.g.: