Re: Config_Files proposal

[Stephen Leake <stephen.a.leake.1@gsfc.nasa.gov>]

Darren New <dnew@san.rr.com> writes:

> Stephen Leake wrote:
> > Note that we are only voting on the general file format. The remaining
> > details of the file format (like how to represent comments) and spec
> > will be worked out later.
> 
> I think this is kind of the wrong way around. Asking which of two completely
> different file formats is better, and then trying to build an API based on
> that, seems backwards.

That isn't what I meant to say :). The API _is_ orthogonal to the file
format.

What I meant to say was that I'd like to decide now whether we will go
forward with Java properties style or XML (or possibly some other
format). Given that choice, there are still (minor) issues to decide
about the file format.

In addition to that decision, there are decisions about the package
spec to be made. Note that the file "grace-config_files_java.ads"
is a package spec that could easily have a body that uses an XML file
format. I should have used a different name :(.

> That said, there's some things missing from the spec:
> 
> 1) When you read three config files off the path, change a value that was in
> the second one, and write it out again, where does it get written?

I tried to answer that in requirement 10, but I can see it isn't very
clear.

The intent is that only one file be writable, and that is where all
values are written.

For example, if you open ~/.myconfig (writable), /usr/local/app/config
(readonly) and /etc/app/config (readonly), then any values you change
are written to ~/.myconfig.

> 2) Can you have a "local" and a "global" config file, such that
> changes to the local override the global, but it's possible to have
> only some of the information in the local file? E.g., the system
> administrator says "the mail server is a smtp-server.example.com,
> but each user fills in his own "from" email address"?

Yes, but any values the user changes will be written to the local
file. Same example as above.

The final doc for the Config_Files library will have examples of these
use cases.

> 3) If you enable #2, and then the user changes her email address,
> does it also store back the mail server address, thereby preventing
> the administrator from changing it?

Hmm. I was going to say "no, the user did not change that value". That
is my intent. But my draft implementation does not follow that intent;
it writes all the values to the writeable (local) file.

I'll declare that implementation broken, in this respect. I guess I
need a "value changed since read" marker, and only changed values get
written. That's not bad. Then I have to enhance the unit test to test
this. That will be harder :).

The requirements need to be clearer on this as well.

Thanks for pointing this out!

Hmm. Now I think we need the queries "what file was this value read from"
and "what file will this value be written to".

> 4) If you have a list of items, such as a recent-file list, how are
> they managed? 

Given the current requirements and spec, you need a unique key for
each scalar item; foo.bar.item.1, foo.bar.item.2, ... foo.bar.item.n.

> Does it make sense to use [] notation or something?

I'm leaving that for a future enhancement. The biggest problem I have
with it at the moment is that it requires some notion of a "list" of
values an arbitrary scalar type in the Config_Files spec. This could
probably be handled with a generic or a tagged type or an
unconstrained array. At the moment, we have no explicit lists in the
API, which keeps things simple (the search path is a list in the body,
but not in the visible part of the spec). Since the same effect can be
accomplished via numbered keys, I don't think it's worth pursuing at
this time.

Hmm, I'm wrong. There is a requirement to return "a list of keys". I
guess that will be a list of strings. When I implement that, I'll
think about this issue again :).

> 5) Do comments go in the files? If so, how does that interact with
> the previous questions?

The requirements say we must support comments. Neither of my
implementations do so. That's one of the "minor" details that remain
to be worked out.

Once again, thanks for your insightful comments.

-- 
-- Stephe