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).

help

Along 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.

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 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.

  1. First of all, a built-in default value of quit is used initially for error handling.
  2. Next, the environment variables affecting output are polled. These are 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.
  3. Then the environment is polled for 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.
  4. Finally, the command-line is parsed, and during parsing, the five built-in options involved in error handling / help output are processed immediately if ever encountered, so as to affect the rest of the parsing. These are --clon-error-handler, --clon-search-path, --clon-theme, --clon-line-width, and --clon-highlight. Again, the last four ones will be explained in the next chapter.

Now you need to get some rest.