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

<div id="contentBody"><div class="title_container"><div class="page_title">overload</div></div><ul><li><a href="#NAME">NAME</a><li><a href="#SYNOPSIS">SYNOPSIS</a><li><a href="#DESCRIPTION">DESCRIPTION</a><ul><li><a href="#Declaration-of-overloaded-functions">Declaration of overloaded functions</a><li><a href="#Calling-Conventions-for-Binary-Operations">Calling Conventions for Binary Operations</a><li><a href="#Calling-Conventions-for-Unary-Operations">Calling Conventions for Unary Operations</a><li><a href="#Calling-Conventions-for-Mutators">Calling Conventions for Mutators</a><li><a href="#Overloadable-Operations">Overloadable Operations</a><li><a href="#Inheritance-and-overloading">Inheritance and overloading</a></ul><li><a href="#SPECIAL-SYMBOLS-FOR-'use-overload'">SPECIAL SYMBOLS FOR <code class="inline"><a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a></code>

</a><ul><li><a href="#Last-Resort">Last Resort</a><li><a href="#Fallback">Fallback</a><li><a href="#Copy-Constructor">Copy Constructor</a></ul><li><a href="#MAGIC-AUTOGENERATION">MAGIC AUTOGENERATION</a><li><a href="#Losing-overloading">Losing overloading</a><li><a href="#Run-time-Overloading">Run-time Overloading</a><li><a href="#Public-functions">Public functions</a><li><a href="#Overloading-constants">Overloading constants</a><li><a href="#IMPLEMENTATION">IMPLEMENTATION</a><li><a href="#Metaphor-clash">Metaphor clash</a><li><a href="#Cookbook">Cookbook</a><ul><li><a href="#Two-face-scalars">Two-face scalars</a><li><a href="#Two-face-references">Two-face references</a><li><a href="#Symbolic-calculator">Symbolic calculator</a><li><a href="#_Really_-symbolic-calculator">Really symbolic calculator</a></ul><li><a href="#AUTHOR">AUTHOR</a><li><a href="#DIAGNOSTICS">DIAGNOSTICS</a><li><a href="#BUGS">BUGS</a></ul><a name="NAME"></a><h1>NAME</h1>

</a><ul><li><a href="#Last-Resort">Last Resort</a><li><a href="#Fallback">Fallback</a><li><a href="#Smart-Match">Smart Match</a><li><a href="#Copy-Constructor">Copy Constructor</a></ul><li><a href="#MAGIC-AUTOGENERATION">MAGIC AUTOGENERATION</a><li><a href="#Minimal-set-of-overloaded-operations">Minimal set of overloaded operations</a><li><a href="#Losing-overloading">Losing overloading</a><li><a href="#Run-time-Overloading">Run-time Overloading</a><li><a href="#Public-functions">Public functions</a><li><a href="#Overloading-constants">Overloading constants</a><li><a href="#IMPLEMENTATION">IMPLEMENTATION</a><li><a href="#Metaphor-clash">Metaphor clash</a><li><a href="#Cookbook">Cookbook</a><ul><li><a href="#Two-face-scalars">Two-face scalars</a><li><a href="#Two-face-references">Two-face references</a><li><a href="#Symbolic-calculator">Symbolic calculator</a><li><a href="#_Really_-symbolic-calculator">Really symbolic calculator</a></ul><li><a href="#AUTHOR">AUTHOR</a><li><a href="#DIAGNOSTICS">DIAGNOSTICS</a><li><a href="#BUGS">BUGS</a></ul><a name="NAME"></a><h1>NAME</h1>

overload - Package for overloading Perl operations

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

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

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

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

'+' => \&myadd,

'-' => \&mysub;

# etc

...</pre>

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

$a = new SomeThing 57;

$a = new SomeThing 57;

$b=5+$a;

100

...

if (overload::Overloaded $b) {...}

101

if (overload::Overloaded $b) {...}

102

...

100

$strval = overload::StrVal $b;</pre>

103

$strval = overload::StrVal $b;</pre>

101

104

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

102

105

<a name="Declaration-of-overloaded-functions"></a><h2>Declaration of overloaded functions</h2>

103

106

The compilation directive

104

107

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

105

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a>

108

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

106

109

"+" => \&add,

107

110

"*=" => "muas";</pre>

108

111

declares function Number::add() for addition, and method muas() in

109

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

112

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

110

113

(or one of its base classes)

111

114

for the assignment form <code class="inline">*=</code>

112

115

of multiplication.

116

119

subroutine, a reference to a subroutine, or an anonymous subroutine

117

120

will all work. Note that values specified as strings are

118

121

interpreted as methods, not subroutines. Legal keys are listed below.

119

The subroutine <code class="inline">add</code>

122

The subroutine <code class="inline">add</code>

120

123

will be called to execute <code class="inline">$a+$b</code>

121

124

if $a

122

is a reference to an object blessed into the package <code class="inline">Number</code>

125

is a reference to an object blessed into the package <code class="inline">Number</code>

123

126

, or if $a is

124

127

not an object from a package with defined mathemagic addition, but $b is a

125

reference to a <code class="inline">Number</code>

128

reference to a <code class="inline">Number</code>

126

129

. It can also be called in other situations, like

127

130

128

131

, or <code class="inline">$a++</code>

133

136

above declaration would also trigger overloading of <code class="inline">+</code>

134

137

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

135

138

136

all the packages which inherit from <code class="inline">Number</code>

139

all the packages which inherit from <code class="inline">Number</code>

137

140

.

138

141

<a name="Calling-Conventions-for-Binary-Operations"></a><h2>Calling Conventions for Binary Operations</h2>

