If the 'destination' is NIL , a string is created and returned with the contents of the 'format'.
If a Nyquist script returns a string, then Audacity displays the string in a pop-up message window.
In LISP / Nyquist, the tilde "~" character in a string has a special meaning. In conjunction with the next character, it acts as a "format specifier".
Some common format directives are:
~A - Prints the expression as ASCII text. Strings are printed without quotes.
~S - Prints the expression as an s-expr. Strings are printed with quotes.
~% - prints a 'newline' control character.
- Code: Select all
(format nil "~s ho ho" "o&&")
This will replace ~s with "o&&", forming a string:
"o&&" ho ho
If the ~A specifier is used,
- Code: Select all
(format nil "~a ho ho" "o&&")
then the created string will be:
o&& ho ho
The returned string may be bound to a variable like this:
- Code: Select all
(setf my-string (format nil "~a ho ho" "o&&"))
Because the destination is NIL, the format function doesn't print the string anywhere, but if the string is the final expression in a script, then the string will be the value that is returned by the script (the "return value") and Audacity will display it in a pop-up message.
- Code: Select all
(setf my-string (format nil "~a ho ho" "o&&"))
(hzosc 440)
This code creates a string "o&& ho ho" and binds the value to the variable "my-string". The string is not printed because the destination is NIL.
The return value of the script is a 440 Hz sine wave.
- Code: Select all
(setf my-string (format nil "~a ho ho" "o&&"))
(hzosc 440)
my-string
In this case, "my-string" is the final expression of the script, so it is returned to Audacity. The value of "my-string" is "o&& ho ho", so Audacity creates a message window and displays the text "o&& ho ho" in it.
If the 'destination' is T , the printing occurs to *standard-output*. For Nyquist plug-ins, the *standard-output* is the debug window.
- Code: Select all
(setf my-string (format t "~a ho ho" "o&&"))
(hzosc 440)
This code creates a string "o&& ho ho" and binds the value to the variable "my-string". The string is printed to the debug output.
The return value of the script is a 440 Hz sine wave.
- Code: Select all
(setf my-string (format t "~a ho ho" "o&&"))
(hzosc 440)
my-string
In this case, "my-string" is printed to the debug window.
"my-string" contains the string "o&& ho ho", but it also carries the "destination" as the debug output, so it is not returned to Audacity so there is no message box.
If we want the last example to return "my-string" to Audacity as well as printing to the debug window, we could write:
- Code: Select all
(setf my-string (format nil "~a ho ho" "o&&"))
(format t "~a" my-string) ;print to debug
(hzosc 440)
my-string ;return value