This method will be triggered every time the tied variable is set
(assigned). Beyond its self reference, it also expects one (and only one)
-argument--the new value the user is trying to assign. Don't worry about
-returning a value from STORE -- the semantic of assignment returning the
+argument: the new value the user is trying to assign. Don't worry about
+returning a value from STORE; the semantic of assignment returning the
assigned value is implemented with FETCH.
sub STORE {
X<array, tying>
A class implementing a tied ordinary array should define the following
-methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps UNTIE and/or DESTROY.
+methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE, CLEAR
+and perhaps UNTIE and/or DESTROY.
FETCHSIZE and STORESIZE are used to provide C<$#array> and
equivalent C<scalar(@array)> access.
croak "@{[&whowasi]}: $file not clobberable"
unless $self->{CLOBBER};
- open(F, "> $file") || croak "can't open $file: $!";
- print F $value;
- close(F);
+ open(my $f, '>', $file) || croak "can't open $file: $!";
+ print $f $value;
+ close($f);
}
If they wanted to clobber something, they might say:
program, where output to STDOUT and STDERR may have to be redirected
in some special way. See nvi and the Apache module for examples.
+When tying a handle, the first argument to C<tie> should begin with an
+asterisk. So, if you are tying STDOUT, use C<*STDOUT>. If you have
+assigned it to a scalar variable, say C<$handle>, use C<*$handle>.
+C<tie $handle> ties the scalar variable C<$handle>, not the handle inside
+it.
+
In our example we're going to create a shouting handle.
package Shout;
X<PRINT>
This method will be triggered every time the tied handle is printed to
-with the C<print()> function.
-Beyond its self reference it also expects the list that was passed to
-the print function.
+with the C<print()> or C<say()> functions. Beyond its self reference
+it also expects the list that was passed to the print function.
sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ }
+C<say()> acts just like C<print()> except $\ will be localized to C<\n> so
+you need do nothing special to handle C<say()> in C<PRINT()>.
+
=item PRINTF this, LIST
X<PRINTF>
=item READLINE this
X<READLINE>
-This method will be called when the handle is read from via <HANDLE>.
-The method should return undef when there is no more data.
-
- sub READLINE { $r = shift; "READLINE called $$r times\n"; }
+This method is called when the handle is read via C<E<lt>HANDLEE<gt>>
+or C<readline HANDLE>.
+
+As per L<C<readline>|perlfunc/readline>, in scalar context it should return
+the next line, or C<undef> for no more data. In list context it should
+return all remaining lines, or an empty list for no more data. The strings
+returned should include the input record separator C<$/> (see L<perlvar>),
+unless it is C<undef> (which means "slurp" mode).
+
+ sub READLINE {
+ my $r = shift;
+ if (wantarray) {
+ return ("all remaining\n",
+ "lines up\n",
+ "to eof\n");
+ } else {
+ return "READLINE called " . ++$$r . " times\n";
+ }
+ }
=item GETC this
X<GETC>
sub GETC { print "Don't GETC, Get Perl"; return "a"; }
+=item EOF this
+X<EOF>
+
+This method will be called when the C<eof> function is called.
+
+Starting with Perl 5.12, an additional integer parameter will be passed. It
+will be zero if C<eof> is called without parameter; C<1> if C<eof> is given
+a filehandle as a parameter, e.g. C<eof(FH)>; and C<2> in the very special
+case that the tied filehandle is C<ARGV> and C<eof> is called with an empty
+parameter list, e.g. C<eof()>.
+
+ sub EOF { not length $stringbuf }
+
=item CLOSE this
X<CLOSE>
So far so good. Those of you who have been paying attention will have
spotted that the tied object hasn't been used so far. So lets add an
extra method to the Remember class to allow comments to be included in
-the file -- say, something like this:
+the file; say, something like this:
sub comment {
my $self = shift;
You cannot easily tie a multilevel data structure (such as a hash of
hashes) to a dbm file. The first problem is that all but GDBM and
Berkeley DB have size limitations, but beyond that, you also have problems
-with how references are to be represented on disk. One experimental
+with how references are to be represented on disk. One
module that does attempt to address this need is DBM::Deep. Check your
nearest CPAN site as described in L<perlmodlib> for source code. Note
that despite its name, DBM::Deep does not use dbm. Another earlier attempt