local-lib5/man/man3/Test::Builder::IO::Scalar.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Test::Builder::IO::Scalar 3"
 132 .TH Test::Builder::IO::Scalar 3 "2009-09-02" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Test::Builder::IO::Scalar \- A copy of IO::Scalar for Test::Builder
 135 .SH "DESCRIPTION"
 136 .IX Header "DESCRIPTION"
 137 This is a copy of IO::Scalar which ships with Test::Builder to
 138 support scalar references as filehandles on Perl 5.6.  Newer
 139 versions of Perl simply use \f(CW\*(C`<open()\*(C'\fR>'s built in support.
 140 .PP
 141 Test::Builder can not have dependencies on other modules without
 142 careful consideration, so its simply been copied into the distribution.
 143 .SH "COPYRIGHT and LICENSE"
 144 .IX Header "COPYRIGHT and LICENSE"
 145 This file came from the \*(L"IO\-stringy\*(R" Perl5 toolkit.
 146 .PP
 147 Copyright (c) 1996 by Eryq.  All rights reserved.
 148 Copyright (c) 1999,2001 by ZeeGee Software Inc.  All rights reserved.
 149 .PP
 150 This program is free software; you can redistribute it and/or
 151 modify it under the same terms as Perl itself.
 152 .Sh "Construction"
 153 .IX Subsection "Construction"
 154 .IP "new [\s-1ARGS\s0...]" 4
 155 .IX Item "new [ARGS...]"
 156 \&\fIClass method.\fR
 157 Return a new, unattached scalar handle.
 158 If any arguments are given, they're sent to \fIopen()\fR.
 159 .IP "open [\s-1SCALARREF\s0]" 4
 160 .IX Item "open [SCALARREF]"
 161 \&\fIInstance method.\fR
 162 Open the scalar handle on a new scalar, pointed to by \s-1SCALARREF\s0.
 163 If no \s-1SCALARREF\s0 is given, a \*(L"private\*(R" scalar is created to hold
 164 the file data.
 165 .Sp
 166 Returns the self object on success, undefined on error.
 167 .IP "opened" 4
 168 .IX Item "opened"
 169 \&\fIInstance method.\fR
 170 Is the scalar handle opened on something?
 171 .IP "close" 4
 172 .IX Item "close"
 173 \&\fIInstance method.\fR
 174 Disassociate the scalar handle from its underlying scalar.
 175 Done automatically on destroy.
 176 .Sh "Input and output"
 177 .IX Subsection "Input and output"
 178 .IP "flush" 4
 179 .IX Item "flush"
 180 \&\fIInstance method.\fR
 181 No\-op, provided for \s-1OO\s0 compatibility.
 182 .IP "getc" 4
 183 .IX Item "getc"
 184 \&\fIInstance method.\fR
 185 Return the next character, or undef if none remain.
 186 .IP "getline" 4
 187 .IX Item "getline"
 188 \&\fIInstance method.\fR
 189 Return the next line, or undef on end of string.
 190 Can safely be called in an array context.
 191 Currently, lines are delimited by \*(L"\en\*(R".
 192 .IP "getlines" 4
 193 .IX Item "getlines"
 194 \&\fIInstance method.\fR
 195 Get all remaining lines.
 196 It will \fIcroak()\fR if accidentally called in a scalar context.
 197 .IP "print \s-1ARGS\s0..." 4
 198 .IX Item "print ARGS..."
 199 \&\fIInstance method.\fR
 200 Print \s-1ARGS\s0 to the underlying scalar.
 201 .Sp
 202 \&\fBWarning:\fR this continues to always cause a seek to the end
 203 of the string, but if you perform \fIseek()\fRs and \fItell()\fRs, it is
 204 still safer to explicitly seek-to-end before subsequent \fIprint()\fRs.
 205 .IP "read \s-1BUF\s0, \s-1NBYTES\s0, [\s-1OFFSET\s0]" 4
 206 .IX Item "read BUF, NBYTES, [OFFSET]"
 207 \&\fIInstance method.\fR
 208 Read some bytes from the scalar.
 209 Returns the number of bytes actually read, 0 on end\-of\-file, undef on error.
 210 .IP "write \s-1BUF\s0, \s-1NBYTES\s0, [\s-1OFFSET\s0]" 4
 211 .IX Item "write BUF, NBYTES, [OFFSET]"
 212 \&\fIInstance method.\fR
 213 Write some bytes to the scalar.
 214 .IP "sysread \s-1BUF\s0, \s-1LEN\s0, [\s-1OFFSET\s0]" 4
 215 .IX Item "sysread BUF, LEN, [OFFSET]"
 216 \&\fIInstance method.\fR
 217 Read some bytes from the scalar.
 218 Returns the number of bytes actually read, 0 on end\-of\-file, undef on error.
 219 .IP "syswrite \s-1BUF\s0, \s-1NBYTES\s0, [\s-1OFFSET\s0]" 4
 220 .IX Item "syswrite BUF, NBYTES, [OFFSET]"
 221 \&\fIInstance method.\fR
 222 Write some bytes to the scalar.
 223 .Sh "Seeking/telling and other attributes"
 224 .IX Subsection "Seeking/telling and other attributes"
 225 .IP "autoflush" 4
 226 .IX Item "autoflush"
 227 \&\fIInstance method.\fR
 228 No\-op, provided for \s-1OO\s0 compatibility.
 229 .IP "binmode" 4
 230 .IX Item "binmode"
 231 \&\fIInstance method.\fR
 232 No\-op, provided for \s-1OO\s0 compatibility.
 233 .IP "clearerr" 4
 234 .IX Item "clearerr"
 235 \&\fIInstance method.\fR  Clear the error and \s-1EOF\s0 flags.  A no\-op.
 236 .IP "eof" 4
 237 .IX Item "eof"
 238 \&\fIInstance method.\fR  Are we at end of file?
 239 .IP "seek \s-1OFFSET\s0, \s-1WHENCE\s0" 4
 240 .IX Item "seek OFFSET, WHENCE"
 241 \&\fIInstance method.\fR  Seek to a given position in the stream.
 242 .IP "sysseek \s-1OFFSET\s0, \s-1WHENCE\s0" 4
 243 .IX Item "sysseek OFFSET, WHENCE"
 244 \&\fIInstance method.\fR Identical to \f(CW\*(C`seek OFFSET, WHENCE\*(C'\fR, \fIq.v.\fR
 245 .IP "tell" 4
 246 .IX Item "tell"
 247 \&\fIInstance method.\fR
 248 Return the current position in the stream, as a numeric offset.
 249 .IP "use_RS [\s-1YESNO\s0]" 4
 250 .IX Item "use_RS [YESNO]"
 251 \&\fIInstance method.\fR
 252 \&\fBDeprecated and ignored.\fR
 253 Obey the curent setting of $/, like IO::Handle does?
 254 Default is false in 1.x, but cold-welded true in 2.x and later.
 255 .IP "setpos \s-1POS\s0" 4
 256 .IX Item "setpos POS"
 257 \&\fIInstance method.\fR
 258 Set the current position, using the opaque value returned by \f(CW\*(C`getpos()\*(C'\fR.
 259 .IP "getpos" 4
 260 .IX Item "getpos"
 261 \&\fIInstance method.\fR
 262 Return the current position in the string, as an opaque object.
 263 .IP "sref" 4
 264 .IX Item "sref"
 265 \&\fIInstance method.\fR
 266 Return a reference to the underlying scalar.
 267 .SH "WARNINGS"
 268 .IX Header "WARNINGS"
 269 Perl's \s-1TIEHANDLE\s0 spec was incomplete prior to 5.005_57;
 270 it was missing support for \f(CW\*(C`seek()\*(C'\fR, \f(CW\*(C`tell()\*(C'\fR, and \f(CW\*(C`eof()\*(C'\fR.
 271 Attempting to use these functions with an IO::Scalar will not work
 272 prior to 5.005_57. IO::Scalar will not have the relevant methods
 273 invoked; and even worse, this kind of bug can lie dormant for a while.
 274 If you turn warnings on (via \f(CW$^W\fR or \f(CW\*(C`perl \-w\*(C'\fR),
 275 and you see something like this...
 276 .PP
 277 .Vb 1
 278 \&    attempt to seek on unopened filehandle
 279 .Ve
 280 .PP
 281 \&...then you are probably trying to use one of these functions
 282 on an IO::Scalar with an old Perl.  The remedy is to simply
 283 use the \s-1OO\s0 version; e.g.:
 284 .PP
 285 .Vb 2
 286 \&    $SH\->seek(0,0);    ### GOOD: will work on any 5.005
 287 \&    seek($SH,0,0);     ### WARNING: will only work on 5.005_57 and beyond
 288 .Ve
 289 .SH "VERSION"
 290 .IX Header "VERSION"
 291 $Id: Scalar.pm,v 1.6 2005/02/10 21:21:53 dfs Exp $
 292 .SH "AUTHORS"
 293 .IX Header "AUTHORS"
 294 .Sh "Primary Maintainer"
 295 .IX Subsection "Primary Maintainer"
 296 David F. Skoll (\fIdfs@roaringpenguin.com\fR).
 297 .Sh "Principal author"
 298 .IX Subsection "Principal author"
 299 Eryq (\fIeryq@zeegee.com\fR).
 300 President, ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
 301 .Sh "Other contributors"
 302 .IX Subsection "Other contributors"
 303 The full set of contributors always includes the folks mentioned
 304 in \*(L"\s-1CHANGE\s0 \s-1LOG\s0\*(R" in IO::Stringy.  But just the same, special
 305 thanks to the following individuals for their invaluable contributions
 306 (if I've forgotten or misspelled your name, please email me!):
 307 .PP
 308 \&\fIAndy Glew,\fR
 309 for contributing \f(CW\*(C`getc()\*(C'\fR.
 310 .PP
 311 \&\fIBrandon Browning,\fR
 312 for suggesting \f(CW\*(C`opened()\*(C'\fR.
 313 .PP
 314 \&\fIDavid Richter,\fR
 315 for finding and fixing the bug in \f(CW\*(C`PRINTF()\*(C'\fR.
 316 .PP
 317 \&\fIEric L. Brine,\fR
 318 for his offset-using \fIread()\fR and \fIwrite()\fR implementations.
 319 .PP
 320 \&\fIRichard Jones,\fR
 321 for his patches to massively improve the performance of \f(CW\*(C`getline()\*(C'\fR
 322 and add \f(CW\*(C`sysread\*(C'\fR and \f(CW\*(C`syswrite\*(C'\fR.
 323 .PP
 324 \&\fIB. K. Oxley (binkley),\fR
 325 for stringification and inheritance improvements,
 326 and sundry good ideas.
 327 .PP
 328 \&\fIDoug Wilson,\fR
 329 for the IO::Handle inheritance and automatic tie\-ing.
 330 .SH "SEE ALSO"
 331 .IX Header "SEE ALSO"
 332 IO::String, which is quite similar but which was designed
 333 more-recently and with an IO::Handle\-like interface in mind,
 334 so you could mix \s-1OO\-\s0 and native-filehandle usage without using \fItied()\fR.
 335 .PP
 336 \&\fINote:\fR as of version 2.x, these classes all work like
 337 their IO::Handle counterparts, so we have comparable
 338 functionality to IO::String.