[Gnu-arch-users] [BUG] feature plan -- Selected inventory

[Tom Lord]

Add a --selection X option to inventory.

X is the name of a file containing a selection spec. 

The output of 

    % tla inventory --selection X

is a subset of the normal `inventory' output -- it's just the
items that are matched by the selection rule.

Here's a little language for selection specs: I think we can use this
language for "selective commit".  In this language, you write a set of
rules which collectively identify the part of the tree we are
interested in.

If we're interested in some part of the tree: We might be interested
only in changes that are internal to that thing (changes to the text
in a file, changes to permissions, changes to the target of a
symlink).  Or we might be interested only in renames of that thing,
wanting to ignore the internal changes.  Or we might be interested in
both renames and contents-changes.

So each rule we write will say how in particular we are interested in
some subset of the tree, although other more specific rules can
provide exceptions.  An example of a rule is:

        (selection (c "./src/hello.c"))

which says "We're interested in the (internal) changes (`c') to the
file named `./src/hello.c'.  The current "tla commit [...] -- FILES ...
syntax amounts to that kind of rule.   E.g. this:

        tla commit -- src/hello.c

Is the same as committing with the selection

        (selection (c "./src/hello.c"))

because changes internal to that source file will be committed, but
renames to it will not.  This:

        (selection (n "./src/hello.c"))

would commit name changes ("n") to the file, but not internal changes.

Another example is:

        (selection (b "./src/hello.c")
               (b "./src/hi.c"))

"b" means "both" -- we're interested in both the internal changes and
renames of the nodes that match.   

Another example, involving a directory, is:

        (selection (-b "./src"))
                ^^
                ||
                |`---- default outcome for nested files
                |
                `----- outcome for ./src itself

"-" means that this rule has no opinion about whether the
exact-matching object ("./src" itself) is interesting or not.  Instead
of "-" we could have used "c" to express interest in permission bits
of ./src, or "n" to express interest in renames of that directory, or
"b" for both renames and permission bits.

"b" in the rule means that for anything nested under ./src, in the
absense of any more specific rule, we're interested in _both_ ("b")
internal changes and name changes to items in the tree.

In addition to outcomes "-", "n", "c", "b" there is also "x" for
exclude -- an item that matches with outcome "x" is excluded from the
selection by that rule.  For example, this rule:


        (selection (xx "./include/X11")
                   (cb "./include"))

means "both ('b') renames and changes below ./include are interesting;
changes but not renames ('c') to ./include itself are interesting; but
as exceptions, ./include/X11 and everything nested under it is not
interesting at all."

In that last example, both rules match the directory
"./include/X11/X.h".  The "cb" pattern is a prefix of the "xx"
pattern, and so the "xx" rule is the more specific.

Note that applying a selection to a tree results, in the general case,
in a sub-forest of the original tree rather than a subtree.  
For example, this tree:


        ./include
          ./include/X11
            ./include/X11/x.h
        ./src
          ./src/hello.c


With the selections:

        (selection (cb "./include/X11")
               (c "./src/hello.c"))

yields the forst (and levels of interest):


        ./include/X11                   c
          ./include/X11/x.h             b

        ./src/hello.c                   b



The way in which a set of rules is combined to form an overall selection
test should be fairly intuitive but here are the details:


                        Selection Membership Test

  Rules := the set of rules

  Item := an inventory item to compare to the selection

  ApplicableRules := { x in Rules such that X(Item) produces
                       a result other than "-" (any of "n", "c",
                       "b", or "x" }


  SpecificityMetric (Rule, Item) := if Rule.pattern is a prefix of Item.loc
                                       return number_of_components 
(Rule.pattern)
                                    else  
                                       return -number_of_components 
(Rule.pattern)


  IsMoreSpecific (metric_a, metric_b) := if (metric_a >= 0)
                                           return metric_a > metric_b
                                         else if (metric_b >= 0)
                                           return 0
                                         ele 
                                           return metric_a < metric_b

  If ApplicableRules is empty
    then Item is not within the selection
  otherwise:

  DominantRules := { x in ApplicableRules s.t. there does 
                     not exist y in ApplicableRules with
                     IsMoreSpecific (SpecificityMetric (y, Item),
                                     SpecificityMetric (y, Item))
                   }


  DominantResults := { result st. there exists an r in DominantResults
                       with result == r(Item) }

  invariant: n_elts (DominantResults) != 0

  if n_elts (DominantResults) > 1
    then error: selection specification is ambiguous
  otherwise
    return x in DominantResults

-t


----

Like my work on GNU arch, Pika Scheme, and other technical contributions 
to the public sphere?   Show your support!

https://www.paypal.com/xclick/business=lord%40emf.net&item_name=support+for+arch+and+other+free+software+efforts+by+tom+lord&no_note=1&tax=0&currency_code=USD

and

address@hidden for www.moneybookers.com payments.


-----

        The cause of death is birth.
                        -- George Harrison