human-readable signatures

[David A. Wheeler]

Havoc Pennington wrote:
> There's a problem with the signature format that it isn't really human-
> readable. The reason is that too many of the types start with the same
> letter. So "si" = string,int32 is good, but "yq" = byte,uint16 you
> wouldn't quite guess.

I actually don't think it's TOO bad.
Single-character-per-type is actually really nifty, because it's
so darn simple to understand. There aren't very many basic types,
and most of them are obvious, so they aren't that hard to deal with.

So I'm not sure that this is really worth doing.  Especially since
many bindings will be at a higher level anyway.  But if you think
it's worth doing, here are a few thoughts.

 > Something else to consider is that we could allow the human readable
 > form as arguments to the dbus-message.h API. On balance I don't really
 > think this is a good idea; it adds complexity and "tmtowtdi" that I'd
 > rather avoid.

If you go there, PLEASE don't create yet-another-function
to accept that variant.  Instead, create a prefix for the "human-readable"
format, then have any function that takes a type signature
look at the first character to see if it's "human-readable".
For example, if "+" is the 'human-readable' prefix, then
anything that took type signatures would just look for the initial "+".

This would simplify the API and eliminate accidental misuse.
It's unlikely that a string omitting its prefix would be a valid
single-char type signature, so accidents would be dealt with
automatically.

Any reports should produce a single-char form, and you can then call
dbus_signature_to_readable() to produce the long version
(which would include the prefix).


> We could add API like this:
> 
>  char* dbus_signature_to_readable   (const char *signature);
>  char* dbus_signature_from_readable (const char *readable_signature);
> 
> The readable format could be something like:
...
>  "aa(si)" -> "array,array,(string,int32)"
...
> There are other options, such as:
>  "array<int32>" "array<(string,int32)>" "array<array<(string,int32)>>"
> 
> But already that's harder to parse, and the <> sucks for command line
> tools.

If your goal is human readability, I don't think that
"array,array,(string,int32)" is the answer.
I don't think that's all that clear, and
that's your goal.  Why not just use square brackets? Also, why not
omit parens when a structure is required in an array?  E.G.:
  "+array[int32]" "+array[string,int32]" "+array[array[string,int32]]"

You could also reuse parens; maybe you could
omit the second paren after array if there's more than one type
inside, since an array with >1 type inside MUST have a struct or map.
E.G.:
  "+array(int32)" "+array(string,int32)" "+array(array(string,int32))"

Either form is in my opinion easier to read than:
  "+array,int32" "+array,(string,int32)" "+array,array,(string,int32)"
though I prefer the square bracket form.
It wouldn't be THAT hard to automatically parse these,
and it'd be a lot easier for humans to read these forms.

Don't worry about the fact that [] and {} are globbing characters
in bash and many other shells.  Parens also have special meaning
(create subprocesses), so you have to quote type signatures anyway.

--- David A. Wheeler