~ubuntu-branches/ubuntu/intrepid/perl-doc-html/intrepid

<div id="breadCrumbs"><a href="index.html">Home</a> > <a href="index-modules-A.html">Core modules</a> > <a href="index-modules-U.html">U</a> > UNIVERSAL</div>

<div id="contentBody"><div class="title_container"><div class="page_title">UNIVERSAL</div></div><ul><li><a href="#NAME">NAME</a><li><a href="#SYNOPSIS">SYNOPSIS</a><li><a href="#DESCRIPTION">DESCRIPTION</a><li><a href="#EXPORTS">EXPORTS</a></ul><a name="NAME"></a><h1>NAME</h1>

UNIVERSAL - base class for ALL classes (blessed references)

<a name="SYNOPSIS"></a><h1>SYNOPSIS</h1>

<pre class="verbatim"> $is_io = $fd->isa("IO::Handle");

$is_io = Class->isa("IO::Handle");</pre>

<pre class="verbatim"> $sub = $obj->can("print");

$sub = Class->can("print");</pre>

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="UNIVERSAL.html">UNIVERSAL</a> qw( isa can VERSION );

$yes = isa $ref, "HASH" ;

$sub = can $ref, "fandango" ;

$ver = VERSION $obj ;</pre>

$is_io = Class->isa("IO::Handle");</pre>

<pre class="verbatim"> $does_log = $obj->DOES("Logger");

$does_log = Class->DOES("Logger");</pre>

$sub = Class->can("print");</pre>

<pre class="verbatim"> $sub = <a class="l_k" href="functions/eval.html">eval</a> { $ref->can("fandango") };

$ver = $obj->VERSION;</pre>

<pre class="verbatim"> # but never do this!

$is_io = UNIVERSAL::isa($fd, "IO::Handle");

100

$sub = UNIVERSAL::can($obj, "print");</pre>

101

<a name="DESCRIPTION"></a><h1>DESCRIPTION</h1>

<code class="inline"><a class="l_w" href="UNIVERSAL.html">UNIVERSAL</a></code> is the base class which all bless references will inherit from,

see <a href="perlobj.html">perlobj</a>.

<code class="inline"><a class="l_w" href="UNIVERSAL.html">UNIVERSAL</a></code> provides the following methods and functions:

102

<code class="inline">UNIVERSAL</code>

103

is the base class from which all blessed references inherit.

104

See <a href="perlobj.html">perlobj</a>.

105

<code class="inline">UNIVERSAL</code>

106

provides the following methods:

107

<ul>

100

101

102

</li>

103

<li><a name="'CLASS-%3eisa(-TYPE-)'"></a><code class="inline">CLASS->isa( TYPE )</code>

104

105

</li>

106

108

109

110

</li>

111

<li><a name="'CLASS-%3eisa(-TYPE-)'"></a><code class="inline">CLASS->isa( TYPE )</code>

112

113

</li>

114

107

115

108

116

Where

109

117

<ul>

110

118

111

119

112

120

is a package name

113

121

</li>

115

123

116

124

is a blessed reference or a string containing a package name

117

125

</li>

118

<li><a name="'CLASS'"></a><code class="inline">CLASS</code>

126

<li><a name="'CLASS'"></a><code class="inline">CLASS</code>

119

127

120

128

is a package name

121

129

</li>

122

130

123

131

124

132

is any of the above or an unblessed reference

125

133

</li>

126

134

</ul>

127

