From @epa

Created by @epa

The pod documentation for Tie​::Handle lists the methods to be
implemented but it doesn't say what the return value should be from
each method, nor what they should do in case of error (die, or return
undef, or whatever).

Also it mentions that Tie​::Handle provides a default new() but doesn't
say what kind of object is generated (for example, an anonymous hash).
If writing a subclass you need to know that.

It would help to have a small working example in the SYNOPSIS, such as
a tied filehandle with does ROT13 on input and output. That would
serve to document the return values and error cases. If it turns out
that most of the methods are implemented as thin wrappers around the
corresponding Perl builtins, that's still useful documentation.

This perlbug was built using Perl 5.00503 - Thu Aug 10 15:31:56 EDT 2000
It is being executed now by  Perl 5.008 - Sat Apr 12 10:55:50 BST 2003.

Site configuration information for perl 5.008:

Configured by tomc at Sat Apr 12 10:55:50 BST 2003.

Summary of my perl5 (revision 5.0 version 8 subversion 0) configuration:
  Platform:
    osname=linux, osvers=2.2.19-6.2.12.1rs, archname=i686-linux
    uname='linux budvar.future-i.net 2.2.19-6.2.12.1rs #1 sat nov 3 02:42:38 cst 2001 i686 unknown '
    config_args=''
    hint=recommended, useposix=true, d_sigaction=define
    usethreads=undef use5005threads=undef useithreads=undef usemultiplicity=undef
    useperlio=define d_sfio=undef uselargefiles=define usesocks=undef
    use64bitint=undef use64bitall=undef uselongdouble=undef
    usemymalloc=n, bincompat5005=undef
  Compiler:
    cc='cc', ccflags ='-fno-strict-aliasing -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -I/usr/include/gdbm',
    optimize='-O2',
    cppflags='-fno-strict-aliasing -I/usr/local/include -I/usr/include/gdbm'
    ccversion='', gccversion='egcs-2.91.66 19990314/Linux (egcs-1.1.2 release)', gccosandvers=''
    intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=1234
    d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=12
    ivtype='long', ivsize=4, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8
    alignbytes=4, prototype=define
  Linker and Libraries:
    ld='cc', ldflags =' -L/usr/local/lib'
    libpth=/usr/local/lib /lib /usr/lib
    libs=-lbind -lnsl -lgdbm -ldl -lm -lc -lcrypt -lutil
    perllibs=-lbind -lnsl -ldl -lm -lc -lcrypt -lutil
    libc=/lib/libc-2.2.4.so, so=so, useshrplib=false, libperl=libperl.a
    gnulibc_version='2.2.4'
  Dynamic Linking:
    dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-rdynamic'
    cccdlflags='-fpic', lddlflags='-shared -L/usr/local/lib'

Locally applied patches:
    


@INC for perl 5.008:
    /home/ed/lib/perl5/5.8.0/i686-linux
    /home/ed/lib/perl5/5.8.0
    /home/ed/lib/perl5/site_perl/5.8.0/i686-linux
    /home/ed/lib/perl5/site_perl/5.8.0
    /home/ed/lib/perl5/site_perl/5.8.0/i686-linux
    /home/ed/lib/perl5/site_perl/5.8.0/i386-linux
    /home/ed/lib/perl5/site_perl/5.8.0/i686-linux
    /home/ed/lib/perl5/site_perl/5.8.0
    /home/ed/lib/perl5/site_perl
    /usr/lib/perl5/5.8.0/i686-linux
    /usr/lib/perl5/5.8.0
    /usr/lib/perl5/site_perl/5.8.0/i686-linux
    /usr/lib/perl5/site_perl/5.8.0
    /usr/lib/perl5/site_perl/5.6.1
    /usr/lib/perl5/site_perl/5.005
    /usr/lib/perl5/site_perl
    .


