Programmer Guide/STx Guru

Whom this is for

This manual is a general introduction to the programming language that is part of the STx environment. Reading this manual will allow you to implement both procedural functions and object-oriented classes for a wide range of tasks, with a natural focus on numerical applications, sound processing, and visualization. As a reader of this manual, you should be slightly familiar with programming in general, and it would be great if you were an avid user of STx (on the other hand, being faintly familiar with starting up STx, loading sound files, and maybe even starting the spectrogram function should suffice).

This manual is intended for reading from start to end (not necessarily without interruptions). It is not a reference manual, meaning that it will abstract from many details (you might even bluntly say: omit them) in order not to depress the reader with a seemingly abundant amount of material. Instead, a careful selection has been taken on what is, and what is not, necessary for achieving common goals. Of course this selectivity (or, if you prefer, these omissions) try hard not to give any false impressions of what can, and what can't, be done with STx (and how). We are well aware that writing such an introductory programmer's (or, as we hope, programmers') manual is a slippery slope, and we hope for the reader's (or, as we hope, the readers') pardon if the depth covering each topic is too shallow, or to deep, or both (we are not quite sure whether the latter is logically possible, but one never knows). We appreciate any comments or criticism, both on this manual and on STx.

If you want to dig deeper into any specific topic, or if you are looking for information on a specific issue, we recommend having a look at the online help of STx (just start STx and select the "Help" menu, or press the "F1" key). The online help is a vast and ever-growing collection of deep, sometimes even exhausting wisdom. It is, in fact, the official reference manual. When new to STx programmers, we recommend first reading this manual (you might skip paragraphs you find particularly uninteresting), probably trying out all the examples by yourself, preferably even modifying and improving them. Afterwards, you will have a basis firm enough for using the STx online help as a reference manual. And you will surely have a sound basis for solving all your future programming tasks with STx, disposing of the need for any other programming languages or environments.

Constants

STx does not strictly discern between string constants and numerical constants. Normally each constant is considered a string, there only being exceptions dependent on the context where the constant occurs. If, for example, a constant occurs as part of a numerical expression, STx tries to get its numerical value.

Generally, you may, but you need not, put single quotes around constants. With a few exceptions depending on context, this will not change the way STx handles the constant. So each of the following strings is a valid STx constant:

string1

'string1'

-12.34

'-12.34'

Regardless of the presence or absence of single quotes, both the first and the second argument will be considered string constants. Also regardless of the presence or absence of single quotes, both the third and the fourth constant will be considered numerical constants when occurring in a numerical context, or string constants when occurring in a string context.

If a string constant contains whitespace characters, it depends on the context whether it is considered one string constant or more than one string constant. If you want to make sure that a string constant is considered one constant, you should always put single quotes around the whole affair:

'Hello World'

Hello World

While the first string is always considered one string constant, the second one may, depending on where it is occurring, be considered one string constant denoting the string "Hello World", or two string constants, denoting the strings "Hello" and "World", respectively.

These issues will be dealt with in more detail below. For the moment, the curious reader may have a look at the following assignment statements:

#a := num '5' * '3' // value of #a will be 15

#b := set 5 * 3 // value of #a will be "5 * 3"

The first statement is a numerical assignment (denoted by the keyword "num"). Both constants, 5 and 3, will be considered numerical constants, even if surrounded by quote characters. On the other hand, the second statement is a string assignment (denoted by the keyword "set"). So the argument will, logically, be interpreted as one string constant, "5 * 3", even though it contains whitespace and lacks any quote character. What happens physically is that all separate words will be concatenated to the one string constant expected, inserting exactly one blank between each pair of words. The following statements show the consequences of this procedure:

#b := set 5 * 3 // value of #b will be "5 * 3"

#b := set 5 * 3 // value of #b will be "5 * 3", too

#b := set '5 * 3' // value of #b will be "5 * 3"

In the second statement, though the words "5", "*", and "3" are separated by more than one whitespace character, the one string that will be built up from them is "5 * 3" – when concatenating them, they get separated by exactly one space character.

You may influence the way concatenation works by quoting some, or all, of the words to concatenate. Quoting a word will prevent STx from automatically inserting a blank before and after that word. So, compare the above statements with the statements below:

#b := set 5 '*' 3 // #b is "5*3" (no space)

#b := set '5' * 3 // #b is "5* 3" (one space)

#b := set 5 ' * ' 3 // #b is "5 * 3" (three spaces)

With the first statement, the word in the middle, "*", is quoted. This indicates STx on concatenation not to insert a space character either before or after this word, resulting in #b being set to "5*3" (no intervening whitespace).

With the second statement, the first word is quoted and will, hence, be concatenated to its right successor (there is no left predecessor) without inserting space. The second and the third word are not quoted and will be concatenated with an additional space in between them. This results in #b being assigned "5* 3" (no whitespace between "5" and "*", one blank between "*" and "3").

With the third statement, concatenation will not add any additional blanks either before or after the word in the middle. The whitespace that is part of the word, i.e. part of the quotation (three blanks before and after the asterisk, each), will be unaltered, though. So what results it #b being assigned the string "5 * 3" (exactly three blanks both before and after the asterisk).

Within a constant, you may alter the meaning of special characters by using the STx escape character "`", the backwards single quote, sometimes called back-tick. At the current stage, we can only use this feature for defining a string constant that contains single quote characters themselves:

#a := set 'Rome is a city but `'Rome`' is a four-letter word'

#a := set Rome is a city but `'Rome`' is a four-letter word

Both statements will assign the string "Rome is a city but 'Rome' is a four-letter word" to a variable called #a (although it may not always be easy later to retrieve the value of this variable). We have to leave these issues open for later discussion.

<splist parent= sort=asc sortby=title showpath=no liststyle=unordered kidsonly=yes >