Session 7
Commands & Functions

You should be pretty familiar with commands by now. Just copy the names of buttons or menu items into your script and add some arguments if necessary—that's it (or use command history). En passant, I've introduced you to a quite similar construct in the previous sessions: built-in functions. Examples of built-in functions are number (), string$ (), selected (), or extractWord$ (). They have much in common with commands but you won't find them in the GUI. They consist of a function name, followed by a (optional) space and a list of arguments enclosed in round brackets. You're not allowed to omit the brackets, even if the arguments list is empty. Within the brackets, the same rules as for command arguments apply: arguments have a fixed order, are separated by commas, and are wrapped in double quotes if they are literal strings.

Return value

Functions always yield a return value and the name of the function tells you the type of its return value. If the name ends with $ the function returns a string, if there's no $ it returns a number. In fact, there are some functions that come in two flavors: with and without a $. An example you already know is selected () and selected$ (). selected () yields a numeric return value (object ID), while selected$ () yields a string value (object type+name).

Since functions are not part of the GUI, you can't use command history to insert them into your scripts. Instead, you have to type them by hand. That's a pity, but it's worth the effort, because the benefit of functions is immense. Many operations can't be implemented without functions and many operations are seriously simplified by using functions.

Praat provides a growing list of built-in functions. In this session, we'll focus on three types of functions: 'management functions', mathematical functions, and string functions. Management functions like selected () and selected$ () can be found scattered in the scripting tutorial of the Praat manual (choose Help > Scripting tutorial in the script editor). They help with the management of objects, files, or scripts. Other examples are fileReadable () to ascertain whether a certain file is readable or exitScript () to abort a script before the end is reached.

Mathematical and string functions are listed in the formulas tutorial of the Praat manual. Choose Help > Formulas tutorial in the script editor or browse online: Mathematical functions / String functions. Praat's mathematical functions cover the usual stuff like round () (round a real number to the nearest integer), sqrt () (calculate square root), or sin () (calculate sine). Besides, there are some advanced statistical and conversion functions. Among the string functions you'll find functions to analyze strings (e.g. length () counts the number of characters), extract substrings (e.g. extractWord$ ()), modify strings (delete/add/replace substrings; e.g. replace$ ()), and convert strings (e.g. number () or string$ ()). Have a look at the huge list of mathematical and string functions in the Praat manual at least once to get a feeling for what is available. Then come back to the list every time you ask yourself how to solve a nasty little problem—more often than not there's a built-in function to help you.

Most of the time, return values of functions are assigned to variables:

type_name$ = selected$ ()
type$ = extractWord$ (type_name$, "")

Functions as arguments

But it's also possible (in most contexts) to replace literal values with functions. In this case, functions behave like variables. For example, you can combine the two statements above into one statement:

type$ = extractWord$ (selected$ (), "")

First, selected$ () is replaced by its return value (type+name of the selected object) like variables are replaced by their content, then extractWord$ () kicks in and the result is assigned to type$.

Another example: The query command Get maximum returns the maximum pitch of a selected pitch object, which is a real number with many digits after the decimal point. If you need to reduce the number of digits, you have two possibilities: (1) Get rid of all decimal places and reduce the pitch maximum to an integer with the mathematical function round () or (2) preserve some decimal places and round the maximum to e.g. 2 digits after the decimal point. The latter can be done with the string function fixed$ (); fixed$ () takes two arguments, a number (in our case the pitch maximum) and the precision you wish (number of decimal places, e.g. 2). Since fixed$ () terminates in a $, it returns a string, therefore we must assign it to a string variable:

# query pitch maximum
pitchMax = Get maximum: 0, 0, "Hertz", "Parabolic"
# round; result: integer number
pitchMaxInt = round (pitchMax)
# round with fixed precision; result: string (sequence of digits)
pitchMaxFix$ = fixed$ (pitchMax, 2)

writeInfoLine: pitchMaxInt, tab$, pitchMaxFix$

To avoid the entire variable assignment, we can insert the functions directly as arguments of writeInfoLine:

pitchMax = Get maximum: 0, 0, "Hertz", "Parabolic"
writeInfoLine: round (pitchMax), tab$, fixed$ (pitchMax, 2)

And what if we want to use the result of fixed$ () as a number? Well, we simply convert it back, from string to number with the number () function:

pitchMax = Get maximum: 0, 0, "Hertz", "Parabolic"
# round with fixed precision; result: string
pitchMaxFix$ = fixed$ (pitchMax, 2)
# convert string to number
pitchMaxFix = number (pitchMaxFix$)

Again, we're allowed to cut a corner by using a function as an argument instead of assigning its return value to a variable:

pitchMax = Get maximum: 0, 0, "Hertz", "Parabolic"
pitchMaxFix = number (fixed$ (pitchMax, 2))