=======================================
                        Module "Tie::Handle" Version 1.0
                    =======================================
                     requires Perl version 5.004 or higher


           Copyright (c) 1997 by Steffen Beyer. All rights reserved.
           This package is free software; you can redistribute and/or
           modify it under the same terms as Perl itself.


What does it do:
----------------

Tie::Handle - tie arbitrary objects to file handles

This module facilitates the tying of file handles with (arbitrary)
objects.

File handles must be given either as symbolic file handles (like "STDOUT")
or as references as returned by the "new()" method of the "IO::Handle"
or "FileHandle" class (either works).

Your class "Your::Class" needs to:

    require Tie::Handle;

and to add "Tie::Handle" to the list of classes to inherit from:

    @ISA = qw(Exporter Tie::Handle);

in order to enable tying of file handles with objects of "Your::Class".

Note that your class "Your::Class" is also responsible for providing
(i.e., overloading) the appropriate methods needed for writing to
and reading from your objects:

    "print()", "read()", "reset()", "getchar()" and "blockread()".

See the module "Data::Locations" for an example of how to implement
most of these.

Remember that you may define the default output file handle using
the Perl function "select()" so that any subsequent "print()" or
"printf()" statement without an explicit file handle will send
output to the chosen default file handle automatically!

See the section on "select()" in the perlfunc(1) manpage for more
details!

To dissociate the connection between a given file handle and object
(which also resets the state information usually associated with that
object which is needed to be able to read from the object line by line),
simply use one of the following statements (depending on wether you are
using symbolic file handles or file handle references):

                untie *FILEHANDLE;
                untie *{FILEHANDLE};
                untie $filehandle;
                untie *{$filehandle};

To reset an object explicitly (in order to restart reading at the
beginning, for instance), you can either call

                ${tied *FILEHANDLE}->reset();
                ${tied *{FILEHANDLE}}->reset();
                ${tied *{$filehandle}}->reset();

or directly

                $object->reset();

Available methods:

     +   $object->tie('FILEHANDLE');

     +   $object->tie($filehandle);

     +   print @items;

     +   print FILEHANDLE @items;

     +   print $filehandle @items;

     +   printf $format, @items;

     +   printf FILEHANDLE $format, @items;

     +   printf $filehandle $format, @items;

     +   $line = <>;

     +   @list = <>;

     +   $line = <FILEHANDLE>;

     +   @list = <FILEHANDLE>;

     +   $line = <$filehandle>;

     +   @list = <$filehandle>;

     +   $key = getc();

     +   $key = getc(FILEHANDLE);

     +   $key = getc($filehandle);

     +   $bytes =
         [sys]read(FILEHANDLE,$buffer,$length[,$offset]);

     +   $bytes =
         [sys]read($filehandle,$buffer,$length[,$offset]);


Installation:
-------------

Simply install this module using the following commands:

                            % perl Makefile.PL
                            % make
                            % make install


Documentation:
--------------

To see the module's documentation, use the command "man Tie::Handle"
thereafter.


Version history:
----------------

This is the initial release.


Author's note:
--------------

I hope you will find this module beneficial!

Share and enjoy!

Yours,
--
    Steffen Beyer <sb@sdm.de> http://www.engelschall.com/u/sb/
     "There is enough for the need of everyone in this world,
      but not for the greed of everyone." - Mahatma Gandhi