interface

interface option ?arg arg ...?

DESCRIPTION

In Tcl "objects" can be created in many ways: in C, in Tcl or in any of the Tcl OO extensions. The term object is used loosely here for each compound command: a command with subcommands (methods) that encapsulates a certain functionality. Different kinds of objects can often have similar functionality: eg. objects for connecting to different kinds of databases would be nicely interchangeable if the would support the same set of methods in the same way. In order to let objects easily communicate with each other they have to be able to find out the others functionality.

An interface is a set of (related) methods that provide a predefined functionality. An object implements an interface if it supports all the methods in the interface the proper way. Of course, one object can support multiple interfaces. It must advertise the interfaces it supports via the "interface" method which has the following form

pathName interface ?interfaceName?

An interface is basically defined by a description of the interface and its methods and a test suite. This is implemented by an object in the interfaces namespace, that supports the "interface" interface. (don't you just love self referential definitions?). This interface defining object must have a name consisting of the interface name and its version number seperated by a hyphen. It should have a doc method that returns the description of the interface in XML format, and a test method that can be used to test a given object for compliance. The test method takes the object to be tested as a first argument, optionally followed by a number of options. These options depend completely on the interface being defined, and can be used to provide necesary parameters or to allow the exlusion of certain tests.

THE INTERFACE COMMAND

The interface command is used to get information about interfaces. It can have any of several forms, depending on the option argument:

interface list ?pattern?

Returns a Tcl list whose elements are the available interfaces that match pattern (using the matching rules of string match). If pattern is omitted then the command returns all interfaces. The command returns interfaces loaded in the interfaces namespaces, as well as autoloadable interfaces.

interface versions interfaceName

Returns a Tcl list whose elements are the available versions of the interface given by interfaceName.

interface doc interfaceName

Returns the documentation of the interface given by interfaceName. If interfaceName does not include a version number (of the form interface-1.0), the documentation for the latest available version is returned.

interface test interfaceName objectName ?options?

tests whether the object objectName fully supports the interface interfaceName. The command returns the number of the tests that failed. The actual errors made are sent to stdout, and are available via "interface testsummarize". The options depend completely on the interface being tested, and can be used to provide necesary parameters or to allow the exlusion of certain tests.

interface testsummarize

Returns a summary of previous "interface test ..." runs, and returns an error if some tests failed.

interface testclear

Clears the results of previous calls to "interface test ...".

AN INTERFACE IMPLEMENTATION

The interface package includes several Tcl commands to easily create an interface defining object. Just use these as indicated in the following example:

proc ::interfaces::interfaceName-version {option args} {
	interface::implement interfaceName interfaceVersion options $cmd $args
	interface::test desription script result ?arg ...?
	...
	interface::testend
}

interface::implement interfaceName interfaceVersion docfile options cmd args

implements the basic interface interface. It checks the method called in cmd and returns the appropriate answers to the basic interface methods. If cmd is test, the proc does not return, and the rest of the proc (that contains the tests) is executed. If you want extra options besides the basic interface methods, you should check for these before calling interface::implement. cmd must be the first argument given to the procedure. interfaceName and interfaceVersion are the name and the version of the interface to be defined. They should be the same as the those used in the name of the procedure. docfile contains the filename of the xml (tmml) documentation of the interface options must be a list consisting of an even number of elements. Each odd-numbered element in this list is treated as an option, and the following element in list is used asdefault value for that option. The options will be made available in the array opt. args contains the resulting arguments given to the proc, and should contain any options set by the caller.

interface::test desription script result ?arg ...?

Test one feature of the interface by running the code in script. This code will have access to the variables

object

object being tested for complience to the interface

opt

array containing options given to the proc

interface

name of interface being tested

version

version of interface being tested

Some extra arguments arg can be given with the following meaning:

error

The test script must cause an error (result must match the error message returned)

skipon condition

The test will be skipped if condition is true

match

use string match instead of == to check whether the pattern result and the result returned by script match

regexp

use regexp instead of == to check whether the pattern result and the result returned by script match

interface

name of interface being tested

version

version of interface being tested

interface::testsummarize

should go at the end of the defining proc. Returns an error and an appropriate error message if there were any errors.

SEE ALSO

interface_interface

KEYWORDS

• interface
• interface::interface
• interface::implement
• interface::test
• interface::testsummarize

Peter De Rijk

hosted at