Defmod Extension

[Jonathan Coxhead]

On 1 Nov 00, Tony van der Hoff wrote,

 | On Tue, 31 Oct 2000, at 11:38:39, Jonathan Coxhead
 | <jonathan at doves.demon.co.uk> wrote on the subject "Defmod Extension":
 | 
 | >   Tony wrote ...
 | >
 | > | 1. I propose to extend DefMod to accept macro definitions in swi files,
 | > | so that I can define some macros to use for filling in the various
 | > | offset fields in (for instance) toolbox object templates.
 | >
 | >   Could you describe what you want to achieve by the change in more detail?
 | >
 | Yes, please forgive me if I'm telling you things you already know ;-)
 | 
 | The toolbox modules define templates, which describe an object. These
 | are used both in the res file, and in in-memory object descriptors.
 | Whilst I have hit the problem specifically in generating resource files,
 | it also applies to in-memory resource generation.
 | 
 | These templates consist of a standard header, followed by an object-
 | specific part.
 | 
 | The header part is defined by OSLib as:
 | TYPE
 |    Toolbox_ResourceFileObject = .Struct
 |    (  Toolbox_Class: class_no,
 |       .Bits: flags,
 |       .Int: version,
 |       [Toolbox_NameLimit] .Char: name,
 |       .Int: size,
 |       .Int: header_size,
 |       .Int: body_size,
 |       .Int: object ...
 |    );
 | 
 | Here, |header_size| is the size of the resulting base structure, and is,
 | in fact the offset of the object-specific part from the beginning of the
 | structure.

   That's |offsetof (toolbox_resource_file_object, object)|.

 | |body_size| is the size of the derived structure; i.e. it includes the
 | object-specific members, but no string and message tables. 

   That's |toolbox_SIZEOF_RESOURCE_FILE_OBJECT (N)|, for some |N|. You can 
get |N| by looking at the |size| field, or "just knowing" what the size is 
(e g, because you've read it from the file).

 | Whilst it is easy enough for a programmer to calculate the contents of
 | these ints at compile time using (in C) |sizeof| statements, it is not
 | necessarily clear which structure to take the size of; particularly as
 | we have introduced a plethora of similar-looking structures with the
 | incorrect sizes. If he were to use sizeof(toolbox_resource_file_object),
 | he'd end up with a possibly incorrect offset to the data.

   I agree that that's a shame, but I don't think that introducing extra 
macros is going to help. We have here an "information overload" situation, 
and so introducing information is not necessarily going to help. I think 
I'd rather a situation where we marked everything that has a better 
interface as "Deprecated", maybe accompanied by a reference to the thing 
that supersedes it (like I've done with some SWI's, marked with a keyword 
of "prefer", to help searches and the like).
 
 | I would like to provide is a set of constants, which can be assigned to
 | these fields at runtime. Ideally, DefMod should perform this task, and
 | allocate the value to a CONST. However, it seems to me that this is a 
 | bit much to expect from DefMod (I would be pleased to be shown to be
 | wrong :-)

   No, you are quite right. That would be a major change, and involve 
DefMod processing NEEDS files itself. Though it's possible, it's not really 
a pleasant prospect.

 | best thing would be for the target language to do it. Hence macros -
 | hardly ideal, as you point out; show me the right way!

   I think documentation of the "approved" structures, and some nice 
examples that use variable-length objects, is the thing to do.

 | The neat thing about the SWI files is that they are language-independent
 | <snip>
 | That is true, but I felt that we'd already started drifting away from
 | that ideal by introducing macros for the ..._MEMBERS declarations. On
 | reflection, this was an incorrect assumption.
 | >
 | >[...]
 | >
 | Yes, you'll recall that I asked you a couple of weeks ago why we'd done
 | it that way. That wasn't your answer then ;-)

   Yes. Oops! It was certainly important at the time, it just slipped my 
mind subsequently.

 | Toolbox_Action was defined long ago, and is therefore immutable as a
 | name. When, for V6.0, we decided to separate out the header and extended
 | parts, we  called the definition, which includes the repeated member,
 | Toolbox_ActionHeader. Maybe this was not the right choice of name;
 | ideally it would have been Toolbox_Action, but we're stuck with it.
 | 
 | Unfortunately, the resultant |toolbox_action_header| structure contains
 | an [UNKNOWN] array of the repeated member, and as UNKNOWN evaluates to
 | 1, it is *not*, in fact, the required header. I'm assuming this was
 | deliberate, to support backward compatibility for other structs (such as
 | Wimp_Window), otherwise we could simply call it a bug, and fix it.
 | In any case, it has rendered the chosen name illogical, as it does not
 | correctly describe the use of the structure, and I think this is the
 | root of the problem.
 | 
 | Also emitted is our macro, TOOLBOX_ACTION_HEADER_MEMBERS, which does
 | contain just the header members. So, to fulfil the object of all this,
 | and get our required header, we need a new struct, just made up from
 | this macro. I've done this in cheader by simply taking the C name of the
 | defined struct (i.e |toolbox_action_header| ), and suffixing it with
 | |_base|, which results in the ungainly and tautologous name
 | |toolbox_action_header_base|. 
 | 
 | In the case of Wimp_Window, we get a wimp_window_base, and all looks
 | fine. So, unless you can see a better way, I think we're stuck with the
 | silly name.

   I think you are right. My habit, when trying to deprecate interfaces, is 
to use a shorter name. It's hard to get much shorter than "action" though! 
But it would be possible--Toolbox_Act? Then use |toolbox_act| and 
|toolbox_ACT_MEMBERS| everywhere; and define all existing toolbox_action 
types in terms of those, and deprecate them?

   Ick!

        /|
 o o o (_|/
        /|
       (_/