[Chicken-users] SRFI-12 exceptions: best practices

[Alaric Snell-Pym]

Hello!

I just fixed a bug in Ugarit that happened because I misused SRFI-12
exceptions. I'd just copied the usage I'd seen in other code, and wrote:

   (if (not (directory? base))
      (signal (make-property-condition 'exn 'message "The archive
does not exist" 'arguments base))))

When I really should have written:

   (if (not (directory? base))
      (signal (make-property-condition 'exn 'location 'backend-fs
'message "The archive does not exist" 'arguments (list base))))

...with the end result being a confusing error message about the wrong
type of arguments to apply (as it appears something somewhere applies
a function to the contents of the arguments property of the condition).

Hunting for actual documentation on the correct usage, I finally found
a small note at http://chicken.wiki.br/man/4/Unit%20library#exceptions
that read:

"Error-exceptions of the exn kind have additional arguments and
location properties that contain the arguments passed to the exception-
handler and the name of the procedure where the error occurred (if
available)."

It occurs to me that the documentation could be expanded a little.
SRFI-12 itself really focusses on the underlying mechanism of
exceptions, rather than talking about how best to use them. Perhaps 
http://chicken.wiki.br/man/4/Unit%20library#exceptions
 could give some real-world advice.

For example, in Ugarit, I'm generally reporting fatal errors in the
configuration file, so I just make a property condition as above, but
I know that libraries that have more useful detail about the exception
make a composite condition that merges a 'exn with their own condition
type to report all the extra data. Am I ok in not making a composite
condition, because I have no extra data to provide? Should I composite
it with a 'chicken-configuration-error kind, even if it has no
properties, just so that the source of the exception in a complex
system with lots of libraries is known? Etc?

If people could codify best practice here on the list, I'll happily
write it up and submit a documentation patch :-)

Thanks,

ABS

--
Alaric Snell-Pym
Work: http://www.snell-systems.co.uk/
Play: http://www.snell-pym.org.uk/alaric/
Blog: http://www.snell-pym.org.uk/?author=4