### 8.3 Scheme Festival specifics ¶

There a number of additions to SIOD that are Festival specific though still part of the Lisp system rather than the synthesis functions per se.

By convention if the first statement of a function is a string, it is treated as a documentation string. The string will be printed when help is requested for that function symbol.

In interactive mode if the function `:backtrace` is called (within parenthesis) the previous stack trace is displayed. Calling `:backtrace` with a numeric argument will display that particular stack frame in full. Note that any command other than `:backtrace` will reset the trace. You may optionally call

    (set_backtrace t)

Which will cause a backtrace to be displayed whenever a Scheme error occurs. This can be put in your `.festivalrc` if you wish. This is especially useful when running Festival in non-interactive mode (batch or script mode) so that more information is printed when an error occurs.

A hook in Lisp terms is a position within some piece of code where a user may specify their own customization. The notion is used heavily in Emacs. In Festival there a number of places where hooks are used. A hook variable contains either a function or list of functions that are to be applied at some point in the processing. For example the `after_synth_hooks` are applied after synthesis has been applied to allow specific customization such as resampling or modification of the gain of the synthesized waveform. The Scheme function `apply_hooks` takes a hook variable as argument and an object and applies the function/list of functions in turn to the object.

When an error occurs in either Scheme or within the C++ part of Festival by default the system jumps to the top level, resets itself and continues. Note that errors are usually serious things, pointing to bugs in parameters or code. Every effort has been made to ensure that the processing of text never causes errors in Festival. However when using Festival as a development system it is often that errors occur in code.

Sometimes in writing Scheme code you know there is a potential for an error but you wish to ignore that and continue on to the next thing without exiting or stopping and returning to the top level. For example you are processing a number of utterances from a database and some files containing the descriptions have errors in them but you want your processing to continue through every utterance that can be processed rather than stopping 5 minutes after you gone home after setting a big batch job for overnight.

Festival’s Scheme provides the function `unwind-protect` which allows the catching of errors and then continuing normally. For example suppose you have the function `process_utt` which takes a filename and does things which you know might cause an error. You can write the following to ensure you continue processing even in an error occurs.

    (unwind-protect
     (process_utt filename)
     (begin
       (format t "Error found in processing %s\n" filename)
       (format t "continuing\n")))

The `unwind-protect` function takes two arguments. The first is evaluated and if no error occurs the value returned from that expression is returned. If an error does occur while evaluating the first expression, the second expression is evaluated. `unwind-protect` may be used recursively. Note that all files opened while evaluating the first expression are closed if an error occurs. All global variables outside the scope of the `unwind-protect` will be left as they were set up until the error. Care should be taken in using this function but its power is necessary to be able to write robust Scheme code.