Session 2
Syntactic Structure
Statements
Scripts must be syntactically well-formed. If they are not well-formed they'll terminate with an error message. The most important rule is that each line consists of exactly one complete statement, i.e. it's not allowed to have two or more statements in one line and it's usually not allowed to truncate a statement in one line and continue it in the next line. Thus, the following two scripts are not well-formed.
Prohibited: two statements per line
Create Sound as pure tone: "tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01
Play Play
Better:
Create Sound as pure tone: "tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01
Play
Play
Prohibited: truncated statement
Create Sound as pure tone:
"tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01
Play
If you absolutely need to spread a statement over two lines you may do so if the second line starts with three dots:
Create Sound as pure tone:
..."tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01
Play
Procedural execution
Statements in a script are executed line by line starting in the first line (procedural execution). Praat scripts are not compiled, which means they are translated on the fly from human-readable to machine-readable. Statements are executed line by line until something happens that can't be interpreted (for example an unannounced environment switch or a syntactic error or a typo). If that happens the script is aborted and displays an error message (remaining statements after the erroneous line are not executed—even if they are correct). In other words, to test a script you must run it. There's no compiler/debugger to warn you of errors beforehand. This means:
Error messages are neither unusual nor embarrassing.
You'll have to deal with them on a regular basis, even as an experienced power scripter. Just keep in mind that every statement up to the first error is executed (i.e. objects are created, settings are altered, windows are opened etc.). Therefore, between correcting an error and starting the next test run, most of the time you must reverse the results of the previous test run (remove objects, restore settings, close windows) to re-establish the initial state for your script.
Error messages consist of a description of the error and a line number. The error description is more or less informative and not always helpful, but the line number is helpful since it informs you where to look for problems—in the indicated line or in its vicinity (by the way, there's a
The statements you've seen so far all look pretty similar. They start with a GUI command, typed exactly as it appears in the GUI. Command names are case-sensitive and the three dots at the end of many commands are replaced by a colon (since Praat version 5.3.63).
# valid:
Create Sound as pure tone: "tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01
# invalid:
Create sound as pure tone: "tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01
Create Sound as pure tone... "tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01
Commands & Arguments
It depends on the GUI command, whether additional arguments must be specified. If clicking a GUI command triggers some action without further interaction, this command doesn't require additional arguments. For example, if you click the Play button in the GUI the selected sound is replayed without you filling in additional parameters. So, the statement below is perfectly valid:
Play
If you click
The first argument in the statement is the first (topmost) parameter in the form, the name of the object. The second argument is the second parameter, the number of channels (ignoring the
Create Sound as pure tone: "tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01
In this case the complete statement consists of one command and 9 arguments. In general, it's a good idea to generate complex statements like this with the help of command history (clear history—perform desired action—paste history). Typing statements like this 'by hand' is prone to errors: misspelled commands, forgotten parameters, wrong order of parameters etc. By using command history instead, you can be absolutely sure that the syntactic structure of the statement is correct. A good method is to insert such statements with command history and then edit parameters to your needs. For example, if you want a 500 Hz tone instead of the standard 440 Hz tone simply adjust the frequency parameter in the inserted statement:
Create Sound as pure tone: "tone", 1, 0, 0.4, 44100, 500, 0.2, 0.01, 0.01
And if you need a 500 Hz tone of 1 second duration adjust the end time parameter accordingly:
Create Sound as pure tone: "tone", 1, 0, 1, 44100, 500, 0.2, 0.01, 0.01
Numbers & Strings
We'll finish this section on the structure of statements with one last rule. The rule is based on the important distinction between numbers and strings. A preliminary definition: Strings are sequences of arbitrary characters (letters, digits, punctuation marks, spaces etc.) while numbers are, well, just numbers ((signed) sequences of digits and the decimal point). We'll come back to this distinction in greater detail and in other contexts. For now, in the context of command arguments, what you need to know is that string arguments must be enclosed in double quotes while numeric arguments must not. Let's have a last look at the tone creation statement:
Create Sound as pure tone: "tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01
Names of objects (1st argument) are always strings; they are written within double quotes. The remaining arguments are numbers (designating time, frequency, and amplitude) and are written without further marks.
To sum up, the pattern of using GUI commands in scripts is always the same:
- Copy simple GUI commands into the script exactly as they appear in the GUI (including spaces).
- Copy GUI commands with three dots at the end of their name (i.e. GUI commands which open an input form) into the script as they appear in the GUI, replacing the three dots with a colon, and add the appropriate number of arguments (see input form) after the colon, separated by commas.
- Wrap string arguments in double quotes.