OK, now you’re completely overwhelmed by the power and flexibility of
Clon, to the point that the fact that you didn’t write it (because
I did) even starts to upset you. So I know what you’re thinking:
“there’s gotta be a way to break it”. I don’t know, like, giving a
value to a flag, using an unknown option, providing an invalid value for
an option, using an equal sign in a negated call etc.
Unfortunately for you, Clon is like a pitbull. Whatever you do to
beat it, it will fight back. The behavior of Clon with respect
to error management during option retrieval is well defined, but
contrary to the traditional approach, you, the end-user have
control over it. Not the application. Error handling may occur when the
command-line is parsed, but also when environment variables are used.
The error management behavior of Clon is controlled by a built-in
option named --clon-error-handler, and its accompanying environment
variable CLON_ERROR_HANDLER. Possibles values for it are
currently the following.
quit ¶This is the default. It means that when Clon encounters an error
related to option retrieval, it prints an informative message about the
error and terminates the application immediately (with an exit status of
1).
helpAlong with quit, this one implements a behavior also frequently
found in many applications out there (I mean, those not using Clon;
believe it or not, there are some; oh boy, do I feel sorry for them).
When an error occurs, the behavior is the same as above, but in addition
to that, the application’s help string is also printed automatically.
There are two exceptions to this however. When the problem is related to
a known option, the original error message is already informative
enough, so there is no point in printing the full help string on top of
it. Finally, when the problem seems related to a built-in option (that
is, an option starting with clon-, then the Clon-specific help
string is printed out, rather than the application’s one.
interactiveWhen interactive error handling is selected and an error is signaled, you are presented with a list of possible options to “fix” the problem. Such options include notably the ability to modify an option’s name or value (handy in case of command-line typo), discard the call altogether and many others, depending on the exact error.
When the error implies a bad value for a particular option, you will
notice that some of the choices that Clon proposes in order to fix
the problem involve providing another value or another
argument. Again, you need to remember the terminology here
(see Valued Options). The argument is what you provide on the
command-line, and the value is the conversion of the argument to the
proper type. This means that most of the time, you will want to use the
“argument” choice. If you know the Common Lisp language (see below), you can
also provide a value directly, in which case what you type in is in fact
Common Lisp code.
none ¶Using this option is not encouraged, unless you are the author of the
application and you are debugging it. A value of none literally
means no particular error handler. Here, I must apologize because I need
to go into some technical details about Common Lisp, the language in which
applications using Clon are written. Common Lisp mandates the existence of
a debugger in which you are dropped in when an unhandled error
condition is thrown. However some Common Lisp implementations may disable the
debugger when creating standalone programs. So the situation when the
Clon error handler is set to none depends on the application.
One last note about erorr handling: we have several chicken-and-egg
problems with it. The error handler must be known for parsing the
command-line, but in order to get it, we’d need to retrieve and option,
which implies parsing the command-line… Whoops. On top of that, if
the error handler is set to help, it requires the use of several
parameters (four, precisely) that also come from options
(see Output), themselves likely to trigger errors when misused.
Second whoops.
Because of this problem, the options affecting error handling are treated in a very special way.
quit is used initially
for error handling.
CLON_SEARCH_PATH, CLON_THEME, CLON_LINE_WIDTH, and
CLON_HIGHLIGHT. They will be described in greater detail in the
next chapter. Most of the time, you won’t need to use the associated
command-line options anyway. During all this time, only the basic error
handler is available.
CLON_ERROR_HANDLER, at which
point a fully functional help one could be set up. Remember that all
of this happens before even looking at the command-line itself.
Now you need to get some rest.