139

The functions specified in the <code class="inline"><a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a> ...</code>

142

The functions specified in the <code class="inline"><a class="l_k" href="functions/use.html">use</a> overload ...</code>

140

143

directive are called

141

144

with three (in one particular case with four, see <a href="#Last-Resort">"Last Resort"</a>)

142

145

arguments. If the corresponding operation is binary, then the first

186

189

is OK if used with preincrement and with postincrement. (In the case

187

190

of postincrement a copying will be performed, see <a href="#Copy-Constructor">"Copy Constructor"</a>.)

188

191

</li>

189

192

190

193

and other assignment versions

191

194

There is nothing special about these methods. They may change the

192

195

value of their arguments, and may leave it as is. The result is going

205

208

Warning. Due to the presence of assignment versions of operations,

206

209

routines which may be called in assignment context may create

207

210

self-referential structures. Currently Perl will not free self-referential

208

structures until cycles are <code class="inline">explicitly</code>

211

structures until cycles are <code class="inline">explicitly</code>

209

212

broken. You may get problems

210

213

when traversing your structures too.

211

214

Say,

212

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a> '+' => <a class="l_k" href="functions/sub.html">sub</a> { <a class="l_k" href="functions/bless.html">bless</a> [ \$_[0], \$_[1] ] };</pre>

215

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> overload '+' => <a class="l_k" href="functions/sub.html">sub</a> { <a class="l_k" href="functions/bless.html">bless</a> [ \$_[0], \$_[1] ] };</pre>

213

216

is asking for trouble, since for code <code class="inline">$obj += $foo</code>

214

217

the subroutine

215

218

is called as <code class="inline">$obj = add($obj, $foo, <a class="l_k" href="functions/undef.html">undef</a>)</code>

228

231

may be both optimized to

229

232

230

233

<a name="Overloadable-Operations"></a><h2>Overloadable Operations</h2>

231

The following symbols can be specified in <code class="inline"><a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a></code>

234

The following symbols can be specified in <code class="inline"><a class="l_k" href="functions/use.html">use</a> overload</code>

232

235

directive:

233

236

<ul>

234

237

<li><a name="*-_Arithmetic-operations_"></a>Arithmetic operations

254

257

If the corresponding "spaceship" variant is available, it can be

255

258

used to substitute for the missing operation. During <code class="inline"><a class="l_k" href="functions/sort.html">sort</a></code>ing

256

259

arrays, <code class="inline">cmp</code>

257

is used to compare values subject to <code class="inline"><a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a></code>

260

is used to compare values subject to <code class="inline"><a class="l_k" href="functions/use.html">use</a> overload</code>

258

261

.

259

262

</li>

260

263

<li><a name="*-_Bit-operations_"></a>Bit operations

261

262

263

stands for unary minus. If the method for <code class="inline">neg</code>

264

265

266

stands for unary minus. If the method for <code class="inline">neg</code>

264

267

is not

265

268

specified, it can be autogenerated using the method for

266

269

subtraction. If the method for <code class="inline">!</code>

267

270

is not specified, it can be

268

autogenerated using the methods for <code class="inline">bool</code>

271

autogenerated using the methods for <code class="inline">bool</code>

269

272

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

270

273

, or <code class="inline">0+</code>

271

274

.

275

The same remarks in <a href="#Arithmetic-operations">"Arithmetic operations"</a> about

276

assignment-variants and autogeneration apply for

277

bit operations <code class="inline">"&"</code>

278

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

279

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

280

as well.

272

281

</li>

273

282

<li><a name="*-_Increment-and-decrement_"></a>Increment and decrement

274

283

289

298

<li><a name="*-_Boolean%2c-string-and-numeric-conversion_"></a>Boolean, string and numeric conversion

290

299

291

300

If one or two of these operations are not overloaded, the remaining ones can

292

be used instead. <code class="inline">bool</code>

301

be used instead. <code class="inline">bool</code>

293

302

is used in the flow control operators

294

303

(like <code class="inline">while</code>

295

304

) and for the ternary <code class="inline">?:</code> operation. These functions can

298

307

As a special case if the overload returns the object itself then it will

299

308

be used directly. An overloaded conversion returning the object is

300

309

probably a bug, because you're likely to get something that looks like

301

<code class="inline">YourPackage=HASH(0x8172b34)</code>

310

<code class="inline">YourPackage=HASH(0x8172b34)</code>

302

311

.

303

312

</li>

304

313

<li><a name="*-_Iteration_"></a>Iteration

323

332

"nomethod".

324

333

</li>

325

334

<li><a name="*-_Special_"></a>Special

326

<pre class="verbatim"> "nomethod", "fallback", "=",</pre>

327

see <a href="http://search.cpan.org/perldoc/SPECIAL SYMBOLS FOR <code class="inline">use overload<#code%3e">"code>" in SPECIAL SYMBOLS FOR <code class="inline">use overload<</a>.

335

<pre class="verbatim"> "nomethod", "fallback", "=", "~~",</pre>

336

see <a href="http://search.cpan.org/perldoc/SPECIAL SYMBOLS FOR <code class="inline"><a class="l_k" href="functions#use.html%22%3euse%3c%2fa%3e-%3cspan-class%3d%22w%22%3eoverload%3c%2fspan%3e%3c%2fcode%3e">"use.html">use</a> overload</code>" in SPECIAL SYMBOLS FOR <code class="inline"><a class="l_k" href="functions</a>.

328

337

</li>

329

338

</ul>

330

339

See <a href="#Fallback">"Fallback"</a> for an explanation of when a missing method can be

331

340

