MMA can be infinitely expanded by the use of PLUGINs.
So, what is a plugin? In it's simplest it is a bit of Python code which is loaded into a running MMA . This code can then communicate with MMA just as if it were a native part of it.
Warning: Since a plugin is just a bunch of Python code it can do anything ... unfortunately this may include malicious or unwanted things. The author of MMA cannot take any responsibility for anything which happens when running a plugin. It is up to you to ensure that any plugins you include in your MMA directories are safe to run.
Only use plugins from a trusted source!
If you want to try writing your own PLUGIN, please refer to the ``writing plugins'' document in either HTML to PDF.
When a plugin is loaded into MMA 's memory it will add a keyword which can be used just like any other command. All PLUGIN command names are prefaced with a single ``@'' character. This serves two purposes:
As mentioned above, a plugin consists of a Python module which is added to MMA 's internal command table. These modules are free to call existing MMA functions, and even add their own plugins, and call other programs.23.1
Each plugin must have a containing directory with the same name as the plugin. So, the plugin ``hello'' would live in the hello directory. Once found and loaded the command @HELLO will be available to your script.
This directory must contain a Python module with the name ``plugin.py''. The plugin.py module should have the following methods defined:
The spelling (including case) of these three methods must be exactly as described above.
In addition, each plugin directory must contain an empty file called __init__.py. This file is necessary for Python's import facility to operate. MMA checks for this file and will generate an error if not found or not empty.23.2
Hoping that a few lines of example code will compensate for the lack of pages of reference, we suggest that you look at the module plugins/hello/plugin.py.
When locating modules MMA makes a case-insensitive search for the directory and python module. So, when loading ``hello'' you could have a directory ``HELLO'' and a module ``PLUGIN.py'' and all will work. The Python module must end with ``.py'' (all lowercase). We really recommend you simplify your life and use the all lowercase version! If you have both a ``hello'' and ``HELLO'' directory a warning message will be printed; one of the two modules will be loaded, but which is indeterminate (the first found will be used).23.3
The directory for a plugin should also contain a sample file which shows how the plugin can be used and some documentation. At its simplest this could be a README text file; more complex plugins can have more extensive examples and other reference material.
Plugins can reside in three different locations. When requested to load a plugin MMA searches, in the order below, the following:
You can change the search path using the DISABLE command, see below.
To enable a PLUGIN it must be first loaded into a running MMA . This is done with the PLUGIN command. For example,
will load the ``hello'' plugin into memory. You can now invoke the command with:
or, you can pass a variety of additional information to the plugin code:
|@Hello Some things to tell HELLO|
If you have both a track and non-track function, you could:
You can disable the search path used when searching for plugins. If you are a bit worried about malicious code:
will prevent any plugins being loaded.
We noted above that the user's current directory, the directory of the current file, and the plugin directory are searched. You can disable any of these using the options ``Dot'', ``Local'' and ``PlugDir''. You can specify more that one by appending settings with single commas. So,
will force the search to only the plugin directory.
For security, there is no ``enable'' command. So, feel safe in putting this in your mmarc file.
We try to give you as many options as possible in MMA . We also try to keep your systems and data as secure as we can.
We don't have any control over what a PLUGIN can do. But, we do make it a bit harder for someone to screw you around. The DISABLE options, above, are one such step.
In addition, the first time a plugin is loaded you will be asked if you wish to give permission for the plugin to load. If you don't recognize the name, just say ``no''.
The prompt will permit the entry of a single character ``y'' (followed by the Enter key). Accepting a plugin will create an entry in the plugin.list file and the plugin will silently load in the future.
If you enter an ``o'' the plugin will be loaded only this run. This may or may not be a wise thing to do ... if you're not sure you probably should not enable it.
If any changes are made to the plugin code, you'll be asked again.
Permissions are stored in a file plugins.list. Depending on your system this will be located in a ``standard'' location.23.4
If you are confident that no harm will come to your system by loading plugins (which is probably true most of the time) you can skip all this security by starting MMA with the -II command line option.