Concerns about addSlot: idioms

[Brian Rice]

It became apparent recently to me that the basic slot-manipulation  
methods are not quite appropriately named. I'll go over this and  
hopefully reach some conclusion or at least make the issue clear  
enough to get some good feedback.

First, I'll kind of lay out the basic idea. The manual also covers  
this here:
http://slate.tunes.org/doc/progman/ 
node7.html#SECTION00041200000000000000

- objects have slots which map symbolic names to values.
- methods can be defined to access and update those values.
- Basic methods:
   addInvisibleSlot:valued:
	makes a slot, without an accessor or mutator method.
   addImmutableSlot:valued:
	same, but it makes an accessor method.
   addSlot:valued:
	same, also with a mutator method.
   addImmutableDelegate:valued:
	an immutable slot that delegates.
   addDelegate:valued:
	same, with a mutator method.
(There's also:)
   addLazySlot:initializer:
	immutable slot, runs a block when you first ask for the value and then
	caches it.

Now here's what the manual doesn't tell you:
- It's usually not needed to call any of these in your own code,  
because...
- There are higher-level prototols:
   ensureNamespace:&delegates:&slots:
	makes a Namespace if there isn't one already, and adds immutable  
slots with
	the given type-specs.
   addPrototype:derivedFrom:
	makes a new prototype+traits, specifying super-types
   define:using:
	runs a block to make a value for an immutable slot, if not defined  
already.
   define:
	wraps define:using: OR addPrototype: depending on whether you use
	&slots: or &parents: (for addProto...) or &builder: (for using:).
	"define: #name -> value" also works.
	In any case, it makes an immutable binding (which can be re-bound  
smartly).
	The &slots: arguments result in mutable slots as of now.

So, which to use? define: in nearly every case. But the manual  
doesn't make a point of this, and it's totally understandable when  
the user thinks "I need to attach this result to some object/ 
namespace so I can keep using it" => "I'll ADD a SLOT to here." =>  
"The language must want me to call addSlot:, right?".

Well, yes. But maybe it shouldn't lead you that way - making mutable  
slots. Maybe addSlot: should do something different. Maybe the manual  
needs to start from define: and then dig down into things.

Notice that if I go from least to most complex selector for slot- 
addition (what the manual does), I get:
addSlot
addImmutableSlot
addDelegate
addImmutableDelegate

This on retrospect doesn't have much logical order to it. If I had to  
pick a decent principle for rationalizing some documentation path,  
I'd probably go for "progressive disclosure" where an overview is  
given and then progressively dig down

Maybe a "jump start" Slate tutorial would go from the bottom up to  
make a slot structure and the stuff that goes on top. The result  
though would be learning the nuts-and-bolts just to get to the actual  
protocol you'd use, and then toss out what was just presented.

There's another idea I've had, which is to use a symbolic-array-based  
format to specify slot attributes when declared. I'll try to  
summarize that later.

Right now, I'd just like to know what people make of all of this.

--
-Brian
http://tunes.org/~water/brice.vcf

-------------- next part --------------
A non-text attachment was scrubbed...
Name: PGP.sig
Type: application/pgp-signature
Size: 186 bytes
Desc: This is a digitally signed message part
Url : /archives/slate/attachments/20060312/dc7bcfc4/PGP.pgp