1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 2008 (1.71)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>Plugins</TITLE>
<META NAME="description" CONTENT="Plugins">
<META NAME="keywords" CONTENT="mma">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
<META NAME="Generator" CONTENT="LaTeX2HTML v2008">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="mma.css">
<LINK REL="next" HREF="node24.html">
<LINK REL="previous" HREF="node22.html">
<LINK REL="up" HREF="mma.html">
<LINK REL="next" HREF="node24.html">
</HEAD>
<BODY bgcolor="#ffffff">
<DIV CLASS="navigation"><!--Navigation Panel-->
<A NAME="tex2html827"
HREF="node24.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html825"
HREF="mma.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html819"
HREF="node22.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html828"
HREF="node24.html">Low Level MIDI Commands</A>
<B> Up:</B> <A NAME="tex2html826"
HREF="mma.html">Reference Manual</A>
<B> Previous:</B> <A NAME="tex2html820"
HREF="node22.html">Subroutines</A>
<BR>
<BR></DIV>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
<UL CLASS="ChildLinks">
<LI><UL>
<LI><A NAME="tex2html829"
HREF="node23.html#SECTION002301000000000000000">Naming and Locating</A>
<LI><A NAME="tex2html830"
HREF="node23.html#SECTION002302000000000000000">Distribution</A>
<LI><A NAME="tex2html831"
HREF="node23.html#SECTION002303000000000000000">Enabling</A>
<LI><A NAME="tex2html832"
HREF="node23.html#SECTION002304000000000000000">Disabling</A>
<LI><A NAME="tex2html833"
HREF="node23.html#SECTION002305000000000000000">Security</A>
</UL></UL>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION002300000000000000000"></A>
<A NAME="sec-plugs"></A>
<BR>
Plugins
</H1>
<P>
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> can be infinitely expanded by the use of P<SMALL>LUGIN</SMALL>s.
<P>
So, what is a plugin? In it's simplest it is a bit of Python code
which is loaded into a running
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> . This code can then communicate
with
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> just as if it were a native part of it.
<P>
<Table CellSpacing=0 Width="80%" Align="Center" CellPadding=10 BGColor="#dddddd" Border=3>
<tr> <td>
<BR><SPAN CLASS="textit">Warning: Since a plugin is
just a bunch of Python code it can do anything ... unfortunately
this <SPAN CLASS="textbf">may</SPAN> include malicious or unwanted things. The author
of
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> 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
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> directories are safe to run. </SPAN>
<BR> <DIV ALIGN="CENTER">
<BIG CLASS="LARGE"><B>Only use plugins from a trusted
source!
</B></BIG></DIV>
</td></tr>
</Table>
<P>
If you want to try writing your own P<SMALL>LUGIN</SMALL>, please refer to the
``writing plugins'' document in either HTML to PDF.
<P>
When a plugin is loaded into
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> 's memory it will add a keyword
which can be used just like any other command. All P<SMALL>LUGIN</SMALL>
command names are prefaced with a single ``@'' character. This serves
two purposes:
<P>
<OL>
<LI>It gives plugin keywords a distinctive appearance,
</LI>
<LI>It permits plugin keywords which duplicate existing keywords.
Native keywords are guaranteed to never begin with an ``@''.
</LI>
</OL>
<P>
<H2><A NAME="SECTION002301000000000000000">
Naming and Locating</A>
</H2>
<P>
As mentioned above, a plugin consists of a Python module which is
added to
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> 's internal command table. These modules are free to
call existing
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> functions, and even add their own plugins, and call other
programs.<A NAME="tex2html88"
HREF="#foot12913"><SUP><SPAN CLASS="arabic">23</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A>
<P>
Each plugin must have a containing directory with the same name as the
plugin. So, the plugin ``hello'' would live in the <TT><SPAN CLASS="textbf">hello</SPAN></TT>
directory. Once found and loaded the command @H<SMALL>ELLO</SMALL> will be
available to your script.
<P>
This directory must contain a Python module with the name
``plugin.py''. The <TT><SPAN CLASS="textbf">plugin.py</SPAN></TT> module should have the following
methods defined:
<P>
<DL COMPACT>
<DT></DT>
<DD><DL>
<DT><STRONG><SPAN CLASS="textbf">run</SPAN></STRONG></DT>
<DD>This is the entry point for a simple (non-track) command.
<P>
</DD>
<DT><STRONG><SPAN CLASS="textbf">track_run</SPAN></STRONG></DT>
<DD>This is the entry point for a track command.
<P>
</DD>
<DT><STRONG><SPAN CLASS="textbf">printUsage</SPAN></STRONG></DT>
<DD>The entry point for a usage command. This is used by
the -I command line option.
<P>
</DD>
</DL>
</DD>
</DL>
<P>
The spelling (including case) of these three methods must be exactly
as described above.
<P>
In addition, each plugin directory <SPAN CLASS="textit">must</SPAN> contain an <SPAN CLASS="textbf">empty</SPAN> file
called <TT><SPAN CLASS="textbf">__init__.py</SPAN></TT>. This file is necessary for Python's import
facility to operate.
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> checks for this file and will generate an
error if not found or not empty.<A NAME="tex2html89"
HREF="#foot12927"><SUP><SPAN CLASS="arabic">23</SPAN>.<SPAN CLASS="arabic">2</SPAN></SUP></A>
<P>
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
<TT><SPAN CLASS="textbf">plugins/hello/plugin.py</SPAN></TT>.
<P>
When locating modules
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> 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 <SPAN CLASS="textit">must</SPAN> 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).<A NAME="tex2html90"
HREF="#foot12930"><SUP><SPAN CLASS="arabic">23</SPAN>.<SPAN CLASS="arabic">3</SPAN></SUP></A>
<P>
<H2><A NAME="SECTION002302000000000000000">
Distribution</A>
</H2>
<P>
The directory for a plugin <SPAN CLASS="textit">should</SPAN> also contain a sample file
which shows how the plugin can be used and some documentation. At its
simplest this could be a <TT><SPAN CLASS="textbf">README</SPAN></TT> text file; more complex plugins
can have more extensive examples and other reference material.
<P>
Plugins can reside in three different locations. When requested to
load a plugin
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> searches, in the order below, the following:
<P>
<OL>
<LI>The user's current directory. This is normally referred to as
``.'',
<P>
</LI>
<LI>The directory of the <SPAN CLASS="textit">current</SPAN> file being processed. This
means that if you load a G<SMALL>ROOVE</SMALL> into memory and the groove's
library file contains a ``load plugin'' directive, the search will match a
plugin in that directory.
<P>
</LI>
<LI>The <TT><SPAN CLASS="textbf">plugins</SPAN></TT> directory. We recommend that all plugins use
this location! It makes it easy to track where your plugins live.
You cannot change the the location or name of this directory: it
must be a directory called <TT><SPAN CLASS="textbf">plugins</SPAN></TT> and be located in the main
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> directory tree (the same location as the <TT><SPAN CLASS="textbf">MMA</SPAN></TT> modules
directory). Unfortunately, if you are using a standard
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> distribution this directory may not be modifiable by you since it is
in a ``root access'' location ... which is why the above locations
are available.
<P>
</LI>
</OL>
<P>
You can change the search path using the D<SMALL>ISABLE</SMALL> command, see
below.
<P>
<H2><A NAME="SECTION002303000000000000000">
Enabling</A>
</H2>
<P>
To enable a P<SMALL>LUGIN</SMALL> it must be first loaded into a running
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> . This is done with the P<SMALL>LUGIN</SMALL> command. For example,
<P>
<Table Hspace="40%" CellSpacing=0 CellPadding=10 BGColor="OldLace" Border=3>
<tr><td>
<B>Plugin Hello </B>
</td></tr>
</Table>
<P>
will load the ``hello'' plugin into memory. You can now invoke the
command with:
<P>
<Table Hspace="40%" CellSpacing=0 CellPadding=10 BGColor="OldLace" Border=3>
<tr><td>
<B>@Hello </B>
</td></tr>
</Table>
<P>
or, you can pass a variety of additional information to the plugin
code:
<P>
<Table Hspace="40%" CellSpacing=0 CellPadding=10 BGColor="OldLace" Border=3>
<tr><td>
<B>@Hello Some things to tell HELLO </B>
</td></tr>
</Table>
<P>
If you have both a track and non-track function, you could:
<P>
<Table Hspace="40%" CellSpacing=0 CellPadding=10 BGColor="OldLace" Border=3>
<tr><td>
<B>Bass @Hello </B>
</td></tr>
</Table>
<P>
<UL>
<LI>Please note that no plugins will be loaded or activated unless
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> is specifically told to load with a P<SMALL>LUGIN</SMALL> directive.
<P>
</LI>
<LI>You may have multiple plugin names on a single P<SMALL>LUGIN</SMALL>
line.
<P>
</LI>
<LI>You <SPAN CLASS="textit">can not</SPAN> reload a plugin. If you try a warning message
will be displayed.
<P>
</LI>
</UL>
<P>
<H2><A NAME="SECTION002304000000000000000">
Disabling</A>
</H2>
<P>
You can disable the search path used when searching for plugins. If
you are a bit worried about malicious code:
<P>
<Table Hspace="40%" CellSpacing=0 CellPadding=10 BGColor="OldLace" Border=3>
<tr><td>
<B>Plugin Disable=ALL </B>
</td></tr>
</Table>
<P>
will prevent any plugins being loaded.
<P>
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,
<P>
<Table Hspace="40%" CellSpacing=0 CellPadding=10 BGColor="OldLace" Border=3>
<tr><td>
<B>Plugin Disable=Dot,Local </B>
</td></tr>
</Table>
<P>
will force the search to only the plugin directory.
<P>
For security, there is no ``enable'' command. So, feel safe in putting
this in your <TT><SPAN CLASS="textbf">mmarc</SPAN></TT> file.
<P>
<H2><A NAME="SECTION002305000000000000000">
Security</A>
</H2>
<P>
We try to give you as many options as possible in
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> . We also try
to keep your systems and data as secure as we can.
<P>
We don't have any control over what a P<SMALL>LUGIN</SMALL> can do. But, we do
make it a bit harder for someone to screw you around. The
D<SMALL>ISABLE</SMALL> options, above, are one such step.
<P>
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''.
<P>
The prompt will permit the entry of a single character ``<TT>y</TT>'' (followed
by the <TT>Enter</TT> key). Accepting a plugin will create an entry
in the <TT><SPAN CLASS="textbf">plugin.list</SPAN></TT> file and the plugin will silently load in
the future.
<P>
If you enter an ``<TT>o</TT>'' 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.
<P>
If any changes are made to the plugin code, you'll be asked again.
<P>
Permissions are stored in a file <TT><SPAN CLASS="textbf">plugins.list</SPAN></TT>. Depending on
your system this will be located in a ``standard''
location.<A NAME="tex2html91"
HREF="#foot12971"><SUP><SPAN CLASS="arabic">23</SPAN>.<SPAN CLASS="arabic">4</SPAN></SUP></A>
<P>
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
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> with the -II command line option.
<P>
<BR><HR><H4>Footnotes</H4>
<DL>
<DT><A NAME="foot12913">...
programs.</A><A
HREF="node23.html#tex2html88"><SUP><SPAN CLASS="arabic">23</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A></DT>
<DD>The reason we're so free with this stuff is that
it's impossible to restrict what a good or malicious Python (or any
other language) program can do. Again, <B>Be Careful.</B>
</DD>
<DT><A NAME="foot12927">... empty.</A><A
HREF="node23.html#tex2html89"><SUP><SPAN CLASS="arabic">23</SPAN>.<SPAN CLASS="arabic">2</SPAN></SUP></A></DT>
<DD>Python doesn't restrict the
__init__.py module to be empty. It can actually contain code. For
security reasons we force it to be empty.
</DD>
<DT><A NAME="foot12930">...
used).</A><A
HREF="node23.html#tex2html90"><SUP><SPAN CLASS="arabic">23</SPAN>.<SPAN CLASS="arabic">3</SPAN></SUP></A></DT>
<DD>This would only be possible on computers with a
case-sensitive filename structure, like Linux.
</DD>
<DT><A NAME="foot12971">...
location.</A><A
HREF="node23.html#tex2html91"><SUP><SPAN CLASS="arabic">23</SPAN>.<SPAN CLASS="arabic">4</SPAN></SUP></A></DT>
<DD>
<FONT Face="Serif" Color="Navy"><I>MMA</I></FONT> uses the Python module appdirs.py (included in
this distribution) to determine the ``best'' location to store
configuration files. For more information see <TT><A NAME="tex2html92"
HREF="http://github.com/ActiveState/appdirs">http://github.com/ActiveState/appdirs</A></TT>.
</DD>
</DL>
<DIV CLASS="navigation"><HR>
<!--Navigation Panel-->
<A NAME="tex2html827"
HREF="node24.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html825"
HREF="mma.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html819"
HREF="node22.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html828"
HREF="node24.html">Low Level MIDI Commands</A>
<B> Up:</B> <A NAME="tex2html826"
HREF="mma.html">Reference Manual</A>
<B> Previous:</B> <A NAME="tex2html820"
HREF="node22.html">Subroutines</A></DIV>
<!--End of Navigation Panel-->
<ADDRESS>
Bob van der Poel
2016-06-11
</ADDRESS>
</BODY>
</HTML>
|
