4.3 Integrity Checks

At this point, you know about the two necessary steps to initialize Clon: defining a synopsis and creating a context. If you paid attention to the quick start application (see Quick Start), you may have noticed that defsynopsis was called as a top-level form whereas make-context was called from the function main. So why the difference?

First, I hope that you see why a context cannot be created as a toplevel form. If you do that, you will end-up creating a context relevant to the Lisp environment from which the application is created, not run.

The synopsis, on the other hand, could be defined either as a toplevel form, as done in the quick start and the demo programs, or in the function main, just before making a context. There is a very good reason to prefer a toplevel form however: that reason is called “integrity checks”.

When you define a synopsis (or any synopsis item, for that matter), Clon performs a number of checks to make sure that you’re making a sensible use of the library. In fact, the number of semantic mistakes that you can make is quite puzzling. You could for instance define several options with identical names, forget to provide a fallback or default value when it is required, provide invalid fallback or default values, and the list goes on and on. These are just a few examples but there are many more, and Clon checks all of those (I think).

Since those mistakes relate to the definition of the application itself, they do not depend on a particular execution of it. Consequently, the sooner Clon catches them, the better. If you define your application’s synopsis as a toplevel form, Clon will be able to perform its integrity checks when the application is created, not only when it is used. In other words, you won’t be able to get a working application until your use of Clon is semantically correct.

This is why it is strongly recommended to create synopsis from toplevel forms, and this also explains why Clon chooses not to provide an initialize function that would wrap around defsynopsis and make-context together.