3. Opening and compiling a grammar

If you are in a hurry to hear "Turkish" music you may jump to §5.2 because BP2 automatically compiles the alphabet and grammar when prompted to produce items...

3.1 What's in the examples folder?

All these files are in 'TEXT' format but they may have different file types to facilitate their selection in BP2's load/save operations. These types are documented on-line: click "Types-creators" in the "Frequently Asked Questions" dialog.

BP2 files can be loaded directly in word processors. Once the file has been edited save it as "ASCII" or "pure text". Then retrieve it under BP2 using the "load any file" option: type cmd-o with the option key down.

3.2 Headers and related files

Here is a very important feature of BP2: "projects" are made of several files linked together. This is a modular approach since that the same file (e.g. "-ho.abc1") may be shared by several projects. Whenever BP2 loads a file it scans its top lines searching the names of related files. If related files are found they will be loaded whenever necessary. For instance, the top of the grammar window for project "-gr.koto3" indicates:

i.e. the names of several related files. (Their use will be explained later.) In turn, the "Alphabet" window, in which "--ho.abc1" has been loaded, contains the name of the sound-object prototype file "-mi.abc1" required for its operation.

Generally you don't need to type or modify headers. For instance, if the grammar contains no header, as soon as you load an alphabet BP2 will insert a header with its name on tip of the "Grammar" and "Data" windows. If you save the alphabet file under a different name, or open another file, these headers are automatically updated accordingly. If you delete the alphabet headerers are removed...

You can look at the different files loaded: see menu "Windows" and try to remember keyboard shortcuts. As usual with Macintosh® software, BP2 keeps a trace of changes and prompts you to save or discard them before you clear a window or exit the program. However, it has a non-standard an altogether safe feature: the first time you type cmd-s after making changes, it prompts you to confirm the name and location of the file.

Closing a window with text or graphic data does not clear its content, except for the "Trace" window. It is sometimes useful to simplify the screen display. Systems above 7.5.1 also make it possible to reduce windows to their drag regions: a double or triple click on the title bar does the job.

3.3 Organising projects

It is important to store related files or their aliases in the same folder so that BP2 finds them immediately. Reserve a special folder to BP2 software, on-line documentation and start-up/shutdown files, as shown Fig.8.

MacOS offers an elegant solution for arranging projects: use aliases instead of moving or duplicating files. You may reserve another folder for the basic elements : alphabets, sound-object prototype files, glossaries, etc., as shown Fig.9.

File names are just indicative and should in general be more explicit. Names in italics are aliases. Here, for instance, an alias "- ho.alphabet1" is required in the same folder as "-gr.grammar1" because the name of this alphabet file appears on top of the grammar file. Similarly, other aliases have been placed near the files calling them. An alias of "-se.startup" is needed in the "Settings" folder so that scripts will execute the "New project" instruction properly.

Note that aliases for BP2 must bear exactly the names by which the files are called when BP2 reads headers. Here we used the same names for aliases and original files, the only way to distinguish them being the italic.

It is advisable to create a separate folder for saving your current work, given that whenever you create new basic elements you will continue storing them in the folders shown Fig.9. A typical example of work folder is shown Fig.10.

Here, Project 1 deals with a grammar (and associated alphabet, etc., files that are automatically loaded), while Project 2 uses only a data file (and associated files). Data files "-da.data1" and "-da.data2" call alphabet, settings, glossary and interactive file, aliases of which have been placed into the "Data" folder.

Some aliases in the "Scripts" folder are shown between brackets because they are only needed if a script calls them directly. Besides, scripts are capable of recording directory and volume changes (see §8).

Data on the demonstration disk is not organised in the rational way explained above, because aliases loose track of their original files if both are moved to a different volume.

3.4 Network operation

Since BP2 is able to resolve aliases and load files on remote volumes, this type of organisation may be extended to local network configurations: the basic elements could for instance be stored on a server and accessed by users with the usual read/write permissions. For instance, it is safe to protect alphabets or sound-objects from unauthorised modifications if they are shared by different projects.

BP2 can read directly text files edited by DOS or Windows editors. In this process, "high ASCII" characters are automatically transcoded. This feature has been implemented to facilitate the direct interpretation of text-oriented musical items or grammars produced in the Wintel environment.

3.5 A very simple grammar

Quit BP2 and double-click "-gr.doeslittle" in the "BP2 examples" folder. This will start again BP2, bypassing the welcome dialog, and the content of the "Grammar" window will be displayed as follows :

Type cmd-k or select "Compile" in the "Action" menu. BP2 quickly compiles the grammar, i.e. it generates some internal code ( tokens) that will enable it to produce items.

Now type cmd-r ("run") or select "Produce items" in the "Action" menu. After a short while an item is displayed in the graphic score and played on the MIDI output. You are given the option to produce more, play again, display as text or cancel. When producing more you will notice that the inference engine (the machines that "runs" the grammar) selects any of the three rules in the grammar to produce an item. This selection is random with equal probabilities, as stated by the instruction "RND" on top of the grammar.

The operation of this grammar is very simple : it starts with a work string containing only 'S', the starting symbol. A rule is selected at random. The selected rule replaces 'S', its left argument, with its right argument. Then no change is possible any more ; the item is displayed and played.

Type cmd-option space or select "Settings" in the "Windows" menu. A "Settings" dialog in two parts is displayed, along with three more option dialogs. These will be analysed in greater detail (see Fig.24 in §5.2). These settings have been loaded automatically from the file "-se.doeslittle" whose name appears on top of the "Grammar" window. For the time being, just watch the checked items : "Show graphics" forces graphic display, and "Use MIDI in/out" allows items to be played on the MIDI device. You may for instance check "Non-stop improvize" button and type cmd-r again. Now BP2 produces items continuously. To stop the production, hold the mouse button down and then click "STOP" when the red dialog appears in the top-left corner.

Improvizing on a slow computer may look deceiving because BP2 takes time to produce a new item and does not keep the tempo. Check the "Compute while playing" button to allow BP2 to proceed with calculations and keep items ready to play in a queue. If the grammar is not too complex, the tempo will be maintained. The drawback is that when you click to stop the improvisation, items still in the queue may continue playing. Clicking again will abort playing, but it may keep a note hanging because its 'NoteOff' has not been received. Flush the output clicking the "MIDI PANIC" button on the "Control Panel".

Every time the grammar is run it produces exactly the same sequence of pieces. This is due to the fact that BP2 resets its inner random number generator unless the "Allow randomize" button is checked on the upper "Settings" dialog.

3.6 A more elaborated project

Type cmd-l or select "Load project" in the "File" menu to load a project : you will be prompted to locate a grammar, and related files will be automatically loaded. Before loading a project, BP2 clears all project windows ; the same may be done by typing cmd-n or selecting "New project" in the "File" menu.

Clearing the current project is a good habit when you start a new job. If windows are not cleared they may still contain headers causing unwanted files to be loaded.

These are the names of the MIDI orchestra file, the interactive file, the time base file, the settings file and the alphabet file respectively. The file "-in.abc1" will be used for controlling BP2 interactively from a MIDI keyboard or controllers (see §6).

The "-se.koto3" settings file has already been automatically loaded. If BP2 does not find its name in the "Grammar" window it searches it in the "Data" window.

You can load grammar and alphabet files separately by typing cmd-o or selecting "Open file" in the "File menu" when the corresponding window is active. This additionally enables you to load files of types different of BP2 types, for example a grammar that has been edited in a word processor and saved as pure text: type cmd-o with the 'option' key down.

3.7 Tokenised alphabet and grammar

If you type cmd-h with the 'option' key down you have the option to display the alphabet in its "tokenised" form. A tokenised alphabet/grammar/glossary is useful to show whatever the compiler has been able to understand. It is displayed in a multi-purpose window called the "Trace" window.

The tokenised alphabet actually displays the entire mapping of homomorphism notated ' _*' that was partly defined in the original alphabet (see §2.4). Predefined symbols '-' and '_' represent silences and prolongations respectively. These are not modified by any homomorphism. Other symbols are specific to this "-ho.abc1" alphabet. Homomorphism ' _*' changes 'a' to 'a'', but 'a'' remains unchanged. Symbol 'chik' is also not affected by the transformation. (See §2.4 or reference manual §4.1 to understand homomorphisms.)

Looking carefully at the alphabet you may notice that a new terminal symbol 'sync' has been appended: it was not in the original file "-ho.abc1". The symbol was actually found between single quotes in the grammar, and therefore appended at compile time. Similarly, out-time sound-objects between angle brackets <<>> may contain terminal symbols that BP2 creates at compile time.

All rules have been numbered and contain weights. (See an explanation of weights in reference manual §4.6) Rules that were not assigned explicit weights appear with default weight <127>, a value that fits well with MIDI parameters.

Rule numbering has no real effect on computation. For instance, the order in which rules are scanned in "ORD" grammars (see reference manual §4.4) is always their actual order of occurrence in the grammar. Nevertheless, BP2 renumbers subgrammars and rules at compile time. These numbers are used for conditional jumps found in grammar procedures (see §8.1 of reference manual).

3.8 Checking grammar consistency

Selecting "Check variables" in the "Search" menu produces a report on variables used in the grammar. Some variables may be undefined, i.e. they appear in the right argument of a rule and nowhere in the left argument of a grammar or glossary rule. The grammar might therefore produce final strings containing these variables. BP2 warns the user at compile time if the grammar contains undefined variables. The grammar may nevertheless be used: when interpreting the final string as a musical item, BP2 ignores left-over variables. When compiling a glossary, however, an error message is returned if any rule or "Define" instruction produced an undefined variable.

Conversely, unreachable variables are the ones found in the left argument of a rule although they appear in no right argument, so that the grammar will never produce them. This is generally not considered a mistake because a grammar may contain unreachable variables coming from an earlier version. Rules containing them will never be candidates. Glossaries may also contain many unreachable variables because a project is generally not using all functionalities of MIDI devices -- it is not likely to make use of the 128 instruments defined in General MIDI, for instance.

When compiling a glossary (see §7), BP2 makes sure that it does not generate variables appearing in the left argument of a grammar rule. Since the glossary is used only once all candidate rules in the grammar have been exhausted (or there is no grammar), the grammar may not be invoked afterwards.

3.9 The start string

Generally the start string is predefined symbol 'S', but sometimes you may want to derive other strings of variables/terminal symbols, especially while debugging a grammar. Type or paste start strings on separate lines in the "Start string" window, then select the one you want by highlighting it with the mouse. If you select no start string then the first one in the window is always used. Since 'S' is already there whenever you start the program you may ignore this "Start string" window until you decide to use alternate start strings.

Another, more intuitive, way of using any expression as a start string is to select it in any window (including the grammar itself) and type cmd-p or select "Play selection" in the "Action" window. Normally this command tries to interpret the selection (using the alphabet), but if the selection contains variables then it is taken as a start string and the grammar is prompted to derive a single item from it.