Are you confused/bored/annoyed by class-based object systems? Then shelf might be the system for you!
shelf provides the functionality needed to work with namesace ensembles as objects in a prototype-based object system. In this documentation, the word prototype signifies the namespace ensemble that is the handle for the object. The ensemble map defines the interface, and it is expected that all methods are called through the ensemble, even when called by other methods bound to the same prototype. Because of this methods usually take the name of the ensemble as their first argument, although this is just a convention. shelf won't be offended in the slightest if the name of the ensemble is passed in some other position, or not at all.
shelf arranges for the ensemble's namespace to be deleted when the ensemble is deleted.
The code footprint of shelf is quite small, and that's partially because components of it have been refactored into other components of ycl. ycl dupensemble provides the ability to produce new namespaces based on a prototype namespace, and ycl var provides methods such as $, $.exists, and $.locate for reading variables up the hierarchy of a prototype.
A prototype has a prototype method that can be used to access methods and attributes in prototypes from which the current prototype was derived.
shelf does not currently utilize TclOO, but it certainly might in the future.
Built-in Methods
The first argument to all built-in methods is the name of the ensemble, and is not noted in the descriptions here.
$name
Returns the value of the first variable named name in the hierarchy for the prototype.
$.locate
Returns the fully-qualified name of the first variable named name in the hirarchy for the prototype, or an error if a matchin variable is not found.
$.exists
Like $.locate, but returns a boolean, indicating whether a matching variable was found.
~
Executed just prior to the deletion of the ensemble.
asmethodspec
spec is a method specification of the form
argsobjvarsnsvarsbody
Where args and body are the standard arguments to proc. objvars, is a list of names of variables that belong to the prototype, and nsvars is a list of names of variables in the namespace in which the procedure will be defined. asmethod transforms body such that variables objvars and nsvars are linked in the local scope of the procedure to the appropriate variables. This allows the procedure body to be written in an a manner that is agnostic to the particular object system in use, since it need only concern itself with local variables. Other object systems may use the same spec, linking the local variables as appropriate for that system.
shelf uses this internally, so an example, although a bit convoluted at the moment (the refactoring is in progress), can be found here
evalscript
Evaluate script in the namespace of the ensemble.
init
Executed by new. The default init does nothing. Provides a convenient hook for customing the initialization of a newly-created prototype.
methodcmdname
Register a command as a method of the ensemble by adding it to the map and arranging for the fully-qualified name of the ensemble to be passed as the first argument to the command. method does not transform the command in any way, but it must already exist.
newname
Create a new copy of the prototype. If name is the empty string, automatically select an appropriate name. Returns tkjhe name of the new prototype.
ns
Returns the name of the namesapce associated with the ensemble.
ondeathscript
Arranges for script to be evaluated in the global namespace when the ensemble is deleted. This command is currently additive. with no way to delte any already-registed scripts, except by using trace directly. It isn't anticipated that such a feature would be needed, but it could be added at some point.
prototype
Returns the name of the prototype upon which the current prototype was based.
subcmdcmdname
Like method, but doesn't arrange for the name of the ensemble to be passed as the first argument to the command.
Built-in Prototypes
glass
a prototype configured such that any command in its associated namespace reachable as a subcommand prototype.
shelf
The mother of all prototypes, including itself.
Example
shelf new swallow
swallow $ airspeed 9
proc fly _ {
upvar 0 [$_ $.locate airspeed] airspeed
puts "$_ is flying at a speed of $airspeed!"
}
swallow method fly
swallow fly
swallow new european
european $ airspeed 11
european $ airspeed ;# -> 11
european fly