autogenerated.

332

341

A computer-readable form of the above table is available in the hash

333

342

%overload::ops, with values being space-separated lists of names:

334

<pre class="verbatim"> with_assign => '+ - * / % ** << >> x .',

335

assign => '+= -= *= /= %= **= <<= >>= x= .=',

336

num_comparison => '< <= > >= == !=',

337

'3way_comparison'=> '<=> cmp',

338

str_comparison => 'lt le gt ge eq ne',

339

binary => '& | ^',

340

unary => 'neg ! ~',

341

mutators => '++ --',

342

func => 'atan2 cos sin exp abs log sqrt',

343

conversion => 'bool "" 0+',

344

iterators => '<>',

345

dereferencing => '${} @{} %{} &{} *{}',

346

special => 'nomethod fallback ='</pre>

343

<pre class="verbatim"> with_assign => '+ - * / % ** << >> x .',

344

assign => '+= -= *= /= %= **= <<= >>= x= .=',

345

num_comparison => '< <= > >= == !=',

346

'3way_comparison'=> '<=> cmp',

347

str_comparison => 'lt le gt ge eq ne',

348

binary => '& &= | |= ^ ^=',

349

unary => 'neg ! ~',

350

mutators => '++ --',

351

func => 'atan2 cos sin exp abs log sqrt',

352

conversion => 'bool "" 0+',

353

iterators => '<>',

354

dereferencing => '${} @{} %{} &{} *{}',

355

special => 'nomethod fallback ='</pre>

347

356

<a name="Inheritance-and-overloading"></a><h2>Inheritance and overloading</h2>

348

357

Inheritance interacts with overloading in two ways.

349

358

<ul>

350

<li><a name="Strings-as-values-of-'use-overload'-directive"></a>Strings as values of <code class="inline">use overload</code> directive

351

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

359

<li><a name="Strings-as-values-of-'use-overload'-directive"></a>Strings as values of <code class="inline"><a class="l_k" href="functions/use.html">use</a> overload</code>

360

directive

361

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

352

362

in

353

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

363

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

354

364

is a string, it is interpreted as a method name.

355

365

</li>

356

366

<li><a name="Overloading-of-an-operation-is-inherited-by-derived-classes"></a>Overloading of an operation is inherited by derived classes

359

369

the ancestors. If some method is overloaded in several ancestor, then

360

370

which description will be used is decided by the usual inheritance

361

371

rules:

362

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

363

inherits from <code class="inline"><a class="l_w" href="B.html">B</a></code> and <code class="inline">C</code>

364

(in this order), <code class="inline"><a class="l_w" href="B.html">B</a></code> overloads

372

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

373

inherits from <code class="inline">B</code>

374

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

375

(in this order), <code class="inline">B</code>

376

overloads

365

377

366

378

with <code class="inline">\&D::plus_sub</code>

367

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

379

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

368

380

overloads <code class="inline">+</code>

369

381

by <code class="inline">"plus_meth"</code>

370

382

371

then the subroutine <code class="inline">D::plus_sub</code>

383

then the subroutine <code class="inline">D::plus_sub</code>

372

384

will be called to implement

373

385

operation <code class="inline">+</code>

374

for an object in package <code class="inline">A</code>

386

for an object in package <code class="inline">A</code>

375

387

.

376

388

</li>

377

389

</ul>

378

Note that since the value of the <code class="inline">fallback</code>

390

Note that since the value of the <code class="inline">fallback</code>

379

391

key is not a subroutine,

380

392

its inheritance is not governed by the above rules. In the current

381

implementation, the value of <code class="inline">fallback</code>

393

implementation, the value of <code class="inline">fallback</code>

382

394

in the first overloaded

383

395

ancestor is used, but this is accidental and subject to change.

384

<a name="SPECIAL-SYMBOLS-FOR-'use-overload'"></a><h1>SPECIAL SYMBOLS FOR <code class="inline"><a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a></code>

396

<a name="SPECIAL-SYMBOLS-FOR-'use-overload'"></a><h1>SPECIAL SYMBOLS FOR <code class="inline"><a class="l_k" href="functions/use.html">use</a> overload</code>

385

397

</h1>

386

398

Three keys are recognized by Perl that are not covered by the above

387

399

description.

398

410

<pre class="verbatim"> &nomethodMethod($a,1,1,"-")</pre>

399

411

if the pair <code class="inline">"nomethod" => "nomethodMethod"</code>

400

412

was specified in the

401

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

413

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

402

414

directive.

403

415

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

404

416

mechanism is not used for the dereference operators

407

419

assigned to <code class="inline">"nomethod"</code>

408

420

, then an exception will be raised via die()--

409

421

unless <code class="inline">"fallback"</code>

410

was specified as a key in <code class="inline"><a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a></code>

422

was specified as a key in <code class="inline"><a class="l_k" href="functions/use.html">use</a> overload</code>

411

423

directive.

412

424

<a name="Fallback"></a><h2>Fallback</h2>

413

425

The key <code class="inline">"fallback"</code>

425

437

</li>

426

438

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

427

439

The same as for the <code class="inline"><a class="l_k" href="functions/undef.html">undef</a></code> value, but no exception is raised. Instead,

428

it silently reverts to what it would have done were there no <code class="inline"><a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a></code>

440

it silently reverts to what it would have done were there no <code class="inline"><a class="l_k" href="functions/use.html">use</a> overload</code>

429

441

430

442

present.

431

443

</li>

438

450

Note. <code class="inline">"fallback"</code>

439

451

inheritance via @ISA is not carved in stone

440

452

yet, see <a href="#Inheritance-and-overloading">"Inheritance and overloading"</a>.

