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

<div id="contentBody"><div class="title_container"><div class="page_title">perllexwarn</div></div><ul><li><a href="#NAME-warning%2c-lexical-warnings-warning">NAME

<div id="contentBody"><div class="title_container"><div class="page_title">perllexwarn</div></div><ul><li><a href="#NAME">NAME

</a><li><a href="#DESCRIPTION">DESCRIPTION</a><ul><li><a href="#Default-Warnings-and-Optional-Warnings">Default Warnings and Optional Warnings</a><li><a href="#What's-wrong-with-*-w*-and-'%24%5eW'">What's wrong with -w and <code class="inline">$^W</code>

</a><li><a href="#Controlling-Warnings-from-the-Command-Line">Controlling Warnings from the Command Line</a><li><a href="#Backward-Compatibility">Backward Compatibility</a><li><a href="#Category-Hierarchy-warning%2c-categories">Category Hierarchy

</a><li><a href="#Fatal-Warnings-warning%2c-fatal">Fatal Warnings

</a><li><a href="#Reporting-Warnings-from-a-Module-warning%2c-reporting-warning%2c-registering">Reporting Warnings from a Module

</a></ul><li><a href="#TODO">TODO</a><li><a href="#SEE-ALSO">SEE ALSO</a><li><a href="#AUTHOR">AUTHOR</a></ul><a name="NAME-warning%2c-lexical-warnings-warning"></a><h1>NAME

</a><li><a href="#Fatal-Warnings">Fatal Warnings

</a><li><a href="#Reporting-Warnings-from-a-Module">Reporting Warnings from a Module

</a></ul><li><a href="#SEE-ALSO">SEE ALSO</a><li><a href="#AUTHOR">AUTHOR</a></ul><a name="NAME"></a><h1>NAME

</h1>

perllexwarn - Perl Lexical Warnings

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

The <code class="inline"><a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a></code>

pragma is a replacement for both the command line

flag -w and the equivalent Perl variable, <code class="inline">$^W</code>

The <code class="inline"><a class="l_k" href="functions/use.html">use</a> warnings</code>

pragma enables to control precisely what warnings are

to be enabled in which parts of a Perl program. It's a more flexible

alternative for both the command line flag -w and the equivalent Perl

100

variable, <code class="inline">$^W</code>

101

.

The pragma works just like the existing "strict" pragma.

102

This pragma works just like the <code class="inline">strict</code>

103

pragma.

104

This means that the scope of the warning pragma is limited to the

105

enclosing block. It also means that the pragma setting will not

100

106

leak across files (via <code class="inline"><a class="l_k" href="functions/use.html">use</a></code>, <code class="inline"><a class="l_k" href="functions/require.html">require</a></code> or <code class="inline"><a class="l_k" href="functions/do.html">do</a></code>). This allows

103

109

By default, optional warnings are disabled, so any legacy code that

104

110

doesn't attempt to control the warnings will work unchanged.

105

111

All warnings are enabled in a block by either of these:

106

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

107

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> 'all';</pre>

112

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

113

<a class="l_k" href="functions/use.html">use</a> warnings 'all';</pre>

108

114

Similarly all warnings are disabled in a block by either of these:

109

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

110

<a class="l_k" href="functions/no.html">no</a> <a class="l_w" href="warnings.html">warnings</a> 'all';</pre>

115

<pre class="verbatim"> <a class="l_k" href="functions/no.html">no</a> warnings;

116

<a class="l_k" href="functions/no.html">no</a> warnings 'all';</pre>

111

117

For example, consider the code below:

112

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

118

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

113

119

<a class="l_k" href="functions/my.html">my</a> @a;

114

120

{

115

<a class="l_k" href="functions/no.html">no</a> <a class="l_w" href="warnings.html">warnings</a>;

121

<a class="l_k" href="functions/no.html">no</a> warnings;

116

122

<a class="l_k" href="functions/my.html">my</a> $b = @a[0];

117

123

}

118

124

125

131

will not.

126

132

<a name="Default-Warnings-and-Optional-Warnings"></a><h2>Default Warnings and Optional Warnings</h2>

127

133

Before the introduction of lexical warnings, Perl had two classes of

128

warnings: mandatory and optional.

134

warnings: mandatory and optional.

129

135

As its name suggests, if your code tripped a mandatory warning, you

130

