[augeas-devel] Determine which files to load dynamically (ticket #42)

[David Lutterkort]

This series of patches addresses a oft-requested feature: determining what
files to load into the tree at runtime, instead of hardcoding it in the
.aug modules.

The implementation now exposes the transforms that were marked for autoload
in modules in the tree underneath /augeas/load. When Augeas starts up, it
creates entries that look like

  /augeas/load
            Hosts
              lens = Hosts.lns
              incl = /etc/hosts
            Pam
              lens = Pam.lns
              incl = /etc/pam.d/*
              excl = *~
              ...

IOW, each transform is represented as a subtree with exactly one 'lens'
child, whose value is the fully qualified name of a lens[1], and any number
of incl and excl nodes, whose values are globs. A file is processed by that
lens if it matches one of the incl globs and none of the excl globs[2]. The
name of the transform node (Hosts, Pam above) carries no meaning at all;
aug_init uses the name of the module in which the transform is contained.

Two additional chanegs make this all nice to work with: (1) a new API call
aug_load which loads files according to what's in /augeas/load right now
and (2) a new flag for aug_init to keep it from loading any files by
default. So, if you only want to load /etc/hosts, you can do something like

  aug = aug_init(root, loadpath, AUG_NO_LOAD);
  aug_rm(aug, "/augeas/load/*[label() != 'Hosts']")
  aug_load(aug)

and you'll never suck in all 10k lines of /etc/services ;)

One thing I am not entirely sold on is what aug_load should consider as a
failure. For now, it only returns -1 if something truly catastrophic
happened, e.g. allocation failure. Most other errors are reported by
putting an 'error' node somewhere underneath /augeas, and aug_load returns
0. That means that to check whether your load succeeded completely, you'll
need to do

     r = aug_load(aug);
     if (r < 0 || aug_match(aug, "/augeas//error", NULL) != 0) {
       report_error ....
     }

feedback and opinions on the usability of all this would be much appreciated,
David

[1] Or the special notation @Module to say 'take the lens of the transform
    marked for autoload in Module', but that's mostly only there because
    the lens for a transform does not need to have a name, as in 'transform
    (l1|l2) filter'

[2] Augeas should really check all these globs and make sure that at most
    one lens matches any given file name.