453

<a name="Smart-Match"></a><h2>Smart Match</h2>

454

The key <code class="inline">"~~"</code>

455

allows you to override the smart matching used by

456

the switch construct. See <a href="feature.html">feature</a>.

441

457

<a name="Copy-Constructor"></a><h2>Copy Constructor</h2>

442

458

The value for <code class="inline">"="</code>

443

459

is a reference to a function with three

444

460

arguments, i.e., it looks like the other values in <code class="inline"><a class="l_k" href="functions/use.html">use</a>

445

<a class="l_w" href="overload.html">overload</a></code>

461

overload</code>

446

462

. However, it does not overload the Perl assignment

447

463

operator. This would go against Camel hair.

448

464

This operation is called in the situations when a mutator is applied

462

478

is expressed via a method for <code class="inline">'++'</code>

463

479

or <code class="inline">'+='</code>

464

480

(or

465

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

481

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

466

482

). Note that if this operation is expressed via <code class="inline">'+'</code>

467

483

468

484

a nonmutator, i.e., as in

548

564

549

565

or <code class="inline">cmp</code>

550

566

:

551

<pre class="verbatim"> <, >, <=, >=, ==, != in terms of <=>

552

lt, gt, le, ge, eq, ne in terms of cmp</pre>

567

<pre class="verbatim"> <, >, <=, >=, ==, != in terms of <=>

568

lt, gt, le, ge, eq, ne in terms of cmp</pre>

553

569

</li>

554

570

<li><a name="_Iterator_"></a>Iterator

555

<pre class="verbatim"> <> in terms of builtin operations</pre>

556

</li>

571

<pre class="verbatim"> <> in terms of builtin operations</pre></li>

557

572

<li><a name="_Dereferencing_"></a>Dereferencing

558

573

<pre class="verbatim"> ${} @{} %{} &{} *{} in terms of builtin operations</pre></li>

559

574

<li><a name="_Copy-operator_"></a>Copy operator

561

576

value is a scalar and not a reference.

562

577

</li>

563

578

</ul>

579

<a name="Minimal-set-of-overloaded-operations"></a><h1>Minimal set of overloaded operations</h1>

580

Since some operations can be automatically generated from others, there is

581

a minimal set of operations that need to be overloaded in order to have

582

the complete set of overloaded operations at one's disposal.

583

Of course, the autogenerated operations may not do exactly what the user

584

expects. See <a href="#MAGIC-AUTOGENERATION">"MAGIC AUTOGENERATION"</a> above. The minimal set is:

585

<pre class="verbatim"> + - * / % ** << >> x

586

<=> cmp

587

& | ^ ~

588

589

Additionally, you need to define at least one of string, boolean or

590

numeric conversions because any one can be used to emulate the others.

591

The string conversion can also be used to emulate concatenation.

564

592

<a name="Losing-overloading"></a><h1>Losing overloading</h1>

565

593

The restriction for the comparison operation is that even if, for example,

566

594

