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
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.
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 () 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 three types of built-in functions: 'management functions', mathematical functions, and string functions. Management functions like
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). 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.
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$ (), "")
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$ () takes two arguments, a number (in our case the pitch maximum) and the precision you wish (number of decimal places, e.g. 2). Since
# 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
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))
to be continued...
• more on functions
• list of 'management' functions
• links to Praat manual