package PerlIO::Util;

use 5.008_001;

use strict;

our $VERSION = '0.72';

require XSLoader;
XSLoader::load(__PACKAGE__, $VERSION);

*IO::Handle::get_layers = \&PerlIO::get_layers;

sub open :method{
	shift; # this class

	if(@_ < 2){
		require Carp;
		Carp::croak('Usage: PerlIO::Util->open($mode, @args)');
	}

	my $mode = shift;
	my $io = _gensym_ref(scalar caller, join ' ', @_);

	unless(open $io, $mode, @_){
		require Carp;
		Carp::croak('Cannot open(%s): %s', join(', ', $mode, @_), $!);
	}
	return $io;
}


1;
__END__

=encoding utf-8

=head1 NAME

PerlIO::Util - A selection of general PerlIO utilities

=head1 VERSION

This document describes PerlIO::Util version 0.72.

=for test_synopsis my($file, $scalar, $io);

=head1 SYNOPSIS

	use PerlIO::Util;

    # utility layers

	# open and flock(IN, LOCK_EX)
	$io = PerlIO::Util->open('+< :flock', $file);

	# open with O_CREAT | O_EXCL
	$io = PerlIO::Util->open('+<:creat :excl', $file);

    my $out = PerlIO::Util->open('>:tee', 'file.txt', \$scalar, \*STDERR);
    print $out 'foo'; # print to 'file.txt', $scalar and *STDERR

    # utility routines

    *STDOUT->push_layer(scalar => \$scalar); # it dies on fail
    print 'foo'; # to $scalar

    print *STDOUT->pop_layer(); # => scalar
    print $scalar; # to *STDOUT

=head1 DESCRIPTION

C<PerlIO::Util> provides general PerlIO utilities: utility layers and utility
methods.

Utility layers are a part of C<PerlIO::Util>, but you don't need to
say C<use PerlIO::Util> for loading them. They will be automatically loaded.

=head1 UTILITY LAYERS

=head2 :flock 

Easy interface to C<flock()>.

See L<PerlIO::flock>.

=head2 :creat

Use of O_CREAT without C<Fcntl>.

See L<PerlIO::creat>.

=head2 :excl

Use of O_EXCL without C<Fcntl>.

See L<PerlIO::excl>.

=head2 :tee

Multiplex output stream.

See L<PerlIO::tee>.

=head2 :dir

PerlIO interface to directory functions.

See L<PerlIO::dir>.

=head2 :reverse

Reverse input stream.

See L<PerlIO::reverse>.

=head2 :fse

Mediation of filesystem encoding.

This layer was split into an independent distribution, C<PerlIO::fse>.

See L<PerlIO::fse>.

=head1 UTILITY METHODS

=head2 PerlIO::Util->open(I<mode>, I<args>)

Calls built-in C<open()>, and returns an C<IO::Handle> instance named I<args>.
It dies on fail.

Unlike Perl's C<open()> (nor C<IO::File>'s), I<mode> is always required. 

=head2 PerlIO::Util->known_layers( )

Returns the known layer names.

=head2 I<FILEHANDLE>->get_layers( )

Returns the names of the PerlIO layers on I<FILEHANDLE>.

See L<PerlIO/Querying the layers of filehandles>.

=head2 I<FILEHANDLE>->push_layer(I<layer> [ => I<arg>])

Almost equivalent to C<binmode(FILEHANDLE, ':layer(arg)')>, but accepts
any type of I<arg>, e.g. a scalar reference to the C<:scalar> layer.

This method dies on fail. Otherwise, it returns I<FILEHANDLE>.

=head2 I<FILEHANDLE>->pop_layer( )

Equivalent to C<binmode(FILEHANDLE, ':pop')>. It removes a top level layer
from I<FILEHANDLE>, but note that you cannot remove dummy layers such as
C<:utf8> or C<:flock>.

This method returns the name of the popped layer.

=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