`<code class="inline">cmp</code>

572

600

numeric conversion is needed in this case (possibly expressed in terms of

573

601

other conversions).

574

602

Similarly, <code class="inline">.=</code>

575

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

603

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

576

604

operators lose their mathemagical properties

577

605

if the string conversion substitution is applied.

578

606

When you chop() a mathemagical object it is promoted to a string and its

586

614

<pre class="verbatim"> <a class="l_k" href="functions/eval.html">eval</a> 'no overload "+", "--", "<="';</pre>

587

615

though the use of these constructs during run-time is questionable.

588

616

<a name="Public-functions"></a><h1>Public functions</h1>

589

Package <code class="inline"><a class="l_w" href="overload.html">overload</a>.pm</code>

617

Package <code class="inline">overload.pm</code>

590

618

provides the following public functions:

591

619

<ul>

592

620

<li><a name="overload%3a%3aStrVal(arg)"></a>overload::StrVal(arg)

593

Gives string value of <code class="inline">arg</code>

621

Gives string value of <code class="inline">arg</code>

594

622

as in absence of stringify overloading. If you

595

623

are using this to get the address of a reference (useful for checking if two

596

624

references point to the same thing) then you may be better off using

598

626

, which is faster.

599

627

</li>

600

628

<li><a name="overload%3a%3aOverloaded(arg)"></a>overload::Overloaded(arg)

601

Returns true if <code class="inline">arg</code>

629

Returns true if <code class="inline">arg</code>

602

630

is subject to overloading of some operations.

603

631

</li>

604

632

<li><a name="overload%3a%3aMethod(obj%2cop)"></a>overload::Method(obj,op)

605

Returns <code class="inline"><a class="l_k" href="functions/undef.html">undef</a></code> or a reference to the method that implements <code class="inline">op</code>

633

Returns <code class="inline"><a class="l_k" href="functions/undef.html">undef</a></code> or a reference to the method that implements <code class="inline">op</code>

606

634

.

607

635

</li>

608

636

</ul>

657

685

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

658

686

<a class="l_k" href="functions/return.html">return</a> unless @_;

659

687

<a class="l_k" href="functions/die.html">die</a> "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';

660

overload::constant <a class="l_w" href="integer.html">integer</a> => <a class="l_k" href="functions/sub.html">sub</a> {<a class="l_w" href="Math/BigInt.html">Math::BigInt</a>->new(<a class="l_k" href="functions/shift.html">shift</a>)};

688

overload::constant integer => <a class="l_k" href="functions/sub.html">sub</a> {Math::BigInt->new(<a class="l_k" href="functions/shift.html">shift</a>)};

661

689

}</pre>

662

BUGS Currently overloaded-ness of constants does not propagate

663

into <code class="inline"><a class="l_k" href="functions/eval.html">eval</a> '...'</code>

664

.

665

690

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

666

691

What follows is subject to change RSN.

667

692

The table of methods for all operations is cached in magic for the

668

693

symbol table hash for the package. The cache is invalidated during

669

processing of <code class="inline"><a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a></code>

670

, <code class="inline"><a class="l_k" href="functions/no.html">no</a> <a class="l_w" href="overload.html">overload</a></code>

694

processing of <code class="inline"><a class="l_k" href="functions/use.html">use</a> overload</code>

695

, <code class="inline"><a class="l_k" href="functions/no.html">no</a> overload</code>

671

696

, new function

672

697

definitions, and changes in @ISA. However, this invalidation remains

673

698

unprocessed until the next <code class="inline"><a class="l_k" href="functions/bless.html">bless</a></code>ing into the package. Hence if you

683

708

If an object belongs to a package using overload, it carries a special

684

709

flag. Thus the only speed penalty during arithmetic operations without

685

710

overloading is the checking of this flag.

686

In fact, if <code class="inline"><a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a></code>

711

In fact, if <code class="inline"><a class="l_k" href="functions/use.html">use</a> overload</code>

687

712

is not present, there is almost no overhead

688

713

for overloadable operations, so most programs should not suffer

689

714

measurable performance penalties. A considerable effort was made to

690

715

minimize the overhead when overload is used in some package, but the

691

716

arguments in question do not belong to packages using overload. When

692

in doubt, test your speed with <code class="inline"><a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a></code>

717

in doubt, test your speed with <code class="inline"><a class="l_k" href="functions/use.html">use</a> overload</code>

693

718

and without it. So far

694

719

there have been no reports of substantial speed degradation if Perl is

695

720

compiled with optimization turned on.

738

763

If some mutator methods are directly applied to the overloaded values,

739

764

one may need to explicitly unlink other values which references the

740

765

same value:

741

<pre class="verbatim"> $a = new Data 23;

766

<pre class="verbatim"> $a = new Data 23;

742

767

...

743

768

$b = $a; # $b is "linked" to $a

744

769

...

745

770

$a = $a->clone; # Unlink $b from $a

746

771

$a->increment_by(4);</pre>

747

772

Note that overloaded access makes this transparent:

748

<pre class="verbatim"> $a = new Data 23;

773

<pre class="verbatim"> $a = new Data 23;

749

774

$b = $a; # $b is "linked" to $a

750

775

$a += 4; # would unlink $b automagically</pre>

751

776

However, it would not make

752

<pre class="verbatim"> $a = new Data 23;

777

<pre class="verbatim"> $a = new Data 23;

753

778

$a = 4; # Now $a is a plain 4, not 'Data'</pre>

754

779

preserve "objectness" of $a. But Perl has a way to make assignments

755

780

to an object do whatever you want. It is just not the overload, but

765

790

<pre class="verbatim"><a name="package-two_face"></a> package two_face; # Scalars with separate string and

766

791

# numeric values.

767

792

<a name="new"></a> sub new { <a class="l_k" href="functions/my.html">my</a> $p = <a class="l_k" href="functions/shift.html">shift</a>; <a class="l_k" href="functions/bless.html">bless</a> [@_], $p }

768

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a> '""' => \&str, '0+' => \&num, fallback => 1;

793

<a class="l_k" href="functions/use.html">use</a> overload '""' => \&str, '0+' => \&num, fallback => 1;

769

794

<a name="num"></a> sub num {<a class="l_k" href="functions/shift.html">shift</a>->[1]}

770

795

<a name="str"></a> sub str {<a class="l_k" href="functions/shift.html">shift</a>->[0]}</pre>

771

796

Use it as follows:

772

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

773

<a class="l_k" href="functions/my.html">my</a> $seven = new two_face ("vii", 7);

797

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

798

<a class="l_k" href="functions/my.html">my</a> $seven = new two_face ("vii", 7);

774

799

<a class="l_k" href="functions/printf.html">printf</a> "seven=$seven, seven=%d, eight=%d\n", $seven, $seven+1;

775

800

<a class="l_k" href="functions/print.html">print</a> "seven contains `i'\n" if $seven =~ /i/;</pre>

776

801

