Keywords: mma-plugins

Subsections

- How to use pluginUtils module
- Function documentation

# Standard Interface

To make life easier for plugin authors, a module, pluginUtils.py, has been added to MMA .5.1

# How to use pluginUtils module

When you access MMA internals, you have to care about MMA changes. For example, the names of the members could change, and you should check the compatibility of your plugin with every new version of MMA that comes out.

The functions defined in pluginUtils are guaranteed to not change and to be updated together with MMA Also, they help you with documentation and argument parsing.

To explain how to use pluginUtils, we have commented the source of the StrumPattern plugin.

        # We import the plugin utilities
        from MMA import pluginUtils as pu

        # ###################################
        # # Documentation and arguments     #
        # ###################################

        # We add plugin parameters and documentation here.
        # The documentation will be printed either calling printUsage() or
        # executing "python mma.py -I pluginname".
        # I suggest to see the output for this plugin to understand how code
        # of this section will be formatted when printed.

        # Minimum MMA required version.
        pu.setMinMMAVersion(15, 12)

        # A short plugin description.
        pu.setDescription("Sets a strum pattern for Plectrum tracks.")

        # A short author line.
        pu.setAuthor("Written by Ignazio Di Napoli <neclepsio@gmail.com>.")

        # Since this is a track plugin, we set the track types for which it can
        # be used. You can specify more than one. To allow for all track types,
        # call setTrackType with no arguments.
        # For non-tracks plugin, don't call setTrackType at all.
        # Whether the plugin is track or non-track is decided by the entry point,
        # but help will use this information.
        pu.setTrackType("Plectrum")

        # We add the arguments for the command, each with name, default value and a
        # small description. A default value of None requires specifying the argument.
        pu.addArgument("Pattern",     None,  "see after")
        pu.addArgument("Strum",       "5",   "strum value to use in sequence (see Plectrum docs)")
        # Some arguments are omitted -- you can see the full source code if you're interested.

        # We add a small doc. %NAME% is replaced by plugin name.
        pu.setPluginDoc("""
        The pattern is specified as a string of comma-separed values, that are equally spaced into the bar.

       ...... Use the command “mma -i strumpattern” to see the complete documentation!

        Each time it's used, %NAME% creates a clone track of the provided one using the voice MutedGuitar for chucks and muted strums.
        Its name is the name of the main track with an appended "-Muted", if you need to change it you must do so every time after using %NAME%.

        This plugin has been written by Ignazio Di Napoli <neclepsio@gmail.com>.
        Version 1.0.
        """)

        # ###################################
        # # Entry points                    #
        # ###################################

        # This prints help when MMA is called with -I switch.
        # Cannot import pluginUtils directly because it wouldn't recognize which
        # plugin is executing it.
        def printUsage():
            pu.printUsage()

        # This is a track plugin, so we define trackRun(trackname, line).
        # For non-track plugins we use run(line).
        # When using this library, only one of the two can be used.
        def trackRun(trackname, line):
            # We check if track type is correct.
            pu.checkTrackType(trackname)
            # We parse the arguments. Errors are thrown if something is wrong,
            # printing the correct usage on screen. Default are used if needed.
            # parseCommandLine also takes an optional boolean argument to allow
            # using of arguments not declared with pu.addArgument, default is False.
            args = pu.parseCommandLine(line)

            # This is how we access arguments.
            pattern = args["Pattern"]
            strum   = args["Strum"]
            # [Omissis]

            # Here I omit plugin logic, this is not interesting for explaining
            # pluginUtils.
            # Let's just pretend we have the result of the computation:
            all_normal = "{1.0 +5 90 80 80 80 80 80;}"
            all_muted = "z"

            # If you don't send all the commands together the result is commands
            # are reversed since each is pushed as the very next command to be executed.
            # So we save all the commands (with addCommand) and send them at the end
            # (with sendCommands).

            pu.addCommand("{} Sequence {}".format(trackname, all_normal))
            pu.addCommand("{}-Muted SeqClear".format(trackname))
            pu.addCommand("{}-Muted Copy {}".format(trackname, trackname))
            pu.addCommand("{}-Muted Voice MutedGuitar".format(trackname))
            pu.addCommand("{}-Muted Sequence {}".format(trackname, all_muted))
            pu.sendCommands()

# Function documentation

Following are the available functions in the pluginUtil.py module.

addArgument(name, default, doc)
  Adds an argument for the plugin, to be using in parseArguments and printUsage. If you do not want to provide a default, use None to trigger an error if the user not specifies the argument. When the plugin is used, the arguments have to be specified as in Call.

addCommand(cmd)
  Adds a MMA command string to the queue. The queue must be sent using sendCommands, so they are pushed together. If you don't send all the commands together the result is commands are reversed since each one is pushed as the very next command to be executed.

checkTrackType(name)
  Checks if the track type is coherent with the ones specified with setTrackTypes. If not, throws an error.

error(string)
  Prints an error and halts execution.

getSysVar(name)
  Returns a system variable. For example, getSysVar("Time") is the same as MMA command $_Time.

getVar(name)
  Returns a user variable.

getName()
  Returns the name of plugin, according to the directory the user installed it.

parseCommandLine(line, allowUnkown=False)
  Parses the plugin command line and returns a dictionary with arguments and values according what has been defined with addArgument. If allowUnknown is True, it allows to use undeclared argument names. Else, throws an error. Throws an error if an argument with no default is not assigned. Hhe arguments have to be specified as in Call.

printUsage()
  Prints documentation using data from addArgument, setAuthor, setDescription, setSynopsis and setTrackType.

sendCommands()
  Sends the commands added with addCommand to the queue.

setAuthor(author)
  Sets the author.

setDescription(descr)
  Sets a short description of the plugin.

setSynopsis(descr)
  Sets a synopsis of the plugin.

setMinMMAVersion(major, minor)
  Sets the miminum MMA version required, throws an error if not met.

setPluginDoc(doc)
  Sets the documentation for the plugin. %NAME% is replaced by plugin name.

setTrackType(*types)
  Sets track types to which the plugin applies; if empty everythi ng is accepted.

warning(string)
  Prints a warning.

#### Footnotes

....5.1
  The module has been authored by Ignazio Di Napoli <neclepsio@gmail.com> and all kudos should go to him.