I have been working off and on (mostly off) for a while now on an
expanded "pretty" format which would allow for, among other things,
conditional formats and "long" placeholders.
Recent threads on the mailing list seem to be leaning towards "long"
placeholders happening sooner, rather than later, so I think it might be
a good time to discuss how they might work, if only so that I can make
sure that what might be desired of an expanded format doesn't conflict
with my goals regarding conditional formats / etc.
The justifications for allowing "long" placeholders are simple:
1) We have a lot of "short" placeholders already, and the
mnemonics are going to keep getting more awkward the more
of them we have
2) Long-forms leave room for options and other fun
3) Terse is fun to write, verbose is fun to read.
To start with, the basic idea for expanded placeholders is to allow, in
addition to the current short-forms, such as %h, %ad, etc, "git log" and
friends would also support "long forms", such as %(hash), %(authordate),
etc. Ideally, the "long" forms would be compatible with / perhaps even
(eventually) share code with, the placeholders used by for-each-ref.
There are several requirements which I know of:
- Long placeholders cannot invalidate any existing placeholders
- Long placeholders must have a method for accepting "parameters"
- Nothing should ever be "illegal". ie: any placeholder which does
not make sense to us should be interpreted literally, rather
than causing a fatal error.
And, for my own part, there are several requirements which my itch has:
- Long placeholders must be able to accept multiple parameters
- Long placeholders must be able to accept a variable number of
parameters
- It must be possible to include an entire "sub-format" as a
parameter of a long placeholder
Our current placeholder rules are very simple. If I recall correctly,
for example, the only escape character is "%". It would be good to keep
this simplicity. The parser internals, however, are most likely due for
a change, to allow for a "parse once, process many" approach to make up
for the long-formats being somewhat slower to parse by nature. Hopefully
this would give us a slight speed boost in the trivial cases as well,
though this is not actually a goal of any work I am doing.
Discussion so far, and the way for-each-ref does things, suggests the
following specification for long formats:
%(placeholdername:optional-parameter)
Meanwhile, the existing %w( ) format gives us a precedent for multiple
parameters: separate them with commas:
%(placeholdername:optional-parameter,optional-parameter)
Currently, for-each-ref is strict about whitespace. For example:
%(objectname:short) is valid
%(objectname: short) is not
While log's %w( ) is less-strict:
%w(0,4,4) is valid
%w(0, 4, 4 ) is too
%w(0,
4, 4) is too
I prefer support for whitespace: there's not really a good reason not to
allow it, as far as I know, and it gives people more freedom to make
things readable how they see fit.
As for the names of long placeholders, for-each-ref seems to have the
opinion of:
- only alphabetic characters (ie: no dashes, etc, between words)
- only lowercase characters (eg: no camelCase)
- strict about both (ie: must be typed exactly, no caSeMixing)
all of these restrictions sound sane, but may be limiting if declared a
convention to follow. I assume a sane extension would be:
- alphanumeric characters and dashes allowed
For my own purposes (conditional formats), I'd like to see the ability
to embed an entire sub-format within a placeholder. Clearly this would
complicate the parser quite a bit (we wouldn't be able to just look for
a closing ")", for example), but I think the flexibility makes it work
it. To achieve this in terms of a specification to shoot for, we can
simply say that any embedded "%(" must be terminated by its own ")" to
be valid. eg:
%(foo-condition: %(format: %H, aka %h), %H )
This does conflict with the idea of whitespace being non-important,
and unfortunately I don't have a good idea for that one yet. There are
four options, as I see it:
A) make whitespace always-important. I don't like this at all
B) Add quotation marks and backslashes as additional escape
characters, allowing for " Sally said \"foo\" ". This seems
like a nasty thing to do to an otherwise simple format
C) add %(preserve-whitespace: whitespace is important here )
This may add weirdness to the parse that makes it hard to
follow, and we'd need to come up with rules about
"inheritance" of whitespace preservation.
D) Require people to type %20 if they want a space at the
beginning/end of a parameter. This idea feels ugly too, but
maybe not as ugly as the alternatives.
For what it's worth, the current WIP code I've got uses option B.
As a final note: "Conditional formats" feel a lot like ternary operators
in C. Because of that, I feel like saying that conditional formats like:
%(opt-color: %Cred%h%Creset, %h)
Look better to me as:
%(opt-color ? %Cred%h%Creset : %h)
But thinking in terms of consistency / simplicity of "what escapes now?"
I think the more-uniform %(placeholdername:parameter,parameter) is
probably the one to go for.
Those are my thoughts on the matter, or at least those I have at the
moment. I'll leave this to the list to discuss for now, and hope that it
doesn't get bikeshedded to death.
-- Will
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html