(The second line creates a scalar which has both a string value, and a

778

803

<pre class="verbatim"> seven=vii, seven=7, eight=8

779

804

seven contains `i'</pre><a name="Two-face-references"></a><h2>Two-face references</h2>

780

805

Suppose you want to create an object which is accessible as both an

781

array reference and a hash reference, similar to the

782

<a href="perlref.html#Pseudo-hashes%3a-Using-an-array-as-a-hash">pseudo-hash</a>

783

builtin Perl type. Let's make it better than a pseudo-hash by

784

allowing index 0 to be treated as a normal element.

806

array reference and a hash reference.

785

807

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

786

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a> '%{}' => \&gethash, '@{}' => <a class="l_k" href="functions/sub.html">sub</a> { $ {<a class="l_k" href="functions/shift.html">shift</a>()} };

808

<a class="l_k" href="functions/use.html">use</a> overload '%{}' => \&gethash, '@{}' => <a class="l_k" href="functions/sub.html">sub</a> { $ {<a class="l_k" href="functions/shift.html">shift</a>()} };

787

809

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

788

810

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

789

811

<a class="l_k" href="functions/bless.html">bless</a> \ [@_], $p;

811

833

$$self->[$key];

812

834

}</pre>

813

835

Now one can access an object using both the array and hash syntax:

814

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> $bar = new two_refs 3,4,5,6;

836

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> $bar = new two_refs 3,4,5,6;

815

837

$bar->[2] = 11;

816

$bar->{two} == 11 or <a class="l_k" href="functions/die.html">die</a> 'bad hash fetch';</pre>

838

$bar->{two} == 11 or <a class="l_k" href="functions/die.html">die</a> 'bad hash fetch';</pre>

817

839

Note several important features of this example. First of all, the

818

840

actual type of $bar is a scalar reference, and we do not overload

819

841

the scalar dereference. Thus we can get the actual non-overloaded

840

862

To remove creation of the tied hash on each access, one may an extra

841

863

level of indirection which allows a non-circular structure of references:

842

864

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

843

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a> '%{}' => <a class="l_k" href="functions/sub.html">sub</a> { ${<a class="l_k" href="functions/shift.html">shift</a>()}->[1] },

865

<a class="l_k" href="functions/use.html">use</a> overload '%{}' => <a class="l_k" href="functions/sub.html">sub</a> { ${<a class="l_k" href="functions/shift.html">shift</a>()}->[1] },

844

866

'@{}' => <a class="l_k" href="functions/sub.html">sub</a> { ${<a class="l_k" href="functions/shift.html">shift</a>()}->[0] };

845

867

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

846

868

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

881

903

There are no loops of references.

882

904

</li>

883

905

<li>

884

Both "objects" which are blessed into the class <code class="inline">two_refs1</code>

906

Both "objects" which are blessed into the class <code class="inline">two_refs1</code>

885

907

are

886

908

references to a reference to an array, thus references to a scalar.

887

909

Thus the accessor expression <code class="inline">$$foo->[$ind]</code>

892

914

<a name="Symbolic-calculator"></a><h2>Symbolic calculator</h2>

893

915

Put this in symbolic.pm in your Perl library directory:

894

916

<pre class="verbatim"><a name="package-symbolic"></a> package symbolic; # Primitive symbolic calculator

895

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a> nomethod => \&wrap;</pre>

917

<a class="l_k" href="functions/use.html">use</a> overload nomethod => \&wrap;</pre>

896

918

<pre class="verbatim"><a name="new"></a> sub new { <a class="l_k" href="functions/shift.html">shift</a>; <a class="l_k" href="functions/bless.html">bless</a> ['n', @_] }

897

919

<a name="wrap"></a> sub wrap {

898

920

<a class="l_k" href="functions/my.html">my</a> ($obj, $other, $inv, $meth) = @_;

900

922

<a class="l_k" href="functions/bless.html">bless</a> [$meth, $obj, $other];

901

923

}</pre>

902

924

This module is very unusual as overloaded modules go: it does not

903

provide any usual overloaded operators, instead it provides the <a href="#Last-Resort">"Last Resort"</a> operator <code class="inline">nomethod</code>

925

provide any usual overloaded operators, instead it provides the <a href="#Last-Resort">"Last Resort"</a> operator <code class="inline">nomethod</code>

904

926

. In this example the corresponding

905

927

subroutine returns an object which encapsulates operations done over

906

the objects: <code class="inline">new symbolic 3</code>

928

the objects: <code class="inline">new symbolic 3</code>

907

929

contains <code class="inline">['n', 3]</code>

908

, <code class="inline">2 + new

909

symbolic 3</code>

930

, <code class="inline">2 + new

931

symbolic 3</code>

910

932

contains <code class="inline">['+', 2, ['n', 3]]</code>

911

933

.

912

934

Here is an example of the script which "calculates" the side of

913

935

circumscribed octagon using the above package:

914

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

936

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

915

937

<a class="l_k" href="functions/my.html">my</a> $iter = 1; # 2**($iter+2) = 8

916

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

938

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

917

939

918

940

<pre class="verbatim"> while ($cnt--) {

919

941

$side = (<a class="l_k" href="functions/sqrt.html">sqrt</a>(1 + $side**2) - 1)/$side;

924

946

<a class="l_k" href="functions/undef.html">undef</a>], 1], ['n', 1]]</pre>

925

947

Note that while we obtained this value using a nice little script,

926

948

there is no simple way to use this value. In fact this value may

927

be inspected in debugger (see <a href="perldebug.html">perldebug</a>), but ony if

928

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

929

Option is set, and not via <code class="inline">p</code>

949

be inspected in debugger (see <a href="perldebug.html">perldebug</a>), but only if

950

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

951

Option is set, and not via <code class="inline">p</code>

930

952

command.

931

953

If one attempts to print this value, then the overloaded operator

932

954

933

will be called, which will call <code class="inline">nomethod</code>

955

will be called, which will call <code class="inline">nomethod</code>

934

956

operator. The

935

957

result of this operator will be stringified again, but this result is

936

again of type <code class="inline">symbolic</code>

958

again of type <code class="inline">symbolic</code>

937

959

, which will lead to an infinite loop.

938

960

Add a pretty-printer method to the module symbolic.pm:

939

961

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

946

968

}</pre>

947

969

Now one can finish the script by

948

970

<pre class="verbatim"> <a class="l_k" href="functions/print.html">print</a> "side = ", $side->pretty, "\n";</pre>

949

The method <code class="inline">pretty</code>

971

The method <code class="inline">pretty</code>

950

972

is doing object-to-string conversion, so it

951

973

is natural to overload the operator <code class="inline">""</code>

952

974

using this method. However,

958

980

will look for an overloaded operator <code class="inline">.</code>; if not present, it will

959

981

look for an overloaded operator <code class="inline">""</code>

960

982

. Thus it is enough to use

961

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a> nomethod => \&wrap, '""' => \&str;

983

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> overload nomethod => \&wrap, '""' => \&str;

962

984

<a name="str"></a> sub str {

963

985

<a class="l_k" href="functions/my.html">my</a> ($meth, $a, $b) = @{+<a class="l_k" href="functions/shift.html">shift</a>};

964

986

$a = 'u' unless <a class="l_k" href="functions/defined.html">defined</a> $a;

972

994

methods.

973

995

Something is still amiss: consider the loop variable $cnt of the

974

996

script. It was a number, not an object. We cannot make this value of

975

type <code class="inline">symbolic</code>

997

type <code class="inline">symbolic</code>

976

998

, since then the loop will not terminate.

977

999

Indeed, to terminate the cycle, the $cnt should become false.

978

However, the operator <code class="inline">bool</code>

1000

However, the operator <code class="inline">bool</code>

979

1001

for checking falsity is overloaded (this

980

1002

time via overloaded <code class="inline">""</code>

981

1003

), and returns a long string, thus any object

982

of type <code class="inline">symbolic</code>

1004

of type <code class="inline">symbolic</code>

983

1005

is true. To overcome this, we need a way to

984

1006

compare an object to 0. In fact, it is easier to write a numeric

985

1007

conversion routine.

986

1008

Here is the text of symbolic.pm with such a routine added (and

987

1009

slightly modified str()):

988

1010

<pre class="verbatim"><a name="package-symbolic"></a> package symbolic; # Primitive symbolic calculator

989

<a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="overload.html">overload</a>

990

nomethod => \&wrap, '""' => \&str, '0+' => \&num;</pre>

1011

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

1012

nomethod => \&wrap, '""' => \&str, '0+' => \&num;</pre>

991

1013

992

1014

<a name="wrap"></a> sub wrap {

993

1015

1003

1025

"[$meth $a]";

1004

1026

}

1005

1027

}

1006

<a class="l_k" href="functions/my.html">my</a> %subr = ( n => <a class="l_k" href="functions/sub.html">sub</a> {$_[0]},

1007

sqrt => <a class="l_k" href="functions/sub.html">sub</a> {<a class="l_k" href="functions/sqrt.html">sqrt</a> $_[0]},

1028

<a class="l_k" href="functions/my.html">my</a> %subr = ( n => <a class="l_k" href="functions/sub.html">sub</a> {$_[0]},

1029

sqrt => <a class="l_k" href="functions/sub.html">sub</a> {<a class="l_k" href="functions/sqrt.html">sqrt</a> $_[0]},

1008

1030

'-' => <a class="l_k" href="functions/sub.html">sub</a> {<a class="l_k" href="functions/shift.html">shift</a>() - <a class="l_k" href="functions/shift.html">shift</a>()},

1009

1031

'+' => <a class="l_k" href="functions/sub.html">sub</a> {<a class="l_k" href="functions/shift.html">shift</a>() + <a class="l_k" href="functions/shift.html">shift</a>()},

1010

1032

'/' => <a class="l_k" href="functions/sub.html">sub</a> {<a class="l_k" href="functions/shift.html">shift</a>() / <a class="l_k" href="functions/shift.html">shift</a>()},

1015

1037

1016

1038

<a class="l_k" href="functions/my.html">my</a> $subr = $subr{$meth}

1017

1039

or <a class="l_k" href="functions/die.html">die</a> "Do not know how to ($meth) in symbolic";

1018

$a = $a->num if <a class="l_k" href="functions/ref.html">ref</a> $a eq __PACKAGE__;

1019

$b = $b->num if <a class="l_k" href="functions/ref.html">ref</a> $b eq __PACKAGE__;

1040

$a = $a->num if <a class="l_k" href="functions/ref.html">ref</a> $a eq __PACKAGE__;

1041

$b = $b->num if <a class="l_k" href="functions/ref.html">ref</a> $b eq __PACKAGE__;

1020

1042

$subr->($a,$b);

1021

1043

}</pre>

1022

1044

All the work of numeric conversion is done in %subr and num(). Of

1024

1046

example below. Here is the extra-credit question: why do we need an

1025

1047

explicit recursion in num()? (Answer is at the end of this section.)

1026

1048

Use this module like this:

1027

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

1028

<a class="l_k" href="functions/my.html">my</a> $iter = new symbolic 2; # 16-gon

1029

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

1049

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

1050

<a class="l_k" href="functions/my.html">my</a> $iter = new symbolic 2; # 16-gon

1051

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

1030

1052

1031

1053

<pre class="verbatim"> while ($cnt) {

1032

1054

$cnt = $cnt - 1; # Mutator `--' not implemented

1047

1069

To implement most arithmetic operations is easy; one should just use

1048

1070

the tables of operations, and change the code which fills %subr to

1049

1071

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> %subr = ( 'n' => <a class="l_k" href="functions/sub.html">sub</a> {$_[0]} );

1050

foreach <a class="l_k" href="functions/my.html">my</a> $op (<a class="l_k" href="functions/split.html">split</a> " ", $overload::ops{with_assign}) {

1072

foreach <a class="l_k" href="functions/my.html">my</a> $op (<a class="l_k" href="functions/split.html">split</a> " ", $overload::ops{with_assign}) {

1051

1073

$subr{$op} = $subr{"$op="} = <a class="l_k" href="functions/eval.html">eval</a> "sub {shift() $op shift()}";

1052

1074

}

1053

1075

<a class="l_k" href="functions/my.html">my</a> @bins = qw(binary 3way_comparison num_comparison str_comparison);

1067

1089

does not mutate

1068

1090

the argument, compare <a href="#Copy-Constructor">"Copy Constructor"</a>).

1069

1091

To implement a copy constructor, add <code class="inline">'=' => \&cpy</code>

1070

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

1092

to <code class="inline"><a class="l_k" href="functions/use.html">use</a> overload</code>

1071

1093

1072

1094

line, and code (this code assumes that mutators change things one level

1073

1095

deep only, so recursive copying is not needed):

1078

1100

To make <code class="inline">++</code>

1079

1101

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

1080

1102

work, we need to implement actual mutators,

1081

either directly, or in <code class="inline">nomethod</code>

1103

either directly, or in <code class="inline">nomethod</code>

1082

1104

. We continue to do things inside

1083

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

1105

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

1084

1106

, thus add

1085

1107

<pre class="verbatim"> if ($meth eq '++' or $meth eq '--') {

1086

1108

@$obj = ($meth, (<a class="l_k" href="functions/bless.html">bless</a> [@$obj]), 1); # Avoid circular reference

1092

1114

instead.

1093

1115

As a final remark, note that one can fill %subr by

1094

1116

1095

1117

foreach <a class="l_k" href="functions/my.html">my</a> $op (<a class="l_k" href="functions/split.html">split</a> " ", $overload::ops{with_assign}) {

1096

1118

1097

1119

}

1098

1120

<a class="l_k" href="functions/my.html">my</a> @bins = qw(binary 3way_comparison num_comparison str_comparison);

1111

1133

explicit recursion since the overloaded <code class="inline">.</code>-operator will fall back

1112

1134

to an existing overloaded operator <code class="inline">""</code>

1113

1135

. Overloaded arithmetic

1114

operators do not fall back to numeric conversion if <code class="inline">fallback</code>

1136

operators do not fall back to numeric conversion if <code class="inline">fallback</code>

1115

1137

1116

1138

not explicitly requested. Thus without an explicit recursion num()

1117

1139

would convert <code class="inline">['+', $a, $b]</code>

1134

1156

$#$obj = 1;

1135

1157

@$obj->[0,1] = ('=', <a class="l_k" href="functions/shift.html">shift</a>);

1136

1158

}</pre>

1137

to the package <code class="inline">symbolic</code>

1159

to the package <code class="inline">symbolic</code>

1138

1160

. After this change one can do

1139

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> $a = new symbolic 3;

1140

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

1161

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> $a = new symbolic 3;

1162

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

1141

1163

1142

1164

and the numeric value of $c becomes 5. However, after calling

1143

1165

<pre class="verbatim"> $a->STORE(12); $b->STORE(5);</pre>

1144

1166

the numeric value of $c becomes 13. There is no doubt now that the module

1145

1167

symbolic provides a symbolic calculator indeed.

1146

1168

To hide the rough edges under the hood, provide a tie()d interface to the

1147

package <code class="inline">symbolic</code>

1169

package <code class="inline">symbolic</code>

1148

1170

(compare with <a href="#Metaphor-clash">"Metaphor clash"</a>). Add methods

1149

1171

<pre class="verbatim"><a name="TIESCALAR"></a> sub TIESCALAR { <a class="l_k" href="functions/my.html">my</a> $pack = <a class="l_k" href="functions/shift.html">shift</a>; $pack->new(@_) }

1150

1172

<a name="FETCH"></a> sub FETCH { <a class="l_k" href="functions/shift.html">shift</a> }

1160

1182

<pre class="verbatim"><a name="vars"></a> sub vars { <a class="l_k" href="functions/my.html">my</a> $p = <a class="l_k" href="functions/shift.html">shift</a>; <a class="l_k" href="functions/tie.html">tie</a>($_, $p), $_->nop foreach @_; }</pre>

1161

1183

Now

1162

1184

<pre class="verbatim"> <a class="l_k" href="functions/my.html">my</a> ($a, $b);

1163

symbolic->vars($a, $b);

1185

symbolic->vars($a, $b);

1164

1186

1165

1187

<pre class="verbatim"> $a = 3; $b = 4;

1166

1188

<a class="l_k" href="functions/printf.html">printf</a> "c5 %s=%f\n", $c, $c;</pre>

1178

1200

this overloading). Say, if <code class="inline">eq</code>

