[augeas-devel] Augeas and contextual help

[David Lutterkort]

On Wed, 2010-11-17 at 22:42 +0100, Raphaël Pinson wrote:
> I see at least two ways of providing such help. One way would provide
> help on a node level. Using augtool, a user would type something like:
> 
>    $ info /files/etc/passwd/root/password
> 
> and get a description of this node. The description would include:
> 
>   - the lens name (in that case Passwd) ;
>   - the regexp for the node label (in that case "password", as
> described in passwd.aug line 33)
>   - the regexp for the node value (in that case Passwd.word, i.e.
> /[A-Za-z0-9_.-]+/)

I like that a lot, we could even include some information on what child
nodes will look like.

There's a few things that need to happen to implement such an info
command: when constructing tree nodes in get_subtree in get.c, the node
needs to be annotated with the subtree lens. From that you could deduce
the regexps for label and value, and the structure of the child nodes.

To get to the point where we can also report variable names, we would
also have to annotate values in the interpreter in syntax.c; currently
lenses (or any other value the interpreter deals with) doesn't carry any
information about the name under which it was defined. For a construct
like 'let var = value', we'd need to write the name 'var' into the
struct info of the value.

> The aug_info call might also be used on a variable, such as:
> 
>   $ info Passwd.word
> 
> if I wanted to get more info on that variable.

For the tree based info, it makes sense to talk about regexps for label
and value; in the general case of getting info for a variable, you'd
need to deal with any value the interpreter knows about. Not impossible,
but a lot more work; e.g., what would the help for 'key /[a-z]+/ .
options*' be ?

But even covering a subset here would be very useful.

David