[io grant] Document &chdir

Author: zoffixznet

doc/Type/IO.pod6

@@ -9,6 +9,36 @@ L<IO::Path|/type/IO::Path>. This is the exception from the rule.
 
 =head1 Routines
 
+=head2 sub chdir
+
+Defined as:
+
+    sub chdir(IO() $path, :$d = True, :$r, :$w, :$x --> IO::Path:D)
+
+Changes value of C<$*CWD> variable to the provided 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/chdir»).
+
+Returns L«C<IO::Path>|/type/IO::Path»
+representing new C<$*CWD> on success. On failure, returns
+L«C<Failure>|/type/Failure» and leaves C<$*CWD> untouched.
+The C<$path> can be any 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.
+
+    chdir        '/tmp'; # change $*CWD to '/tmp' and check its .d is True
+    chdir :r, :w '/tmp'; # … check its .r and .w are True
+    chdir '/not-there';  # returns Failure
+
 =head2 sub print
 
 Print the given text on C<$*OUT> (standard output), e.g.: