next up previous
Next: Creating Effects Up: Reference Manaul Previous: Documentation Strings

Subsections


Paths, Files and Libraries

This chapter covers MMA filenames, extensions and a variety of commands and/or directives which effect the way in which files are read and processed.

But, first a few comments on the location of the MMA Python modules.

The Python language (which was used to write MMA) has a very useful feature: it can include other files and refer to functions and data defined in these files. A large number of these files or modules are included in every Python distribution. The program MMA consists of a short, main, program and several ``module'' files. Without these additional modules MMA will not work.

The only sticky problem in a program intended for a wider audience is where to place these modules. We've decided that they should be in one of three locations:

If, when initializing itself, MMA cannot find one of the above directories, it will terminate with an error message.


File Extensions

For most files the use of a the filename extension ``.mma'' is optional. However, we suggest that most (with the exceptions listed below) have the extension present. It makes it much easier to identify MMA song and library files and to do selective processing on these files.

The following is a list of the different files which MMA processes and the logic used extension processing:

Song Files
The input file specified on the command line should always be named with the ``.mma'' extension. When MMA searches for the file it will automatically add the extension if the file name specified does not exist and doesn't have the extension.

Library Files
Library files really should all be named with the extension. MMA will find non-extension names when used in a Use or Include directive. However, it will not process these files when creating indexes with the ``-g'' command line option--these index files are used by the Groove commands to automatically find and include libraries.

RC Files
As noted in the RC-File discussion ([*]) MMA will automatically include a variety of ``RC'' files. You can use the extension on these files, but common usage suggests that these files are probably better without.

MMAstart and MMAend
MMA will automatically include a file at the beginning or end of processing ([*]). Typically these files are named MMAstart and MMAend. Common usage is to not use the extension if the file is in the current directory; use the file if it is in an ``includes'' directory.

One further point to remember is that filenames specified on the command line are subject to wildcard expansion via the shell you are using.

Eof

Normally, a file is processed until its end. However, you can short-circuit this behavior with the Eof directive. If MMA finds a line starting with EOF no further processing will be done on that file ... it's just as if the real end of file was encountered. Anything on the same line, after the Eof is also discarded.

You may find this handy if you want to test process only a part of a file, or if you making large edits to a library file. It is used quit often when using the Label and Goto directives to simulate constructs like D.C. al Coda, etc.


LibPath

The search for library files can be set with the LibPath variable. Internally, the LibPath items are stored as a python list. To set LibPath:

SetLibPath PATH1 PATH2 ...

You can have any number of paths in the SetLibPath directive.

When MMA starts up it attempts to set the library path to a useful value. If initial RCFile does not set the path, then the following locations are checked:

The path is set to the first found directory.

You can disable the LibPath by using the line:19.1

SetLibPath

with no arguments (however, if you do this in the RCFile, the above routine will find a default location).

This is commonly set in an RC file ([*]).

The LibPath is used by the routine which auto-loads grooves from the library, and the Use directive. The -g command line option is used to maintain the library database ([*]).

If there is a single ``+'' in the command argument, or if any of the arguments start with a ``+'' the new locations are appended to the existing path value. For example:

SetLibPat +/usr/share/mma/lib/geoff /usr/share/mma/lib/myjazz

OutPath

MIDI file generation is to an automatically generated filename ([*]). If the OutPath variable is set, that value will be prepended to the output filename.

To set the value:

SetOutPath PATH

Just make sure that ``PATH'' is a simple pathname with no spaces in it. The variable is case sensitive (assuming that your operating system supports case sensitive filename). This is a common directive in an RC file ([*]). By default, it has no value.

You can disable the OutPath variable by not using an argument in the SetOutPath directive.

Include

Other files with sequence, pattern or music data can be included at any point in your input file. There is no limit to the level of includes.

Include Filename

A search for the file is done in the current directory and in the directories in the IncPath (see below). The ``.mma'' filename extension is optional.

The use of this command should be quite rare. We can see it being used to include some temporary library files. Anything else? Let us know.


IncPath

The search for include files (and MMAstart and MMAEnd) files can be set with the IncPath variable. Internally, the IncPath items are stored as a python list. To set IncPath:

SetIncPath PATH1 PATH2 ...

You can have any number of paths in the SetIncPath directive.

When MMA starts up it attempts to set the include path to a useful value. If initial RCFile does not set the path, then the following locations are checked:

The path is set to the first found directory.

You can disable the IncPath by using the line:

SetIncPath

