=begin pod :kind("Type") :subkind("class") :category("domain-specific")

=TITLE class IO::ArgFiles

=SUBTITLE Iterate over contents of files specified on command line

   class IO::ArgFiles is IO::CatHandle { }

This class exists for backwards compatibility reasons and provides no additional
methods to L«C<IO::CatHandle>|/type/IO::CatHandle», so it can be used in the same way as it, for
instance, in this way:

=for code
my $argfiles = IO::ArgFiles.new(@*ARGS);
.say for $argfiles.lines;

If invoked with C<raku io-argfiles.raku *.raku> it will print the contents of all
the files with that extension in the directory. However, that is totally
equivalent to:

=for code
my $argfiles = IO::CatHandle.new(@*ARGS);
.say for $argfiles.lines;

=head1 Variables

=head2 C<$*ARGFILES>

This class is the magic behind the C<$*ARGFILES> variable, which provides a way
to iterate over files passed in to the program on the command line (i.e.
elements of L<C«@*ARGS»|/language/variables#index-entry-%40%2AARGS>). Thus the
examples above can be simplified like so:

    .say for $*ARGFILES.lines;

    # or
    while ! $*ARGFILES.eof {
        say $*ARGFILES.get;
    }

    # or
    say $*ARGFILES.slurp;

Save one of the variations above in a file, say C<argfiles.raku>.  Then create
another file (named, say C<sonnet18.txt> with the contents:

=for code :lang<text>
Shall I compare thee to a summer's day?

Running the command

=for code :lang<text>
$ raku argfiles.raku sonnet18.txt

will then give the output

=for code :lang<text>
Shall I compare thee to a summer's day?

As of 6.d language, C<$*ARGFILES> I<inside>
L<C«sub MAIN»|/language/functions#sub_MAIN> is always set to C<$*IN>, even
when C<@*ARGS> is not empty. That means that

=for code
sub MAIN () {
    .say for $*ARGFILES.lines;
}

which can be used as C<cat *.raku | raku argfiles-main.raku>, for instance, is
totally equivalent to:

=for code
sub MAIN () {
    .say for $*IN.lines;
}

and, in fact, can't be used to process the arguments in the command line, since,
in this case, it would result in an usage error.

Bear in mind that the object C<$*ARGFILES> is going to contain a handle for
every argument in a command line, even if that argument is not a valid file. You
can retrieve them via the C<.handles> method.

=for code
for $*ARGFILES.handles -> $fh {
    say $fh;
}

That code will fail if any of the arguments is not the valid name of a file. You
will have to deal with that case at another level, checking that
L<C<@*ARGS>|/language/variables#index-entry-%40*ARGS> contains valid file names,
for instance.

=end pod

# vim: expandtab shiftwidth=4 ft=perl6
