Created a "Type" independent routines

This shows up as "routines" because it's not a class or anything, but
does not make htmlify.p6 choke.

This closes #2070. Also closes #2578 since we will not be creating
that unless this proves down the line to be untenable.

Still, #2059 has to be addressed. We have copied routines here, but
not eliminated them there.

Author: JJ

doc/Type/independent-routines.pod6

@@ -0,0 +1,392 @@
+=begin pod
+
+=TITLE Independent routines
+
+=SUBTITLE Routines not defined within any class or role.
+
+These routines are defined in different files, but are not actually attached to
+any particular class or role.
+
+=head2 sub mkdir
+
+Defined as:
+
+    sub    mkdir(IO() $path, Int() $mode = 0o777 --> IO::Path:D)
+
+Creates a new directory; see L«C<mode>|/routine/mode» for explanation and
+valid values for C<$mode>. Returns the L<IO::Path> object pointing to
+the newly created directory on success;
+L<fails|/routine/fail> with L<X::IO::Mkdir> if directory cannot be created.
+
+Also creates parent directories, as needed (similar to *nix utility
+C<mkdir> with C<-p> option); that is, C<mkdir "foo/bar/ber/meow"> will
+create C<foo>, C<foo/bar>, and C<foo/bar/ber> directories if they do not
+exist, as well as C<foo/bar/ber/meow>.
+
+=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 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/r» returns C<True>
+
+=item C<:w> — check L«C<.w>|/routine/w» returns C<True>
+
+=item C<:x> — check L«C<.x>|/routine/x» returns C<True>
+
+By default, only C<:d> test is performed.
+
+=for code
+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
+
+Note that the following construct is a mistake:
+
+=for code
+# WRONG! DO NOT DO THIS!
+my $*CWD = chdir '/tmp/';
+
+Use L«C<indir>|/routine/indir» instead.
+
+=head2 sub &*chdir
+
+Defined as:
+
+=for code
+PROCESS::<&chdir> = sub (IO() $path --> IO::Path:D) { }
+
+Changes value of C<$*CWD> variable to the provided C<$path> and sets
+the process's current directory to the value of
+L«C<$path.absolute>|/routine/absolute». B<NOTE:> that in most cases,
+you want to use L«C<chdir>|/routine/chdir» routine instead.
+
+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 object with an IO method that returns an
+L«C<IO::Path>|/type/IO::Path» object.
+
+Note that unlike regular L«C<chdir>|/routine/chdir», there are no arguments
+to specify which file tests to perform.
+
+=for code
+&*chdir('/tmp');  # change $*CWD and process's current directory to '/tmp'
+&*chdir('/not-there'); # returns Failure
+
+Note that the following construct is a mistake:
+
+=for code
+# WRONG! DO NOT DO THIS!
+my $*CWD = &*chdir('/tmp');
+
+Use the following, instead; or see L«C<indir>|/routine/indir» if
+you do not need to change process's current directory:
+
+=for code
+temp $*CWD;
+&*chdir('/tmp');
+
+=head2 sub chmod
+
+Defined as:
+
+    sub chmod(Int() $mode, *@filenames --> List)
+
+Coerces all C<@filenames> to L«C<IO::Path>|/type/IO::Path» and calls
+L«C<IO::Path.chmod>|/type/IO::Path#method_chmod» with C<$mode> on them.
+Returns a L«C<List>|/type/List» containing a subset of C<@filenames> for which
+C<chmod> was successfully executed.
+
+    chmod 0o755, <myfile1  myfile2>; # make two files executable by the owner
+
+=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 an L<IO::Path> object based on C<$path>,
+optionally ensuring the new path passes several file tests. If C<$path> is
+relative, it will be turned into an absolute path, even if an L<IO::Path>
+object was given. B<NOTE:> that this routine does I<NOT> alter the process's
+current directory (see L«C<&*chdir>|/routine/&*chdir»). The C<$*CWD>
+outside of the C<&code> is not affected, even if C<&code> explicitly assigns
+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».
+B<WARNING:> keep in mind that lazily evaluated things might end up NOT
+having the C<$*CWD> set by C<indir> in their dynamic scope by the time
+they're actually evaluated. Either ensure the generators have their
+C<$*CWD> set or L<eagerly evaluate|/routine/eager> them before returning
+the results from C<indir>:
+
+    say indir("/tmp", {
+        gather { take ".".IO }
+    })».CWD; # OUTPUT: «(/home/camelia)␤»
+
+    say indir("/tmp", {
+        eager gather { take ".".IO }
+    })».CWD; # OUTPUT: «(/tmp)␤»
+
+    say indir("/tmp", {
+        my $cwd = $*CWD;
+        gather { temp $*CWD = $cwd; take ".".IO }
+    })».CWD; # OUTPUT: «(/tmp)␤»
+
+The routine's C<$path> argument 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
+
+Defined as:
+
+    multi sub print(**@args --> True)
+    multi sub print(Junction:D --> True)
+
+Prints the given text on standard output (the
+L«C<$*OUT>|/language/variables#index-entry-%24%2AOUT» filehandle), coercing non-L<Str|/type/Str> objects
+to L<Str|/type/Str> by calling L«C<.Str> method|/routine/Str». L<Junction|/type/Junction> arguments
+L<autothread|/language/glossary#index-entry-Autothreading> and the order of printed strings
+is not guaranteed.
+
+    print "Hi there!\n";   # OUTPUT: «Hi there!␤»
+    print "Hi there!";     # OUTPUT: «Hi there!»
+    print [1, 2, 3];       # OUTPUT: «1 2 3»
+
+To print text and include the trailing newline, use L«C<put>|/type/IO#sub_put».
+
+=head2 sub put
+
+Defined as:
+
+    multi sub put(**@args --> True)
+    multi sub put(Junction:D --> True)
+
+Same as L«C<print>|/type/IO#sub_print», except it uses
+L«C<print-nl>|/routine/print-nl» (which prints a L<newline|/language/newline>,
+by default) at the end. L<Junction|/type/Junction> arguments
+L<autothread|/language/glossary#index-entry-Autothreading> and the order of
+printed strings is not guaranteed.
+
+    put "Hi there!\n";   # OUTPUT: «Hi there!␤␤»
+    put "Hi there!";     # OUTPUT: «Hi there!␤»
+    put [1, 2, 3];       # OUTPUT: «1 2 3␤»
+
+=head2 sub say
+
+Defined as:
+
+    multi sub say(**@args --> True)
+
+Prints the "gist" of given objects. Same as L«C<put>|/type/IO#sub_put»,
+except uses L«C<.gist>|/routine/gist» method to obtain string
+representation of the object.
+
+B<NOTE:> the L«C<.gist>|/routine/gist» method of some objects, such as
+L<Lists|/type/List#method_gist>, returns only B<partial> information
+about the object (hence the "gist"). If you mean to print textual
+information, you most likely want to use L«C<put>|/type/IO#sub_put»
+instead.
+
+    say Range;        # OUTPUT: «(Range)␤»
+    say class Foo {}; # OUTPUT: «(Foo)␤»
+    say 'I ♥ Perl6';  # OUTPUT: «I ♥ Perl6␤»
+    say 1..Inf;       # OUTPUT: «1..Inf␤»
+
+=head2 routine note
+
+Defined as:
+
+    method note(Mu: -->Bool:D)
+    multi sub note(            --> Bool:D)
+    multi sub note(Str:D $note --> Bool:D)
+    multi sub note(**@args     --> Bool:D)
+
+Like L«C<say>|/routine/say», except prints output to L«C<$*ERR>|/language/variables#index-entry-%24%2AERR» handle (STDERR).
+If no arguments are given to subroutine forms, will use string C<"Noted">.
+
+=begin code
+note;       # STDERR OUTPUT: «Noted␤»
+note 'foo'; # STDERR OUTPUT: «foo␤»
+note 1..*;  # STDERR OUTPUT: «1..Inf␤»
+=end code
+
+=head2 sub prompt
+
+    multi sub prompt()
+    multi sub prompt($msg)
+
+L<Prints|/routine/print> C<$msg> to C<$*OUT> handle if C<$msg> was provided,
+then L<gets|/routine/get> a line of input from C<$*IN> handle. By default, this
+is equivalent to printing C<$msg> to
+L<STDOUT|https://en.wikipedia.org/wiki/Standard_streams#Standard_output_.28stdout.29>,
+reading a line from
+L<STDIN|https://en.wikipedia.org/wiki/Standard_streams#Standard_input_.28stdin.29>,
+removing the trailing new line, and returning the resultant string. As of Rakudo
+2018.08, C<prompt> will create L<allomorphs|/language/numerics#Allomorphs> for
+numeric values, equivalent to calling C<val prompt>.
+
+=for code
+my $name = prompt "What's your name? ";
+say "Hi, $name! Nice to meet you!";
+my $age = prompt("Say your age (number)");
+my Int $years = $age;
+my Str $age-badge = $age;
+
+In the code above, C<$age> will be duck-typed to the allomorph L<IntStr|/type/IntStr> if it's
+entered correctly as a number.
+
+=head2 sub open
+
+    multi sub open(IO() $path, |args --> IO::Handle:D)
+
+Creates L<a handle|/type/IO::Handle> with the given C<$path>, and calls
+L«C<IO::Handle.open>|/type/IO::Handle#method_open», passing any of the
+remaining arguments to it. Note that L<IO::Path> type provides numerous
+methods for reading and writing from files, so in many common cases you
+do not need to C<open> files or deal with L<IO::Handle> type directly.
+
+=begin code
+my $fh = open :w, '/tmp/some-file.txt';
+$fh.say: 'I ♥ writing Perl code';
+$fh.close;
+
+$fh = open '/tmp/some-file.txt';
+print $fh.readchars: 4;
+$fh.seek: 7, SeekFromCurrent;
+say $fh.readchars: 4;
+$fh.close;
+
+# OUTPUT: «I ♥ Perl␤»
+=end code
+
+=head2 sub slurp
+
+Defined as:
+
+    multi sub slurp(IO::Handle:D $fh = $*ARGFILES, |c)
+    multi sub slurp(IO() $path, |c)
+
+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 as L<open()|/routine/open>; possible encodings are the
+same as in all the other C<IO> methods and are listed in
+L<C<encoding>|/type/IO::Handle#method_encoding> routine.  The routine
+will C<fail> if the file does not exist, or is a directory. Without any
+arguments, sub C<slurp> operates on C<$*ARGFILES>, which defaults to
+C<$*IN> in the absence of any filenames.
+
+=begin code
+# read entire file as (Unicode) Str
+my $text_contents   = slurp "path/to/file";
+
+# read entire file as Latin1 Str
+my $text_contents   = slurp "path/to/file", enc => "latin1";
+
+# read entire file as Buf
+my $binary_contents = slurp "path/to/file", :bin;
+=end code
+
+=head2 sub spurt
+
+Defined as:
+
+    multi spurt(IO() $path, |c)
+
+The C<$path> can be any object with an IO method that returns an
+L«C<IO::Path>|/type/IO::Path» object. Calls L«C<IO::Path.spurt>|/routine/spurt»
+on the C<$path>, forwarding any of the remaining arguments.
+
+=head3 Options
+
+=item :enc
+
+The encoding with which the contents will be written.
+
+=item :append
+
+Boolean indicating whether to append to a (potentially) existing file.  If
+the file did not exist yet, it will be created.  Defaults to C<False>.
+
+=item :createonly
+
+Boolean indicating whether to fail if the file already exists.  Defaults to
+C<False>.
+
+=head3 Examples
+
+=begin code
+# write directly to a file
+spurt 'path/to/file', 'default text, directly written';
+
+# write directly with a non-Unicode encoding
+spurt 'path/to/latin1_file', 'latin1 text: äöüß', :enc<latin1>;
+
+spurt 'file-that-already-exists', 'some text';           # overwrite file's contents:
+spurt 'file-that-already-exists', ' new text', :append;  # append to file's contents:
+say slurp 'file-that-already-exists';                    # OUTPUT: «some text new text␤»
+
+# fail when writing to a pre-existing file
+spurt 'file-that-already-exists', 'new text', :createonly;
+# OUTPUT: «Failed to open file /home/camelia/file-that-already-exists: file already exists …»
+=end code
+
+=head2 sub shell
+
+    sub shell($cmd --> Proc)
+
+Runs a command through the system shell, which defaults to
+C<%*ENV<ComSpec> /c> in Windows, C</bin/sh -c> otherwise. All shell meta
+characters are interpreted by the shell, including pipes, redirects,
+environment variable substitutions and so on. Shell escapes are a severe
+security concern and can cause confusion with unusual file names. Use
+L<run|/type/Proc#sub_run> if you want to be safe.
+
+The return value is of L<type Proc|/type/Proc>.
+
+    shell 'ls -lR | gzip -9 > ls-lR.gz';
+
+See L<Proc|/type/Proc> for more details, for example on how to capture
+output.
+
+=head1 Related classes
+
+See also the related classes L<IO::Handle> and L<IO::Path>.
+
+=end pod
+
+# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6