136

would get a warning whether you wanted it or not.

131

137

For example, the code below would always produce an <code class="inline">"isn't numeric"</code>

141

147

be reported for the <code class="inline">$a</code>

142

148

variable.

143

149

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> $a = "2:" + 3;

144

<a class="l_k" href="functions/no.html">no</a> <a class="l_w" href="warnings.html">warnings</a>;

150

<a class="l_k" href="functions/no.html">no</a> warnings;

145

151

146

152

Note that neither the -w flag or the <code class="inline">$^W</code>

147

153

can be used to

178

184

is the way you can inadvertently

179

185

change the warning setting in unexpected places in your code. For example,

180

186

when the code below is run (without the -w flag), the second call

181

to <code class="inline">doit</code>

187

to <code class="inline">doit</code>

182

188

will trip a <code class="inline">"Use of uninitialized value"</code>

183

189

warning, whereas

184

190

the first will not.

199

205

There are three Command Line flags that can be used to control when

200

206

warnings are (or aren't) produced:

201

207

<ul>

202

<li><a name="*-w*--w"></a>-w

208

<li><a name="*-w*"></a>-w

203

209

204

210

This is the existing flag. If the lexical warnings pragma is not

205

211

used in any of you code, or any of the modules that you use, this flag

206

212

will enable warnings everywhere. See <a href="#Backward-Compatibility">"Backward Compatibility"</a> for

207

213

details of how this flag interacts with lexical warnings.

208

214

</li>

209

<li><a name="*-W*--W"></a>-W

215

<li><a name="*-W*"></a>-W

210

216

211

217

If the -W flag is used on the command line, it will enable all warnings

212

218

throughout the program regardless of whether warnings were disabled

213

locally using <code class="inline"><a class="l_k" href="functions/no.html">no</a> <a class="l_w" href="warnings.html">warnings</a></code>

219

locally using <code class="inline"><a class="l_k" href="functions/no.html">no</a> warnings</code>

214

220

or <code class="inline">$^W =0</code>

215

221

. This includes all files that get

216

222

included via <code class="inline"><a class="l_k" href="functions/use.html">use</a></code>, <code class="inline"><a class="l_k" href="functions/require.html">require</a></code> or <code class="inline"><a class="l_k" href="functions/do.html">do</a></code>.

217

223

Think of it as the Perl equivalent of the "lint" command.

218

224

</li>

219

<li><a name="*-X*--X"></a>-X

225

<li><a name="*-X*"></a>-X

220

226

221

227

Does the exact opposite to the -W flag, i.e. it disables all warnings.

222

228

</li>

232

238

<li>

233

239

If none of the three command line flags (-w, -W or -X) that

234

240

control warnings is used and neither <code class="inline">$^W</code>

235

or the <code class="inline"><a class="l_w" href="warnings.html">warnings</a></code> pragma

241

or the <code class="inline">warnings</code>

242

pragma

236

243

are used, then default warnings will be enabled and optional warnings

237

244

disabled.

238

245

This means that legacy code that doesn't attempt to control the warnings

243

250

variable as in 5.005 -- this

244

251

means that any legacy code that currently relies on manipulating <code class="inline">$^W</code>

245

252

246

to control warning behavior will still work as is.

253

to control warning behavior will still work as is.

247

254

</li>

248

255

<li>

249

256

Apart from now being a boolean, the <code class="inline">$^W</code>

252

259

disable/enable default warnings.

253

260

</li>

254

261

<li>

255

If a piece of code is under the control of the <code class="inline"><a class="l_w" href="warnings.html">warnings</a></code> pragma,

262

If a piece of code is under the control of the <code class="inline">warnings</code>

263

pragma,

256

264

both the <code class="inline">$^W</code>

257

265

variable and the -w flag will be ignored for the

258

266

scope of the lexical warning.

263

271

</li>

264

272

</ol>

265

273

The combined effect of 3 & 4 is that it will allow code which uses

266

the <code class="inline"><a class="l_w" href="warnings.html">warnings</a></code> pragma to control the warning behavior of $^W-type

274

the <code class="inline">warnings</code>

275

pragma to control the warning behavior of $^W-type

267

276

code (using a <code class="inline"><a class="l_k" href="functions/local.html">local</a> $^W=0</code>

268

277

) if it really wants to, but not vice-versa.

269

<a name="Category-Hierarchy-warning%2c-categories"></a><h2>Category Hierarchy

278

<a name="Category-Hierarchy"></a><h2>Category Hierarchy

270

279

</h2>

271

280

A hierarchy of "categories" have been defined to allow groups of warnings

272

281

to be enabled/disabled in isolation.

361

370

362

371

+- utf8

363

372

364

+- void

365

366

+- y2k</pre>Just like the "strict" pragma any of these categories can be combined

367

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

368

<a class="l_k" href="functions/no.html">no</a> <a class="l_w" href="warnings.html">warnings</a> qw(io syntax untie);</pre>

373

+- void</pre>Just like the "strict" pragma any of these categories can be combined

374

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings qw(void redefine);

375

<a class="l_k" href="functions/no.html">no</a> warnings qw(io syntax untie);</pre>

369

376

Also like the "strict" pragma, if there is more than one instance of the

370

<code class="inline"><a class="l_w" href="warnings.html">warnings</a></code> pragma in a given scope the cumulative effect is additive.

371

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> qw(void); # only "void" warnings enabled

372

...

373

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> qw(io); # only "void" & "io" warnings enabled

374

...

375

<a class="l_k" href="functions/no.html">no</a> <a class="l_w" href="warnings.html">warnings</a> qw(void); # only "io" warnings enabled</pre>

377

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

378

pragma in a given scope the cumulative effect is additive.

379

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings qw(void); # only "void" warnings enabled

380

...

381

<a class="l_k" href="functions/use.html">use</a> warnings qw(io); # only "void" & "io" warnings enabled

382

...

383

<a class="l_k" href="functions/no.html">no</a> warnings qw(void); # only "io" warnings enabled</pre>

376

384

To determine which category a specific warning has been assigned to see

377

385

<a href="perldiag.html">perldiag</a>.

378

386

Note: In Perl 5.6.1, the lexical warnings category "deprecated" was a

379

387

sub-category of the "syntax" category. It is now a top-level category

380

388

in its own right.

381

<a name="Fatal-Warnings-warning%2c-fatal"></a><h2>Fatal Warnings

389

<a name="Fatal-Warnings"></a><h2>Fatal Warnings

382

390

</h2>

383

391

The presence of the word "FATAL" in the category list will escalate any

384

392

warnings detected from the categories specified in the lexical scope

386

394

and <code class="inline"><a class="l_k" href="functions/join.html">join</a></code> can all produce a <code class="inline">"Useless use of xxx in void context"</code>

387

395

388

396

warning.

389

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

397

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

390

398

391

399

<pre class="verbatim"> {

392

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> FATAL => qw(void);

400

<a class="l_k" href="functions/use.html">use</a> warnings FATAL => qw(void);

393

401

<a class="l_k" href="functions/length.html">length</a> "abc";

394

402

}</pre>

395

403

396

404

<pre class="verbatim"> <a class="l_k" href="functions/print.html">print</a> "done\n";</pre>

397

405

When run it produces this output

398

406

<pre class="verbatim"> Useless use of time in void context at fatal line 3.

399

Useless use of length in void context at fatal line 7. </pre>The scope where <code class="inline"><a class="l_k" href="functions/length.html">length</a></code> is used has escalated the <code class="inline">void</code>

407

Useless use of length in void context at fatal line 7.</pre>The scope where <code class="inline"><a class="l_k" href="functions/length.html">length</a></code> is used has escalated the <code class="inline">void</code>

400

408

warnings

401

409

category into a fatal error, so the program terminates immediately it

402

410

encounters the warning.

403

411

To explicitly turn off a "FATAL" warning you just disable the warning

404

412

it is associated with. So, for example, to disable the "void" warning

405

413

in the example above, either of these will do the trick:

406

<pre class="verbatim"> <a class="l_k" href="functions/no.html">no</a> <a class="l_w" href="warnings.html">warnings</a> qw(void);

407

<a class="l_k" href="functions/no.html">no</a> <a class="l_w" href="warnings.html">warnings</a> FATAL => qw(void);</pre>

414

<pre class="verbatim"> <a class="l_k" href="functions/no.html">no</a> warnings qw(void);

415

<a class="l_k" href="functions/no.html">no</a> warnings FATAL => qw(void);</pre>

408

416

If you want to downgrade a warning that has been escalated into a fatal

409

417

error back to a normal warning, you can use the "NONFATAL" keyword. For

410

418

example, the code below will promote all warnings into fatal errors,

411

419

except for those in the "syntax" category.

412

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> FATAL => 'all', NONFATAL => 'syntax';</pre>

413

<a name="Reporting-Warnings-from-a-Module-warning%2c-reporting-warning%2c-registering"></a><h2>Reporting Warnings from a Module

420

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings FATAL => 'all', NONFATAL => 'syntax';</pre>

421

<a name="Reporting-Warnings-from-a-Module"></a><h2>Reporting Warnings from a Module

414

422

</h2>

415

The <code class="inline"><a class="l_w" href="warnings.html">warnings</a></code> pragma provides a number of functions that are useful for

423

The <code class="inline">warnings</code>

424

pragma provides a number of functions that are useful for

416

425

module authors. These are used when you want to report a module-specific

417

warning to a calling module has enabled warnings via the <code class="inline"><a class="l_w" href="warnings.html">warnings</a></code>

426

warning to a calling module has enabled warnings via the <code class="inline">warnings</code>

427

418

428

pragma.

419

Consider the module <code class="inline">MyMod::Abc</code>

429

Consider the module <code class="inline">MyMod::Abc</code>

420

430

below.

421

431

<pre class="verbatim"><a name="package-MyMod::Abc"></a> package MyMod::Abc;</pre>

422

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings/register.html">warnings::register</a>;</pre>

432

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings::register;</pre>

423

433

<pre class="verbatim"><a name="open"></a> sub open {

424

434

<a class="l_k" href="functions/my.html">my</a> $path = <a class="l_k" href="functions/shift.html">shift</a>;

425

435

if ($path !~ m#^/#) {

429

439

}

430

440

}</pre>

431

441

432

The call to <code class="inline"><a class="l_w" href="warnings/register.html">warnings::register</a></code> will create a new warnings category

442

The call to <code class="inline">warnings::register</code>

443

will create a new warnings category

433

444

called "MyMod::abc", i.e. the new category name matches the current

434

445

package name. The <code class="inline"><a class="l_k" href="functions/open.html">open</a></code> function in the module will display a warning

435

446

message if it gets given a relative path as a parameter. This warnings

436

will only be displayed if the code that uses <code class="inline">MyMod::Abc</code>

447

will only be displayed if the code that uses <code class="inline">MyMod::Abc</code>

437

448

has actually

438

enabled them with the <code class="inline"><a class="l_w" href="warnings.html">warnings</a></code> pragma like below.

439

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> MyMod::Abc;

440

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> 'MyMod::Abc';

449

enabled them with the <code class="inline">warnings</code>

450

pragma like below.

451

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> MyMod::Abc;

452

<a class="l_k" href="functions/use.html">use</a> warnings 'MyMod::Abc';

441

453

...

442

454

abc::open("../fred.txt");</pre>

443

455

It is also possible to test whether the pre-defined warnings categories are

444

set in the calling module with the <code class="inline">warnings::enabled</code>

456

set in the calling module with the <code class="inline">warnings::enabled</code>

445

457

function. Consider

446

458

this snippet of code:

447

459

<pre class="verbatim"><a name="package-MyMod::Abc"></a> package MyMod::Abc;</pre>

455

467

1;</pre>The function <code class="inline"><a class="l_k" href="functions/open.html">open</a></code> has been deprecated, so code has been included to

456

468

display a warning message whenever the calling module has (at least) the

457

469

"deprecated" warnings category enabled. Something like this, say.

458

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> 'deprecated';

459

<a class="l_k" href="functions/use.html">use</a> MyMod::Abc;

470

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

471

<a class="l_k" href="functions/use.html">use</a> MyMod::Abc;

460

472

...

461

473

MyMod::Abc::open($filename);</pre>

462

Either the <code class="inline">warnings::warn</code>

463

or <code class="inline">warnings::warnif</code>

474

Either the <code class="inline">warnings::warn</code>

475

or <code class="inline">warnings::warnif</code>

464

476

function should be

465

477

used to actually display the warnings message. This is because they can

466

478

make use of the feature that allows warnings to be escalated into fatal

467

479

errors. So in this case

468

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> MyMod::Abc;

469

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> FATAL => 'MyMod::Abc';

480

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> MyMod::Abc;

481

<a class="l_k" href="functions/use.html">use</a> warnings FATAL => 'MyMod::Abc';

470

482

...

471

483

MyMod::Abc::open('../fred.txt');</pre>

472

the <code class="inline">warnings::warnif</code>

484

the <code class="inline">warnings::warnif</code>

473

485

function will detect this and die after

474

486

displaying the warning message.

475

The three warnings functions, <code class="inline">warnings::warn</code>

476

, <code class="inline">warnings::warnif</code>

487

The three warnings functions, <code class="inline">warnings::warn</code>

488

, <code class="inline">warnings::warnif</code>

477

489

478

and <code class="inline">warnings::enabled</code>

490

and <code class="inline">warnings::enabled</code>

479

491

can optionally take an object reference in place

480

492

of a category name. In this case the functions will use the class name

481

493

of the object as the warnings category.

482

494

Consider this example:

483

495

<pre class="verbatim"><a name="package-Original"></a> package Original;</pre>

484

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

485

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings/register.html">warnings::register</a>;</pre>

496

<pre class="verbatim"> <a class="l_k" href="functions/no.html">no</a> warnings;

497

<a class="l_k" href="functions/use.html">use</a> warnings::register;</pre>

486

498

<pre class="verbatim"><a name="new"></a> sub new

487

499

{

488

500

<a class="l_k" href="functions/my.html">my</a> $class = <a class="l_k" href="functions/shift.html">shift</a>;

502

514

}</pre>

503

515

504

516

<pre class="verbatim"><a name="package-Derived"></a> package Derived;</pre>

505

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings/register.html">warnings::register</a>;

506

<a class="l_k" href="functions/use.html">use</a> Original;

517

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> warnings::register;

518

<a class="l_k" href="functions/use.html">use</a> Original;

507

519

<a class="l_k" href="functions/our.html">our</a> @ISA = qw( Original );

508

520

<a name="new"></a> sub new

509

521

{

512

524

}</pre>

513

525

514

526

The code below makes use of both modules, but it only enables warnings from

515

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

527

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

516

528

.

517

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

518

<a class="l_k" href="functions/use.html">use</a> Derived;

519

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="warnings.html">warnings</a> 'Derived';

520

<a class="l_k" href="functions/my.html">my</a> $a = new Original;

529

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

530

<a class="l_k" href="functions/use.html">use</a> Derived;

531

<a class="l_k" href="functions/use.html">use</a> warnings 'Derived';

532

<a class="l_k" href="functions/my.html">my</a> $a = Original->new();

521

533

$a->doit(1);

522

<a class="l_k" href="functions/my.html">my</a> $b = new Derived;

534

<a class="l_k" href="functions/my.html">my</a> $b = Derived->new();

523

535

$a->doit(1);</pre>

524

When this code is run only the <code class="inline">Derived</code>

536

When this code is run only the <code class="inline">Derived</code>

525

537

object, <code class="inline">$b</code>

526

538

, will generate

527

a warning.

528

<pre class="verbatim"> Odd numbers are unsafe at main.pl line 7</pre>

539

a warning.

540

<pre class="verbatim"> Odd numbers are unsafe at main.pl line 7</pre>

529

541

Notice also that the warning is reported at the line where the object is first

530

542

used.

531

532

<pre class="verbatim"> perl5db.pl

533

The debugger saves and restores C<$^W> at runtime. I haven't checked

534

whether the debugger will still work with the lexical warnings

535

patch applied.</pre><pre class="verbatim"> <a class="l_w" href="diagnostics.html">diagnostics</a>.pm

536

I *think* I've got <a class="l_w" href="diagnostics.html">diagnostics</a> to work with the lexical <a class="l_w" href="warnings.html">warnings</a>

537

patch, but there were design decisions made in <a class="l_w" href="diagnostics.html">diagnostics</a> to work

538

around the limitations of C<$^W>. Now that those limitations are gone,

539

the module should be revisited.</pre>

540

<pre class="verbatim"> document calling the warnings::* functions from XS</pre>

541

543

542

544

<a href="warnings.html">warnings</a>, <a href="perldiag.html">perldiag</a>.

543

545

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

559

561

560

562

</form>

561

563

564

562

565

<h2>Labels:</h2>

563

566

564

567

Older »