Entry Points

Following are simple examples for each entry point recognized by MMA .

run(param-list):

The RUN() function is executed when a MMA script encounters the plugin's keyword in a non-track context. Following is a simple bit of Python code we used in the hello example shipped with MMA .

 

def run(l):
    print("Hello. This is the run() function in the MMA plugin.")
    print("We are at line %s in the MMA file %s." % (gbl.lineno, gbl.infile))

    if l:
        print("Args passed are:")
        for i in l:
            print(i)

In the first line we pass the parameter “l”. This is set by the main MMA parser and contains a list of any parameters passed to the @HELLO function.

We leave the rest of the program as an exercise.

trackRun():

The next entry point is the TRACKRUN() function. This is executed when the parser finds the plugin's keyword in a track context. For example:

Plectrum-Main @Hello My command params

The difference between the simple and track versions is that trackRun() is also passed the “name” of the track. For example, the above example will have the first parameter set to the string “PLECTRUM-MAIN”. Using the following code you can set a variable (in this case “self”) to point to the Plectrum-Main class.

 

    self = gbl.tnames[name]

For this to work, you will need to import MMA 's global module into the namespace. We suggest you do that at the top of your plugin.py module:

 

    import MMA.gbl as gbl

Using the “self” variable you now have access to all of the variables associated with the track. You'll have to dig though the code a bit, but a few examples (most of the settings are in the form of a list with a value for every sequence point in your song):

 

  self.volume  -- track specific volume 
  self.articulate -- track specifc articulations
  self.sticky -- a True/False setting

For more variables we suggest you examine the pat.py module.

Yes, you can change these values from your plugin. Is that a good idea? Probably not! For an alternate method to change settings read the “returning values” chapter, below.

dataRun(param-list):

The DATARUN() function is executed when a MMA script encounters the plugin's keyword in a data line context. If you examine the very simple code for addgm/plugin.py you'll see a one line python function defined in the example file plugins/addgm shipped with MMA .

 

def dataRun(ln):
     return ['Gm'] + ln

All it does is to add "Gm" to the start of data line. However, there is nothing saying you can't do much, much more with this. The function is passed the entire data line (as a Python list). You could parse it and change chord names or types, etc.

• If no leading comment line number is present in your data line and the run() function is defined, the run() function (from the plugin) will be called.

• If there is not a leading comment line number and run() has not been defined, a comment line number based on MMA 's internal tables is inserted into the start of the line and the dataRun() function (from the plugin) is called.

• In most cases you'll find it easiest to create a plugin which has a trackRun() and/or a run() function or a dataRun() function. Combining them will lead to your confusion!

printUsage():

The final entry point is the PRINTUSAGE() command. It receives no parameters and is only called when MMA finds a -I plugin-name command line argument. This code is then interpreted and the program ends.

PRINTUSAGE() should print a simple usage message.