> 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

>> [ foreign-status-plist will be added to the API, no magic procedure
>> calling for foreign-status-ref. ]

Lazy loading helps avoid calling strerror() or FormatMessage() on every
error if the consumer only cares about the error number. If 'message is
a lambda then the call to the function that gets the error message can
be delayed until that lambda is called. Not sure how important this is.

If the precise error message depends on some state, all that state needs
to be rolled into the foreign status object or a closure around the
lambda. But in most cases the only state needed is the error code, for
which a strerror()-like API returns a generic error message.

>> I just mean one-liners like:
>>
>> (define (foreign-status:type status) (foreign-status-ref status 'type))
>> (define (foreign-status:number status) (foreign-status-ref status '
>> number))
>> (define (foreign-status:name status) (foreign-status-ref status 'name))
>>
>> Obviously we would only want a few of these at most, and I'm okay with
>> zero of them.
>
> Bleah.  One foreign-status-ref to rule them all.

Another vote in favor of the foreign-status-ref monopoly.

Users can easily define their own one-liners if they want to.

> 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.

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?

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.

>>     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.

>>     That must of course include the errno, e.g. 'errno /[fixnum]/,
>>
>> I think we should use a more generic key like 'number, and say that
>> all foreign-status objects have a number (exact integer), a name
>> (symbol), or both (and in particular the errno type has both).

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.

> Oops, I didn't remind myself how I'm doing that in the current SRFI 198
> draft, it is of course 'number as you suggest.

That nomenclature is tricky as well. 'number and 'symbol would be a
clear and obvious distinction, if it weren't for stuff like SQLSTATE
codes which are almost numeric except some of them have one letter.

'code and 'mnemonic is decent if we return the almost-numeric SQLSTATE
values from 'code and the longer human-readable C identifiers from
'mnemonic.

I think 'mnenonic is a bit too fancy a word, but 'name would be too
ambiguous. 'identifier is a also a bit ambiguous.

> 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.

> 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. If you mean the mapping from C
mnemonic identifiers to Scheme symbols, I just added some samples to the
Registry today: <https://misc.lassi.io/2020/scheme-registry.html>.

Web server for the registry still pending, so I'm pushing updates on my
server for the time being. Server on the way.

>>     my pet project/pain point you also want above only needs a name
>>     for the key, I've used 'symbol in the SRFI 198 document so far,
>>     and to state that the value must include the C define string, such
>>     as "ENOENT" (not that the value itself has to be a string).
>>
>> I'd go with the key 'name, as above, and require the value for the
>> 'errno error-set to be precisely 'ENOENT, since that is what Posix
>> standardizes.

+1. Check out the samples; they make it quite clear that we should
simply use the C identifiers as-is for Scheme symbols.

> All very good by me; I've used 'symbol so far, 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.

>> IMO this is much more important in Scheme than the actual value of
>> errno (carried on the 'number key), since that value varies from
>> system to system and isn't even usually in the man page (you have to
>> poke around in the include file).
>
> And that's my exact pain point when you add the fun of mapping from
> number to name on some systems like Linux.

+1. The number is just so easy to obtain that it's a no-brainer to
always include it. It's a pity C APIs don't export official functions to
map numbers to mnemonics.

> I can't recall seeing errnos as raw integers ever being documented in
> man pages, and looking at what purports to be Bell Labs Research
> Versions 6 and 7 man pages collection (http://man.cat-v.org/), the
> defines weren't in them.  Per
> http://tzimmermann.org/2017/06/30/everything-about-errno-plus-transactions/ perror(3)
> was the interface to use, going back to V4 in 27 NOV 1974, and the
> earliest he could find numeric error codes was in V4, 31 AUG 1973.
> Since pretty much everyone had a copy of the source back then, although
> maybe not always online, I suppose people just cross referenced the
> appropriate include file.

POSIX specifies errno mnemonics only, not any numbers.

There are lots of conflicting errno values in practice:
<https://misc.lassi.io/2020/errno-conflicts.text>.

>>     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?

>>     And a very optional, but also general convention 'heritage, here
>>     something like "SRFI 170", to give the user hints where to find
>>     original discussions of a procedure once it's for example been
>>     assimilated into R7RS-large.
>>
>> I'd rather keep that information in a documentation index outside the
>> program, as it is only useful to human beings.

No opinion on this one.

> And my position from the beginning is that humans are the primary
> consumers of foreign-status objects.  But see below.
>
>>     'message is also a general convention for all error-sets, but
>>     again not mandatory, especially in the embedded/low memory domain.
>>
>> +1.  So I'm proposing eight standard keys: 'type, 'name, 'number,
>> 'args, 'scheme-procedure, 'foreign-interface, 'message, 'localizer, of
>> which 'type and either 'name or 'number are mandatory.

All good ones. We can debate the meaning of "standard" but that's minor
polish.

> I say type -> 'error-set, or I'm not sure what you're referring to,
> maybe two types of arg keys per the above, pass on 'localizer but
> obviously there will be one or more localization keys in the common
> conventions for all error-sets.  For 'heritage, surely it's mostly
> harmless, but, yeah, it does add to the API surface.  I suppose it's
> self-explanatory and can excluded from the "standard" keys, and added to
> a "grab bag" of selected keys one should look at before adding a new one
> to an error-set.

We can freely add lots of keys into the Registry. It's good to advertise
a tight standard set in the SRFI itself so people know which properties
to check first and then reach for more if those are not enough.

> For 'name or 'number being mandatory, we should think about a larger 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."