=encoding euc-jp

=head1 NAME

=begin original

Test::Builder::IO::Scalar - A copy of IO::Scalar for Test::Builder

=end original

Test::Builder::IO::Scalar - Test::Builder のための IO::Scalar のコピー

=head1 DESCRIPTION

=begin original

This is a copy of IO::Scalar which ships with Test::Builder to
support scalar references as filehandles on Perl 5.6.  Newer
versions of Perl simply use C<<open()>>'s built in support.

=end original

これは、Perl 5.6 でファイルハンドルとしてのスカラリファレンス対応のために
Test::Builder に同梱している IO::Scalar のコピーです。
より新しいバージョンの Perl では単に C<<open()>> の組み込み対応を使います。

=begin original

Test::Builder can not have dependencies on other modules without
careful consideration, so its simply been copied into the distribution.

=end original

Test::Builder は、注意深い考慮なしには他のモジュールへの依存を持てないので、
単に配布に含めるためにコピーしています。

=head1 COPYRIGHT and LICENSE

=begin original

This file came from the "IO-stringy" Perl5 toolkit.

=end original

This file came from the "IO-stringy" Perl5 toolkit.
(TBT)

Copyright (c) 1996 by Eryq.  All rights reserved.
Copyright (c) 1999,2001 by ZeeGee Software Inc.  All rights reserved.

This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=cut

=head2 Construction

=over 4

=cut

=item new [ARGS...]

=begin original

I<Class method.>
Return a new, unattached scalar handle.
If any arguments are given, they're sent to open().

=end original

I<Class method.>
Return a new, unattached scalar handle.
If any arguments are given, they're sent to open().
(TBT)

=cut

=item open [SCALARREF]

=begin original

I<Instance method.>
Open the scalar handle on a new scalar, pointed to by SCALARREF.
If no SCALARREF is given, a "private" scalar is created to hold
the file data.

=end original

I<Instance method.>
Open the scalar handle on a new scalar, pointed to by SCALARREF.
If no SCALARREF is given, a "private" scalar is created to hold
the file data.
(TBT)

=begin original

Returns the self object on success, undefined on error.

=end original

Returns the self object on success, undefined on error.
(TBT)

=cut

=item opened

=begin original

I<Instance method.>
Is the scalar handle opened on something?

=end original

I<Instance method.>
Is the scalar handle opened on something?
(TBT)

=cut

=item close

=begin original

I<Instance method.>
Disassociate the scalar handle from its underlying scalar.
Done automatically on destroy.

=end original

I<Instance method.>
Disassociate the scalar handle from its underlying scalar.
Done automatically on destroy.
(TBT)

=cut

=back

=cut

=head2 Input and output

=over 4

=cut

=item flush

=begin original

I<Instance method.>
No-op, provided for OO compatibility.

=end original

I<Instance method.>
No-op, provided for OO compatibility.
(TBT)

=cut

=item getc

=begin original

I<Instance method.>
Return the next character, or undef if none remain.

=end original

I<Instance method.>
Return the next character, or undef if none remain.
(TBT)

=cut

=item getline

=begin original

I<Instance method.>
Return the next line, or undef on end of string.
Can safely be called in an array context.
Currently, lines are delimited by "\n".

=end original

I<Instance method.>
Return the next line, or undef on end of string.
Can safely be called in an array context.
Currently, lines are delimited by "\n".
(TBT)

=cut

=item getlines

=begin original

I<Instance method.>
Get all remaining lines.
It will croak() if accidentally called in a scalar context.

=end original

I<Instance method.>
Get all remaining lines.
It will croak() if accidentally called in a scalar context.
(TBT)

=cut

=item print ARGS...

=begin original

I<Instance method.>
Print ARGS to the underlying scalar.

=end original

I<Instance method.>
Print ARGS to the underlying scalar.
(TBT)

=begin original

B<Warning:> this continues to always cause a seek to the end
of the string, but if you perform seek()s and tell()s, it is
still safer to explicitly seek-to-end before subsequent print()s.

=end original

B<Warning:> this continues to always cause a seek to the end
of the string, but if you perform seek()s and tell()s, it is
still safer to explicitly seek-to-end before subsequent print()s.
(TBT)