1179

1201

is overloaded, then the method <code class="inline">(eq</code>

1180

1202

is shown by debugger. The method <code class="inline">()</code>

1181

corresponds to the <code class="inline">fallback</code>

1203

corresponds to the <code class="inline">fallback</code>

1182

1204

1183

1205

key (in fact a presence of this method shows that this package has

1184

overloading enabled, and it is what is used by the <code class="inline">Overloaded</code>

1206

overloading enabled, and it is what is used by the <code class="inline">Overloaded</code>

1185

1207

1186

function of module <code class="inline"><a class="l_w" href="overload.html">overload</a></code>).

1208

function of module <code class="inline">overload</code>

1209

).

1187

1210

The module might issue the following warnings:

1188

1211

<ul>

1189

1212

<li><a name="Odd-number-of-arguments-for-overload%3a%3aconstant"></a>Odd number of arguments for overload::constant

1204

1227

has a special meaning in Perl. The symbol table is filled with names

1205

1228

looking like line-noise.

1206

1229

For the purpose of inheritance every overloaded package behaves as if

1207

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

1230

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

1208

1231

is present (possibly undefined). This may create

1209

1232

interesting effects if some package is not overloaded, but inherits

1210

1233

from two overloaded packages.

1236

1259

1237

1260

</form>

1238

1261

1262

1239

1263

<h2>Labels:</h2>

1240

1264

1241

1265

Older »