Environment for perl 5.008:
    HOME=/home/ed
    LANG=en_US
    LANGUAGE (unset)
    LD_LIBRARY_PATH=/home/ed/lib:/home/ed/wine/inst/lib:/usr/local/lib
    LOGDIR (unset)
    PATH=/home/ed/bin:/home/ed/bin/i686-pc-linux-gnu:/home/ed/wine/inst/bin:/home/ed/lib/ant/bin:/bin:/usr/bin:/usr/local/maple/bin:/usr/local/bin:/usr/X11R6/bin:/usr/local/java/bin:/var/qmail/bin:/usr/local/pgsql-7.1.3/bin:/usr/local/ezmlm/bin:/opt/kde/bin:/usr/local/X11/bin:/usr/krb5/bin:/usr/athena/bin:/sbin:/usr/sbin:/opt/IBMJava2-13/bin:/usr/local/jdk1.2.2/bin:/usr/share/smlnj/bin:/usr/games:/usr/kerberos/bin:/usr/kerberos/sbin:/usr/libexec/openssh
    PERL5LIB=/home/ed/lib/perl5/5.8.0:/home/ed/lib/perl5/site_perl/5.8.0:/home/ed/lib/perl5/site_perl/5.8.0/i686-linux:/home/ed/lib/perl5/site_perl/5.8.0/i386-linux:/home/ed/lib/perl5/site_perl
    PERL_BADLANG (unset)
    SHELL=/bin/bash

From @jkeenan

On Sun Jul 13 22​:36​:28 2003, ed wrote​:

The pod documentation for Tie​::Handle lists the methods to be
implemented but it doesn't say what the return value should be from
each method, nor what they should do in case of error (die, or return
undef, or whatever).

Also it mentions that Tie​::Handle provides a default new() but doesn't
say what kind of object is generated (for example, an anonymous hash).
If writing a subclass you need to know that.

It would help to have a small working example in the SYNOPSIS, such as
a tied filehandle with does ROT13 on input and output. That would
serve to document the return values and error cases. If it turns out
that most of the methods are implemented as thin wrappers around the
corresponding Perl builtins, that's still useful documentation.

The documentation currently (5.14.2) shown with 'perldoc Tie​::Handle'
points in two locations to 'perldoc perltie'. The latter has a large
section on "Tying Handles."

Would the "Tying Handles" discussion address the original poster's concerns?

Thank you very much.
Jim Keenan

The RT System itself - Status changed from 'new' to 'open'

From @xdg

On Thu, Dec 1, 2011 at 10​:29 PM, James E Keenan via RT
<perlbug-followup@​perl.org> wrote​:

On Sun Jul 13 22​:36​:28 2003, ed wrote​:

The documentation currently (5.14.2) shown with 'perldoc Tie​::Handle'
points in two locations to 'perldoc perltie'.  The latter has a large
section on "Tying Handles."

Would the "Tying Handles" discussion address the original poster's concerns?

Not really. In general, I think that anyone subclassing it really
needs to read five things​:

  * perltie
  * docs of Tie​::Handle
  * code of Tie​::Handle
  * docs of Tie​::StdHandle
  * code of Tie​::StdHandle

Tie​::StdHandle is an example of a fully-functioning Tie​::Handle
subclass that is a thin wrapper around a regular handle and is
effectively the "synopsis" for tying filehandles.

See below for specific responses.

The pod documentation for Tie​::Handle lists the methods to be
implemented but it doesn't say what the return value should be from
each method, nor what they should do in case of error (die, or return
undef, or whatever).

The documentation should clarify that the return values should
correspond to the corresponding built in functions. This is implied,
but never exactly stated, even in perltie.

Also it mentions that Tie​::Handle provides a default new() but doesn't
say what kind of object is generated (for example, an anonymous hash).
If writing a subclass you need to know that.

The new() method just wraps TIEHANDLE. On quick glance, I'm not sure
that Tie​::Handle should even provide new() and there seems to be some
odd circularity of TIEHANDLE calling new() as well. Tie​::Array
doesn't provide new(). Tie​::Hash and Tie​::Array scalar do and make
noises about "grandfathering" the new. So it may be an original
design bug that we can't shake now.

It would help to have a small working example in the SYNOPSIS, such as
a tied filehandle with does ROT13 on input and output. That would
serve to document the return values and error cases. If it turns out
that most of the methods are implemented as thin wrappers around the
corresponding Perl builtins, that's still useful documentation.

The Tie​::Handle documentation should point people to the code of
Tie​::StdHandle as the fully working example.

-- David