5.1.5 Value Stringification Protocol

Okay, back to implementing our new option type.

The third and last protocol we need to implement is called the value stringification protocol. This protocol can be seen as the reverse protocol for argument conversion (see Argument Conversion Protocol): its purpose is to transform an option’s value into a corresponding argument that the end-user could have provided in order to get that value.

The main use for this protocol is to advertise the fallback and default values correctly in help strings: the end-user does not want to see those values, but rather the argument that would lead to them. However, you are free to use it wherever you like (see the convert method for enum options for instance).

The value stringification protocol is implemented through a stringify generic function for which you must provide a method.

Generic Function: stringify OPTION VALUE ¶

Transform OPTION’s VALUE into an argument.

I admit that this function could also have been called argumentize or even deconvertify. As you can see, you need to provide a method with the first argument specialized to your new option type. You can assume that VALUE is a valid value for your option, so no checking is necessary and no error needs to be raised.

Let’s look at the enumeration example now.

(defmethod stringify ((enum enum) value)
  "Transform ENUM's VALUE into an argument."
  (string-downcase (symbol-name value)))

Pretty straightforward, right?