CoCoA » CoCoALib

John Abbott wrote:

Here are some ideas about how we might achieve a reasonable design:

• obsolete/obsolescent fns go into 2 files obsolete.H and obsolete.C (or obsolescent.H???)

I prefer obsolescent, as in CoCoA-5 (maybe we can have obsolete for afterwards)

• have a compilation flag (perhaps CoCoA_OBSOLETE) which make the contents of obsolete.H visible only when set

CoCoA_NO_OBSOLESCENT

• perhaps have a global run-time flag which says whether to allow calls to obsolete fns; this flag would then be checked in every "forwarding fn" in obsolete.C, throwing an error if calling is forbidden.

I think that obsolescent function should available and working, but just printing an evident and helpful warning (as in CoCoA-5).

Maybe this is too complicated? KISS?

I would like to have an easy way of being sure that my code is "clean" (i.e. does not call any obsolete fns).

Just compile with CoCoA_NO_OBSOLESCENT ;-)

John Abbott wrote:

I have a first implementation (but called the file obsolete.C since I find "obsolete" easier to type than "obsolescent"). I can rename the file if you want... I have not yet checked in.

I prefer //obsolescent// because it is compatible with the same idea in cocoa-5 and also because we still allow them for some time.
Later we could have also //obsolete// for those definitely out (just returning useful error)

I am unsure about printing out a warning message each time an obsolete fn is called. I know it is what we do in CoCoA-5. Currently, either the fn is called silently (if the user has set the global flag for allowing obsolete fns), or an error is thrown.

I think we should also have the warning. Maybe we could have a global counter for each function (too bad for parallel misbehaviour) giving the error only the first time.
This way a user will get his result anyway and all possible warnings.

I suppose it could be useful to have an easy way of knowing all obsolete fns which have been called...

the counter? a registry?

Anyway let's start with the KISS approach.

I have checkedin the relevant files. The new files are called obsolescent.H and obsolescent.C.

CoCoALib is always built with the obsolescent fns; only the declarations in the header file appear/disappear depending on the setting of the compile-time/preprocessor flag. Currently the preprocessor flag is called CoCoA_OBSOLETE but I shall change that shortly.

My preference is that obsolescent fns remain invisible by default; the user must do something to make them visible. So probably the flag name could be something like CoCoA_ALLOW_OBSOLESCENT.

Should it be a simple flag? Undefined means "forbid calls to obsolescent fns", and defined means "allow calls to obsolescent fns".
Or perhaps something slightly more refined? When defined the value says what to do when calling an obsolescent fn:

• (A) do nothing special, just call the proper fn
• (B) print out a warning that fn has been called, then call the proper fn
• (C) throw an error (perhaps saying which obsolescent fn was called)

I'll change the current impl so that it does (B) rather than (A).

John Abbott wrote:

My preference is that obsolescent fns remain invisible by default; the user must do something to make them visible. So probably the flag name could be something like CoCoA_ALLOW_OBSOLESCENT.

Should it be a simple flag? Undefined means "forbid calls to obsolescent fns", and defined means "allow calls to obsolescent fns".
Or perhaps something slightly more refined? When defined the value says what to do when calling an obsolescent fn:

• (A) do nothing special, just call the proper fn
• (B) print out a warning that fn has been called, then call the proper fn
• (C) throw an error (perhaps saying which obsolescent fn was called)

CoCoA_OBSOLESCENT_SILENT
CoCoA_OBSOLESCENT_WARNING
CoCoA_OBSOLESCENT_ERROR

Perhaps we do not need any preprocessor flag. What about the following approach?

The file library.H does not include obsolescent.H (this requires a small change to MakeUniversalHeader.sh).
A user who wants to access obsolescent fns must include both CoCoA/library.H and CoCoA/obsolescent.H.

This seems to be a very KISS approach; what do you think?

John Abbott wrote:

Perhaps we do not need any preprocessor flag. What about the following approach?

The file library.H does not include obsolescent.H (this requires a small change to MakeUniversalHeader.sh).
A user who wants to access obsolescent fns must include both CoCoA/library.H and CoCoA/obsolescent.H.

This seems to be a very KISS approach; what do you think?

I think obsolescent should be included by default (we are doing that to help the users).
For when we developers compile we can/know disable it.

I really do not like the idea of including obsolescent fns by default: in what sense would they be obsolescent?

Is it really too much to ask the user to add just one line to their file: #include "CoCoA/obsolescent.H"

Having a preprocessor flag determine the visibility of the obsolescent fns would make it "obligatory" to recompile the whole library after changing the compilation flags. Perhaps a workaround would be possible, but I'm not willing to do it.

When a user wants to check whether all calls to obsolescent fns have been removed, it is enough just to comment out the include directive for obsolescent.H at the start of the user's source file, and then recompile just that file -- no need to recompile CoCoALib.

Note that CoCoALib (i.e. libcocoa.a) always contains the obsolescent fns; they become "visible" only when the user includes obsolescent.H.

I really do feel that this is the right approach (i.e. put an extra include in the user's source file). It is even possible for the user to combine files which need obsolescent fns and those which do not (and the include directive makes it clear which files use them).

John Abbott wrote:

Is it really too much to ask the user to add just one line to their file: #include "CoCoA/obsolescent.H"

ok

Also added doc/txt/obsolescent.txt (with relevant changes to the index files).

Perhaps Anna could check what I've written?

Also done some cleaning to obsolescent.C.