Previous: , Up: Option Retrieval   [Contents][Index]


3.4.2 Error Management

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). This is the behavior of most programs out there I guess.

interactive

When 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 the --clon-error-handler option: we have a chicken-and-egg problem with it. The error handler must be known for parsing the command-line, but in order to get it, we need to retrieve the option which implies parsing the command-line… Whoops. Because of this problem, the option is treated in a very special way.

  1. First of all, a built-in default value of quit is used initially.
  2. However, if the CLON_ERROR_HANDLER environment variable is set, its value will be used immediately, even before trying to get the option on the command-line (if an error happens when trying the environment variable, the quit handler is used).
  3. Finally, if the option is found on the command-line during the parsing of it, its value is updated immediately (so it also applies for parsing the rest of the command-line).

Now you need to get some rest.


Previous: , Up: Option Retrieval   [Contents][Index]