When used as an instance or class method (<code class="inline">$obj->isa( TYPE )</code>

135

When used as an instance or class method (<code class="inline">$obj->isa( TYPE )</code>

128

136

129

130

returns true if $obj is blessed into package <code class="inline">TYPE</code>

137

138

returns true if $obj is blessed into package <code class="inline">TYPE</code>

131

139

132

inherits from package <code class="inline">TYPE</code>

140

inherits from package <code class="inline">TYPE</code>

133

141

.

134

When used as a class method (<code class="inline">CLASS->isa( TYPE )</code>

135

: sometimes

136

referred to as a static method), <code class="inline">isa</code>

137

returns true if <code class="inline">CLASS</code>

142

When used as a class method (<code class="inline">CLASS->isa( TYPE )</code>

143

, sometimes

144

referred to as a static method), <code class="inline">isa</code>

145

returns true if <code class="inline">CLASS</code>

138

146

139

inherits from (or is itself) the name of the package <code class="inline">TYPE</code>

147

inherits from (or is itself) the name of the package <code class="inline">TYPE</code>

140

148

141

inherits from package <code class="inline">TYPE</code>

149

inherits from package <code class="inline">TYPE</code>

142

150

.

143

When used as a function, like

144

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="UNIVERSAL.html">UNIVERSAL</a> qw( isa ) ;

145

$yes = isa $h, "HASH";

146

$yes = isa "Foo", "Bar";</pre>

147

or

148

<pre class="verbatim"> <a class="l_k" href="functions/require.html">require</a> <a class="l_w" href="UNIVERSAL.html">UNIVERSAL</a> ;

149

$yes = UNIVERSAL::isa $a, "ARRAY";</pre>

150

151

returns true in the same cases as above and also if <code class="inline">VAL</code>

152

is an

153

unblessed reference to a perl variable of type <code class="inline">TYPE</code>

154

, such as "HASH",

155

"ARRAY", or "Regexp".

156

</li>

157

<li><a name="'%24obj-%3ecan(-METHOD-)'"></a><code class="inline">$obj->can( METHOD )</code>

158

159

</li>

160

<li><a name="'CLASS-%3ecan(-METHOD-)'"></a><code class="inline">CLASS->can( METHOD )</code>

161

162

</li>

163

<li><a name="'can(-VAL%2c-METHOD-)'"></a><code class="inline">can( VAL, METHOD )</code>

164

165

166

checks if the object or class has a method called <code class="inline">METHOD</code>

167

. If it does

168

then a reference to the sub is returned. If it does not then undef is

169

returned. This includes methods inherited or imported by <code class="inline">$obj</code>

170

, <code class="inline">CLASS</code>

151

If you're not sure what you have (the <code class="inline">VAL</code>

152

case), wrap the method call in an

153

<code class="inline"><a class="l_k" href="functions/eval.html">eval</a></code> block to catch the exception if <code class="inline">VAL</code>

154

is undefined.

155

If you want to be sure that you're calling <code class="inline">isa</code>

156

as a method, not a class,

157

check the invocant with <code class="inline">blessed</code>

158

from <a href="Scalar/Util.html">Scalar::Util</a> first:

159

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> Scalar::Util 'blessed';</pre>

160

<pre class="verbatim"> if ( blessed( $obj ) && $obj->isa("Some::Class") {

161

...

162

}</pre></li>

163

164

165

</li>

166

<li><a name="'CLASS-%3eDOES(-ROLE-)'"></a><code class="inline">CLASS->DOES( ROLE )</code>

167

168

169

checks if the object or class performs the role <code class="inline">ROLE</code>

170

. A role is a

171

named group of specific behavior (often methods of particular names and

172

signatures), similar to a class, but not necessarily a complete class by

173

itself. For example, logging or serialization may be roles.

174

175

and <code class="inline">isa</code>

176

are similar, in that if either is true, you know that the

177

object or class on which you call the method can perform specific behavior.

178

However, <code class="inline">DOES</code>

179

is different from <code class="inline">isa</code>

180

in that it does not care how the

181

invocant performs the operations, merely that it does. (<code class="inline">isa</code>

182

of course

183

mandates an inheritance relationship. Other relationships include aggregation,

184

delegation, and mocking.)

185

By default, classes in Perl only perform the <code class="inline">UNIVERSAL</code>

186

role. To mark that

187

your own classes perform other roles, override <code class="inline">DOES</code>

188

appropriately.

189

There is a relationship between roles and classes, as each class implies the

190

existence of a role of the same name. There is also a relationship between

191

inheritance and roles, in that a subclass that inherits from an ancestor class

192

implicitly performs any roles its parent performs. Thus you can use <code class="inline">DOES</code>

193

194

place of <code class="inline">isa</code>

195

safely, as it will return true in all places where <code class="inline">isa</code>

196

will

197

return true (provided that any overridden <code class="inline">DOES</code>

198

and <code class="inline">isa</code>

199

methods behave

200

appropriately).

201

</li>

202

<li><a name="'%24obj-%3ecan(-METHOD-)'"></a><code class="inline">$obj->can( METHOD )</code>

203

204

</li>

205

<li><a name="'CLASS-%3ecan(-METHOD-)'"></a><code class="inline">CLASS->can( METHOD )</code>

206

207

</li>

208

<li><a name="'eval-%7b-VAL-%3ecan(-METHOD-)-%7d'"></a><code class="inline"><a class="l_k" href="functions/eval.html">eval</a> { VAL->can( METHOD ) }</code>

209

210

211

checks if the object or class has a method called <code class="inline">METHOD</code>

212

. If it does,

213

then it returns a reference to the sub. If it does not, then it returns

214

undef. This includes methods inherited or imported by <code class="inline">$obj</code>

215

, <code class="inline">CLASS</code>

171

216

, or

172

217

173

218

.

174

175

cannot know whether an object will be able to provide a method

176

through AUTOLOAD, so a return value of undef does not necessarily mean

177

the object will not be able to handle the method call. To get around

178

this some module authors use a forward declaration (see <a href="perlsub.html">perlsub</a>)

179

for methods they will handle via AUTOLOAD. For such 'dummy' subs, <code class="inline">can</code>

180

181

will still return a code reference, which, when called, will fall through

182

to the AUTOLOAD. If no suitable AUTOLOAD is provided, calling the coderef

183

will cause an error.

184

185

can be called as a class (static) method, an object method, or a

186

function.

187

When used as a function, if <code class="inline">VAL</code>

188

is a blessed reference or package name which

189

has a method called <code class="inline">METHOD</code>

190

, <code class="inline">can</code>

191

returns a reference to the subroutine.

192

If <code class="inline">VAL</code>

193

is not a blessed reference, or if it does not have a method

194

<code class="inline">METHOD</code>

195

, undef is returned.

219

220

cannot know whether an object will be able to provide a method through

221

AUTOLOAD (unless the object's class has overriden <code class="inline">can</code>

222

appropriately), so a

223

return value of undef does not necessarily mean the object will not be able

224

to handle the method call. To get around this some module authors use a forward

225

declaration (see <a href="perlsub.html">perlsub</a>) for methods they will handle via AUTOLOAD. For

226

such 'dummy' subs, <code class="inline">can</code>

227

will still return a code reference, which, when

228

called, will fall through to the AUTOLOAD. If no suitable AUTOLOAD is provided,

229

calling the coderef will cause an error.

230

You may call <code class="inline">can</code>

231

as a class (static) method or an object method.

232

Again, the same rule about having a valid invocant applies -- use an <code class="inline"><a class="l_k" href="functions/eval.html">eval</a></code>

233

block or <code class="inline">blessed</code>

234

if you need to be extra paranoid.

196

235

</li>

197

<li><a name="'VERSION-(-%5b-REQUIRE-%5d-)'"></a><code class="inline">VERSION ( [ REQUIRE ] )</code>

236

<li><a name="'VERSION-(-%5b-REQUIRE-%5d-)'"></a><code class="inline">VERSION ( [ REQUIRE ] )</code>

198

237

199

<code class="inline">VERSION</code>

238

<code class="inline">VERSION</code>

200

239

will return the value of the variable <code class="inline">$VERSION</code>

201

240

in the

202

package the object is blessed into. If <code class="inline">REQUIRE</code>

241

package the object is blessed into. If <code class="inline">REQUIRE</code>

203

242

is given then

204

243

it will do a comparison and die if the package version is not

205

greater than or equal to <code class="inline">REQUIRE</code>

244

greater than or equal to <code class="inline">REQUIRE</code>

206

245

.

207

<code class="inline">VERSION</code>

208

can be called as either a class (static) method, an object

209

method or a function.

246

<code class="inline">VERSION</code>

247

can be called as either a class (static) method or an object

248

method.

210

249

</li>

211

250

</ul>

212

251

<a name="EXPORTS"></a><h1>EXPORTS</h1>

213

252

None by default.

214

You may request the import of all three functions (<code class="inline">isa</code>

215

, <code class="inline">can</code>

216

, and

217

<code class="inline">VERSION</code>

218

), however it isn't usually necessary to do so. Perl magically

219

makes these functions act as methods on all objects. The one exception is

220

221

, which is useful as a function when operating on non-blessed

222

references.

253

You may request the import of three functions (<code class="inline">isa</code>

254

, <code class="inline">can</code>

255

, and <code class="inline">VERSION</code>

256

257

however it is usually harmful to do so. Please don't do this in new code.

258

For example, previous versions of this documentation suggested using <code class="inline">isa</code>

259

260

a function to determine the type of a reference:

261

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> UNIVERSAL 'isa';</pre>

262

<pre class="verbatim"> $yes = isa $h, "HASH";

263

$yes = isa "Foo", "Bar";</pre>

264

The problem is that this code will never call an overridden <code class="inline">isa</code>

265

method in

266

any class. Instead, use <code class="inline">reftype</code>

267

from <a href="Scalar/Util.html">Scalar::Util</a> for the first case:

268

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> Scalar::Util 'reftype';</pre>

269

<pre class="verbatim"> $yes = reftype( $h ) eq "HASH";</pre>

270

and the method form of <code class="inline">isa</code>

271

for the second:

272

223

273

</div>

224

274

225

275

</div>

237

287

238

288

</form>

239

289

290

240

291

<h2>Labels:</h2>

241

292

242

293

Older »