> From: Lassi Kortela <xxxxxx@lassi.io>
> Date: Sunday, August 02, 2020 6:35 AM
>
> Are we settled on something like the following so far?

Thanks for this email, I was thinking along the same lines.

> The foreign-error type is an abstract data type (ADT).

Must we *require* it be an ADT?  foreign-error? can be nearly
sure an object that's a plist is a foreign-error.

> (foreign-error? object) => boolean
>
> (foreign-error-ref ferr symbol) => object

Leaves out the object being a lambda, with convenience additional
arguments being the lambda's arguments to hand to it.  Not required,
but why make more work for the consumer of an error?

Which brought up my first thought of the day: localization conventions
will necessarily have to be documented somewhere like in this SRFI,
but any lambdas that take arguments should have a requirement to be
documented in the error object (which may be localized, hence the
above requirement its conventions be documented).

That will be a duplicate of information in the registry if the creator
of an error-set collection is diligent, but we can't expect users of
libraries using SRFI 198 to find this out by looking at the registry,
which also might not be in an easily digestible for humans format.
(Of course, we could do something about the latter....)

> (make-foreign-error . plist) => ferr
>
> (raise-foreign-error . plist)

Also (raise-continuable-foreign-error . plist) ?  I have no informed
opinion on using continuable raising, have always used this paradigm
to exit the program, but the option exists.  And document that both
must use make-foreign-error, whereas exactly what raise and
raise-continuable do is totally at the discretion of the implementer.

> - Plist keys should be symbols.

Why not "must" be symbols?  Provides one way to validate the plist.

> - Need to decide whether keyword objects are also accepted and converted
> to symbols internally.

Does that create a portability issue for libraries using SRFI 198, if
the user chooses to use keyword objects?  Very unfortunately, you had
to withdraw your keyword SRFI :-( One of the two things I miss the
most from Common Lisp ).

> - Specify what to do in case of duplicate plist keys (after normalizing
> them all to symbols). First one wins?

That's the general rule?  But why not stash duplicates somewhere in
the error object?  In general we want to preserve information,
especially when calls to it are malformed, the user should still be
able to make some sense out of a mess (and of the least likely to be
caught in testing).  Thus a call to make-foreign-error without an
'error-set key will still return an error object, with all the data
handed to it in it.

I need to make that explicit in the SRFI specification text, what all
malformed calls to make-foreign-error will do.  Probably two varieties,
if a value for the key 'error-set can be extracted, and if not.

> Do we need a `raise-foreign-error` in the SRFI? (raise
> (make-foreign-error ...)) is not substantially more difficult.

We ***really*** want to encourage this paradigm.  Quoting text from
SRFI 170, the end of SRFI 198's Rationale is:

> Sometimes it will make sense to simply return an error object, but an
> often preferred method is to raise an exception, as in SRFI 170, in
> which procedures never return error codes nor use an analogue of the
> POSIX errno variable to indicate system-call-level errors.
>
> Thus procedures can return useful values, and the programmer can
> assume that if a foreign interface procedure returns, it succeeded.
> This greatly simplifies the flow of the code from the programmer's
> point of view.

And we might as well hide the details of whichever system's raising
from the user of SRFI 198.

- Harold