1pluginmgr(n)                   Plugin management                  pluginmgr(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       pluginmgr - Manage a plugin
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require pluginmgr  ?0.3?
14
15       ::pluginmgr objectName ?option value...?
16
17       ::pluginmgr::paths objectName name...
18
19       objectName method ?arg arg ...?
20
21       objectName clone
22
23       objectName configure
24
25       objectName configure option
26
27       objectName configure -option value...
28
29       objectName cget -option
30
31       objectName destroy
32
33       objectName do arg...
34
35       objectName interpreter
36
37       objectName plugin
38
39       objectName load string
40
41       objectName unload
42
43       objectName list
44
45       objectName path path
46
47       objectName paths
48
49______________________________________________________________________________
50

DESCRIPTION

52       This  package  provides commands and objects for the generic management
53       of plugins which can be loaded into an application.
54
55       To avoid the implementation of yet another system to  locate  Tcl  code
56       the  system  provides  by  this  package is built on top of the regular
57       package management system. Each plugin is considered as a package and a
58       simple  invokation  of package require is enough to locate and load it,
59       if it exists. The only time we will need additional  paths  is  when  a
60       plugin  manager  is part of a wrapped application and has to be able to
61       search for plugins existing outside of that application. For this situ‐
62       ation  the  package  provides a command to create a general set of such
63       paths based on names for the plugin manager and/or application in ques‐
64       tion.
65
66       The  main  contribution  of  this  package is a generic framework which
67       allows the easy declaration of
68
69       [1]    How to translate a plugin name to the name of the package imple‐
70              menting it, and vice versa.
71
72       [2]    The list of commands a plugin has to provide as API, and also of
73              more complex checks as code.
74
75       [3]    The list of commands expected by the plugin  from  the  environ‐
76              ment.
77
78       This  then  allows the easy generation of plugin managers customized to
79       particular types of plugins for an application.
80
81       It should be noted that all plugin code  is  considered  untrusted  and
82       will  always  be executed within a safe interpreter. The interpreter is
83       enabled enough to allow plugins the loading of all additional  packages
84       they may need.
85

PUBLIC API

87   PACKAGE COMMANDS
88       ::pluginmgr objectName ?option value...?
89              This command creates a new plugin manager object with an associ‐
90              ated Tcl command whose name is objectName. This  object  command
91              is  explained  in full detail in the sections OBJECT COMMAND and
92              OBJECT METHODS. The object command will  be  created  under  the
93              current  namespace if the objectName is not fully qualified, and
94              in the specified namespace otherwise.
95
96              The options and their values coming after the name of the object
97              are used to set the initial configuration of the mamager object,
98              specifying the applicable plugins and their API.
99
100       ::pluginmgr::paths objectName name...
101              This utility command adds  a  set  of  paths  to  the  specified
102              object, based on the given names.  It will search for:
103
104              [1]    The  environment variable name_PLUGINS. Its contents will
105                     be interpreted as a list of package  paths.  The  entries
106                     have to be separated by either : (unix) or ; (windows).
107
108                     The name will be converted to upper-case letters.
109
110              [2]    The      registry     entry     "HKEY_LOCAL_MACHINE\SOFT‐
111                     WARE\name\PLUGINS".  Its contents will be interpreted  as
112                     a list of package paths. The entries have to be separated
113                     by ;. This item is considered only when on Windows (tm).
114
115                     The casing of letters is not changed.
116
117              [3]    The registry entry "HKEY_CURRENT_USER\SOFTWARE\name\PLUG‐
118                     INS".   Its  contents  will  be  interpreted as a list of
119                     package paths. The entries have to  be  separated  by  ;.
120                     This item is considered only when on Windows (tm).
121
122                     The casing of letters is not changed.
123
124              [4]    The directory "~/.name/plugin".
125
126              [5]    The directory "~/.name/plugins".
127
128                     The casing of letters is not changed.
129
130       and add all the paths found that way to the list of package paths main‐
131       tained by the object.
132
133       If name is namespaced each item in the list will be repeated per prefix
134       of  name,  with  conversion  of  :-sequences  into the proper separator
135       (underscore for environment variables, backslash for registry  entries,
136       and / for directories).
137
138       Examples:
139
140
141
142                  ::pluginmgr::paths ::obj docidx
143
144                  => env  DOCIDX_PLUGINS
145                     reg  HKEY_LOCAL_MACHINE\SOFTWARE\docidx\PLUGINS
146                     reg  HKEY_CURRENT_USER\SOFTWARE\docidx\PLUGINS
147                     path ~/.docidx/plugins
148
149                  ::pluginmgr::paths ::obj doctools::idx
150
151                  => env  DOCTOOLS_PLUGINS
152                     env  DOCTOOLS_IDX_PLUGINS
153                     reg  HKEY_LOCAL_MACHINE\SOFTWARE\doctools\PLUGINS
154                     reg  HKEY_LOCAL_MACHINE\SOFTWARE\doctools\idx\PLUGINS
155                     reg  HKEY_CURRENT_USER\SOFTWARE\doctools\PLUGINS
156                     reg  HKEY_CURRENT_USER\SOFTWARE\doctools\idx\PLUGINS
157                     path ~/.doctools/plugin
158                     path ~/.doctools/idx/plugin
159
160
161   OBJECT COMMAND
162       All  commands  created  by the command ::pluginmgr (See section PACKAGE
163       COMMANDS) have the following general form and may  be  used  to  invoke
164       various operations on their plugin manager object.
165
166       objectName method ?arg arg ...?
167              The  method method and its arg'uments determine the exact behav‐
168              ior of the command. See section OBJECT METHODS for the  detailed
169              specifications.
170
171   OBJECT METHODS
172       objectName clone
173              This  method  creates a new plugin management object and returns
174              the associated object command. The generated object is  a  clone
175              of  the  object  the  method was invoked on. I.e. the new object
176              will have the same configuration as  the  current  object.  With
177              regard  to state, if the current object has a plugin loaded then
178              this plugin and all associated state is moved to  the  generated
179              clone  and  the  current object is reset into the base state (no
180              plugin loaded). In this manner a configured  plugin  manager  is
181              also a factory for loaded plugins.
182
183       objectName configure
184              The method returns a list of all known options and their current
185              values when called without any arguments.
186
187       objectName configure option
188              The method behaves like the method cget when called with a  sin‐
189              gle  argument  and  returns the value of the option specified by
190              said argument.
191
192       objectName configure -option value...
193              The method reconfigures the specified  options  of  the  object,
194              setting  them to the associated values, when called with an even
195              number of arguments, at least two.
196
197              The legal options are described in the section OBJECT CONFIGURA‐
198              TION.
199
200       objectName cget -option
201              This method expects a legal configuration option as argument and
202              will return the current value of that option for the object  the
203              method was invoked for.
204
205              The  legal configuration options are described in section OBJECT
206              CONFIGURATION.
207
208       objectName destroy
209              This method destroys the object it is invoked for.
210
211       objectName do arg...
212              This method interprets its list of arguments as the words  of  a
213              command and invokes this command in the execution context of the
214              plugin.  The result of the invoked command is made the result of
215              the method.  The call will fail with an error if no valid plugin
216              has been loaded into the manager object.
217
218       objectName interpreter
219              This method returns the handle of the safe interpreter the  cur‐
220              rent plugin is loaded into. An empty string as return value sig‐
221              nals that the manager currently has no valid plugin loaded.
222
223       objectName plugin
224              This method returns the name of the plugin currently loaded.  An
225              empty  string as return value signals that the manager currently
226              has no valid plugin loaded.
227
228       objectName load string
229              This method loads, validates, and  initializes  a  named  plugin
230              into the manager object.
231
232              The algorithm to locate and load the plugin employed is:
233
234              [1]    If  the string contains the path to an existing file then
235                     this file is taken as the implementation of the plugin.
236
237              [2]    Otherwise the plugin name is translated  into  a  package
238                     name via the value of the option -pattern and then loaded
239                     through the regular package management.
240
241              [3]    The load fails.
242
243       The algorithm to validate and initialize the loaded code is:
244
245              [1]    If the option -api is  non-empty  introspection  commands
246                     are used to ascertain that the plugin provides the listed
247                     commands.
248
249              [2]    If the option -check is non-empty the  specified  command
250                     prefix is called.
251
252              [3]    If  either  of  the  above  fails the candidate plugin is
253                     unloaded again
254
255              [4]    Otherwise all the commands specified via the option -cmds
256                     are installed in the plugin.
257
258       A previously loaded plugin is discarded, but only if the new plugin was
259       found and sucessfully validated and initialized. Note that  there  will
260       be no intereference between old and new plugin as both will be put into
261       separate safe interpreters.
262
263       objectName unload
264              This method unloads the currently loaded plugin. It returns  the
265              empty  string. The call will be silently ignored if no plugin is
266              loaded at all.
267
268       objectName list
269              This method uses the contents of the option -pattern to find all
270              packages  which can be plugins under the purview of this manager
271              object. It translates their names into plugin names and  returns
272              a list containing them.
273
274       objectName path path
275              This  methods  adds the specified path to the list of additional
276              package paths to look at when searching for a plugin. It returns
277              the empty string. Duplicate paths are ignored, i.e. each path is
278              added only once. Paths are made absolute, but  are  not  normal‐
279              ized.
280
281       objectName paths
282              This method returns a list containing all additional paths which
283              have been added to the plugin manager object since its creation.
284
285   OBJECT CONFIGURATION
286       All plugin  manager  objects  understand  the  following  configuration
287       options:
288
289       -pattern string
290              The  value of this option is a glob pattern which has to contain
291              exactly one '*'-operator. All packages whose  names  match  this
292              pattern  are  the  plugins recognized by the manager object. And
293              vice versa, the replacement of the '*'-operator  with  a  plugin
294              name  will yield the name of the package implementing that plug‐
295              in.
296
297              This option has no default, except if option -name was set.   It
298              has  to  be  set  before  attempting  to  load  a plugin, either
299              directly, or through option -name.
300
301       -api list
302              The value of this option is a list of  command  names,  and  any
303              plugin loaded has to provide these commands. Names which are not
304              fully qualified are considered to be rooted in the global names‐
305              pace.   If  empty  no  expectations  are made on the plugin. The
306              default value is the empty list.
307
308       -check cmdprefix
309              The value of this option is interpreted  as  a  command  prefix.
310              Its  purpose  is  to  perform  complex checks on a loaded plugin
311              package to validate it, which go beyond a simple  list  of  pro‐
312              vided commands.
313
314              It  is  called with the manager object command as the only argu‐
315              ment and has to return a boolean value. A value of true will  be
316              interpreted  to  mean that the candidate plugin passed the test.
317              The call will happen if and only if the candidate plugin already
318              passed the basic API check specified through the option -api.
319
320              The  default  value  is the empty list, which causes the manager
321              object to suppress the call and to assume the  candidate  plugin
322              passes.
323
324       -cmds dict
325              The value of this option is a dictionary.  It specifies the com‐
326              mands which will be made available to the plugin (as keys),  and
327              the trusted commands in the environment which implement them (as
328              values).  The trusted commands will be executed  in  the  inter‐
329              preter specified by the option -cmdip.  The default value is the
330              empty dictionary.
331
332       -cmdip ipspec
333              The value of this option is the path of  the  interpreter  where
334              the  trusted  commands  given to the plugin will be executed in.
335              The default is the empty string, referring to the current inter‐
336              preter.
337
338       -setup cmdprefix
339              The value of this option is interpreted as a command prefix.
340
341              It  is  called  whenever a new safe interpreter for a plugin has
342              been created, but before a plugin is loaded. It is provided with
343              the  manager  object  command  and the interpreter handle as its
344              only arguments. Any return value will be ignored.
345
346              Its purpose is give a user of the plugin management the  ability
347              to  define  commands,  packages,  etc.  a chosen plugin may need
348              while being loaded.
349

BUGS, IDEAS, FEEDBACK

351       This document, and the package it describes, will  undoubtedly  contain
352       bugs  and other problems.  Please report such in the category pluginmgr
353       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
354       also  report any ideas for enhancements you may have for either package
355       and/or documentation.
356
357       When proposing code changes, please provide unified diffs, i.e the out‐
358       put of diff -u.
359
360       Note  further  that  attachments  are  strongly  preferred over inlined
361       patches. Attachments can be made by going  to  the  Edit  form  of  the
362       ticket  immediately  after  its  creation, and then using the left-most
363       button in the secondary navigation bar.
364

KEYWORDS

366       plugin management, plugin search
367

CATEGORY

369       Programming tools
370
372       Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net>
373
374
375
376
377tcllib                                0.3                         pluginmgr(n)
Impressum