Document I/O

lib/Language/io.pod

@@ -4,6 +4,142 @@
 
 =SUBTITLE File-related operations
 
+Here we present a quick overview of the file-related input/output
+operations, detailed documentation can be found in the documentation for the
+C<IO> role, as well as the L<IO::Handle>, L<IO::Path>, and
+L<IO::FileTestable> types.
+
+=head1 Reading from files
+
+To read in the contents of a file one could open the file via the C<open>
+function with the C<:r> (read) file mode option and slurp in the contents:
+
+    my $fh = open "testfile", :r;
+    my $contents = $fh.slurp;
+    $fh.close;
+
+where we explicitly close the file handle using the C<close> method on the
+C<IO::Handle> object.  This is a very traditional way of reading the
+contents of a file.  However, we can do the same much more easily and
+clearly like so:
+
+    my $contents = "testfile".IO.slurp;
+
+By adding the C<IO> role to the file name string, we are effectively able to
+refer to the string as the file object itself and thus slurp in its
+contents directly.  Note that the C<slurp> takes care of opening and closing
+the file for you.
+
+=head1 Writing to files
+
+To write data to a file, again we have the choice of the traditional method
+of calling the C<open> function -- this time with the C<:w> (write) option
+-- and spurting the data to the file:
+
+    my $fh = open "testfile", :w;
+    spurt $fh, "data and stuff\n";
+    $fh.close;
+
+We can simplify this by using C<spurt> to open the file in write mode,
+writing the data to the file and closing it again for us:
+
+    spurt "testfile", "data and stuff\n";
+
+By default all (text) files are written as UTF-8, however if necessary, one
+can explicitly specify an encoding via the C<:enc> option:
+
+    spurt "testfile", "latin1 text: äöüß", enc => "latin1";
+
+To append to a file, one can specify the C<:a> option when opening the file
+handle explicitly,
+
+    my $fh = open "testfile", :a;
+    spurt $fh "more data\n";
+    $fh.close;
+
+or with the C<:append> option in the call to C<spurt>:
+
+    spurt "testfile", "more data\n", :append;
+
+One can also explicitly write binary data to a file by opening it with the
+C<:bin> option.  The input/output operations now take place using the C<Buf>
+type instead of the C<Str> type.
+
+=head1 Checking files and directories
+
+We don't want an error to be thrown if we try to open a file that doesn't
+exist.  So, how do we know that the file even exists before reading it?
+This is what the C<e> method on an C<IO::Handle> object is for.
+
+    if "nonexistent_file".IO.e {
+	say "file exists";
+    }
+    else {
+	say "file doesn't exist";
+    }
+
+It is also possible to use the colon pair syntax to achieve the same thing:
+
+    if "path/to/file".IO ~~ :e {
+	say 'file exists';
+    }
+
+    my $file = "path/to/file";
+    if $file.IO ~~ :e {
+	say 'file exists';
+    }
+
+Similarly to the file existence check, one can also check to see if a path
+is a directory.  For instance, assuming that the file C<testfile> and the
+directory C<lib> exist, we would obtain from the existence test method C<e>
+the same result, namely that both exist:
+
+    say "testfile".IO.e;  # True
+    say "lib".IO.e;       # True
+
+However, since only one of them is a directory, the directory test method
+C<d> will give a different result:
+
+    say "testfile".IO.d;  # False
+    say "lib".IO.d;       # True
+
+Naturally the tables are turned if we check to see if the path is a file via
+the file test method C<f>:
+
+    say "testfile".IO.f;  # True
+    say "lib".IO.f;       # False
+
+=head1 Getting a directory listing
+
+To list the files and directories in the current directory, one merely needs
+to use the C<dir> function.  This returns a list of C<IO::Path> objects one
+can then write to, read from etc.
+
+    say dir;    # "/path/to/testfile".IO "/path/to/lib".IO
+
+To list the files and directories in a given directory, simply pass a path
+as an argument to C<dir>:
+
+    say dir "/etc/";    # "/etc/ld.so.conf".IO "/etc/shadow".IO ....
+
+=head1 Creating and removing directories
+
+To create a new directory, simply call the C<mkdir> function with the
+directory name as its argument:
+
+    mkdir "newdir";
+
+The function returns the name of the created directory on success and C<Nil>
+on failure.  Thus the standard Perl idiom
+
+    mkdir "newdir" or die "$!";
+
+works as expected.
+
+Similarly, one can remove I<empty> directories with C<rmdir>:
+
+    rmdir "newdir" or die "$!";
+
 =begin comment
 TODO: base on https://github.com/perl6/specs/blob/master/S32-setting-library/IO.pod?
 TODO: http://doc.perl6.org/type/IO::Handle has close but no open