[Xotcl] A problem, Parameters and Documentation

[Kristoffer Lawson]

I have a problem where I have many classes which would have a lot of very
simple methods to set/get certain attributes. The simplest way is to have
lots of instprocs, but that's a lot of cut&pasting as each one is almost
the same. Now I'm sure you're all thinking "parameters". Well, originally
I thought that would work, but it seems I have misunderstood the parameter
documentation. You see, simple parameters wont work. I need the
automatically created instprocs to do more than return an instvar. I
originally thought that extending Class::Parameter might work, but it now
seems that this might not be the case. So what I'm looking for is
input and ideas from anyone who cares to share them. In addition I
have some comments and questions about XOTcl itself.

I'll split this discussion up into a few sections.


1. Parameter Documentation.

The bit about extending Class::Parameter at
http://media.wu-wien.ac.at/doc/tutorial.html#parameter wasn't exactly
clear to me. Especially the line:

C c1 {{a -default 1 -someInstproc x} ...}

I still can't quite work out what that line is actually doing. Is C a
class creating an object called c1? Is it a meta-class creating a class
object c1? And in both situations wouldn't the argument just be sent
as-is, so no parameter handling?

I now understand (after playing around in the shell), that when using the
"parameter" method I can additionally specify methods to call in the 
used parameter class. However, this is not immediately clear from the
tutorial. In addition it does not mention what arguments are sent to this
procedures and which object receives the messages (I worked it out by
testing). In addition I would like to know the calling order. If I use a
parameter line like {{a -default 1 -someInstproc x}}, is the parameter
"a", and the method for it, created after or before the call to
someInstproc? It appears to be after.

The role of Class::Parameter is not quite obvious either. It is used to
set the default, but am I correct in understanding that it does not
actually handle the creation of parameters or their methods? Does it do
anything else? Another interesting thing I noticed: when -someInstproc is
called above [self callingobject] returns an empty string inside the
proc. I could've used that to override the normal method created.


2. My problem in more general terms

If I look at my situation from a wider perspective the need I have is
to have an interface that looks like parameters to the developer using my
library, but which are handled differently internally. I want to easily be
able to allow a developer to do the following:

set textOb [Text new $root -enabled 1 -text "Hello, world\n"]

As mentioned, that is easy to do by providing the methods "enabled" and
"text", but as each one is exactly the same I would like a mechanism that
is like the parameter one, but handled slightly different internally. In
the ENIÄK system those would be referred to as attributes, and the methods
basically just translate them to ENIÄK commands.


3. Some solutions

1) Cut&paste. Well, it does the trick, but it's a bit bothersome.

2) Code generation from a separate script. Ugly, hacky and experience
shows that it's awkward to maintain.

3) For loops. I could create a whole bunch of similar instprocs for
each class in a for loop (hooray for script programming). But it might not
be quite obvious to anyone reading the code, plus do I lose the
possibility of using xoDoc documentation?

4) Metaclasses. I could create an EniakClass metaclass, which provides
each class with a method to create instprocs easily. It would look like
the parameter mechanism except that instead of specifying -parameter when
creating a class, I could use -attribute. I do not wish to override the
parameter method as I use normal parameters as well. That of course means
changing a lot of classes from being instances of Class to instances of
EniakClass. Still, all in all not a truely horrible solution.

5) Something else?


4. XoDoc

With solution 4) above I have the issue of using xodoc and that
"-attribute" method invocation when creating a class. Xodoc obviously
does not understand that. So I would still like to see a documented way of
extending xodoc -generation dynamically on an application level so that
certain metatags in certain contexts would generate certain output for
different target platforms (ie. something for Html, something for XML
etc.). Probably something to keep in mind with future releases.


5. Spoiling all the fun

Some of my attributes will most likely have to be handled specially
anyway. For those I will just have to make their own procedures. Mostly 
these specially handled ones are the kind where I don't necessarily
want the developer to specify attribute values directly (as some of the 
protocol attribute values can be cryptic, so I want to map them to
clearer forms). The downside to this model is that while they appear the
same to the developer they will be implemented (and probably
documented) differently than the ones created in the generic way. So am I
stuck?

         -     ---------- = = ---------//--+
         |    /     Kristoffer Lawson      |  www.fishpool.fi|.com
         +-> |    setok at fishpool.com       |  - - --+------
             |-- Fishpool Creations Ltd - /         |
             +-------- = - - - = ---------      /~setok/