Debian Codegraph @

upstream/mageia-cauldron/man3pm/Tie::Handle.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Tie::Handle 3pm"
61 .TH Tie::Handle 3pm 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Tie::Handle \- base class definitions for tied handles
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& package NewHandle;
72 \& require Tie::Handle;
73 \&
74 \& @ISA = qw(Tie::Handle);
75 \&
76 \& sub READ { ... } # Provide a needed method
77 \& sub TIEHANDLE { ... } # Overrides inherited method
78 \&
79 \&
80 \& package main;
81 \&
82 \& tie *FH, \*(AqNewHandle\*(Aq;
83 .Ve
84 .SH DESCRIPTION
85 .IX Header "DESCRIPTION"
86 This module provides some skeletal methods for handle\-tying classes. See
87 perltie for a list of the functions required in tying a handle to a package.
88 The basic \fBTie::Handle\fR package provides a \f(CW\*(C`new\*(C'\fR method, as well as methods
89 \&\f(CW\*(C`TIEHANDLE\*(C'\fR, \f(CW\*(C`PRINT\*(C'\fR, \f(CW\*(C`PRINTF\*(C'\fR and \f(CW\*(C`GETC\*(C'\fR.
90 .PP
91 For developers wishing to write their own tied\-handle classes, the methods
92 are summarized below. The perltie section not only documents these, but
93 has sample code as well:
94 .IP "TIEHANDLE classname, LIST" 4
95 .IX Item "TIEHANDLE classname, LIST"
96 The method invoked by the command \f(CW\*(C`tie *glob, classname\*(C'\fR. Associates a new
97 glob instance with the specified class. \f(CW\*(C`LIST\*(C'\fR would represent additional
98 arguments (along the lines of AnyDBM_File and compatriots) needed to
99 complete the association.
100 .IP "WRITE this, scalar, length, offset" 4
101 .IX Item "WRITE this, scalar, length, offset"
102 Write \fIlength\fR bytes of data from \fIscalar\fR starting at \fIoffset\fR.
103 .IP "PRINT this, LIST" 4
104 .IX Item "PRINT this, LIST"
105 Print the values in \fILIST\fR
106 .IP "PRINTF this, format, LIST" 4
107 .IX Item "PRINTF this, format, LIST"
108 Print the values in \fILIST\fR using \fIformat\fR
109 .IP "READ this, scalar, length, offset" 4
110 .IX Item "READ this, scalar, length, offset"
111 Read \fIlength\fR bytes of data into \fIscalar\fR starting at \fIoffset\fR.
112 .IP "READLINE this" 4
113 .IX Item "READLINE this"
114 Read a single line
115 .IP "GETC this" 4
116 .IX Item "GETC this"
117 Get a single character
118 .IP "CLOSE this" 4
119 .IX Item "CLOSE this"
120 Close the handle
121 .IP "OPEN this, filename" 4
122 .IX Item "OPEN this, filename"
123 (Re\-)open the handle
124 .IP "BINMODE this" 4
125 .IX Item "BINMODE this"
126 Specify content is binary
127 .IP "EOF this" 4
128 .IX Item "EOF this"
129 Test for end of file.
130 .IP "TELL this" 4
131 .IX Item "TELL this"
132 Return position in the file.
133 .IP "SEEK this, offset, whence" 4
134 .IX Item "SEEK this, offset, whence"
135 Position the file.
136 .Sp
137 Test for end of file.
138 .IP "DESTROY this" 4
139 .IX Item "DESTROY this"
140 Free the storage associated with the tied handle referenced by \fIthis\fR.
141 This is rarely needed, as Perl manages its memory quite well. But the
142 option exists, should a class wish to perform specific actions upon the
143 destruction of an instance.
144 .SH "MORE INFORMATION"
145 .IX Header "MORE INFORMATION"
146 The perltie section contains an example of tying handles.
147 .SH COMPATIBILITY
148 .IX Header "COMPATIBILITY"
149 This version of Tie::Handle is neither related to nor compatible with
150 the Tie::Handle (3.0) module available on CPAN. It was due to an
151 accident that two modules with the same name appeared. The namespace
152 clash has been cleared in favor of this module that comes with the
153 perl core in September 2000 and accordingly the version number has
154 been bumped up to 4.0.