gem_plugin 0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,164 @@
1
+ <?xml version="1.0" encoding="iso-8859-1"?>
2
+ <!DOCTYPE html
3
+ PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
+
6
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
7
+ <head>
8
+ <title>File: LICENSE</title>
9
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
10
+ <meta http-equiv="Content-Script-Type" content="text/javascript" />
11
+ <link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
12
+ <script type="text/javascript">
13
+ // <![CDATA[
14
+
15
+ function popupCode( url ) {
16
+ window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
17
+ }
18
+
19
+ function toggleCode( id ) {
20
+ if ( document.getElementById )
21
+ elem = document.getElementById( id );
22
+ else if ( document.all )
23
+ elem = eval( "document.all." + id );
24
+ else
25
+ return false;
26
+
27
+ elemStyle = elem.style;
28
+
29
+ if ( elemStyle.display != "block" ) {
30
+ elemStyle.display = "block"
31
+ } else {
32
+ elemStyle.display = "none"
33
+ }
34
+
35
+ return true;
36
+ }
37
+
38
+ // Make codeblocks hidden by default
39
+ document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
40
+
41
+ // ]]>
42
+ </script>
43
+
44
+ </head>
45
+ <body>
46
+
47
+
48
+
49
+ <div id="fileHeader">
50
+ <h1>LICENSE</h1>
51
+ <table class="header-table">
52
+ <tr class="top-aligned-row">
53
+ <td><strong>Path:</strong></td>
54
+ <td>LICENSE
55
+ </td>
56
+ </tr>
57
+ <tr class="top-aligned-row">
58
+ <td><strong>Last Update:</strong></td>
59
+ <td>Sun Mar 05 21:05:11 EST 2006</td>
60
+ </tr>
61
+ </table>
62
+ </div>
63
+ <!-- banner header -->
64
+
65
+ <div id="bodyContent">
66
+
67
+
68
+
69
+ <div id="contextContent">
70
+
71
+ <div id="description">
72
+ <p>
73
+ Ruby is copyrighted free software by Zed A. Shaw &lt;zedshaw at zedshaw dot
74
+ com&gt; You can redistribute it and/or modify it under either the terms of
75
+ the GPL or the conditions below:
76
+ </p>
77
+ <pre>
78
+ 1. You may make and give away verbatim copies of the source form of the
79
+ software without restriction, provided that you duplicate all of the
80
+ original copyright notices and associated disclaimers.
81
+
82
+ 2. You may modify your copy of the software in any way, provided that
83
+ you do at least ONE of the following:
84
+
85
+ a) place your modifications in the Public Domain or otherwise
86
+ make them Freely Available, such as by posting said
87
+ modifications to Usenet or an equivalent medium, or by allowing
88
+ the author to include your modifications in the software.
89
+
90
+ b) use the modified software only within your corporation or
91
+ organization.
92
+
93
+ c) rename any non-standard executables so the names do not conflict
94
+ with standard executables, which must also be provided.
95
+
96
+ d) make other distribution arrangements with the author.
97
+
98
+ 3. You may distribute the software in object code or executable
99
+ form, provided that you do at least ONE of the following:
100
+
101
+ a) distribute the executables and library files of the software,
102
+ together with instructions (in the manual page or equivalent)
103
+ on where to get the original distribution.
104
+
105
+ b) accompany the distribution with the machine-readable source of
106
+ the software.
107
+
108
+ c) give non-standard executables non-standard names, with
109
+ instructions on where to get the original software distribution.
110
+
111
+ d) make other distribution arrangements with the author.
112
+
113
+ 4. You may modify and include the part of the software into any other
114
+ software (possibly commercial). But some files in the distribution
115
+ are not written by the author, so that they are not under this terms.
116
+
117
+ They are gc.c(partly), utils.c(partly), regex.[ch], st.[ch] and some
118
+ files under the ./missing directory. See each file for the copying
119
+ condition.
120
+
121
+ 5. The scripts and library files supplied as input to or produced as
122
+ output from the software do not automatically fall under the
123
+ copyright of the software, but belong to whomever generated them,
124
+ and may be sold commercially, and may be aggregated with this
125
+ software.
126
+
127
+ 6. THIS SOFTWARE IS PROVIDED &quot;AS IS&quot; AND WITHOUT ANY EXPRESS OR
128
+ IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
129
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
130
+ PURPOSE.
131
+ </pre>
132
+
133
+ </div>
134
+
135
+
136
+ </div>
137
+
138
+
139
+ </div>
140
+
141
+
142
+ <!-- if includes -->
143
+
144
+ <div id="section">
145
+
146
+
147
+
148
+
149
+
150
+
151
+
152
+
153
+ <!-- if method_list -->
154
+
155
+
156
+ </div>
157
+
158
+
159
+ <div id="validator-badges">
160
+ <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
161
+ </div>
162
+
163
+ </body>
164
+ </html>
@@ -0,0 +1,273 @@
1
+ <?xml version="1.0" encoding="iso-8859-1"?>
2
+ <!DOCTYPE html
3
+ PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
+
6
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
7
+ <head>
8
+ <title>File: README</title>
9
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
10
+ <meta http-equiv="Content-Script-Type" content="text/javascript" />
11
+ <link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
12
+ <script type="text/javascript">
13
+ // <![CDATA[
14
+
15
+ function popupCode( url ) {
16
+ window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
17
+ }
18
+
19
+ function toggleCode( id ) {
20
+ if ( document.getElementById )
21
+ elem = document.getElementById( id );
22
+ else if ( document.all )
23
+ elem = eval( "document.all." + id );
24
+ else
25
+ return false;
26
+
27
+ elemStyle = elem.style;
28
+
29
+ if ( elemStyle.display != "block" ) {
30
+ elemStyle.display = "block"
31
+ } else {
32
+ elemStyle.display = "none"
33
+ }
34
+
35
+ return true;
36
+ }
37
+
38
+ // Make codeblocks hidden by default
39
+ document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
40
+
41
+ // ]]>
42
+ </script>
43
+
44
+ </head>
45
+ <body>
46
+
47
+
48
+
49
+ <div id="fileHeader">
50
+ <h1>README</h1>
51
+ <table class="header-table">
52
+ <tr class="top-aligned-row">
53
+ <td><strong>Path:</strong></td>
54
+ <td>README
55
+ </td>
56
+ </tr>
57
+ <tr class="top-aligned-row">
58
+ <td><strong>Last Update:</strong></td>
59
+ <td>Mon Mar 06 00:33:03 EST 2006</td>
60
+ </tr>
61
+ </table>
62
+ </div>
63
+ <!-- banner header -->
64
+
65
+ <div id="bodyContent">
66
+
67
+
68
+
69
+ <div id="contextContent">
70
+
71
+ <div id="description">
72
+ <h1><a href="../classes/GemPlugin.html">GemPlugin</a>: Gem Based Plugin System</h1>
73
+ <p>
74
+ <a href="../classes/GemPlugin.html">GemPlugin</a> is a system that lets
75
+ your users install gems and lets you load them as additional features to
76
+ use in your software. It originated from the Mongrel (<a
77
+ href="http://mongrel.rubyforge.org">mongrel.rubyforge.org</a>) project but
78
+ proved useful enough to break out into a separate project.
79
+ </p>
80
+ <p>
81
+ <a href="../classes/GemPlugin.html">GemPlugin</a> works by listing the gems
82
+ installed, and doing a require_gem on any that have the right dependencies.
83
+ For example, if a gem depends on &quot;gem_plugin&quot; and
84
+ &quot;mongrel&quot; then it&#8217;ll load as a Mongrel plugin. This makes
85
+ it so that users of the plugins only need to gem install (and maybe config
86
+ a bit), and plugin authors only need to make gems.
87
+ </p>
88
+ <h2>Implementers</h2>
89
+ <p>
90
+ To use <a href="../classes/GemPlugin.html">GemPlugin</a> in your system you
91
+ only have to require &#8216;gem_plugin&#8217; and then use the <a
92
+ href="../classes/GemPlugin/Manager.html#M000008">GemPlugin::Manager.create</a>,
93
+ <a
94
+ href="../classes/GemPlugin/Manager.html#M000006">GemPlugin::Manager.load</a>,
95
+ and <a
96
+ href="../classes/GemPlugin/Manager.html#M000009">GemPlugin::Manager.available</a>
97
+ methods to work with them.
98
+ </p>
99
+ <ul>
100
+ <li><a
101
+ href="../classes/GemPlugin/Manager.html#M000006">GemPlugin::Manager.load</a>
102
+ &#8212; Takes a &quot;depend include/exclude map&quot; and loads plugins
103
+ based on it.
104
+
105
+ </li>
106
+ <li><a
107
+ href="../classes/GemPlugin/Manager.html#M000008">GemPlugin::Manager.create</a>
108
+ &#8212; Takes a URI style name and some options then creates one for you.
109
+
110
+ </li>
111
+ <li><a
112
+ href="../classes/GemPlugin/Manager.html#M000009">GemPlugin::Manager.available</a>
113
+ &#8212; Lets you inspect and mess with the internal plugin registry.
114
+
115
+ </li>
116
+ </ul>
117
+ <h3>Loading Plugins</h3>
118
+ <p>
119
+ As an example from Mongrel it&#8217;s necessary to load plugins that depend
120
+ on rails after the Rails system is configured, but load other plugins right
121
+ when Mongrel is ready. To do this we very first do:
122
+ </p>
123
+ <pre>
124
+ GemPlugin::Manager.instance.load &quot;mongrel&quot; =&gt; GemPlugin::INCLUDE, &quot;rails&quot; =&gt; GemPlugin::EXCLUDE
125
+ </pre>
126
+ <p>
127
+ Later, when it&#8217;s ready to load Rails plugins as well we do this:
128
+ </p>
129
+ <pre>
130
+ GemPlugin::Manager.instance.load &quot;mongrel&quot; =&gt; GemPlugin::INCLUDE
131
+ </pre>
132
+ <p>
133
+ This simply loads any plugins that remain and are ready for use in Rails.
134
+ </p>
135
+ <h3>Creating Plugins</h3>
136
+ <p>
137
+ Creating a plugin is cake:
138
+ </p>
139
+ <pre>
140
+ plug = GemPlugin::Manager.instance.create(&quot;/commands/snazzy&quot;, &quot;something&quot; =&gt; &quot;yeah&quot;)
141
+ </pre>
142
+ <p>
143
+ In this case we&#8217;re making the snazzy command and passing a couple
144
+ fake options.
145
+ </p>
146
+ <h3>Finding Available Plugins</h3>
147
+ <p>
148
+ Finding plugins is also very easy, you just call
149
+ GemPlugin::Manager.instance.available and you get a Hash that maps
150
+ categories to name =&gt; class. For example, if I had the
151
+ &quot;/commands/snazzy&quot; plugin registered above, then I&#8217;d get
152
+ the following:
153
+ </p>
154
+ <pre>
155
+ puts GemPlugin::Manager.instance.available[&quot;/commands&quot;].inspect
156
+ -&gt; { &quot;/snazzy&quot; =&gt; Snazzy}
157
+ </pre>
158
+ <h3>Plugins Inside Modules</h3>
159
+ <p>
160
+ Plugins that are placed in modules are also lowercased when registered but
161
+ still retain their module. So, if Snazzy was actually MyModule::Snazzy,
162
+ then it&#8217;d be registered as &quot;/commands/mymodule::snazzy&quot;.
163
+ </p>
164
+ <h2>Plugin Authors</h2>
165
+ <p>
166
+ People who wish to write gem plugins have a faily easy time of it, but need
167
+ to know the particular rules for the target system. To keep this example
168
+ concrete we&#8217;ll assume you want to write a Mongrel command plugin.
169
+ </p>
170
+ <p>
171
+ First thing is create your project like normal and setup Rake to make your
172
+ gem. Your plugin then needs to be created like so:
173
+ </p>
174
+ <pre>
175
+ class Snazzy &lt; GemPlugin::Plugin &quot;/commands&quot;
176
+ ...
177
+ end
178
+ </pre>
179
+ <p>
180
+ And place this code in a file you will have RubyGems autorequire (I use
181
+ lib/init.rb).
182
+ </p>
183
+ <p>
184
+ Next you need to add the following to whatever Rakefile code you use to
185
+ create your gem:
186
+ </p>
187
+ <pre>
188
+ spec.add_dependency('gem_plugin', '&gt;= 0.1')
189
+ spec.add_dependency('mongrel', '&gt;= 0.3.9')
190
+ spec.autorequire = 'init.rb'
191
+ </pre>
192
+ <p>
193
+ This does three things:
194
+ </p>
195
+ <ul>
196
+ <li>Tells GemPlugins::Manager.load that this is a <a
197
+ href="../classes/GemPlugin.html">GemPlugin</a>.
198
+
199
+ </li>
200
+ <li>Tells Mongrel that this is a Mongrel specific <a
201
+ href="../classes/GemPlugin.html">GemPlugin</a>.
202
+
203
+ </li>
204
+ <li>Tells RubyGems to run init.rb when the gem is required, just hooking up
205
+ your plugin.
206
+
207
+ </li>
208
+ </ul>
209
+ <p>
210
+ Now, all the users of your plugin have to do is gem install it and then
211
+ they get the plugin automagically.
212
+ </p>
213
+ <p>
214
+ People writing GemPlugins for other systems would have to check the
215
+ documentation from that project to get an idea of what extra requirements
216
+ might be needed. For example, you&#8217;d probably have to depend on
217
+ another project other that <b>mongrel</b> and most likely have a few more
218
+ things to configure in your init.rb.
219
+ </p>
220
+ <h2>Plugin Users</h2>
221
+ <p>
222
+ Plugin users have it the easiest of all. They simply do:
223
+ </p>
224
+ <pre>
225
+ gem install mongrel_command_snazzy
226
+ </pre>
227
+ <p>
228
+ And that&#8217;s it. When they run mongrel_rails (given the above example)
229
+ this snazzy command get loaded automatically without any intervention.
230
+ </p>
231
+ <p>
232
+ The only thing missing in this release is a way for end users to configure
233
+ such a plugin. I really think this is the job of the implementers to
234
+ define.
235
+ </p>
236
+ <h2>Contact</h2>
237
+ <p>
238
+ E-mail zedshaw at zedshaw.com and I&#8217;ll help. Comments about the API
239
+ are welcome.
240
+ </p>
241
+
242
+ </div>
243
+
244
+
245
+ </div>
246
+
247
+
248
+ </div>
249
+
250
+
251
+ <!-- if includes -->
252
+
253
+ <div id="section">
254
+
255
+
256
+
257
+
258
+
259
+
260
+
261
+
262
+ <!-- if method_list -->
263
+
264
+
265
+ </div>
266
+
267
+
268
+ <div id="validator-badges">
269
+ <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
270
+ </div>
271
+
272
+ </body>
273
+ </html>
@@ -0,0 +1,109 @@
1
+ <?xml version="1.0" encoding="iso-8859-1"?>
2
+ <!DOCTYPE html
3
+ PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
+
6
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
7
+ <head>
8
+ <title>File: gem_plugin.rb</title>
9
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
10
+ <meta http-equiv="Content-Script-Type" content="text/javascript" />
11
+ <link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
12
+ <script type="text/javascript">
13
+ // <![CDATA[
14
+
15
+ function popupCode( url ) {
16
+ window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
17
+ }
18
+
19
+ function toggleCode( id ) {
20
+ if ( document.getElementById )
21
+ elem = document.getElementById( id );
22
+ else if ( document.all )
23
+ elem = eval( "document.all." + id );
24
+ else
25
+ return false;
26
+
27
+ elemStyle = elem.style;
28
+
29
+ if ( elemStyle.display != "block" ) {
30
+ elemStyle.display = "block"
31
+ } else {
32
+ elemStyle.display = "none"
33
+ }
34
+
35
+ return true;
36
+ }
37
+
38
+ // Make codeblocks hidden by default
39
+ document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
40
+
41
+ // ]]>
42
+ </script>
43
+
44
+ </head>
45
+ <body>
46
+
47
+
48
+
49
+ <div id="fileHeader">
50
+ <h1>gem_plugin.rb</h1>
51
+ <table class="header-table">
52
+ <tr class="top-aligned-row">
53
+ <td><strong>Path:</strong></td>
54
+ <td>lib/gem_plugin.rb
55
+ </td>
56
+ </tr>
57
+ <tr class="top-aligned-row">
58
+ <td><strong>Last Update:</strong></td>
59
+ <td>Sun Mar 05 22:03:34 EST 2006</td>
60
+ </tr>
61
+ </table>
62
+ </div>
63
+ <!-- banner header -->
64
+
65
+ <div id="bodyContent">
66
+
67
+
68
+
69
+ <div id="contextContent">
70
+
71
+
72
+ <div id="requires-list">
73
+ <h3 class="section-bar">Required files</h3>
74
+
75
+ <div class="name-list">
76
+ singleton&nbsp;&nbsp;
77
+ rubygems&nbsp;&nbsp;
78
+ </div>
79
+ </div>
80
+
81
+ </div>
82
+
83
+
84
+ </div>
85
+
86
+
87
+ <!-- if includes -->
88
+
89
+ <div id="section">
90
+
91
+
92
+
93
+
94
+
95
+
96
+
97
+
98
+ <!-- if method_list -->
99
+
100
+
101
+ </div>
102
+
103
+
104
+ <div id="validator-badges">
105
+ <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
106
+ </div>
107
+
108
+ </body>
109
+ </html>