[tap-l] User Supplied YAML Diagnostic Keys: Descriptive Version
Michael G Schwern
schwern at pobox.com
Sun Apr 13 18:41:04 UTC 2008
> --- Steffen Schwigon <ss5 at renormalist.net> wrote:
>> And we are talking about the diagnostics part, which is primarily for
>> the user, so the rules are reversed there.
> There are two goals we want:
> 1. Make it as human-readable as possible.
> 2. Maximize flexibility.
> As for human-readable, consider these:
> tap-have: 4
> tap-want: 5
<mccoy>It's worse than that, Jim.</mccoy>
tap tap tap tap tap. Similar things should look similar, so you can quickly
and visually group them. Different things should look different so you can
quickly and visually separate them. By giving everything the same prefix you
make it all look the same. And it's saying that the primary use case is
differentiating user vs standard keys.
I agree, it's ugly.
> Regarding maximum flexibility, Adrian Howard has already pointed out
> that if we restrict people to 'X-', then we can always be more
> permissive in the future. If we open it up to just about anything they
> want and it turns out to be a mistake, we could easily be backed into a
> corner. Why on earth would we *deliberately* choose an option that we
> know might be problematic, particularly when someone's non-unicode
> aware language might get confused about what is and isn't lower-case?
Because we pave cow paths. If we restrict users to just one style then they
do not have a flexibility to try out new things. We'll never discover what
users actually need to do, because they can't do it. No cow paths will form
because we've already laid a rail.
Furthermore, all the TAP spec has to worry about is the set of reserved
keywords. Whatever users do with the non-reserved stuff is their
responsibility. We treat users like adults and give them power and
Remember, the producer and the displayer of the non-reserved keys are both
under local user control. They choose the custom keys and they choose what
they need and can handle. If Yahoo thinks it's a good idea to write their
keys in Klingon then Yahoo will be prepared to handle their keys in Klingon.
The user knows best.
All TAP needs to do is carve out a wide and clear enough reserved space for
future use so we don't bump into the user. We all seem to be basically in
agreement about what that set is.
Yes, it makes the spec a little fuzzy but it's worth it. Yes, people might do
horrible things with it and blow big gaping holes in their feet, but they
might also do surprisingly brilliant things with it. TAP is not about having
a simple spec or easy parsing, it's about testing anything.
> It doesn't hurt us to play it safe with such a major change. It
> *might* hurt us to make a major change when we already KNOW that
> potential problems are out there. We're not talking about a minor
> utility that only a handful of people would use. We're talking about
> playing fast and loose with core infrastructure tool that many people
> are dependent on.
> On an implementation detail, parsers will need to differentiate between
> TAP standard keys an user-supplied keys.
TAP parsers should ignore any key they don't explicitly know about, otherwise
adding new standard keys becomes difficult. Same reason we ignore non-TAP
output. A TAP parser needs to know nothing about the keys, it just passes
them through to the displayer.
A TAP displayer just has a set of standard and custom keys it knows what to do
something about. Anything else it displays in a generic fashion (or ignores).
All you need is a simple string equality, something most languages can
The only time one would need to programmatically separate reserved from
user-defined keys is if you're writing a strict-validating parser or you want
to explicitly differentiate how standard vs user keys are displayed. And
maybe you do, but the consequences of ambiguity in those scenarios is very
minor. You still get the right test results and the user sees the diagnostics.
> Not all languages make it that easy. Also -- I don't know the
> specifics here -- are we now going to have to require 'encoding'
> meta-information in TAP to make sure that the above regex works?
Two possible solutions:
A) Just reserve ASCII [a-z]. This is very easy to check for but I'm worried
it's carving out too small a space.
B) Reserve "lower case" and leave the spec a little fuzzy around the edges
for the moment.
I like B. It gives us some room to move. As demonstrated above, determining
what's user and what's reserved isn't a big deal. The only reason it exists
is so we don't define a standard TAP key that blows over a user one with a
different meaning. For this to happen because of ambiguity over what is
"lower case" requires a double breakdown:
1) The user has to use an edge case key, which might happen.
2) TAP has to define the same edge case key.
Are we really going to define a standard TAP key starting with a Hungarian i?
Or musical notes? Are we going to provide standardized keys localized to
the user's language? (the displayer can do that) Not likely.
We don't have to draw the spec with a fine point pen. It's ok to have some
fuzzy bits if we're not sure about it and there's no serious consequences.
Character encoding is one. We have very little information about how the YAML
diagnostics are going to be used and we know nothing about how they'll
interact with alternative character sets. Let's see what happens and when we
know more we'll draw the lines a little clearer.
100. Claymore mines are not filled with yummy candy, and it is wrong
to tell new soldiers that they are.
-- The 213 Things Skippy Is No Longer Allowed To Do In The U.S. Army
More information about the tap-l