Provides explicit control over printing slot values used when defining methods on write-event and print-object. formatting-slots uses formatting directives to control slot value printing. Directives may be applied globally to all slots or locally to a single slot. A local formatting directive always overrides a global directive with the same name. Directives are specified as keyword value pairs, where keyword is the name of the directive and value is its value.

Object is the object whose slots are to be printed. Stream is the output stream . Following stream comes zero or more global directives. Local directives are specified along with the slots in the body of the macro.

formatting-slots implements the following directives:

:preamble {string | char}

Sets a string or character to be printed before any slot formatting occurs.

:postamble {string | char}

Sets a string or character to be printed after all slot formatting occurs.

:delimiter {string | char}

Sets a string or char to be printed between each value. Defaults to #\Space.

:print-if { t | :bound | :always}

Controls how a slot should be processed. If t (the default), the slot is formatted without first checking its current state. This means that an error will be signaled if the slot is unbound at the time that its value should be printed. This is the correct behavior for printing required instrument parameter values since the error detects incomplete score data at the earliest possible time. If the value is :always, then an unbound slot will print "-unset-" as its value, otherwise its value is printed. Use :always inside methods on the Lisp function print-object to include slots in the printed representation of the object even if they are unbound. If the value is :bound, then a slot is formatted only if it actually contains a value, otherwise it is omitted from the formatting-slots display altogether. Use :bound to print optional, keyword or message parameters. All Music Kit parameters are formatted using :bound.

:prefix {string | char | function-name}

Sets a string or character to be printed after :delimiter and before the value. If supplied, :prefix must print any delimiter between itself and the value to be printed. If :prefix is a function, it is called at macro expansion time to return the actual prefix string or character to be used. The function is be passed one argument, the name of the slot to be prefixed. The system provides two prefix functions, keyword-prefix, which returns the Lisp keyword name for a given, and music-kit-prefix, which returns the objective C message string for a slot.

:suffix {string | char | function-name}

Like :prefix except that it is processed after the value has been printed.

:default {value | nil}

Sets a value to be printed if the slot is unbound.

:eol {nil | t}

Sets whether or not an end-of-line character is printed after formatting-slots has processed all other directives. Defaults to nil.

:printer {function-name | lambda-expression}

Sets the function called to print the value. This function is passed two arguments, the value to print and the output stream. The default printer is princ.

:filter {function-name | lambda-expression}

Sets a function to receive the value just before it is printed. :filter returns a value to print.

:decimals {integer | nil}

Creates a filter to check for numeric slot values. If the value is not numeric it is printed as is. If the value is a floating point number then it is rounded to integer places after the decimal point. If :decimals is 0 then floating point values are coerced to integers. :decimals and :filter are exclusive keywords.

:format {:quoted | :string | :careful}

Controls how a value should be formatted. :quoted causes the Lisp quote character ' to appear just before the printed value. :string causes the value to be printed inside string quotes "...". :careful first checks the value to be printed. If the value is a list or an unbound symbol, it is quoted before printing, otherwise it value is printed as is. :careful is useful for printing note names or instrument envelopes.

:constructor {function}

Provides an escape to user defined formatting via a supplied function. This function is called at macro expansion time to return a function of one argument which will become the formatting function for the slot. :constructor cannot be used in conjunction with any other keyword.

In addition to local directives, three special tokens &key, &rest and &optional may appear in the body of formatting-slots. These tokens implement a shorthand for formatting values in "lambda list" format. All slot directives appearing after &key will automatically contain a :print-if value of :bound and a :prefix value equal to the keyword name of the slot.

Example:

(formatting-slots (object stream :print-if :bound
                         :prefix mk-make-prefix)
  freq amp)

freq:c4 amp:.9

(formatting-slots (obj stream :preamble "(fm-violin "
                      :postamble ")" :eol t)
  time dur freq &key :amp :ampenv)

(fm-violin 0.0 1.0 440.0 .5 :ampenv '(0 0 1 100))