Home printable version

Possible API changes

In the Development Roadmap, I talked about the API changing between now (version 0.7.5) and version 1.0

What might those changes involve?

Below I list some some areas of concern for me. I am sure there are others as well.

If you have any ideas or opinions for how the API should look, now is the time to have your say. The API will be fixed as at version 1.0. Any feedback is welcome.


The whole Offsider framework grew out of an earlier project, which was modelling simple key/value lookup tables (ie, dictionaries). That is why the term Dictionary keeps cropping up. It also explains why so much of the software has Dictionary in its name.

Unfortunately, the use of Dictionary no longer makes sense, and is a bit confusing. I plan to remove Dictionary from Offsiders, and replace it with some other name. Obvious possibilities are Offsider or offsider.

This represents a major change, since it impacts on pretty much ALL offsider code. For this reason, it is likely to happen very soon. done version 0.8.0

When Dictionary is used within a method definition, it has the meaning of this, so there is also an argument for having this as an alias for Dictionary. (some languages also use Self or self) done version 0.8.0

Obviously, methods like addChildDictionary will need to be renamed as well.

Keys, Methods, Attachments

Any offsider can have keys, methods and attachments. For each of these, there are a number of methods that allow you to retrieve or update the values. For example, we have getKey, setKey, appendToKey, pipeKey, keys, hasKey and so on.

In fact we have an equivalent set of methods for each type.

Obviously, one thing we need to do is make sure that the methods have similar names across the three types.

In addition, however, it suggests that we should be able to somehow factor out the similarities.

For example, we might be able to say

Dictionary set key foo value-for-foo
Dictionary set attachment foo2 value-for-foo2
Dictionary has method blah
Dictionary has attachment baz
Dictionary list key(s)


The error system works fairly well, but I think it should be possible for each object to store its own private error messages. This does not neccessarily require a change to the underlying framework, because each object can override the Error method anyway, and we can just create a clonable template for objects that require their own private errors. Nevertheless, I want to look at this a little more closely.

Also, I think the name for Dictionary.error.dy stinks and should be changed.

There is also a housekeeping issue here. There are lots of error keys used throughout the framework, but no associated entry in Dictionary.error.dy . Those missing keys need to be tracked down, and the entries added.

Construct and Initialise

We have a number of different methods for creating new dictionaries. We have create, clone, addChildDictionary, createStandard and so on.

We need to look at all of these methods and factor out the common elements as separate methods.

The ObjectiveC programming language has a nice paradigm which should work here. It has separate phases for constructing a new object, and then initialising it.

In addition, we often need to create a named executable.

Once we have the refactored methods, it should give us a lot more flexibility in coming up with new ways to create objects.

Method name consistency

In general, we need to go through the entire API and make sure that, where possible, we have consistency in naming.

We should also look at related projects, like QueueReader, Weave and Tree and retain the same consistency there.


The current baseDirectory is stored in an environment variable $DICTIONARYBASE.

It would be preferable if this was changed to $BASEDIRECTORY. done version 0.8.0


When you override a default method, you often want to call the default method as part of that. In many programming languages, you can do something like super() to achieve this.

It is not obvious how this can be done for offsiders (see the ObjectHelper template for one way to do this), but would prove very useful if we can find some intuitive solution.

(20100210 11:15:13) This page was produced using rsml. Source file was whatAPIchanges