[augeas-devel] Creating a custom lense

[David Lutterkort]

On Wed, 2008-04-23 at 22:33 +0100, Dean Wilson wrote:
> On 23/04/2008, David Lutterkort <dlutter at redhat.com> wrote:
> >       * The definition of sep_ws was enclosed in '[ .. ]' which created
> >         a bunch of spurious nodes with NULL labels (the reason I use
> >         that construct for toplevel comments in hosts.aug and similar is
> >         a little subtle, and has to do with how comments are preserved
> >         when entries are deleted; it's probably the most arcane aspect
> >         of writing lenses. I need to describe that better ;)
> 
> OK, I'll be careful when I do that next time. Must not cargo cult.

You didn't have much of a chance since I haven't documented that very
clearly: when you use 'del' to omit spaces/comments etc. from the tree,
Augeas needs to key them off something so that it knows which exact
strings to restore when it writes the file back out. That key is the
label of the closest enclosing '[ .. ]' construct in which the 'del'
lens is used. So that deleted string lives as long as that node is
around, with the added complication that multiple nodes can have the
same label, and the spaces for them are put on a list keyed off that
label. When the file is written out, info about spaces/comments is
popped of that list one after the other.

You can see some of that behavior if you write an /etc/hosts file with
an entry that has several aliases, and separate them with different
amounts of spaces (say 4 between the first and second, 8 between the
next two etc) Then, in augtool, insert a new alias at the front of the
list of aliases:

        augtool> ins alias before /files/etc/hosts/1/alias[1]
        augtool> set /files/etc/hosts/1/alias[1] new
        augtool> save
        
What you'll see is that all the aliases for that entry have shifted one
to the right, with the first one now being 'new', and the last two
entries separated by a single space (the default for that separator)

The way the 'record' lens in hosts.aug is written, the space before each
alias belongs to that alias node in the tree, and if there are multiple
alias nodes, the spacing is restored from left to right.

With toplevel comments in files, you usually don't have a good
association between the comments and the entries before or after them.
To make those comments entries with their own lifespan, I usually
enclose them in their own treenode, '[ del ... ]', which constructs a
tree node with a NULL label and value, that is solely used to remember
where comments were in the file. The API hides tree nodes with NULL
labels, so you can't ever get to them from augtool. For example, if you
delete every entry from /etc/hosts with 'rm /files/etc/hosts/*' and
save, you'll be left with an /etc/hosts file with only comments in it.

> >  The way you fixed it is the right one: just have one lens 'comment' that
> >  matches actual comments and blank lines.
> 
> For the archive, this doesn't preserve blank lines though so you end
> up with a much shorter config file in some cases.

That's bad. Try changing one entry in one of those files to the value it
already has and then save. You should get a new file, and it should be
character-for-character identical to the original file, everythign else
is a bug. You have to make some modification to the tree to cause Augeas
to write a file at all; that's so you don't get spurious mtime changes
just because Augeas read a bunch of files and wrote changes to one of
them back.

> One that does stick out to me - why the {} {} {} in the
> test_aptsources.aug file?

Those are the comment nodes with NULL label and value.

David