1plugin(n) Plugin management plugin(n)
2______________________________________________________________________________
6
8 plugin - Manage a plugin
9
11 package require Tcl 8.4
12 package require pluginmgr ?0.1?
14 ::pluginmgr objectName ?option value...?
16 ::pluginmgr::paths objectName name...
18 objectName method ?arg arg ...?
20 objectName clone
22 objectName configure
24 objectName configure option
26 objectName configure -option value...
28 objectName cget -option
30 objectName destroy
32 objectName do arg...
34 objectName interpreter
36 objectName plugin
38 objectName load string
40 objectName unload
42 objectName list
44 objectName path path
46 objectName paths
48_________________________________________________________________
50
52 This package provides commands and objects for the generic management
53 of plugins which can be loaded into an application.
54 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 The main contribution of this package is a generic framework which
67 allows the easy declaration of
68 [1] How to translate a plugin name to the name of the package imple‐
70 menting it, and vice versa.
71 [2] The list of commands a plugin has to provide as API, and also of
73 more complex checks as code.
74 [3] The list of commands expected by the plugin from the environ‐
76 ment. This then allows the easy generation of plugin managers
77 customized to particular types of plugins for an application.
78 It should be noted that all plugin code is considered untrusted and
80 will always be executed within a safe interpreter. The interpreter is
81 enabled enough to allow plugins the loading of all additional packages
82 they may need.
83
85 PACKAGE COMMANDS
86 ::pluginmgr objectName ?option value...?
87 This command creates a new plugin manager object with an associ‐
88 ated Tcl command whose name is objectName. This object command
89 is explained in full detail in the sections OBJECT COMMAND and
90 OBJECT METHODS. The object command will be created under the
91 current namespace if the objectName is not fully qualified, and
92 in the specified namespace otherwise.
93 The options and their values coming after the name of the object
95 are used to set the initial configuration of the mamager object,
96 specifying the applicable plugins and their API.
97 ::pluginmgr::paths objectName name...
99 This utility command adds a set of paths to the specified
100 object, based on the given names. It will search for:
101 [1] The environment variable name_PLUGINS. Its contents will
103 be interpreted as a list of package paths. The entries
104 have to be separated by either : (unix) or ; (windows).
105 The name will be converted to upper-case letters.
107 [2] The registry entry "HKEY_LOCAL_MACHINE\SOFT‐
109 WARE\name\PLUGINS". Its contents will be interpreted as
110 a list of package paths. The entries have to be separated
111 by ;. This item is considered only when on Windows (tm).
112 The casing of letters is not changed.
114 [3] The registry entry "HKEY_CURRENT_USER\SOFTWARE\name\PLUG‐
116 INS". Its contents will be interpreted as a list of
117 package paths. The entries have to be separated by ;.
118 This item is considered only when on Windows (tm).
119 The casing of letters is not changed.
121 [4] The directory "~/.name/plugin".
123 The casing of letters is not changed.
125 and add all the paths found that way to the list of package paths main‐
127 tained by the object.
128 If name is namespaced each item in the list will be repeated per prefix
130 of name, with conversion of :-sequences into the proper separator
131 (underscore for environment variables, backslash for registry entries,
132 and / for directories).
133 Examples:
135 ::pluginmgr::paths ::obj docidx
138 => env DOCIDX_PLUGINS
140 reg HKEY_LOCAL_MACHINE\SOFTWARE\docidx\PLUGINS
141 reg HKEY_CURRENT_USER\SOFTWARE\docidx\PLUGINS
142 path ~/.docidx/plugins
143 ::pluginmgr::paths ::obj doctools::idx
145 => env DOCTOOLS_PLUGINS
147 env DOCTOOLS_IDX_PLUGINS
148 reg HKEY_LOCAL_MACHINE\SOFTWARE\doctools\PLUGINS
149 reg HKEY_LOCAL_MACHINE\SOFTWARE\doctools\idx\PLUGINS
150 reg HKEY_CURRENT_USER\SOFTWARE\doctools\PLUGINS
151 reg HKEY_CURRENT_USER\SOFTWARE\doctools\idx\PLUGINS
152 path ~/.doctools/plugins
153 path ~/.doctools/idx/plugins
154 OBJECT COMMAND
157 All commands created by the command ::pluginmgr (See section PACKAGE
158 COMMANDS) have the following general form and may be used to invoke
159 various operations on their plugin manager object.
160 objectName method ?arg arg ...?
162 The method method and its arg'uments determine the exact behav‐
163 ior of the command. See section OBJECT METHODS for the detailed
164 specifications.
165 OBJECT METHODS
167 objectName clone
168 This method creates a new plugin management object and returns
169 the associated object command. The generated object is a clone
170 of the object the method was invoked on. I.e. the new object
171 will have the same configuration as the current object. With
172 regard to state, if the current object has a plugin loaded then
173 this plugin and all associated state is moved to the generated
174 clone and the current object is reset into the base state (no
175 plugin loaded). In this manner a configured plugin manager is
176 also a factory for loaded plugins.
177 objectName configure
179 The method returns a list of all known options and their current
180 values when called without any arguments.
181 objectName configure option
183 The method behaves like the method cget when called with a sin‐
184 gle argument and returns the value of the option specified by
185 said argument.
186 objectName configure -option value...
188 The method reconfigures the specified options of the object,
189 setting them to the associated values, when called with an even
190 number of arguments, at least two.
191 The legal options are described in the section OBJECT CONFIGURA‐
193 TION.
194 objectName cget -option
196 This method expects a legal configuration option as argument and
197 will return the current value of that option for the object the
198 method was invoked for.
199 The legal configuration options are described in section OBJECT
201 CONFIGURATION.
202 objectName destroy
204 This method destroys the object it is invoked for.
205 objectName do arg...
207 This method interprets its list of arguments as the words of a
208 command and invokes this command in the execution context of the
209 plugin. The result of the invoked command is made the result of
210 the method. The call will fail with an error if no valid plugin
211 has been loaded into the manager object.
212 objectName interpreter
214 This method returns the handle of the safe interpreter the cur‐
215 rent plugin is loaded into. An empty string as return value sig‐
216 nals that the manager currently has no valid plugin loaded.
217 objectName plugin
219 This method returns the name of the plugin currently loaded. An
220 empty string as return value signals that the manager currently
221 has no valid plugin loaded.
222 objectName load string
224 This method loads, validates, and initializes a named plugin
225 into the manager object.
226 The algorithm to locate and load the plugin employed is:
228 [1] If the string contains the path to an existing file then
230 this file is taken as the implementation of the plugin.
231 [2] Otherwise the plugin name is translated into a package
233 name via the value of the option -pattern and then loaded
234 through the regular package management.
235 [3] The load fails.
237 The algorithm to validate and initialize the loaded code is:
239 [1] If the option -api is non-empty introspection commands
241 are used to ascertain that the plugin provides the listed
242 commands.
243 [2] If the option -check is non-empty the specified command
245 prefix is called.
246 [3] If either of the above fails the candidate plugin is
248 unloaded again
249 [4] Otherwise all the commands specified via the option -cmds
251 are installed in the plugin.
252 A previously loaded plugin is discarded, but only if the new plugin was
254 found and sucessfully validated and initialized. Note that there will
255 be no intereference between old and new plugin as both will be put into
256 separate safe interpreters.
257 objectName unload
259 This method unloads the currently loaded plugin. It returns the
260 empty string. The call will be silently ignored if no plugin is
261 loaded at all.
262 objectName list
264 This method uses the contents of the option -pattern to find all
265 packages which can be plugins under the purview of this manager
266 object. It translates their names into plugin names and returns
267 a list containing them.
268 objectName path path
270 This methods adds the specified path to the list of additional
271 package paths to look at when searching for a plugin. It returns
272 the empty string. Duplicate paths are ignored, i.e. each path is
273 added only once. Paths are made absolute, but are not normal‐
274 ized.
275 objectName paths
277 This method returns a list containing all additional paths which
278 have been added to the plugin manager object since its creation.
279 OBJECT CONFIGURATION
281 All plugin manager objects understand the following configuration
282 options:
283 -pattern string
285 The value of this option is a glob pattern which has to contain
286 exactly one '*'-operator. All packages whose names match this
287 pattern are the plugins recognized by the manager object. And
288 vice versa, the replacement of the '*'-operator with a plugin
289 name will yield the name of the package implementing that plug‐
290 in.
291 This option has no default, except if option -name was set. It
293 has to be set before attempting to load a plugin, either
294 directly, or through option -name.
295 -api list
297 The value of this option is a list of command names, and any
298 plugin loaded has to provide these commands. Names which are not
299 fully qualified are considered to be rooted in the global names‐
300 pace. If empty no expectations are made on the plugin. The
301 default value is the empty list.
302 -check cmdprefix
304 The value of this option is interpreted as a command prefix.
305 Its purpose is to perform complex checks on a loaded plugin
306 package to validate it, which go beyond a simple list of pro‐
307 vided commands.
308 It is called with the manager object command as the only argu‐
310 ment and has to return a boolean value. A value of true will be
311 interpreted to mean that the candidate plugin passed the test.
312 The call will happen if and only if the candidate plugin already
313 passed the basic API check specified through the option -api.
314 The default value is the empty list, which causes the manager
316 object to suppress the call and to assume the candidate plugin
317 passes.
318 -cmds dict
320 The value of this option is a dictionary. It specifies the com‐
321 mands which will be made available to the plugin (as keys), and
322 the trusted commands in the environment which implement them (as
323 values). The trusted commands will be executed in the inter‐
324 preter specified by the option -cmdip. The default value is the
325 empty dictionary.
326 -cmdip ipspec
328 The value of this option is the path of the interpreter where
329 the trusted commands given to the plugin will be executed in.
330 The default is the empty string, referring to the current inter‐
331 preter.
332 -setup cmdprefix
334 The value of this option is interpreted as a command prefix.
335 It is called whenever a new safe interpreter for a plugin has
337 been created, but before a plugin is loaded. It is provided with
338 the manager object command and the interpreter handle as its
339 only arguments. Any return value will be ignored.
340 Its purpose is give a user of the plugin management the ability
342 to define commands, packages, etc. a chosen plugin may need
343 while being loaded.
344
346 plugin management, plugin search
347
349 Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net>
350pluginmgr 1.1 plugin(n)