4.1.3.1 Constructors

Let’s have a look at the expansion of defsynopsis from the quick start example (see Quick Start).

The original code is like this:

(defsynopsis (:postfix "FILES...")
  (text :contents "A very short program.")
  (group (:header "Immediate exit options:")
    (flag :short-name "h" :long-name "help"
          :description "Print this help and exit.")
    (flag :short-name "v" :long-name "version"
          :description "Print version number and exit.")))

And once the macro is expanded, it will look like this:

(make-synopsis :postfix "FILES..."
  :item (make-text :contents "A very short program.")
  :item (make-group :header "Immediate exit options:"
          :item (make-flag :short-name "h"
                           :long-name "help"
                           :description "Print this help and exit.")
          :item (make-flag :short-name "v"
                           :long-name "version"
                           :description "Print version number and exit.")))

As you can see, every synopsis element has a corresponding make-SOMETHING constructor, and the keywords used here and there in defsynopsis are in fact initargs to those constructors. We now examine those constructors in greater detail.

Function: make-text [:hidden BOOL] :contents STRING ¶

Create an arbitrary text object, possibly hidden, whose contents is STRING.

Function: make-OPTION :INITARG INITVAL… ¶

Create a new OPTION object, OPTION being any built-in option type (flag, stropt etc., see Built-In Valued Options) or user-defined one (see New Option Types). For a list of available initialization arguments (depending on the option type), see Built-In Option Types.

Function: make-group [:header STRING :hidden BOOL] :item ITEM1 :item ITEM2… ¶

Create a group object, possibly hidden, whose header is STRING. Every ITEM is an arbitrary text object, option object or group object. The order is important as it determines the display of the help string.

Function: make-synopsis [:postfix STRING] :item ITEM1 :item ITEM2… ¶

Create a synopsis object whose postfix is STRING. Every ITEM is an arbitrary text object, option object or group object. The order is important as it determines the display of the help string.

In fact, the defsynopsis macro allows you to freely mix declarative forms, constructor calls or whatever Lisp code you may want to use. The way this works is as follows: if a synopsis ITEM (see Synopsis Items) is a list whose car is text, group, or any option type (inluding those you define yourselves; see New Option Types), then the ITEM is expanded as explained earlier. Otherwise, it is just left as-is.

To sum up, here’s a example of things you can do in defsynopsis.

(net.didierverna.clon:defsynopsis ()
  (flag #| ... |#)
  *my-great-option*
  (setq *another-option* (net.didierverna.clon:make-switch #| ... |#)))