8 Tie::Handle, Tie::StdHandle - base class definitions for tied handles
17 sub READ { ... } # Provide a needed method
18 sub TIEHANDLE { ... } # Overrides inherited method
27 This module provides some skeletal methods for handle-tying classes. See
28 L<perltie> for a list of the functions required in tying a handle to a package.
29 The basic B<Tie::Handle> package provides a C<new> method, as well as methods
30 C<TIEHANDLE>, C<PRINT>, C<PRINTF> and C<GETC>.
32 For developers wishing to write their own tied-handle classes, the methods
33 are summarized below. The L<perltie> section not only documents these, but
34 has sample code as well:
38 =item TIEHANDLE classname, LIST
40 The method invoked by the command C<tie *glob, classname>. Associates a new
41 glob instance with the specified class. C<LIST> would represent additional
42 arguments (along the lines of L<AnyDBM_File> and compatriots) needed to
43 complete the association.
45 =item WRITE this, scalar, length, offset
47 Write I<length> bytes of data from I<scalar> starting at I<offset>.
49 =item PRINT this, LIST
51 Print the values in I<LIST>
53 =item PRINTF this, format, LIST
55 Print the values in I<LIST> using I<format>
57 =item READ this, scalar, length, offset
59 Read I<length> bytes of data into I<scalar> starting at I<offset>.
67 Get a single character
73 =item OPEN this, filename
79 Specify content is binary
87 Return position in the file.
89 =item SEEK this, offset, whence
97 Free the storage associated with the tied handle referenced by I<this>.
98 This is rarely needed, as Perl manages its memory quite well. But the
99 option exists, should a class wish to perform specific actions upon the
100 destruction of an instance.
104 =head1 MORE INFORMATION
106 The L<perltie> section contains an example of tying handles.
111 use warnings::register;
118 # "Grandfather" the new, a la Tie::Hash
122 if (defined &{"{$pkg}::new"}) {
123 warnings::warnif("WARNING: calling ${pkg}->new since ${pkg}->TIEHANDLE is missing");
127 croak "$pkg doesn't define a TIEHANDLE method";
133 if($self->can('WRITE') != \&WRITE) {
134 my $buf = join(defined $, ? $, : "",@_);
135 $buf .= $\ if defined $\;
136 $self->WRITE($buf,length($buf),0);
139 croak ref($self)," doesn't define a PRINT method";
146 if($self->can('WRITE') != \&WRITE) {
147 my $buf = sprintf(shift,@_);
148 $self->WRITE($buf,length($buf),0);
151 croak ref($self)," doesn't define a PRINTF method";
157 croak "$pkg doesn't define a READLINE method";
163 if($self->can('READ') != \&READ) {
169 croak ref($self)," doesn't define a GETC method";
175 croak "$pkg doesn't define a READ method";
180 croak "$pkg doesn't define a WRITE method";
185 croak "$pkg doesn't define a CLOSE method";
188 package Tie::StdHandle;
189 our @ISA = 'Tie::Handle';
195 my $fh = do { \local *HANDLE};
197 $fh->OPEN(@_) if (@_);
201 sub EOF { eof($_[0]) }
202 sub TELL { tell($_[0]) }
203 sub FILENO { fileno($_[0]) }
204 sub SEEK { seek($_[0],$_[1],$_[2]) }
205 sub CLOSE { close($_[0]) }
206 sub BINMODE { binmode($_[0]) }
210 $_[0]->CLOSE if defined($_[0]->FILENO);
214 sub READ { read($_[0],$_[1],$_[2]) }
215 sub READLINE { my $fh = $_[0]; <$fh> }
216 sub GETC { getc($_[0]) }
221 print $fh substr($_[1],0,$_[2])