Are restarts part of a function's "public interface"? in Common Lisp?

8
votes

I've been trying to understand proper use of restarts and handlers in Common Lisp by reading Peter Seibel's Beyond Exception Handling: Conditions and Restart chapter of Practical Common Lisp, Kent Pitman's Conditional Handling in the Lisp Language Family, as well as some other references.

From what I understand about restarts, they are options provided by a function to its callers to choose the function's behavior when some condition is encountered.

Should it be the case, then, that restarts are treated as part of a function's "public interface", and be documented accordingly?

After all, callers have to know about the restarts and what they do in order to invoke them, right? And it would be a bad thing to get rid of a restart that a caller could be invoking, I presume.

1
common-lispcondition-system
nhplace.com/kent/Papers/Exceptional-Situations-1990.html – Rainer Joswig
cs.cmu.edu/Groups/AI/html/cltl/clm/… – Rainer Joswig
The question is interesting, but you may want to come up with an example to make clear what you are asking. – Rainer Joswig
It's a general question about how the existence of restarts should be recorded and communicated. Should restarts be part of a function's contract? – Tianxiang Xiong
Does the caller see the restart? Usually not. If he provides handlers, then they see the restart - when they are actually called. The handler can query what restarts are available in that case. For interactive handling, they are discoverable. The condition system can be used in different ways. Without knowing how you are using it, it's difficult what you want to document and where. – Rainer Joswig

1 Answers

1
votes

Restarts are named by symbols. If such a symbol is exported from a package, I'd see it as part of the public API, otherwise not. I'd expect all exported symbols to be documented at the appropriate places (docstrings).