Secret Origins
==============

<njs> there are too many namespaces...
<dscherge_> how so? selector wise do you mean?
<njs> I'm speaking more generally than the selector stuff in
  particular; just, manifest ids, and file ids, and tags, and dates,
  and authors, and branch heads, and 'the current working copy', and
  (immediate ancestor of <one of the above>), and (file name + <one of
  the above>), and ...
<njs>   selectors are one attempt to deal with this, and they do some
  of it, but... it's a mess.
<dscherge_> agreed. in terms of log I seem to be doing log | head -n
  100 way too often at the moment 
<dscherge_> I'd like to see something like "monotone log last 5"
  or "monotone log next 5" for looking at close ancestors or
  descendants
<njs>   maybe
<dscherge_> and perhaps something like "monotone log <selector>" to
  list the details of some set of manifests

Goal
====

Have a tiny little language for talking about revisions and files
within them, that we can pass to diff and the like without
embarrassment.  There are a _lot_ of namespaces.

  revisions:
    item selectors:
      "the working directory"
        "some other working directory" ?
    set selectors:
      "the thing with id beginning ..."
      "the head of this branch"
      "the thing tagged ___"
      "the thing committed at ..."
      "the thing committed by ..."
      "the thing whose changelog matches regexp ..." ?
    

for set selectors, a nice ui would be "error: ambiguous selector",
<lists possibilities if less than, say, 5>, <numbers each in list>,
<lets you pick by number>.  Maybe ^ would be good for giving the
number.

are there commands for which you legimately want to specify a set of
revisions, an ambiguity is not an error?

Character set constraints
=========================

authors need @
in fact rfc2822 says that email names can contain
  ALPHA DIGIT !#$%&'*+-/=?^_`{}|~.
ye gods.

okay, guess we steal []~, and let you quote them if you need them.

NOTE: \ quoting applies.  sigh... I don't think it's will ever
actually be needed, but...

Examples
========

  file "foo" in revision tagged "monotone-0.15":
    t:monotone-0.15/foo
  the immediate ancestor of the revision committed by graydon on
  2004-11-17.  (~ is "intersection" operator.  because it's binary, it
                can never occur at left edge of string, and thus runs
                no risk of looking like a shell metacharacter):
    address@hidden

  this is an error if there are multiple parents.

Syntax
======

file_specifier = rel_rev_specifier '/' path_specifier

path_specifier = <a monotone path name>

rel_rev_specifier = rev_specifier
                    | rel_rev_specifier '[' relative_address ']'

rev_specifier = atomic_rev_specifier *('~' atomic_rev_speficier)

atomic_rev_specifier = (rev_tag ':')? rev_data
rev_data = [anything that can occur in a email address, etc.]*
rev_tag = [a-zA-Z]*

relative_address = <TBA... how do we give a nice syntax for when there
  are multiple parents?  use case is basically, "hmm, what happened in
  that merge?
    diff foo foo[first parent]
    diff foo foo[second parent]"
  because we have the nice []'s to bracket this off, we get pretty
  arbitrary choice of characters.  what's a good syntax?  have to deal
  with both children and parents.  don't have to solve the whole
  problem in this syntax alone, because can chain []'s.  hmm.
  maybe, [+<number>] means <number>th parent, [-<number>] means
  <number>th child, can be abbreviated to [+] and [-] to mean unique
  parent and child.  [+][+][+] to mean 3 revisions back is a little
  verbose, though.  also, people will probably expect +3 to mean three
  revisions back.  maybe can simplify some for parents on the
  assumption that there will never be more than two... that doesn't
  help with children, though.  hmm.>

Notes
=====

if rev_data = rev_tag = "", we infer rev_tag = "wd", current working
directory.