This is Peter's interface package at http://tcl-dbi.sourceforge.net/interface/.
Please have a look! I think we tcler's should adopt this methodology for packages. The following excerpts are taken from CLT.
Here is my initial cry for help where Peter replied with his solution:
I would like to be able to grab a script library/package that could beimplemented separately in both Tcl procedures and/or an object-
orientated system such as [itcl] or allny the others. I'd like to define
the interface and then be able to use whoeversany package that implements the
interface wusithng twhateiver technology ofit choicoses. I haven't thought through
this very much but I think if we can cleanly define an interface, have
a standard so that many systems(snit,stoop,...) can be used toimplement the interface , andwith the interface User being able to handle
it(these drop in replacements), we will get more libraries of cool SW.
I have wrestled with a file buffer library for a little text editor of
mine. It started out as an library of routines to process/manage many
open buffers of text. It has lots of functions and was gettingunweieldly. I next wrote it in itcl or base parts of it and it was much
slicker. I have not taken the time to integrate it into my old systembecause it was not designed as a drop in replacement, nor was the
application. Had I followed some standards I could have easily done
this. I suspect we all could get more code in our hands and offload
work to others if we some standards out there.
art
----
======
# Example using interface package definition
package require interface
proc ::interfaces::stack-1.0 {option args} {
set interface stack
set version 1.0
switch $option {
interface {
# This is an interface defining object, so it supports the interface interface
# This code will advertise this fact
if {[llength $arg]} {
if {[string equal [lindex $args 0] interface]} {
return 0.8
} else {
error "::interfaces::$interface-$version does not support interface interface"
}
} else {
return [list interface 0.8]
}
}
doc {
# return xml documentation
return $::stackdock
}
test {
# run some tests on an object supposed to support the interface
set len [llength $args]
if {$len < 1} {
error "wrong # args: should be \"interfaces::$interface-$version test object ?options?\""
}
set object [lindex $args 0]
array set opt [lrange $args 1 end]
# the testleak is needed due to a small bug in the interface::test routine
set ::interface::testleak 0
interface::test {interface match} {
$object interface stack
} $version
interface::test {push and pop} {
$object clear
$object push 1
$object pop
} 1
interface::test {push, push and pop} {
$object clear
$object push 1
$object push 2
$object pop
} 2
interface::test {stack empty error} {
$object clear
$object pop
$object pop
} {stack empty} error
# more test should follow
interface::testend
}
}
}
# implementation of "object" implementing the interface
# this is of course just a test case for demonstrating interfaces,
# and not a real object, nor a good or even reasonable implementation
proc stack1 {option args} {
global stack1_data
switch $option {
clear {
set stack1_data {}
}
push {
eval lappend stack1_data $args
}
pop {
if {![llength $stack1_data]} {
error "stack empty"
}
set result [lindex $stack1_data end]
set stack1_data [lrange $stack1_data 0 end-1]
return $result
}
interface {
set interfaces {stack 1.0 nop 0.0}
if {[llength $args]} {
set reqinterface [lindex $args 0]
foreach {interface version} $interfaces {
if {[string equal $reqinterface $interface]} {
return $version
}
}
error "stack1 does not support interface $reqinterface"
} else {
return $interfaces
}
}
}
}
# test if stack1 does indeed comply with the stack-1.0 interface
interface test stack-1.0 stack1
# return documentation
interface doc stack-1.0
# It will usually be placed in a file in a doc directory, so it can also be
# used to generate man pages, etc
set stackdock {
<manpage package="interface" title="stack_interface" id="stack_interface" cat="stack">
<namesection>
<name>stack_interface</name>
<desc>description of the stack interface</desc>
</namesection>
<section>
<title>DESCRIPTION</title>
a very simple demonstration interface
</section>
<section>
<title>THE STACK INTERFACE</title>
<commandlist>
<commanddef>
<command><cmd>objectName</cmd> <method>clear</method></command>
<desc>clear the stack</desc>
</commanddef>
<commanddef>
<command><cmd>objectName</cmd> <method>push</method> <m>value</m> ?<m>value</m> ...?</command>
<desc>push value(s) on the stack</desc>
</commanddef>
<commanddef>
<command><cmd>objectName</cmd> <method>pop</method></command>
<desc>get values from the stack</desc>
</commanddef>
</commandlist>
</section>
<keywords>
<keyword>stack_interface</keyword>
</keywords>
</manpage>
}
======
----
Wow !!! this is exactly what I was thinking of. Looks great !! Would
you consider this going into the tcllib ? I see the interface test is
not replacing a test package for the implementation object. Since the
interface namespace is a separate both implementing procedures and
objects can implement it. It is not native inside the OO system so it
will work generically for everything. I am not too familiar with XML
yet. How would you render this documentation ? Maybe you could add to
the demo an implementation in some OO system or ask for others to
provide one for their OO system of choice.
* Of course I would not mind getting this in tcllib, but I have no idea how stuff gets in it.
* interface test is indeed not a replacement for a test package for the implementation object, but is meant to be used in one. An implementation can support several interfaces, so a typical test package will invoke interface test for all supported interfaces, and maybe add some tests specific to the object.
* The whole idea of the interface package is indeed to be as generic and implementation agnostic as possbile (cfr. the extremely simplified example)
* tmml (http://tmml.sourceforge.net/) contains some tools to convert the XML to man pages or html. (I got the CVS version)
art morel
----
[LV]: wrote:
Stuff gets into [tcllib] in at least two ways:
* someone who has '''written''' some software signs up to be a http://tcllib.sf.net/ developer, talks to the other developers on the tcllib-dev mailing list (to get pointers to guidelines, confirm namespace choices, etc.), and then checks the code, with doc, tests, etc. into the cvs
* someone who has written some software evangelizes someone who is already a tcllib developer to do the work for them - or at least gets them enthusiastic enough about the package that the newly recruited convert does the work for the software creator.
However, my understanding is that the intent of the tcllib/[tklib]
maintainers is to prevent someone from just including arbitrary code from the
internet/wiki/etc. into tcllib. The orignal author needs to be involved
in some capacity, including, hopefully, further maintenance. If not that,
someone needs to step forward in that capacity.
According to Peter.DeRijk <mailto:[email protected]>:
- Of course I would not mind getting this in tcllib, but I have no idea
how stuff gets in it.
----
Any takers to help get this package to sourceforge then into tcllib?
----
[Lars H]: More concretely, one can initiate getting something into tcllib by filing it as an RFE for the tcllib Sourceforge project. However, for anything to go into tcllib it needs documentation or tests, preferably both. The standard documtation format for tcllib is [doctools].
That said, I don't get the point of this interface thingie. Is it supposed to be some kind of support for abstract packages (call for a package, and don't worry about what piece of code feels like implementing it), or what? Doesn't [package] already do that?
<<categories>> Package