> From: Lassi Kortela <xxxxxx@lassi.io>
> Date: Sunday, August 09, 2020 4:01 PM
>
> > Note we need to rename the SRFI (again :-) now that it's been decided
> > not all Foreign Interface responses are errors, and status is the least
> > worst name we can come up with, so "SRFI 198: Foreign Interface Status
> > Handling"??
>
> How about "Foreign status objects"? Prior names like that:
>
> * Range Objects
> * Keyword objects
> * Parameter objects

With raise-foreign-error we "handle" the error class of foreign
interface statuses, but if people think "Foreign status objects" is more
appropriate, that's fine with me.

> [...]
>
>> BTW, for "type", do you mean what I've been calling 'error-set, with
>> values like 'errno?
>
> Good that you bring this up. The names 'set and 'error-set have bothered
> me for a while. While 'error-set is redundant, 'set is almost too
> condensed -- a 3-letter word that is both a noun and a verb.
>
> The longer one would now have to be 'status-set instead of 'error-set.

Somehow I don't like that name, but of course it would have to be
changed from 'error-set. I think 'set is better, in context it should
be unambiguous/obvious.

> Long words like 'collection or 'enumeration are too long :) 'enum is a
> bit cryptic. 'class is overloaded (pun intended), so is 'type. 'source?
> 'group? 'facility?

'status-collection would be OK, but is long as you note. To me
'status-enumeration doesn't really describe what it is, class and type
are way too overloaded as you note, 'status-source is not bad, 'group
is bad.  'status-facility, well, I'd prefer to go for the gold and
name it 'status-instrumentality ^_^.  (Which was part of the US
government's vocabulary in the run up to our direct participation in
WWII, and during it.)

> After all of the above, 'set still best describes what it is -- a
> particular set of status codes, disjoint from other sets of status codes.

Yeah, 'set is best.

>>>     Anyway, one thing we can absolutely require in an SRFI, here the
>>>     'errno error-set for all of our POSIX SRFIs starting with 170, is
>>>     mandatory key/value pairs for foreign-status objects.
>>>
>>> +1
>
> Not 100% sure what is meant here, but sounds like something good.

For *our* POSIX SRFIs, it means implementations of them will be
non-conforming if they don't raise foreign errors with specific keys
like 'number, who's value is the errno fixnum, and 'name, who's value
is the C define names, like 'ENOENT or "ENOENT".

I suppose we could require it to be a symbol rather than a string,
and fixing the Scheme type would I assume be better for fancy
development environments, but a string would pointlessly use memory.

> [...]
>
> Most status sets would support both.
>
> It's another matter how easy it is to grovel the status symbols (pun
> intended) from C. In some situations very easy, in others almost impossible.

I want to make 'number mandatory, and 'name mandatory for "enough
memory" i.e. non-small memory embedded implementations, and for
those, using a symbol like 'ENOENT is "strongly recommended".  But
scarce memory might be better reserved for some data of what caused
the error.

We need a good name here for such constrained systems, and some sort
of annotation for Schemeregistry, and perhaps SRFIs, for otherwise
mandatory key/value pairs than can be fudged for small memory systems.

> [ We implicitly agree names are hard, and you note SQLSTATE can be
>   alphanumeric, not a pure number. ]

I deliberately show the latter in my PostgreSQL examples in SRFI 198
(which does not mandate anything but what we're now naming as 'set)
and thus use 'code instead of 'numbers.

>> Not all foreign errors have numbers and real names, that's one reason
>> I'm using libsodium in the examples along with errno and PostgreSQL
>> (Lassi will be forwarding some discussion plus a new paragraph in my
>> repo detailing this).  It's a genetic UNIX™ 0 or -1 return value API, it
>> would be a /severe/ burden on the interface implementor to create a
>> /comprehensive/ set of numbers.  E.g. for my backup program, I'm just
>> wrapping a small fraction of the API for symmetric ciphering, I don't
>> need any public key stuff.
>
> +1. Harold has convinced me that status sets where the numeric status
> codes don't have any mnemonic identifiers in existence is a good idea.

But note here there's not even a number to distinguish different
errors in the libsodium library, we'd have to make them up, which is
ill advised.  I'm assuming the library author would not report
statuses where functions worked, so the UNIX™ -1 is implicit in all
the ones that are generated.

SRFI 198 allows for non-error status reporting, but you don't have to
take advantage of that if it's not needed, like with SRFI 170.

>> There's no official error naming scheme either; I suppose one could be
>> created, but it would in my implementation be at least in part
>> duplicative of the 'foreign-procedure value.  I could be swayed on this,
>> but I think we'd then need to provide some general advice to users of
>> the SRFI, naming is after all one of the hardest things we do if it is
>> to be correct.
>
> Not sure what you mean by error naming....

The equivalent of ENOENT.  libsodium doesn't have such a thing.

> [ We all agree on ENOENT etc. ]
>
>> All very good by me; I've used 'symbol so far [ for the key for
>> names like ENOENT ], but was not happy about it, and that's back
>> when it was nested inside a 'code record slot.
>
> 'symbol is fine if the other one is 'number. But if the other one is
> 'code which can be a Scheme symbol in case it contains a letter, then
> using 'symbol to talk about the mnemonic identifiers is confusing.

John and I have agreed 'name works best for this errno key.

> [ We agree on the number to name mapping pain point, etc. ]
>
>>>     Definitely only a "strongly suggest" is 'args, the list of
>>>     arguments handed ... whichever of the previous, probably should
>>>     require 'scheme-procedure.  Or make two args keys, one for each.
>>>
>>> Plists historically have not allowed or expected duplicate keys.
>>
>> Errr, I mean with two different names, something like like
>> 'scheme-procedure-args and 'foreign-interface-args, although those are
>> very long and won't make only Lassi unhappy.  Probably just 'args for
>> the ones to the Scheme procedure, and perhaps 'foreign-interface-args if
>> you choose to go to that much trouble in providing truly excellent
>> status objects.
>
> Or 'scheme-call and 'foreign-call which are both lists; use (car ...) to
> get the procedure name.
>
> I'd like to port this SRFI to the Common Lisp condition system, so it'd
> be nice to use something other than 'scheme. Would it be too vague to
> use just 'call and 'foreign-call?

I'd rather keep names of procedures and functions (a particular
interface in the 'set, more broadly speaking), and arg lists separate.
Especially don't want any special rules like "use (car ...)" anywhere.

> [ 'heritage, and "standard" keys. ]
>
> All good ones. We can debate the meaning of "standard" but that's minor
> polish.

Standard might not be the best word, but I like it.

> [...]
>
>> For 'name or 'number being mandatory [ ***for all status sets*** ],
>> we should think about a larger [sub]set including those two, in which
>> one is mandatory. For example, in my posited use of SRFI 198 for
>> libsodium, 'message fills this niche.
>
> I wouldn't worry about mandatory anything. Make everything optional. If
> we explain _why_ it's especially useful to have particular properties,
> and where to easily get the right values for them, people will be more
> compelled to include them than if we mandate something we can't
> technically enforce and is very inconvenient in some situations.
>
> "WIBNI [Bell Labs: Wouldn't It Be Nice If]: What most requirements
> documents and specifications consist entirely of."

I tend to agree, especially since I can't think of other keys to make
a subset from which at least one is mandatory.  Plus I doubt my
ability to predict this for all future uses of SRFI 198.  'set is
mandatory, and implicitly at least one other key is unless you're
channeling the spirit of ed and "?".

- Harold