local-lib5/man/man3/IO::ScalarArray.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 "IO::ScalarArray 3"
 132 .TH IO::ScalarArray 3 "2005-02-10" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 IO::ScalarArray \- IO:: interface for reading/writing an array of scalars
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 Perform I/O on strings, using the basic \s-1OO\s0 interface...
 138 .PP
 139 .Vb 2
 140 \&    use IO::ScalarArray;
 141 \&    @data = ("My mes", "sage:\en");
 142 .Ve
 143 .PP
 144 .Vb 5
 145 \&    ### Open a handle on an array, and append to it:
 146 \&    $AH = new IO::ScalarArray \e@data;
 147 \&    $AH\->print("Hello");
 148 \&    $AH\->print(", world!\enBye now!\en");
 149 \&    print "The array is now: ", @data, "\en";
 150 .Ve
 151 .PP
 152 .Vb 6
 153 \&    ### Open a handle on an array, read it line\-by\-line, then close it:
 154 \&    $AH = new IO::ScalarArray \e@data;
 155 \&    while (defined($_ = $AH\->getline)) {
 156 \&        print "Got line: $_";
 157 \&    }
 158 \&    $AH\->close;
 159 .Ve
 160 .PP
 161 .Vb 3
 162 \&    ### Open a handle on an array, and slurp in all the lines:
 163 \&    $AH = new IO::ScalarArray \e@data;
 164 \&    print "All lines:\en", $AH\->getlines;
 165 .Ve
 166 .PP
 167 .Vb 3
 168 \&    ### Get the current position (either of two ways):
 169 \&    $pos = $AH\->getpos;
 170 \&    $offset = $AH\->tell;
 171 .Ve
 172 .PP
 173 .Vb 3
 174 \&    ### Set the current position (either of two ways):
 175 \&    $AH\->setpos($pos);
 176 \&    $AH\->seek($offset, 0);
 177 .Ve
 178 .PP
 179 .Vb 4
 180 \&    ### Open an anonymous temporary array:
 181 \&    $AH = new IO::ScalarArray;
 182 \&    $AH\->print("Hi there!");
 183 \&    print "I printed: ", @{$AH\->aref}, "\en";      ### get at value
 184 .Ve
 185 .PP
 186 Don't like \s-1OO\s0 for your I/O?  No problem.
 187 Thanks to the magic of an invisible \fItie()\fR, the following now
 188 works out of the box, just as it does with IO::Handle:
 189 .PP
 190 .Vb 2
 191 \&    use IO::ScalarArray;
 192 \&    @data = ("My mes", "sage:\en");
 193 .Ve
 194 .PP
 195 .Vb 5
 196 \&    ### Open a handle on an array, and append to it:
 197 \&    $AH = new IO::ScalarArray \e@data;
 198 \&    print $AH "Hello";
 199 \&    print $AH ", world!\enBye now!\en";
 200 \&    print "The array is now: ", @data, "\en";
 201 .Ve
 202 .PP
 203 .Vb 6
 204 \&    ### Open a handle on a string, read it line\-by\-line, then close it:
 205 \&    $AH = new IO::ScalarArray \e@data;
 206 \&    while (<$AH>) {
 207 \&        print "Got line: $_";
 208 \&    }
 209 \&    close $AH;
 210 .Ve
 211 .PP
 212 .Vb 3
 213 \&    ### Open a handle on a string, and slurp in all the lines:
 214 \&    $AH = new IO::ScalarArray \e@data;
 215 \&    print "All lines:\en", <$AH>;
 216 .Ve
 217 .PP
 218 .Vb 2
 219 \&    ### Get the current position (WARNING: requires 5.6):
 220 \&    $offset = tell $AH;
 221 .Ve
 222 .PP
 223 .Vb 2
 224 \&    ### Set the current position (WARNING: requires 5.6):
 225 \&    seek $AH, $offset, 0;
 226 .Ve
 227 .PP
 228 .Vb 4
 229 \&    ### Open an anonymous temporary scalar:
 230 \&    $AH = new IO::ScalarArray;
 231 \&    print $AH "Hi there!";
 232 \&    print "I printed: ", @{$AH\->aref}, "\en";      ### get at value
 233 .Ve
 234 .PP
 235 And for you folks with 1.x code out there: the old \fItie()\fR style still works,
 236 though this is \fIunnecessary and deprecated\fR:
 237 .PP
 238 .Vb 1
 239 \&    use IO::ScalarArray;
 240 .Ve
 241 .PP
 242 .Vb 5
 243 \&    ### Writing to a scalar...
 244 \&    my @a;
 245 \&    tie *OUT, 'IO::ScalarArray', \e@a;
 246 \&    print OUT "line 1\enline 2\en", "line 3\en";
 247 \&    print "Array is now: ", @a, "\en"
 248 .Ve
 249 .PP
 250 .Vb 7
 251 \&    ### Reading and writing an anonymous scalar...
 252 \&    tie *OUT, 'IO::ScalarArray';
 253 \&    print OUT "line 1\enline 2\en", "line 3\en";
 254 \&    tied(OUT)\->seek(0,0);
 255 \&    while (<OUT>) {
 256 \&        print "Got line: ", $_;
 257 \&    }
 258 .Ve
 259 .SH "DESCRIPTION"
 260 .IX Header "DESCRIPTION"
 261 This class is part of the IO::Stringy distribution;
 262 see IO::Stringy for change log and general information.
 263 .PP
 264 The IO::ScalarArray class implements objects which behave just like
 265 IO::Handle (or FileHandle) objects, except that you may use them
 266 to write to (or read from) arrays of scalars.  Logically, an
 267 array of scalars defines an in-core \*(L"file\*(R" whose contents are
 268 the concatenation of the scalars in the array.  The handles created by
 269 this class are automatically tiehandle'd (though please see \*(L"\s-1WARNINGS\s0\*(R"
 270 for information relevant to your Perl version).
 271 .PP
 272 For writing large amounts of data with individual \fIprint()\fR statements,
 273 this class is likely to be more efficient than IO::Scalar.
 274 .PP
 275 Basically, this:
 276 .PP
 277 .Vb 4
 278 \&    my @a;
 279 \&    $AH = new IO::ScalarArray \e@a;
 280 \&    $AH\->print("Hel", "lo, ");         ### OO style
 281 \&    $AH\->print("world!\en");            ### ditto
 282 .Ve
 283 .PP
 284 Or this:
 285 .PP
 286 .Vb 4
 287 \&    my @a;
 288 \&    $AH = new IO::ScalarArray \e@a;
 289 \&    print $AH "Hel", "lo, ";           ### non\-OO style
 290 \&    print $AH "world!\en";              ### ditto
 291 .Ve
 292 .PP
 293 Causes \f(CW@a\fR to be set to the following array of 3 strings:
 294 .PP
 295 .Vb 3
 296 \&    ( "Hel" ,
 297 \&      "lo, " ,
 298 \&      "world!\en" )
 299 .Ve
 300 .PP
 301 See IO::Scalar and compare with this class.
 302 .SH "PUBLIC INTERFACE"
 303 .IX Header "PUBLIC INTERFACE"
 304 .Sh "Construction"
 305 .IX Subsection "Construction"
 306 .IP "new [\s-1ARGS\s0...]" 4
 307 .IX Item "new [ARGS...]"
 308 \&\fIClass method.\fR
 309 Return a new, unattached array handle.
 310 If any arguments are given, they're sent to \fIopen()\fR.
 311 .IP "open [\s-1ARRAYREF\s0]" 4
 312 .IX Item "open [ARRAYREF]"
 313 \&\fIInstance method.\fR
 314 Open the array handle on a new array, pointed to by \s-1ARRAYREF\s0.
 315 If no \s-1ARRAYREF\s0 is given, a \*(L"private\*(R" array is created to hold
 316 the file data.
 317 .Sp
 318 Returns the self object on success, undefined on error.
 319 .IP "opened" 4
 320 .IX Item "opened"
 321 \&\fIInstance method.\fR
 322 Is the array handle opened on something?
 323 .IP "close" 4
 324 .IX Item "close"
 325 \&\fIInstance method.\fR
 326 Disassociate the array handle from its underlying array.
 327 Done automatically on destroy.
 328 .Sh "Input and output"
 329 .IX Subsection "Input and output"
 330 .IP "flush" 4
 331 .IX Item "flush"
 332 \&\fIInstance method.\fR
 333 No\-op, provided for \s-1OO\s0 compatibility.
 334 .IP "getc" 4
 335 .IX Item "getc"
 336 \&\fIInstance method.\fR
 337 Return the next character, or undef if none remain.
 338 This does a \fIread\fR\|(1), which is somewhat costly.
 339 .IP "getline" 4
 340 .IX Item "getline"
 341 \&\fIInstance method.\fR
 342 Return the next line, or undef on end of data.
 343 Can safely be called in an array context.
 344 Currently, lines are delimited by \*(L"\en\*(R".
 345 .IP "getlines" 4
 346 .IX Item "getlines"
 347 \&\fIInstance method.\fR
 348 Get all remaining lines.
 349 It will \fIcroak()\fR if accidentally called in a scalar context.
 350 .IP "print \s-1ARGS\s0..." 4
 351 .IX Item "print ARGS..."
 352 \&\fIInstance method.\fR
 353 Print \s-1ARGS\s0 to the underlying array.
 354 .Sp
 355 Currently, this always causes a \*(L"seek to the end of the array\*(R"
 356 and generates a new array entry.  This may change in the future.
 357 .IP "read \s-1BUF\s0, \s-1NBYTES\s0, [\s-1OFFSET\s0];" 4
 358 .IX Item "read BUF, NBYTES, [OFFSET];"
 359 \&\fIInstance method.\fR
 360 Read some bytes from the array.
 361 Returns the number of bytes actually read, 0 on end\-of\-file, undef on error.
 362 .IP "write \s-1BUF\s0, \s-1NBYTES\s0, [\s-1OFFSET\s0];" 4
 363 .IX Item "write BUF, NBYTES, [OFFSET];"
 364 \&\fIInstance method.\fR
 365 Write some bytes into the array.
 366 .Sh "Seeking/telling and other attributes"
 367 .IX Subsection "Seeking/telling and other attributes"
 368 .IP "autoflush" 4
 369 .IX Item "autoflush"
 370 \&\fIInstance method.\fR
 371 No\-op, provided for \s-1OO\s0 compatibility.
 372 .IP "binmode" 4
 373 .IX Item "binmode"
 374 \&\fIInstance method.\fR
 375 No\-op, provided for \s-1OO\s0 compatibility.
 376 .IP "clearerr" 4
 377 .IX Item "clearerr"
 378 \&\fIInstance method.\fR  Clear the error and \s-1EOF\s0 flags.  A no\-op.
 379 .IP "eof" 4
 380 .IX Item "eof"
 381 \&\fIInstance method.\fR  Are we at end of file?
 382 .IP "seek \s-1POS\s0,WHENCE" 4
 383 .IX Item "seek POS,WHENCE"
 384 \&\fIInstance method.\fR
 385 Seek to a given position in the stream.
 386 Only a \s-1WHENCE\s0 of 0 (\s-1SEEK_SET\s0) is supported.
 387 .IP "tell" 4
 388 .IX Item "tell"
 389 \&\fIInstance method.\fR
 390 Return the current position in the stream, as a numeric offset.
 391 .IP "setpos \s-1POS\s0" 4
 392 .IX Item "setpos POS"
 393 \&\fIInstance method.\fR
 394 Seek to a given position in the array, using the opaque \fIgetpos()\fR value.
 395 Don't expect this to be a number.
 396 .IP "getpos" 4
 397 .IX Item "getpos"
 398 \&\fIInstance method.\fR
 399 Return the current position in the array, as an opaque value.
 400 Don't expect this to be a number.
 401 .IP "aref" 4
 402 .IX Item "aref"
 403 \&\fIInstance method.\fR
 404 Return a reference to the underlying array.
 405 .SH "WARNINGS"
 406 .IX Header "WARNINGS"
 407 Perl's \s-1TIEHANDLE\s0 spec was incomplete prior to 5.005_57;
 408 it was missing support for \f(CW\*(C`seek()\*(C'\fR, \f(CW\*(C`tell()\*(C'\fR, and \f(CW\*(C`eof()\*(C'\fR.
 409 Attempting to use these functions with an IO::ScalarArray will not work
 410 prior to 5.005_57. IO::ScalarArray will not have the relevant methods
 411 invoked; and even worse, this kind of bug can lie dormant for a while.
 412 If you turn warnings on (via \f(CW$^W\fR or \f(CW\*(C`perl \-w\*(C'\fR),
 413 and you see something like this...
 414 .PP
 415 .Vb 1
 416 \&    attempt to seek on unopened filehandle
 417 .Ve
 418 .PP
 419 \&...then you are probably trying to use one of these functions
 420 on an IO::ScalarArray with an old Perl.  The remedy is to simply
 421 use the \s-1OO\s0 version; e.g.:
 422 .PP
 423 .Vb 2
 424 \&    $AH\->seek(0,0);    ### GOOD: will work on any 5.005
 425 \&    seek($AH,0,0);     ### WARNING: will only work on 5.005_57 and beyond
 426 .Ve
 427 .SH "VERSION"
 428 .IX Header "VERSION"
 429 $Id: ScalarArray.pm,v 1.7 2005/02/10 21:21:53 dfs Exp $
 430 .SH "AUTHOR"
 431 .IX Header "AUTHOR"
 432 .Sh "Primary Maintainer"
 433 .IX Subsection "Primary Maintainer"
 434 David F. Skoll (\fIdfs@roaringpenguin.com\fR).
 435 .Sh "Principal author"
 436 .IX Subsection "Principal author"
 437 Eryq (\fIeryq@zeegee.com\fR).
 438 President, ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
 439 .Sh "Other contributors"
 440 .IX Subsection "Other contributors"
 441 Thanks to the following individuals for their invaluable contributions
 442 (if I've forgotten or misspelled your name, please email me!):
 443 .PP
 444 \&\fIAndy Glew,\fR
 445 for suggesting \f(CW\*(C`getc()\*(C'\fR.
 446 .PP
 447 \&\fIBrandon Browning,\fR
 448 for suggesting \f(CW\*(C`opened()\*(C'\fR.
 449 .PP
 450 \&\fIEric L. Brine,\fR
 451 for his offset-using \fIread()\fR and \fIwrite()\fR implementations.
 452 .PP
 453 \&\fIDoug Wilson,\fR
 454 for the IO::Handle inheritance and automatic tie\-ing.