NAME

interface - simple compile time interface checking for OO Perl

SYNOPSIS

  package Foo;

  use interface 'Iterator', 'Generator', 'Clonable', 'DBI::DBD';

ABSTRACT

Compile-time interface compliance testing. Inspects the methods defined in your module, and compares them against the methods defined in the modules you list. Requires no special or additional syntax.

Should you fail to implement any method contained in any of the listed classes, compile will abort with an error message.

DESCRIPTION

Methods starting with an underscore are ignored, and assumed not to be part of the interface.

The modules listed on the "use interface" line will be added to your @ISA array. This isn't done to re-use code from them - interface definitions should be empty code stubs, or perhaps a reference implementation. It is done so that your module asses the "->isa()" test for the name of the package that you're implementing the interface of. This tells Perl that your module may be used in place of the modules you implement the interface of.

Sample interface definition:

  package TestInterface;

  sub foo { }

  sub bar { }

  sub baz { }

  1;

A package claiming to implement the interface "TestInterface" would need to define the methods "foo()", "bar()", and "baz()".

An "interface" may need some explaination. It's an Object Orientation idea, also known as polymorphism, that says that you should be able to use interchangeable objects interchangably. Thank heavens the OO people came and showed us the light!

The flip side of polymorphism is type safety. In Perl, "->isa()" lets you check to make sure something is derived from a base class. The logic goes that if its derived from a base class, and we're looking for an object that fills the need of the base class, then the subclass will work just as well, and we can accept it. Extending objects is done by subclassing base classes and passing off the subclasses as versions of the original.

While this OO rote might almost have you convinced that the world works this way, this turns out to be almostly completely useless. In the real world, there are only a few reasons that one object is used in place of another: Someone wrote some really horrible code, and you want to swap out their object with a better version of the same thing. You're switching to an object that does the same thing but in a different way, for example using a database store instead of a flat file store. You're making some minor changes to an existing object and you want to be able to extend the base class in other directions in the future. Only in the last case is inherited code with subclassing even useful. In fact, there is a move towards using composition (has-a) instead of inheritance (is-a) across the whole industry, mainly because they got tired of people pointing out that OO sucks because inheritance only serves to make a great big mess of otherwise clean code.

Seperating the interface from the implementation lets you make multiple implementations of an idea. They can share code with each other, but they don't have to. The programmer has assured us that their module does what is required by stating that it implements the interface. While this isn't proof that the code works, climaing to implement an interface is a kind of contract. The programmer knows what work is required of him and she has agreed to deliver on it.

The interface definition can be a package full of stub methods that don't do anything, or it could be an actual working implementation of an object you're striving for compatability with. The first case is cleanist, and the package full of stubs serves as good documentation. The second case can be handy in cases where the first case wasn't done but someone ignored the Wisdom of the Interface and wrote a package anyway.

The Wisdom of the Interface says to write an interface for each new kind of object that could have multiple implementations. The interfaces serves as a contract for the minimum features needed to implement an object of that type. When working with objects - creating them, checking types when you accept them, etc - always work with the interface type, never the type of an individual implementation. This keeps your code generic.

In order to do the composition thing (has-a), you contain one or more objects that you need to do your work, you implement an interface that dispatches method calls to those objects. Perhaps your new() method creates those objects and stores them in instance variables.

EXPORT

None. EXPORT is silly. You stay in your namespace, I'll stay in mine.

DIAGNOSTICS

Failing to implement a required method will generate a fatal similar to the following:

Baz is missing methods: bar from Stub, and import from your, and import from ImplicitThis at interface.pm line 47. BEGIN failed--compilation aborted at Baz.pm line 5.

AGNOSTICS

Hear the one about the insomniac dyslexic agnostic? He stayed up all night wondering if there was a Dog.

CHANGES

  0.01: Initial release.
  0.02: Stephen Nelson submitted a typo report. Thanks!
        Mention of protocol.pm by James Smith 
        An object is now considered to implemenant an interface if it ->can()
        do something, not just if it has a method.
        Hacked on docs a bit.
  0.03: Doing an "eval $caller;" in our import() doesn't get perl to finish
        loading the module that called us.  Somewhere before 5.8.8, this seems
        to have stopped working.  So we use CHECK { } now like we should have
        always.

BUGS

Yes.

This will very likely break highly introspective code, for example, anything Damian Conway might write.

Does not work with packages not stored in a file where "use" can find them. This bug applies to programs run from "perl -e" and in subpackages burried in other packages. Code in the "main" package cannot use this module for this reason.

Does not work when AUTOLOAD is used to dispatch method calls. Modules that use AUTOLOAD cannot be used as an interface definition, and modules that use AUTOLOAD cannot be tested to comply with an interface definition.

It should be an error to use two different interfaces that both declare a method of the same name, as it would be ambigious which you are intending to implement. I haven't decided. Perhaps I'll just make this warning.

This module was done in pragma-style without permission. I'm interested on feedback on how to handle this.

Another arrangement worth considering is to create a Class::Interface thing that the interface uses, not your code. When you use that interface, the code is awaken, and import() inspects your code without exporting anything. This would just move the logic around. Interfaces would be marked interfaces rather than the people who use the interfaces making them as interfaces. Once again, thoughts and suggestions encouraged.

The code is frightening.

There are spelling and grammar errors in this POD documentation.

My Wiki is really slow because my computer is slow, doesn't have much memory, and its 4000 lines of code. I need to trim that down. I think I could do it in about 400 lines. Update: TinyWiki is borne. TinyWiki is no more than 100 lines, now by definition. It is fast enough.

AUTHOR

Scott Walters, SWALTERS, Root of all Evil, <scott@slowass.net>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. If you don't believe in free software, just remember that free software programmers are gnome-like. I wouldn't want to be visited by gnomes.