wongkc@sor.CS.ColoState.Edu (kam chooi wong) (03/09/90)
I was using the ENVIRONMENT class in Eiffel and discovered some
misleading/incorrect descriptions in the Eiffel Language Manual.
On page 188, the example code shows in order to store
persistent objects and associate them with an environment,
....(env and ext_file declared here)
env.Create; -- create an environment
ext_file.Create("session1.S"); -- create a file to be
-- associated with the environment
ext_file.open_write;
env.set_file(file1); -- associate file with environment
env.store_on_end;
....(some other manipulations)
(1) The suffix ".S" as in the "session1.S" file should really
be ".ENV". The file1 variable listed above in the example
should really be ext_file.
(2) There is no information in the Language manual or in the
Library manual that hints at the required ".ENV" suffix.
I had to look at the online ENVIRONMENT.E code file
under the installed Eiffel's library/support subdirectory
to find out why I got the run-time error in my own
program. One of the preconditions (in the require clause)
of the set_file feature in class ENVIRONMENT is good_suffix
which is an instance of the boolean routine is_env_of(f: file).
A short on the class ENVIRONMENT does not reveal the
precondition "good_suffix" nor the "is_env_of(f)" routine
as this is a non-exported feature.
If I am missing something altogether, I appreciate people letting
me know. Otherwise, I would like to suggest that there should be
some documentation on such "secret" required features and their
semantics in the relevant chapters in future updates of the manuals.bertrand@eiffel.UUCP (Bertrand Meyer) (03/09/90)
In <5193@ccncsu.ColoState.EDU>, wongkc@sor.CS.ColoState.Edu (kam chooi wong) notes an undocumented rule enforced by the current implementation: files used to store persistent objects (through the mechanisms of class ENVIRONMENT) must have a name finishing with ``.env''. He is indeed correct. Although the rule initially had a justification, it should by now have been dropped. This is a case where the documentation was updated ahead of the software itself... For the time being environment files still will have to have ``.env'' names. Our apologies for any inconvenience this may cause. -- -- Bertrand Meyer bertrand@eiffel.com
olender@cs.colostate.edu (Kurt Olender) (03/10/90)
The case of the undocumented ".env" file extension reveals a more
general point.
When a "require" clause of an exported routine contains a non-exported feature
(say a boolean function that computes a rather complex condition on the input
to the routine), "short" does not print that require clause. That is how
short is documented to work, and it indeed does.
Thus, the automatic documentation mechanism will not record in it's public
interface what may be a rather important restriction on the form or
values of some input data. Certainly, if a call violates this restriction
the client will fail, but the client programmer will have no idea why
without looking at the original source. He or she may see a message generated
from a require clause label, but that label does not appear in the short
output either.
On the other hand, the client programmer doesn't need to know the names
of features that aren't public, and can't use.
perhaps short should print the label of any require clause containing
a private feature. The output of short environment.e might then look
something like:
require
once_set;
file_created: not f.Void;
good_suffix
do
presumably, then, the programmer must use some descriptive name for
the preconditions.