[augeas-devel] Finalizing the API

[David Lutterkort]

I haven't officially committed to having the Augeas API in augeas.h
stable, but I want to do that with the next release. There is one change
I want to make to the API: merge the aug_get and aug_exists call into
one

        int aug_get(augeas_t aug, const char *path, const char **value)

where the return value is the same as the one from current aug_exists,
and, if VALUE is non-NULL, *VALUE will point to the value associated
with PATH after the call.

There's two more things in the current API I am not entirely happy
about, but also not unhappy enough to try and change them: (1) aug_match
allocates and returns an unbounded number of paths, but I think that is
not that big an issue, and can be addressed with additional calls. (2)
having aug_print is kinda odd, but since I envision it mostly being used
for debugging etc., it's probably not much of an issue, either.

With that addressed, the API guarantee would be
      * the current calls will stay around with their current behavior
        indefinitely
      * path expressions will maintain their current semantics, and '//'
        and '**' in path expressions are reserved for future extensions
        (for recursive searches over the tree like
        'match /augeas/files/**/error')

The other sticky issue about API stability is that the schemas and where
they map things into the tree is also part of the API; I'd like to have
some sort of convention for making it clear what schemas are stable and
won't change and which ones are experimental. 

There's also the issue of documenting schema - it would be easy enough
to generate something like Relax-NG from lenses, but I am not sure how
useful that is. The main point of schema documentation is to make it
easy to determine where in the tree values from files show up (e.g. that
the third alias of the second host from /etc/hosts is
in /files/etc/hosts/2/alias[3])

does anybody have ideas/opinions about any of these ?
David