=cut

=item read BUF, NBYTES, [OFFSET]

=begin original

I<Instance method.>
Read some bytes from the scalar.
Returns the number of bytes actually read, 0 on end-of-file, undef on error.

=end original

I<Instance method.>
Read some bytes from the scalar.
Returns the number of bytes actually read, 0 on end-of-file, undef on error.
(TBT)

=cut

=item write BUF, NBYTES, [OFFSET]

=begin original

I<Instance method.>
Write some bytes to the scalar.

=end original

I<Instance method.>
Write some bytes to the scalar.
(TBT)

=cut

=item sysread BUF, LEN, [OFFSET]

=begin original

I<Instance method.>
Read some bytes from the scalar.
Returns the number of bytes actually read, 0 on end-of-file, undef on error.

=end original

I<Instance method.>
Read some bytes from the scalar.
Returns the number of bytes actually read, 0 on end-of-file, undef on error.
(TBT)

=cut

=item syswrite BUF, NBYTES, [OFFSET]

=begin original

I<Instance method.>
Write some bytes to the scalar.

=end original

I<Instance method.>
Write some bytes to the scalar.
(TBT)

=cut

=back

=cut

=head2 Seeking/telling and other attributes

=over 4

=cut

=item autoflush

=begin original

I<Instance method.>
No-op, provided for OO compatibility.

=end original

I<Instance method.>
No-op, provided for OO compatibility.
(TBT)

=cut

=item binmode

=begin original

I<Instance method.>
No-op, provided for OO compatibility.

=end original

I<Instance method.>
No-op, provided for OO compatibility.
(TBT)

=cut

=item clearerr

=begin original

I<Instance method.>  Clear the error and EOF flags.  A no-op.

=end original

I<Instance method.>  Clear the error and EOF flags.  A no-op.
(TBT)

=cut

=item eof

=begin original

I<Instance method.>  Are we at end of file?

=end original

I<Instance method.>  Are we at end of file?
(TBT)

=cut

=item seek OFFSET, WHENCE

=begin original

I<Instance method.>  Seek to a given position in the stream.

=end original

I<Instance method.>  Seek to a given position in the stream.
(TBT)

=cut

=item sysseek OFFSET, WHENCE

=begin original

I<Instance method.> Identical to C<seek OFFSET, WHENCE>, I<q.v.>

=end original

I<Instance method.> Identical to C<seek OFFSET, WHENCE>, I<q.v.>
(TBT)

=cut

=item tell

=begin original

I<Instance method.>
Return the current position in the stream, as a numeric offset.

=end original

I<Instance method.>
Return the current position in the stream, as a numeric offset.
(TBT)

=cut

=item  use_RS [YESNO]

=begin original

I<Instance method.>
B<Deprecated and ignored.>
Obey the current setting of $/, like IO::Handle does?
Default is false in 1.x, but cold-welded true in 2.x and later.

=end original

I<Instance method.>
B<Deprecated and ignored.>
Obey the current setting of $/, like IO::Handle does?
Default is false in 1.x, but cold-welded true in 2.x and later.
(TBT)

=cut

=item setpos POS

=begin original

I<Instance method.>
Set the current position, using the opaque value returned by C<getpos()>.

=end original

I<Instance method.>
Set the current position, using the opaque value returned by C<getpos()>.
(TBT)

=cut

=item getpos

=begin original

I<Instance method.>
Return the current position in the string, as an opaque object.

=end original

I<Instance method.>
Return the current position in the string, as an opaque object.
(TBT)

=cut

=item sref

=begin original

I<Instance method.>
Return a reference to the underlying scalar.

=end original

I<Instance method.>
Return a reference to the underlying scalar.
(TBT)

=cut

=back

=cut

=head1 WARNINGS

=begin original

Perl's TIEHANDLE spec was incomplete prior to 5.005_57;
it was missing support for C<seek()>, C<tell()>, and C<eof()>.
Attempting to use these functions with an IO::Scalar will not work
prior to 5.005_57. IO::Scalar will not have the relevant methods
invoked; and even worse, this kind of bug can lie dormant for a while.
If you turn warnings on (via C<$^W> or C<perl -w>),
and you see something like this...

