[BRLTTY] Low-level BrlAPI questions

[Samuel Thibault]

Dave Mielke, le dim. 09 mai 2021 05:46:00 -0400, a ecrit:
> [quoted lines by Samuel Thibault on 2021/05/09 at 11:36 +0200]
> 
> >> Some bindings might wish to use a list rather than an array.
> >
> >If bindings want to return a list, fine for them, "array" is just a word
> >for the brlapi protocol, it can be expressed whichever way is fine for
> >bindings.
> 
> They may wish to use an array for isArray==true but a list for isArray==false. In other words, they may wish to use an array for a multi-value result but a list for a multi-value single item. I think it's healthy to make them aware of the difference.

Why making the difference? What is the actual benefit here? The more
subtle we make the API, the less approchable it becomes.

> >Just like the display size if of fixed size.
> 
> Yes, but it's a single value so why not tell them?

It's not a single value, there are two dimensions to be provided.


Really, the original intent was a straightforward:

- if isArray = False, there is just one scalar value to return
- if isArray = True, there is possibly different values to return, and
  thus use whatever suits best the language (list, array, tuple) to
  convey the values, even if there is just one value.
- if count != 0 (only valid for isArray = True), the number of values
  being returned is always equal to that count.

If we make the interface more complex, we'll have to document it, thus
making the documentation even bigger and longer to grasp, test it, make
people understand the subtleties, etc.

What is the *actual* benefit of departing from this?


Aura Kelloniemi, le dim. 09 mai 2021 13:30:14 +0300, a ecrit:
> My suggestion #1
> isArray is left for describing the intended logical use for the value – not
> its representation.

But then what does it actually mean? (for *all* language bindings that
we may ever write)

> My suggestion #2 is that count contains the number of values returned, if
> isArray == false. If isArray == true, then count contains the maximum number
> of values that may be returned/stored.

We don't actually need this: the getParameter function already returns
the actual number of values. count can already provided the maximum
number of values in all cases, and getParameter provides the actual
number of values.

> My suggestion #3 is that we add more fields (or change existing ones) to
> describe more precisely the type of the parameter.

But what is left to describe?


Now, if a language wishes to use a ad-hoc two-value type for a very
particular case such as the display size, why not, that's not a
problem. But I don't think we want encode this in the parameter
description, since then all other bindings would have to cope with such
subtlety, and for a various number of them that may simply not make any
sense.


Perhaps basically what I mean is that I don't think we will ever find
a description beyond what I proposed above (scalar vs array) that will
make sense universally. Languages all have their own way of calling
things, of making fields mutable or not, labelled or not, etc. I don't
think we want to try to encompass all possible case, that looks to
me like a lost cause to me. Bindings can still very well do they own
special-casing wherever it seems to be a good idea because there happens
to be an idiomatic way of doing things, e.g. a Dimensions type for the
ad-hoc two-value display size case.

Samuel