with no arguments (however, if you do this in the RCFile, the above routine will find a default location).

This is commonly set in an RC file ([*]).

If there is a single ``+'' in the command argument, or if any of the arguments start with a ``+'' the new locations are appended to the existing path value. For example:

SetIncPat +/usr/share/mma/myincs


Use

Similar to Include, but a bit more useful. The Use command is used to include library files and their predefined grooves.

Compared to Include, Use has important features:

Let's examine each feature in a bit more detail.

When a Use directive is issued, eg:

use stdlib/swing stdlib/metronome

MMA assumes that you are loading two library files. To locate the files, MMA prepends each string in the LibPath variable to the library filename ([*] for the defaults used for this variable). The search for the file ends when a match is found; an error is reported if the file is not found. For example, if you have set LibPath with the line:

SetLibPath . /usr/local/share/mma/lib /share/mma/lib

and you are attempting to use the file ``swing'', the following locations will be checked:

  1. ./swing.mma
  2. /usr/local/share/mma/swing.mma
  3. /home/bob/share/mma/swing.mma

Line 2 assumes that the user's home directory is /home/bob.

If things aren't working out quite right, check to see if the filename is correct. Problems you can encounter include:

As mentioned above, the current state of the compiler is saved during a Use. MMA accomplishes this by issuing a slightly modified DefGroove and Groove command before and after the reading of the file. Please note that Include doesn't do this.

In most cases you will not need to use the Use directive in your music files. If you have properly installed MMA and keep the MMADIR files up-to-date by using the command:

mma -g

grooves from library files will be automatically found and loaded. Internally, the Use directive is used, so existing states are saved.

If you are developing new or alternate library files you will find the Use directive handy.


MmaStart

If you wish to process a certain file or files before your main input file, set the MmaStart filename in an RCFile. For example, we have a number of files in a directory which we wish certain Pan settings. In that directory, we have a file mmarc which contains the following command:

MmaStart setpan

The actual file setpan has the following directives:

Bass Pan 0
Bass1 Pan 0
Bass2 Pan 0
Walk Pan 0
Walk1 Pan 0
Walk2 Pan 0

So, before each file in that directory is processed, the Pan for the bass and walking bass voices are set to the left channel.

If the file specified by a MmaStart directive does not exist a warning message will be printed (this is not an error).

Also useful is the ability to include a generic file with all the MIDI files you create. For example, we like to have a MIDI reset at the start of our files, so we have the following in our mmarc file:

MMAstart reset

This includes the file reset.mma located in the ``includes'' directory ([*]).

Because it is not uncommon to have multiple mmarc files, each with a different MMAstart directive, the files are appended to the existing list. Each file will be processed in the order it is declared. You can have multiple filenames on a MMAstart line.


MmaEnd

Just the opposite of MmaStart, this command specifies a file to be included at the end of a main input file. See our comments above for more details.

To continue our example, in our mmarc file we have:

MmaEnd nopan

and in the file nopan we have:

Bass Pan 64
Bass1 Pan 64
Bass2 Pan 64
Walk Pan 64
Walk1 Pan 64
Walk2 Pan 64

If the file specified by a MmaEnd directive does not exist a warning message will be printed (this is not an error).

Because it is not uncommon to have multiple mmarc files, each with a different MMAend directive, the files are appended to the existing list. Each file will be processed in the order it is declared. You can have multiple filenames on a MMAend line.


RC Files

When MMA starts it checks for initialization files. Only the first found file is processed.

The following files are checked (in order):

  1. mmarc
  2.  /.mmarc
  3. /usr/local/etc/mmarc
  4. /etc/mmarc

All found files will be processed.

Note that the second file is an ``invisible'' file due to the leading ``.'' in the filename.

By default, no rc files are installed.

The rc file is processed as a MMA input file. As such, it can contain anything a normal input file can, including music commands. However, we suggest you limit the contents of your RC files to things like:

SetOutPath
SetLibPath
MMAStart
MMAEnd

A useful setup is to have your source files in one directory and MIDI files saved into a different directory. Having the file mmarc in the directory with the source files permits setting OutPath to the MIDI path.

Library Files

Included in this distribution are a number of predefined patterns, sequences and grooves. They are in different files in the ``lib'' directory.

The library files should be self-documenting. A list of standard file and the grooves they define is included in the separate document, supplied in this distribution as ``mma-lib.ps''.



Footnotes

... line:19.1
This is NOT a good idea!

next up previous
Next: Creating Effects Up: Reference Manaul Previous: Documentation Strings
2004-04-19