=end original

Perl's TIEHANDLE spec was incomplete prior to 5.005_57;
it was missing support for C<seek()>, C<tell()>, and C<eof()>.
Attempting to use these functions with an IO::Scalar will not work
prior to 5.005_57. IO::Scalar will not have the relevant methods
invoked; and even worse, this kind of bug can lie dormant for a while.
If you turn warnings on (via C<$^W> or C<perl -w>),
and you see something like this...
(TBT)

    attempt to seek on unopened filehandle

=begin original

...then you are probably trying to use one of these functions
on an IO::Scalar with an old Perl.  The remedy is to simply
use the OO version; e.g.:

=end original

...then you are probably trying to use one of these functions
on an IO::Scalar with an old Perl.  The remedy is to simply
use the OO version; e.g.:
(TBT)

    $SH->seek(0,0);    ### GOOD: will work on any 5.005
    seek($SH,0,0);     ### WARNING: will only work on 5.005_57 and beyond

=head1 VERSION

$Id: Scalar.pm,v 1.6 2005/02/10 21:21:53 dfs Exp $

=head1 AUTHORS

=head2 Primary Maintainer

David F. Skoll (F<dfs@roaringpenguin.com>).

=head2 Principal author

Eryq (F<eryq@zeegee.com>).
President, ZeeGee Software Inc (F<http://www.zeegee.com>).

=head2 Other contributors

=begin original

The full set of contributors always includes the folks mentioned
in L<IO::Stringy/"CHANGE LOG">.  But just the same, special
thanks to the following individuals for their invaluable contributions
(if I've forgotten or misspelled your name, please email me!):

=end original

The full set of contributors always includes the folks mentioned
in L<IO::Stringy/"CHANGE LOG">.  But just the same, special
thanks to the following individuals for their invaluable contributions
(if I've forgotten or misspelled your name, please email me!):
(TBT)

=begin original

I<Andy Glew,>
for contributing C<getc()>.

=end original

I<Andy Glew,>
for contributing C<getc()>.
(TBT)

=begin original

I<Brandon Browning,>
for suggesting C<opened()>.

=end original

I<Brandon Browning,>
for suggesting C<opened()>.
(TBT)

=begin original

I<David Richter,>
for finding and fixing the bug in C<PRINTF()>.

=end original

I<David Richter,>
for finding and fixing the bug in C<PRINTF()>.
(TBT)

=begin original

I<Eric L. Brine,>
for his offset-using read() and write() implementations.

=end original

I<Eric L. Brine,>
for his offset-using read() and write() implementations.
(TBT)

=begin original

I<Richard Jones,>
for his patches to massively improve the performance of C<getline()>
and add C<sysread> and C<syswrite>.

=end original

I<Richard Jones,>
for his patches to massively improve the performance of C<getline()>
and add C<sysread> and C<syswrite>.
(TBT)

=begin original

I<B. K. Oxley (binkley),>
for stringification and inheritance improvements,
and sundry good ideas.

=end original

I<B. K. Oxley (binkley),>
for stringification and inheritance improvements,
and sundry good ideas.
(TBT)

=begin original

I<Doug Wilson,>
for the IO::Handle inheritance and automatic tie-ing.

=end original

I<Doug Wilson,>
for the IO::Handle inheritance and automatic tie-ing.
(TBT)

=head1 SEE ALSO

=begin original

L<IO::String>, which is quite similar but which was designed
more-recently and with an IO::Handle-like interface in mind,
so you could mix OO- and native-filehandle usage without using tied().

=end original

L<IO::String>, which is quite similar but which was designed
more-recently and with an IO::Handle-like interface in mind,
so you could mix OO- and native-filehandle usage without using tied().
(TBT)

=begin original

I<Note:> as of version 2.x, these classes all work like
their IO::Handle counterparts, so we have comparable
functionality to IO::String.

=end original

I<Note:> as of version 2.x, these classes all work like
their IO::Handle counterparts, so we have comparable
functionality to IO::String.
(TBT)

=begin meta

Translate: SHIRAKATA Kentaro <argrath@ub32.org>
Status: in progress

=end meta

=cut