X-Git-Url: http://git.maemo.org/git/?p=dh-make-perl;a=blobdiff_plain;f=dev%2Farm%2Flibio-stringy-perl%2Fio-stringy-2.110%2Fdocs%2FIO%2FWrap.pm.html;fp=dev%2Farm%2Flibio-stringy-perl%2Fio-stringy-2.110%2Fdocs%2FIO%2FWrap.pm.html;h=a547c7ae28306b393d21c928effabe6fe2e4c378;hp=0000000000000000000000000000000000000000;hb=f477fa73365d491991707e7ed9217b48d6994551;hpb=da95c414033799c3a62606f299c3c00b5c77ca11;ds=sidebyside diff --git a/dev/arm/libio-stringy-perl/io-stringy-2.110/docs/IO/Wrap.pm.html b/dev/arm/libio-stringy-perl/io-stringy-2.110/docs/IO/Wrap.pm.html new file mode 100644 index 0000000..a547c7a --- /dev/null +++ b/dev/arm/libio-stringy-perl/io-stringy-2.110/docs/IO/Wrap.pm.html @@ -0,0 +1,178 @@ + +
+IO::Wrap - wrap raw filehandles in IO::Handle interface + + + +
+ use IO::Wrap; + + ### Do stuff with any kind of filehandle (including a bare globref), or + ### any kind of blessed object that responds to a print() message. + ### + sub do_stuff { + my $fh = shift; + + ### At this point, we have no idea what the user gave us... + ### a globref? a FileHandle? a scalar filehandle name? + + $fh = wraphandle($fh); + + ### At this point, we know we have an IO::Handle-like object! + + $fh->print("Hey there!"); + ... + } + ++ + +
Let's say you want to write some code which does I/O, but you don't
+want to force the caller to provide you with a FileHandle or IO::Handle
+object. You want them to be able to say:
+
+
+ do_stuff(\*STDOUT);
+ do_stuff('STDERR');
+ do_stuff($some_FileHandle_object);
+ do_stuff($some_IO_Handle_object);
+
+
+
And even:
+
+
+ do_stuff($any_object_with_a_print_method);
+
+
+
Sure, one way to do it is to force the caller to use tiehandle(). +But that puts the burden on them. Another way to do it is to +use IO::Wrap, which provides you with the following functions: + + + +
A raw scalar filehandle name, like "STDOUT"
or "Class::HANDLE"
.
+In this case, the filehandle name is wrapped in an IO::Wrap object,
+which is returned.
+
+
A raw filehandle glob, like \*STDOUT
.
+In this case, the filehandle glob is wrapped in an IO::Wrap object,
+which is returned.
+
+
A blessed FileHandle object.
+In this case, the FileHandle is wrapped in an IO::Wrap object if and only
+if your FileHandle class does not support the read()
method.
+
+
Any other kind of blessed object, which is assumed to be already +conformant to the IO::Handle interface. +In this case, you just get back that object. + +
If you get back an IO::Wrap object, it will obey a basic subset of
+the IO:: interface. That is, the following methods (note: I said
+methods, not named operators) should work on the thing you get back:
+
+
+ close
+ getline
+ getlines
+ print ARGS...
+ read BUFFER,NBYTES
+ seek POS,WHENCE
+ tell
+
+
+
+
Clearly, when wrapping a raw external filehandle (like \*STDOUT), +I didn't want to close the file descriptor when the "wrapper" object is +destroyed... since the user might not appreciate that! Hence, +there's no DESTROY method in this class. + + +
When wrapping a FileHandle object, however, I believe that Perl will +invoke the FileHandle::DESTROY when the last reference goes away, +so in that case, the filehandle is closed if the wrapped FileHandle +really was the last reference to it. + + + +
This module does not allow you to wrap filehandle names which are given
+as strings that lack the package they were opened in. That is, if a user
+opens FOO in package Foo, they must pass it to you either as \*FOO
+or as "Foo::FOO"
. However, "STDIN"
and friends will work just fine.
+
+
+
+
$Id: Wrap.pm,v 2.102 2001/08/17 02:06:33 eryq Exp $ + + + + +
Eryq (