6 # Tie::StdHandle used to be inside Tie::Handle. For backwards compatibility
7 # loading Tie::Handle has to make Tie::StdHandle available.
12 Tie::Handle - base class definitions for tied handles
19 @ISA = qw(Tie::Handle);
21 sub READ { ... } # Provide a needed method
22 sub TIEHANDLE { ... } # Overrides inherited method
31 This module provides some skeletal methods for handle-tying classes. See
32 L<perltie> for a list of the functions required in tying a handle to a package.
33 The basic B<Tie::Handle> package provides a C<new> method, as well as methods
34 C<TIEHANDLE>, C<PRINT>, C<PRINTF> and C<GETC>.
36 For developers wishing to write their own tied-handle classes, the methods
37 are summarized below. The L<perltie> section not only documents these, but
38 has sample code as well:
42 =item TIEHANDLE classname, LIST
44 The method invoked by the command C<tie *glob, classname>. Associates a new
45 glob instance with the specified class. C<LIST> would represent additional
46 arguments (along the lines of L<AnyDBM_File> and compatriots) needed to
47 complete the association.
49 =item WRITE this, scalar, length, offset
51 Write I<length> bytes of data from I<scalar> starting at I<offset>.
53 =item PRINT this, LIST
55 Print the values in I<LIST>
57 =item PRINTF this, format, LIST
59 Print the values in I<LIST> using I<format>
61 =item READ this, scalar, length, offset
63 Read I<length> bytes of data into I<scalar> starting at I<offset>.
71 Get a single character
77 =item OPEN this, filename
83 Specify content is binary
91 Return position in the file.
93 =item SEEK this, offset, whence
101 Free the storage associated with the tied handle referenced by I<this>.
102 This is rarely needed, as Perl manages its memory quite well. But the
103 option exists, should a class wish to perform specific actions upon the
104 destruction of an instance.
108 =head1 MORE INFORMATION
110 The L<perltie> section contains an example of tying handles.
114 This version of Tie::Handle is neither related to nor compatible with
115 the Tie::Handle (3.0) module available on CPAN. It was due to an
116 accident that two modules with the same name appeared. The namespace
117 clash has been cleared in favor of this module that comes with the
118 perl core in September 2000 and accordingly the version number has
119 been bumped up to 4.0.
124 use warnings::register;
131 # "Grandfather" the new, a la Tie::Hash
135 if (defined &{"{$pkg}::new"}) {
136 warnings::warnif("WARNING: calling ${pkg}->new since ${pkg}->TIEHANDLE is missing");
140 croak "$pkg doesn't define a TIEHANDLE method";
146 if($self->can('WRITE') != \&WRITE) {
147 my $buf = join(defined $, ? $, : "",@_);
148 $buf .= $\ if defined $\;
149 $self->WRITE($buf,length($buf),0);
152 croak ref($self)," doesn't define a PRINT method";
159 if($self->can('WRITE') != \&WRITE) {
160 my $buf = sprintf(shift,@_);
161 $self->WRITE($buf,length($buf),0);
164 croak ref($self)," doesn't define a PRINTF method";
170 croak "$pkg doesn't define a READLINE method";
176 if($self->can('READ') != \&READ) {
182 croak ref($self)," doesn't define a GETC method";
188 croak "$pkg doesn't define a READ method";
193 croak "$pkg doesn't define a WRITE method";
198 croak "$pkg doesn't define a CLOSE method";