view release on metacpan or  search on metacpan

share/Synopsis/S32-setting-library/IO.pod  view on Meta::CPAN


=encoding utf8

=head1 TITLE

DRAFT: Synopsis 32: Setting Library - IO

=head1 AUTHORS

    The authors of the related Perl 5 docs
    Rod Adams <rod@rodadams.net>
    Larry Wall <larry@wall.org>
    Aaron Sherman <ajs@ajs.com>
    Mark Stosberg <mark@summersault.com>
    Carl Mäsak <cmasak@gmail.com>
    Moritz Lenz <moritz@faui2k3.org>
    Tim Nelson <wayland@wayland.id.au>
    Daniel Ruoso <daniel@ruoso.com>
    Lyle Hopkins <webmaster@cosmicperl.com>

=head1 VERSION

    Created: 19 Feb 2009 extracted from S29-functions.pod; added stuff from S16-IO later

    Last Modified: 4 July 2010
    Version: 13

The document is a draft.

If you read the HTML version, it is generated from the Pod in the specs
repository under
L<https://github.com/perl6/specs/blob/master/S32-setting-library/IO.pod>
so edit it there in the git repository if you would like to make changes.

=head2 IO

[Note: if a method declaration indicates a method name qualified by
type, it should be taken as shorthand to say which role or class the
method is actually declared in.]

=over 4

=item open
X<open>

    multi open (Str $name,
        Bool :$rw = False,
        Bool :$bin = False,
        Str  :$enc = "Unicode",
        Any  :$nl = "\n",
        Bool :$chomp = True,
        ...
        --> IO
    ) is export

A convenience method/function that hides most of the OO complexity.
It will only open normal files.  Text is the default.  Note that
the "Unicode" encoding implies figuring out which actual UTF is
in use, either from a BOM or other heuristics.  If heuristics are
inconclusive, UTF-8 will be assumed.  (No 8-bit encoding will ever
be picked implicitly.)  A file opened with C<:bin> may still be
processed line-by-line, but IO will be in terms of C<Buf> rather
than C<Str> types.

TODO: document read/write/append modes (:r, :w, :a)

=item dir
X<dir>

    multi dir($directory = '.', Mu :$test = none('.', '..')) { ... }

Returns a lazy list of file names in the C<$directory>. By default the current
and the parent directory are excluded, which can be controlled with the
C<$test> named paramater. Only items that smart-match against this test are
returned.

=item getc
X<getc>

    method getc (Int $chars = 1 --> Char)

See below for details.

=item print
X<print>

    method print (*@LIST --> Bool)
    multi print (*@LIST --> Bool)
    method Str::print (IO $io --> Bool)
    method Array::print (IO $io --> Bool)
    method Hash::print (IO $io --> Bool)

See below for details.

=item say
X<say>

    method say (*@LIST --> Bool)
    multi say (*@LIST --> Bool)
    method Str::say (IO $io --> Bool)
    method Array::say (IO $io --> Bool)
    method Hash::say (IO $io --> Bool)

See below for details.

=item note
X<note>

    multi note (*@LIST --> Bool)

See below for details.

=item printf
X<printf>

    method printf (Str $fmt, *@LIST --> Bool)
    multi printf (Str $fmt, *@LIST --> Bool)

See below for details.