diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Test::Builder::IO::Scalar.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Test::Builder::IO::Scalar.3pm | 268 |
1 files changed, 268 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Test::Builder::IO::Scalar.3pm b/upstream/mageia-cauldron/man3pm/Test::Builder::IO::Scalar.3pm new file mode 100644 index 00000000..382b0559 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Test::Builder::IO::Scalar.3pm @@ -0,0 +1,268 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Test::Builder::IO::Scalar 3pm" +.TH Test::Builder::IO::Scalar 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Test::Builder::IO::Scalar \- A copy of IO::Scalar for Test::Builder +.SH DESCRIPTION +.IX Header "DESCRIPTION" +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 \f(CWopen()\fR's built in support. +.PP +Test::Builder can not have dependencies on other modules without +careful consideration, so its simply been copied into the distribution. +.SH "COPYRIGHT and LICENSE" +.IX Header "COPYRIGHT and LICENSE" +This file came from the "IO-stringy" Perl5 toolkit. +.PP +Copyright (c) 1996 by Eryq. All rights reserved. +Copyright (c) 1999,2001 by ZeeGee Software Inc. All rights reserved. +.PP +This program is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. +.SS Construction +.IX Subsection "Construction" +.IP "new [ARGS...]" 4 +.IX Item "new [ARGS...]" +\&\fIClass method.\fR +Return a new, unattached scalar handle. +If any arguments are given, they're sent to \fBopen()\fR. +.IP "open [SCALARREF]" 4 +.IX Item "open [SCALARREF]" +\&\fIInstance method.\fR +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. +.Sp +Returns the self object on success, undefined on error. +.IP opened 4 +.IX Item "opened" +\&\fIInstance method.\fR +Is the scalar handle opened on something? +.IP close 4 +.IX Item "close" +\&\fIInstance method.\fR +Disassociate the scalar handle from its underlying scalar. +Done automatically on destroy. +.SS "Input and output" +.IX Subsection "Input and output" +.IP flush 4 +.IX Item "flush" +\&\fIInstance method.\fR +No-op, provided for OO compatibility. +.IP getc 4 +.IX Item "getc" +\&\fIInstance method.\fR +Return the next character, or undef if none remain. +.IP getline 4 +.IX Item "getline" +\&\fIInstance method.\fR +Return the next line, or undef on end of string. +Can safely be called in an array context. +Currently, lines are delimited by "\en". +.IP getlines 4 +.IX Item "getlines" +\&\fIInstance method.\fR +Get all remaining lines. +It will \fBcroak()\fR if accidentally called in a scalar context. +.IP "print ARGS..." 4 +.IX Item "print ARGS..." +\&\fIInstance method.\fR +Print ARGS to the underlying scalar. +.Sp +\&\fBWarning:\fR this continues to always cause a seek to the end +of the string, but if you perform \fBseek()\fRs and \fBtell()\fRs, it is +still safer to explicitly seek-to-end before subsequent \fBprint()\fRs. +.IP "read BUF, NBYTES, [OFFSET]" 4 +.IX Item "read BUF, NBYTES, [OFFSET]" +\&\fIInstance method.\fR +Read some bytes from the scalar. +Returns the number of bytes actually read, 0 on end-of-file, undef on error. +.IP "write BUF, NBYTES, [OFFSET]" 4 +.IX Item "write BUF, NBYTES, [OFFSET]" +\&\fIInstance method.\fR +Write some bytes to the scalar. +.IP "sysread BUF, LEN, [OFFSET]" 4 +.IX Item "sysread BUF, LEN, [OFFSET]" +\&\fIInstance method.\fR +Read some bytes from the scalar. +Returns the number of bytes actually read, 0 on end-of-file, undef on error. +.IP "syswrite BUF, NBYTES, [OFFSET]" 4 +.IX Item "syswrite BUF, NBYTES, [OFFSET]" +\&\fIInstance method.\fR +Write some bytes to the scalar. +.SS "Seeking/telling and other attributes" +.IX Subsection "Seeking/telling and other attributes" +.IP autoflush 4 +.IX Item "autoflush" +\&\fIInstance method.\fR +No-op, provided for OO compatibility. +.IP binmode 4 +.IX Item "binmode" +\&\fIInstance method.\fR +No-op, provided for OO compatibility. +.IP clearerr 4 +.IX Item "clearerr" +\&\fIInstance method.\fR Clear the error and EOF flags. A no-op. +.IP eof 4 +.IX Item "eof" +\&\fIInstance method.\fR Are we at end of file? +.IP "seek OFFSET, WHENCE" 4 +.IX Item "seek OFFSET, WHENCE" +\&\fIInstance method.\fR Seek to a given position in the stream. +.IP "sysseek OFFSET, WHENCE" 4 +.IX Item "sysseek OFFSET, WHENCE" +\&\fIInstance method.\fR Identical to \f(CW\*(C`seek OFFSET, WHENCE\*(C'\fR, \fIq.v.\fR +.IP tell 4 +.IX Item "tell" +\&\fIInstance method.\fR +Return the current position in the stream, as a numeric offset. +.IP "use_RS [YESNO]" 4 +.IX Item "use_RS [YESNO]" +\&\fIInstance method.\fR +\&\fBDeprecated and ignored.\fR +Obey the current setting of $/, like IO::Handle does? +Default is false in 1.x, but cold-welded true in 2.x and later. +.IP "setpos POS" 4 +.IX Item "setpos POS" +\&\fIInstance method.\fR +Set the current position, using the opaque value returned by \f(CWgetpos()\fR. +.IP getpos 4 +.IX Item "getpos" +\&\fIInstance method.\fR +Return the current position in the string, as an opaque object. +.IP sref 4 +.IX Item "sref" +\&\fIInstance method.\fR +Return a reference to the underlying scalar. +.SH WARNINGS +.IX Header "WARNINGS" +Perl's TIEHANDLE spec was incomplete prior to 5.005_57; +it was missing support for \f(CWseek()\fR, \f(CWtell()\fR, and \f(CWeof()\fR. +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 \f(CW$^W\fR or \f(CW\*(C`perl \-w\*(C'\fR), +and you see something like this... +.PP +.Vb 1 +\& attempt to seek on unopened filehandle +.Ve +.PP +\&...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.: +.PP +.Vb 2 +\& $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 +.Ve +.SH VERSION +.IX Header "VERSION" +\&\f(CW$Id:\fR Scalar.pm,v 1.6 2005/02/10 21:21:53 dfs Exp $ +.SH AUTHORS +.IX Header "AUTHORS" +.SS "Primary Maintainer" +.IX Subsection "Primary Maintainer" +David F. Skoll (\fIdfs@roaringpenguin.com\fR). +.SS "Principal author" +.IX Subsection "Principal author" +Eryq (\fIeryq@zeegee.com\fR). +President, ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR). +.SS "Other contributors" +.IX Subsection "Other contributors" +The full set of contributors always includes the folks mentioned +in "CHANGE LOG" in IO::Stringy. 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!): +.PP +\&\fIAndy Glew,\fR +for contributing \f(CWgetc()\fR. +.PP +\&\fIBrandon Browning,\fR +for suggesting \f(CWopened()\fR. +.PP +\&\fIDavid Richter,\fR +for finding and fixing the bug in \f(CWPRINTF()\fR. +.PP +\&\fIEric L. Brine,\fR +for his offset-using \fBread()\fR and \fBwrite()\fR implementations. +.PP +\&\fIRichard Jones,\fR +for his patches to massively improve the performance of \f(CWgetline()\fR +and add \f(CW\*(C`sysread\*(C'\fR and \f(CW\*(C`syswrite\*(C'\fR. +.PP +\&\fIB. K. Oxley (binkley),\fR +for stringification and inheritance improvements, +and sundry good ideas. +.PP +\&\fIDoug Wilson,\fR +for the IO::Handle inheritance and automatic tie-ing. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +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 \fBtied()\fR. +.PP +\&\fINote:\fR as of version 2.x, these classes all work like +their IO::Handle counterparts, so we have comparable +functionality to IO::String. |