=encoding utf-8
=head1 NAME
PerlIO::Util::JA - PerlIOに関する汎用ユーティリティ集
=head1 VERSION
This document describes PerlIO::Util version 0.72
=for test_synopsis my($in, $out, $file, $scalar);
=head1 SYNOPSIS
use PerlIO::Util;
# utility layers
open $in, '+<:flock', $file; # with flock(IN, LOCK_EX)
open $in, '+<:creat :excl', $file; # with O_CREAT | O_EXCL
open $out, '>:tee', $file, \$scalar, \*STDERR;
print $out "foo"; # print to $file, $scalar and *STDERR
# utility routines
$in = PerlIO::Util->open('<', $file); # it dies on fail
*STDOUT->push_layer(scalar => \$scalar); # it dies on fail
print "foo";
print *STDOUT->pop_layer(); # => scalar
print $scalar; # => foo
=head1 DESCRIPTION
C<PerlIO::Util>はPerlIOに関するユーティリティレイヤとユーティリティメソッドを
提供するモジュールである。
ユーティリティレイヤはC<PerlIO::Util>の一部だが,使用に際してC<use PerlIO::Util>
と書く必要はない。PerlIOは必要に応じてレイヤを自動的にロードする。
=head1 UTILITY LAYERS
=head2 :flock
C<flock()>に対する簡易なインターフェイスを提供する。
See L<PerlIO::flock>.
=head2 :creat
C<Fcntl>を用いずに,O_CREATを使用する。
See L<PerlIO::creat>.
=head2 :excl
C<Fcntl>を用いずに,O_EXCLを使用する。
See L<PerlIO::excl>.
=head2 :tee
複数のファイルやストリームに同時に出力する。
See L<PerlIO::tee>.
=head2 :dir
PerlIOインターフェイスでディレクトリを読む。
ディレクトリハンドルをファイルハンドルとして扱うため,
C<:encodeing>などのPerlIOレイヤを適用できる。
See L<PerlIO::dir>.
=head2 :reverse
ファイルを逆順に読む。
一旦全て読み込んでからC<reverse()>するより高速だが,
コンソールやパイプなどのC<seek()>できないストリームは扱えない。
See L<PerlIO::reverse>.
=head2 :fse
ファイルシステムエンコーディングを扱う。
与えられたファイル名がPerlのユニコード文字列であるとき,
C<Encode>モジュールを使ってファイルシステムのエンコーディングに変換する。
なお,Windows以外では自動的にファイルシステムのエンコーディングを取得するが,
それ以外の環境では環境変数PERLIO_FSEで指定するか,C<use PerlIO::fse>の引数としてエンコーディングを指定する必要がある。
なお,このレイヤーは0.70で独立したモジュールとなった。
See L<PerlIO::fse>.
=head1 UTILITY METHODS
=head2 PerlIO::Util-E<gt>open(I<mode>, I<args>)
ビルトイン関数のC<open()>を呼び出し,C<IO::Handle>オブジェクトを返す。
C<open()>に失敗すると致命的エラーとなる。
PerlのC<open()>と異なり(またC<IO::File>のC<new()>とも異なり),I<mode>は
常に必須である。つまり,基本的にはC<IO::File>のC<new()>の代替として使用できるが,常にB<3-arg open>を強要し,失敗すると致命的エラーとなる点でC<IO::File>のC<new()>と異なる。
=head2 PerlIO::Util->known_layers( )
定義済みのPerlIOレイヤの名前を返す。
=head2 I<FILEHANDLE>-E<gt>get_layers( )
I<FILEHANDLE>のPerlIOレイヤの名前を返す。
これはI<PerlIO::get_layers(I<FILEHANDLE>)>の別名である。
See L<PerlIO/Querying the layers of filehandles>.
=head2 I<FILEHANDLE>-E<gt>push_layer(I<layer> [ => I<arg>])
C<binmode(FILEHANDLE, ':layer(arg)')>とほぼ同じだが,I<arg>はどんな
データ型でもよい。たとえば,C<:scalar>に対してスカラリファレンスを与えることができる。
このメソッドは失敗すると致命的エラーとなる。成功したときはI<FILEHANDLE>を返す。
=head2 I<FILEHANDLE>-E<gt>pop_layer( )
C<binmode(FILEHANDLE, ':pop')>に等しい。これはI<FILEHANDLE>の最上部の
レイヤを取り除く。なお,C<:utf8>やC<:flock>のようなダミーレイヤを取り除くことはできない。
このメソッドは実際に取り除いたレイヤの名前を返す。
=head1 DEPENDENCIES
Perl 5.8.1 or later, and a C compiler.
=head1 BUGS
No bugs have been reported.
Please report any bugs or feature requests to
E<lt>gfuji (at) cpan.orgE<gt>, or through the web interface at
L<http://rt.cpan.org/>.
=head1 SEE ALSO
L<PerlIO::flock>, L<PerlIO::creat>, L<PerlIO::excl>, L<PerlIO::tee>,
L<PerlIO::dir>, L<PerlIO::reverse>, L<PerlIO::fse>.
L<PerlIO> for C<push_layer()> and C<pop_layer()>.
L<perliol> for implementation details.
L<perlfunc/open>.
L<perlopentut>.
=head1 AUTHOR
Goro Fuji (藤 吾郎) E<lt>gfuji(at)cpan.orgE<gt>.
=head1 LICENSE AND COPYRIGHT
Copyright (c) 2008-2010, Goro Fuji E<lt>gfuji(at)cpan.orgE<gt>. Some rights reserved.
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
=cut