[RFD] Expanded Pretty Format Placeholders Proposal

[RFD] Expanded Pretty Format Placeholders Proposal

[Will Palmer]

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

Re: [RFD] Expanded Pretty Format Placeholders Proposal

[Will Palmer]

On Fri, 2011-03-11 at 00:47 +0000, Will Palmer wrote:
..snip
> 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 )


of course, this conflicts with the need to embed a literal ")" within a
sub-format. The simplest option for this would be to either allow %) as
an escape, as with %%. Even simpler, of course, would be %x29, but this
seems needlessly obscure. The only objection I have to %) is "It's
ugly". To me, %(format: "this is a paren: )") is easier to read, but
that would just be moving the problem around, adding the necessity of
the just-as-ugly-or-moreso %", or alternatively C-style \" and \\.
So I think that %) will be the best option.


> 
> -- Will
> 

Re: [RFD] Expanded Pretty Format Placeholders Proposal

[Junio C Hamano]

Will Palmer <wmpalmer@gmail.com> writes:

> On Fri, 2011-03-11 at 00:47 +0000, Will Palmer wrote:
> ...
>> 	%(foo-condition: %(format: %H, aka %h), %H )
>
> of course, this conflicts with the need to embed a literal ")" within a
> sub-format. The simplest option for this would be to either allow %) as
> an escape, as with %%. Even simpler, of course, would be %x29, but this
> seems needlessly obscure. The only objection I have to %) is "It's
> ugly". To me, %(format: "this is a paren: )") is easier to read, but
> that would just be moving the problem around, adding the necessity of
> the just-as-ugly-or-moreso %", or alternatively C-style \" and \\.
> So I think that %) will be the best option.

I somehow had an impression that you will be using "" to quote strings to
protect leading or trailing whitespaces, and if you were to support double
quotes anyway, \" and \\ become a very natural thing to do (so does your
"close parenthesis inside dq").

Re: [RFD] Expanded Pretty Format Placeholders Proposal

[Will Palmer]

On Thu, 2011-03-17 at 14:35 -0700, Junio C Hamano wrote:
> Will Palmer <wmpalmer@gmail.com> writes:
> 
> > On Fri, 2011-03-11 at 00:47 +0000, Will Palmer wrote:
> > ...
> >> 	%(foo-condition: %(format: %H, aka %h), %H )
> >
> > of course, this conflicts with the need to embed a literal ")" within a
> > sub-format. The simplest option for this would be to either allow %) as
> > an escape, as with %%. Even simpler, of course, would be %x29, but this
> > seems needlessly obscure. The only objection I have to %) is "It's
> > ugly". To me, %(format: "this is a paren: )") is easier to read, but
> > that would just be moving the problem around, adding the necessity of
> > the just-as-ugly-or-moreso %", or alternatively C-style \" and \\.
> > So I think that %) will be the best option.
> 
> I somehow had an impression that you will be using "" to quote strings to
> protect leading or trailing whitespaces, and if you were to support double
> quotes anyway, \" and \\ become a very natural thing to do (so does your
> "close parenthesis inside dq").

I do have double-quoted strings implemented, but in trying to break the
big-ugly-POC patch down into more-manageable changes, I questioned the
need for it when %x20 or the "magic" space-if-nonempty might do just as
well for most cases, so I took it out of the initial patch.

I admit that double-quotes do feel quite natural from a C perspective,
even if they do go against the conventions we've already established for
escaping things in pretty-formats. I'll see about adding double-quoted
string support in a single patch in the series, so it can be evaluated
independently, and accepted/rejected on its own easily.

Re: [RFD] Expanded Pretty Format Placeholders Proposal

[Junio C Hamano]

Will Palmer <wmpalmer@gmail.com> writes:

>> I somehow had an impression that you will be using "" to quote strings to
>> protect leading or trailing whitespaces, and if you were to support double
>> quotes anyway, \" and \\ become a very natural thing to do (so does your
>> "close parenthesis inside dq").
>
> I do have double-quoted strings implemented, but in trying to break the
> big-ugly-POC patch down into more-manageable changes, I questioned the
> need for it when %x20 or the "magic" space-if-nonempty might do just as
> well for most cases, so I took it out of the initial patch.

True enough; %x20 is probably acceptable and %xXX is what we already have
anyway.  Besides, values in the configuration file needs to use dq when
they have whitespaces in them, and it would make it trickier to read if
the language used in value (i.e. the one you are designing when used as
part of alias) overused dq and bs.

I wasn't objecting to %-quoting.  I just wanted to make sure that the
reason you favored it over dq was sane and well thought out.

Thanks.