rubigen 1.5.7 → 1.5.8

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.
@@ -1,13 +0,0 @@
1
- Feature: Development processes of newgem itself (rake tasks)
2
-
3
- As a Newgem maintainer or contributor
4
- I want rake tasks to maintain and release the gem
5
- So that I can spend time on the tests and code, and not excessive time on maintenance processes
6
-
7
- Scenario: Generate RubyGem
8
- Given this project is active project folder
9
- And "pkg" folder is deleted
10
- When I invoke task "rake gem"
11
- Then folder "pkg" is created
12
- And file with name matching "pkg/*.gem" is created else you should run "rake manifest" to fix this
13
- And gem spec key "rdoc_options" contains /(--mainREADME.rdoc|\[\"--main\", \"README.rdoc\"\])/
@@ -1,267 +0,0 @@
1
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3
- <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4
- <head>
5
- <link rel="stylesheet" href="stylesheets/screen.css" type="text/css" media="screen" />
6
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7
- <title>
8
- rubigen
9
- </title>
10
- <script src="javascripts/rounded_corners_lite.inc.js" type="text/javascript"></script>
11
- <style>
12
- </style>
13
- <script type="text/javascript">
14
- window.onload = function() {
15
- settings = {
16
- tl: { radius: 10 },
17
- tr: { radius: 10 },
18
- bl: { radius: 10 },
19
- br: { radius: 10 },
20
- antiAlias: true,
21
- autoPad: true,
22
- validTags: ["div"]
23
- }
24
- var versionBox = new curvyCorners(settings, document.getElementById("version"));
25
- versionBox.applyCornersToAll();
26
-
27
- var twitterBox = new curvyCorners(settings, document.getElementById("twitter_search"));
28
- twitterBox.applyCornersToAll();
29
- }
30
- </script>
31
- </head>
32
- <body>
33
- <div id="main">
34
- <h1>rubigen</h1>
35
- <div class="sidebar">
36
- <div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/rubigen"; return false'>
37
- <p>Get Version</p>
38
- <a href="http://rubyforge.org/projects/rubigen" class="numbers">1.5.7</a>
39
- </div>
40
-
41
- <div id="twitter_search">
42
- <h3>Heard on twitter ('rubigen')...</h3>
43
- <!-- HELP FILE - http://twitterwidget.jazzychad.com/tw/ -->
44
- <script language = "javascript">
45
- var jtw_search = 'rubigen';
46
- var jtw_widget_background = 'd77';
47
- var jtw_widget_border = '0';
48
- var jtw_tweet_textcolor = 'fff';
49
- var jtw_tweet_background = '000';
50
- var jtw_tweet_border = '0px';
51
- </script>
52
- <script src="http://twitterwidget.jazzychad.com/tw/searchwidget.js" type="text/javascript"></script>
53
- </div>
54
-
55
- </div>
56
- <h1>Ruby Generator Framework</h1>
57
- <h2>What</h2>
58
- <p>A framework to allow Ruby applications to generate file/folder stubs (like the <code>rails</code> command does for Ruby on Rails, and the &#8216;script/generate&#8217; command within a Rails application during development).</p>
59
- <p>The RubyConf 2007 presentation is now <a href="http://rubyconf2007.confreaks.com/d3t1p1_rubigen.html">online</a> together with the theme from the A-Team.</p>
60
- <h2>Background</h2>
61
- <p>RubiGen is originally extracted from Ruby on Rails (specifically the rails_generator from its railties gem).</p>
62
- <p>The rails_generator was hardcoded with Rails-specific dependencies (<code>RAILS_ROOT</code>), Rails generators (&#8216;app&#8217; = Rails application; &#8216;model&#8217; = Rails model+tests+migration), and generally assumed it was the only generator framework within the Ruby world (it was). So, any RubyGem whose name ended with &#8216;_generator&#8217; was assumed to be a generator for a Rails application.</p>
63
- <p>But if you are developing an Adhearsion application, then you may want a different set of generators.<br />
64
- If you are developing a RubyGem, then you will want a different set of generators.</p>
65
- <p>RubiGen exists to give different development environments their own generator framework.</p>
66
- <h2>Installing</h2>
67
- <p>RubiGen is only required at development time, and normally isn&#8217;t required at deployment time (unless your application uses it to generate files etc for its users).</p>
68
- <p>On your development machine:</p>
69
- <p><pre class='syntax'><span class="ident">sudo</span> <span class="ident">gem</span> <span class="ident">install</span> <span class="ident">rubigen</span></pre></p>
70
- <h2>Usage</h2>
71
- <p>RubiGen will be normally integrated into another RubyGem, such as <code>newgem</code> or <code>rails</code> or <code>camping</code>, rather than be used on its own.</p>
72
- <p>These frameworks might use RubiGen for two reasons:</p>
73
- <ol>
74
- <li>To generate an initial stub for developers, e.g. <code>rails</code> generated a stub to write a Rails application. <code>newgem</code> generates a stub to write a RubyGem. <br/>
75
- <span class="caps">BTW</span> &#8211; RubiGen has a builtin application <code>ruby_app</code> which generates a bare-bones Ruby application stub (lib, test, and script folders, plus a Rakefile, and a script/generate script)</li>
76
- <li>To generate components within their development areas, e.g. Rails had its <code>script/generate</code> script within each Rails application, which hooked back into the rails_generator to lookup and execute generators.</li>
77
- </ol>
78
- <p>So, there are two steps to integrating RubiGen into your framework:</p>
79
- <ol>
80
- <li>Use it to generate an initial stub for the developers of your framework. This would create the folders <br />
81
- (<code>lib/app</code>, <code>test</code>, <code>script</code>, <code>doc</code>, <code>log</code>, etc) and starting files (<code>Rakefile</code>, <br />
82
- <code>README.txt</code>, <code>test/test_helper.rb</code> etc). Importantly, it would generate a <code>script/generate</code> file.<br />
83
- The <code>script/generate</code> file (example below) will allow developers of your framework to <br />
84
- generate components/extensions within the framework. <br />
85
- RubiGen allows you to restrict which generators are available. For example, within<br />
86
- RubyGem development environment (as generated by <code>newgem</code>), the <code>script/generator</code><br />
87
- only shows <code>rubygem</code>-related generators. Rails could restrict <code>script/generator</code><br />
88
- to only show Rails related generators</li>
89
- <li>Your framework RubyGem (e.g. <code>newgem</code> or <code>rails</code> RubyGems) needs to add <code>rubigen</code> as a <br />
90
- dependency, so that users of your RubyGem can access the generator framework.</li>
91
- </ol>
92
- <h1>Creating generators</h1>
93
- <p>There are two types of generators:</p>
94
- <ol>
95
- <li>Application Generators &#8211; used by developers of your framework to get started. <br />
96
- Generally, you will create one Application Generator for your framework.<br />
97
- It generates a base stub (such as the <code>rails</code> stub for new Rails applications)<br />
98
- for your framework users.</li>
99
- <li>Component Generators &#8211; used by developers to extend their application.<br />
100
- You may include 1+ built-in generators with your framework.<br />
101
- Developers can also write generators for your framework, and like Rails&#8217; generator<br />
102
- install them in various places and have access to their via RubiGen.</li>
103
- </ol>
104
- <h2>Creating an Application Generator for your Framework</h2>
105
- <h3>Easy way</h3>
106
- <p><a href="http://newgem.rubyforge.org/">newgem</a> (v0.13.0+) can generate an Application Generator<br />
107
- for a RubyGem.</p>
108
- <ol>
109
- <li>Create new RubyGem: <code>newgem foobar</code></li>
110
- <li>Create generator: <code>script/generator application_generator foobar</code></li>
111
- <li>Update tests + generator</li>
112
- <li>Install</li>
113
- <li>Run with: foobar</li>
114
- </ol>
115
- <p>For more documentation, run <code>script/generator application_generator</code></p>
116
- <h3><span class="caps">DIY</span></h3>
117
- <p>Without RubiGen, to give your users a head start and create a stub for them, you will <br />
118
- copiously use <code>mkdir_p</code> and <code>File.open</code>. Your script will either be primitive (only<br />
119
- create the bare folders and very few files) or it will be very long and unreadable<br />
120
- (ok, perhaps I&#8217;m just talking about the <code>newgem</code> script, which I am dubiously responsible<br />
121
- for&#8230; :P).</p>
122
- <p>With RubiGen, you can create stubs using powerful, yet simple, syntax. Templates are<br />
123
- extracted into a <code>templates</code> folder, and activating the generator from a script requires<br />
124
- only a few lines of code.</p>
125
- <p>These are the <code>newgem</code> files related to its Application Generator.</p>
126
- bin/
127
- bin/newgem # Appliction Generator script; Usage: newgem gemname [options]
128
- app_generators/
129
- app_generators/newgem/
130
- app_generators/newgem/newgem_generator.rb
131
- app_generators/newgem/<span class="caps">USAGE</span>
132
- app_generators/newgem/templates/
133
- app_generators/newgem/templates/app.rb
134
- app_generators/newgem/templates/History.txt
135
- app_generators/newgem/templates/&#8230; lots and lots of templates
136
- <p>The <code>bin/newgem</code> script is very simple, and looks like:</p>
137
- <p><pre class='syntax'>
138
- <span class="ident">require</span> <span class="punct">'</span><span class="string">rubygems</span><span class="punct">'</span>
139
- <span class="ident">require</span> <span class="punct">'</span><span class="string">rubigen</span><span class="punct">'</span>
140
-
141
- <span class="keyword">if</span> <span class="punct">%w(</span><span class="string">-v --version</span><span class="punct">).</span><span class="ident">include?</span> <span class="constant">ARGV</span><span class="punct">.</span><span class="ident">first</span>
142
- <span class="ident">require</span> <span class="punct">'</span><span class="string">newgem/version</span><span class="punct">'</span>
143
- <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string"><span class="expr">#{File.basename($0)}</span> <span class="expr">#{Newgem::VERSION}</span></span><span class="punct">&quot;</span>
144
- <span class="ident">exit</span><span class="punct">(</span><span class="number">0</span><span class="punct">)</span>
145
- <span class="keyword">end</span>
146
-
147
- <span class="ident">require</span> <span class="punct">'</span><span class="string">rubigen/scripts/generate</span><span class="punct">'</span>
148
- <span class="constant">RubiGen</span><span class="punct">::</span><span class="constant">Base</span><span class="punct">.</span><span class="ident">use_application_sources!</span>
149
- <span class="constant">RubiGen</span><span class="punct">::</span><span class="constant">Scripts</span><span class="punct">::</span><span class="constant">Generate</span><span class="punct">.</span><span class="ident">new</span><span class="punct">.</span><span class="ident">run</span><span class="punct">(</span><span class="constant">ARGV</span><span class="punct">,</span> <span class="symbol">:generator</span> <span class="punct">=&gt;</span> <span class="punct">'</span><span class="string">newgem</span><span class="punct">')</span>
150
- </pre></p>
151
- <p>You can copy and paste this for your own generator script, and place it in your RubyGem&#8217;s <code>bin</code> folder.<br />
152
- Change <code>newgem</code> to your RubyGem&#8217;s name in the script above (and in all the folders listed above too)</p>
153
- <p><span class="caps">NOTE</span>: If you leave <code>newgem</code> there, then it will execute the <code>newgem_generator.rb</code> generator; <br />
154
- as the generators are loaded from all RubyGem&#8217;s having <code>/app_generators</code> folders.</p>
155
- <p>So, for your RubyGem, you need to keep the <code>/app_generators</code> folder (as you are creating an <br />
156
- Application Generator, not a Component Generator), but change <code>newgem</code> to <code>your gem name</code> in<br />
157
- all the subfolders and files. <span class="caps">ESPECIALLY</span> <code>newgem_generator.rb</code> &#8594; <code>yourgem_generator.rb</code>,<br />
158
- as this is how the generator is discovered (via <code>RubiGen::Base.use_application_sources!</code>).</p>
159
- <p>All the generator work is performed within <code>yourgem_generator.rb</code>. A stub for it will be:</p>
160
- <p><pre class='syntax'>
161
- <span class="ident">require</span> <span class="punct">'</span><span class="string">rbconfig</span><span class="punct">'</span>
162
-
163
- <span class="keyword">class </span><span class="class">YourgemGenerator</span> <span class="punct">&lt;</span> <span class="constant">RubiGen</span><span class="punct">::</span><span class="constant">Base</span>
164
- <span class="constant">DEFAULT_SHEBANG</span> <span class="punct">=</span> <span class="constant">File</span><span class="punct">.</span><span class="ident">join</span><span class="punct">(</span><span class="constant">Config</span><span class="punct">::</span><span class="constant">CONFIG</span><span class="punct">['</span><span class="string">bindir</span><span class="punct">'],</span>
165
- <span class="constant">Config</span><span class="punct">::</span><span class="constant">CONFIG</span><span class="punct">['</span><span class="string">ruby_install_name</span><span class="punct">'])</span>
166
-
167
- <span class="ident">default_options</span> <span class="symbol">:shebang</span> <span class="punct">=&gt;</span> <span class="constant">DEFAULT_SHEBANG</span><span class="punct">,</span>
168
- <span class="symbol">:an_option</span> <span class="punct">=&gt;</span> <span class="punct">'</span><span class="string">some_default</span><span class="punct">'</span>
169
-
170
- <span class="ident">attr_reader</span> <span class="symbol">:app_name</span><span class="punct">,</span> <span class="symbol">:module_name</span>
171
-
172
- <span class="keyword">def </span><span class="method">initialize</span><span class="punct">(</span><span class="ident">runtime_args</span><span class="punct">,</span> <span class="ident">runtime_options</span> <span class="punct">=</span> <span class="punct">{})</span>
173
- <span class="keyword">super</span>
174
- <span class="ident">usage</span> <span class="keyword">if</span> <span class="ident">args</span><span class="punct">.</span><span class="ident">empty?</span>
175
- <span class="attribute">@destination_root</span> <span class="punct">=</span> <span class="ident">args</span><span class="punct">.</span><span class="ident">shift</span>
176
- <span class="attribute">@app_name</span> <span class="punct">=</span> <span class="constant">File</span><span class="punct">.</span><span class="ident">basename</span><span class="punct">(</span><span class="constant">File</span><span class="punct">.</span><span class="ident">expand_path</span><span class="punct">(</span><span class="attribute">@destination_root</span><span class="punct">))</span>
177
- <span class="attribute">@module_name</span> <span class="punct">=</span> <span class="ident">app_name</span><span class="punct">.</span><span class="ident">camelize</span>
178
- <span class="ident">extract_options</span>
179
- <span class="keyword">end</span>
180
-
181
- <span class="keyword">def </span><span class="method">manifest</span>
182
- <span class="comment"># Use /usr/bin/env if no special shebang was specified</span>
183
- <span class="ident">script_options</span> <span class="punct">=</span> <span class="punct">{</span> <span class="symbol">:chmod</span> <span class="punct">=&gt;</span> <span class="number">0755</span><span class="punct">,</span> <span class="symbol">:shebang</span> <span class="punct">=&gt;</span> <span class="ident">options</span><span class="punct">[</span><span class="symbol">:shebang</span><span class="punct">]</span> <span class="punct">==</span> <span class="constant">DEFAULT_SHEBANG</span> <span class="punct">?</span> <span class="constant">nil</span> <span class="punct">:</span> <span class="ident">options</span><span class="punct">[</span><span class="symbol">:shebang</span><span class="punct">]</span> <span class="punct">}</span>
184
- <span class="ident">windows</span> <span class="punct">=</span> <span class="punct">(</span><span class="constant">RUBY_PLATFORM</span> <span class="punct">=~</span> <span class="punct">/</span><span class="regex">dos|win32|cygwin</span><span class="punct">/</span><span class="ident">i</span><span class="punct">)</span> <span class="punct">||</span> <span class="punct">(</span><span class="constant">RUBY_PLATFORM</span> <span class="punct">=~</span> <span class="punct">/</span><span class="regex">(:?mswin|mingw)</span><span class="punct">/)</span>
185
-
186
- <span class="ident">record</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">m</span><span class="punct">|</span>
187
- <span class="comment"># Root directory and all subdirectories.</span>
188
- <span class="ident">m</span><span class="punct">.</span><span class="ident">directory</span> <span class="punct">'</span><span class="string"></span><span class="punct">'</span>
189
- <span class="constant">BASEDIRS</span><span class="punct">.</span><span class="ident">each</span> <span class="punct">{</span> <span class="punct">|</span><span class="ident">path</span><span class="punct">|</span> <span class="ident">m</span><span class="punct">.</span><span class="ident">directory</span> <span class="ident">path</span> <span class="punct">}</span>
190
-
191
- <span class="comment"># Root</span>
192
- <span class="ident">m</span><span class="punct">.</span><span class="ident">template_copy_each</span> <span class="punct">%w(</span><span class="string"> Rakefile </span><span class="punct">)</span>
193
- <span class="ident">m</span><span class="punct">.</span><span class="ident">file_copy_each</span> <span class="punct">%w(</span><span class="string"> README.txt </span><span class="punct">)</span>
194
-
195
- <span class="comment"># Test helper</span>
196
- <span class="ident">m</span><span class="punct">.</span><span class="ident">template</span> <span class="punct">&quot;</span><span class="string">test_helper.rb</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">test/test_helper.rb</span><span class="punct">&quot;</span>
197
-
198
- <span class="comment"># Scripts</span>
199
- <span class="punct">%w(</span><span class="string"> generate </span><span class="punct">).</span><span class="ident">each</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">file</span><span class="punct">|</span>
200
- <span class="ident">m</span><span class="punct">.</span><span class="ident">template</span> <span class="punct">&quot;</span><span class="string">script/<span class="expr">#{file}</span></span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">script/<span class="expr">#{file}</span></span><span class="punct">&quot;,</span> <span class="ident">script_options</span>
201
- <span class="ident">m</span><span class="punct">.</span><span class="ident">template</span> <span class="punct">&quot;</span><span class="string">script/win_script.cmd</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">script/<span class="expr">#{file}</span>.cmd</span><span class="punct">&quot;,</span>
202
- <span class="symbol">:assigns</span> <span class="punct">=&gt;</span> <span class="punct">{</span> <span class="symbol">:filename</span> <span class="punct">=&gt;</span> <span class="ident">file</span> <span class="punct">}</span> <span class="keyword">if</span> <span class="ident">windows</span>
203
- <span class="keyword">end</span>
204
-
205
- <span class="keyword">end</span>
206
- <span class="keyword">end</span>
207
-
208
- <span class="ident">protected</span>
209
- <span class="keyword">def </span><span class="method">banner</span>
210
- <span class="punct">&lt;&lt;-</span><span class="constant">EOS</span><span class="string">
211
- Create a stub for <span class="expr">#{File.basename $0}</span> to get started.
212
-
213
- Usage: <span class="expr">#{File.basename $0}</span> /path/to/your/app [options]&quot;
214
- </span><span class="constant">EOS</span>
215
- <span class="keyword">end</span>
216
-
217
- <span class="keyword">def </span><span class="method">add_options!</span><span class="punct">(</span><span class="ident">opts</span><span class="punct">)</span>
218
- <span class="ident">opts</span><span class="punct">.</span><span class="ident">separator</span> <span class="punct">'</span><span class="string"></span><span class="punct">'</span>
219
- <span class="ident">opts</span><span class="punct">.</span><span class="ident">separator</span> <span class="punct">&quot;</span><span class="string"><span class="expr">#{File.basename $0}</span> options:</span><span class="punct">&quot;</span>
220
- <span class="ident">opts</span><span class="punct">.</span><span class="ident">on</span><span class="punct">(&quot;</span><span class="string">-v</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">--version</span><span class="punct">&quot;,</span> <span class="punct">&quot;</span><span class="string">Show the <span class="expr">#{File.basename($0)}</span> version number and quit.</span><span class="punct">&quot;)</span>
221
- <span class="keyword">end</span>
222
-
223
- <span class="comment"># Installation skeleton. Intermediate directories are automatically</span>
224
- <span class="comment"># created so don't sweat their absence here.</span>
225
- <span class="constant">BASEDIRS</span> <span class="punct">=</span> <span class="punct">%w(</span><span class="string">
226
- doc
227
- lib
228
- log
229
- script
230
- test
231
- tmp
232
- </span><span class="punct">)</span>
233
- <span class="keyword">end</span>
234
- </pre></p>
235
- <p>Easy peasy.</p>
236
- <h2>Creating a Component Generator for your Framework</h2>
237
- <p>You can include Component Generators in RubyGems, and they will be automatially picked up<br />
238
- by your framework&#8217;s <code>script/generate</code> script.</p>
239
- <h3>Easy way</h3>
240
- <p>Use <a href="http://newgem.rubyforge.org/">newgem</a>, (v0.13.0+), and run:</p>
241
- <pre>
242
- script/generate component_generator
243
- </pre>
244
- <p>and follow the instructions.</p>
245
- <h2>Live at RubyConf 2007</h2>
246
- <p>RubiGen had the 9am, Sunday timeslot at RubyConf 2007 and was <a href="http://rubyconf2007.confreaks.com/d3t1p1_rubigen.html">recorded for your viewing pleasure</a>.</p>
247
- <h2>Forum</h2>
248
- <p><a href="http://groups.google.com/group/rubigen">http://groups.google.com/group/rubigen</a></p>
249
- <h2>How to submit patches</h2>
250
- <p>Read the <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/">8 steps for fixing other people&#8217;s code</a> and for section <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups">8b: Submit patch to Google Groups</a>, use the Google Group above.</p>
251
- <p>The source for this project is available via git. You can <a href="http://github.com/drnic/rubigen/tree/master">browse and/or fork the source</a>, or to clone the project locally:</p>
252
- <pre>git clone git://github.com/drnic/rubigen.git</pre>
253
- <p>The original Subversion repository is <code>svn://rubyforge.org/var/svn/rubigen/trunk</code> for anonymous access.</p>
254
- <h2>Thanks go to&#8230;</h2>
255
- <p><a href="http://bitsweat.net/">Jeremy Kemper</a> (bitsweat) who wrote the original <a href="http://dev.rubyonrails.org">Rails Generator</a>.</p>
256
- <h2>License</h2>
257
- <p>This code is free to use under the terms of the <span class="caps">MIT</span> license.</p>
258
- <h2>Contact</h2>
259
- <p>Comments are welcome. Send an email to <a href="mailto:drnicwilliams@gmail.com">Dr Nic Williams</a> via the <a href="http://groups.google.com/group/rubigen">forum</a></p>
260
- <p class="coda">
261
- <a href="drnicwilliams@gmail.com">Dr Nic Williams</a>, 1st February 2011<br>
262
- Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
263
- </p>
264
- </div>
265
- <!-- insert site tracking codes here, like Google Urchin -->
266
- </body>
267
- </html>
@@ -1,258 +0,0 @@
1
- h1. rubigen
2
-
3
- h1. Ruby Generator Framework
4
-
5
- h2. What
6
-
7
- A framework to allow Ruby applications to generate file/folder stubs (like the <code>rails</code> command does for Ruby on Rails, and the 'script/generate' command within a Rails application during development).
8
-
9
- The RubyConf 2007 presentation is now "online":http://rubyconf2007.confreaks.com/d3t1p1_rubigen.html together with the theme from the A-Team.
10
-
11
- h2. Background
12
-
13
- RubiGen is originally extracted from Ruby on Rails (specifically the rails_generator from its railties gem).
14
-
15
- The rails_generator was hardcoded with Rails-specific dependencies (<code>RAILS_ROOT</code>), Rails generators ('app' = Rails application; 'model' = Rails model+tests+migration), and generally assumed it was the only generator framework within the Ruby world (it was). So, any RubyGem whose name ended with '_generator' was assumed to be a generator for a Rails application.
16
-
17
- But if you are developing an Adhearsion application, then you may want a different set of generators.
18
- If you are developing a RubyGem, then you will want a different set of generators.
19
-
20
- RubiGen exists to give different development environments their own generator framework.
21
-
22
- h2. Installing
23
-
24
- RubiGen is only required at development time, and normally isn't required at deployment time (unless your application uses it to generate files etc for its users).
25
-
26
- On your development machine:
27
-
28
- <pre syntax="ruby">sudo gem install rubigen</pre>
29
-
30
- h2. Usage
31
-
32
- RubiGen will be normally integrated into another RubyGem, such as <code>newgem</code> or <code>rails</code> or <code>camping</code>, rather than be used on its own.
33
-
34
- These frameworks might use RubiGen for two reasons:
35
-
36
- # To generate an initial stub for developers, e.g. <code>rails</code> generated a stub to write a Rails application. <code>newgem</code> generates a stub to write a RubyGem. <br/>
37
- BTW - RubiGen has a builtin application <code>ruby_app</code> which generates a bare-bones Ruby application stub (lib, test, and script folders, plus a Rakefile, and a script/generate script)
38
- # To generate components within their development areas, e.g. Rails had its <code>script/generate</code> script within each Rails application, which hooked back into the rails_generator to lookup and execute generators.
39
-
40
- So, there are two steps to integrating RubiGen into your framework:
41
-
42
- # Use it to generate an initial stub for the developers of your framework. This would create the folders
43
- (<code>lib/app</code>, <code>test</code>, <code>script</code>, <code>doc</code>, <code>log</code>, etc) and starting files (<code>Rakefile</code>,
44
- <code>README.txt</code>, <code>test/test_helper.rb</code> etc). Importantly, it would generate a <code>script/generate</code> file.
45
- The <code>script/generate</code> file (example below) will allow developers of your framework to
46
- generate components/extensions within the framework. <br />
47
- RubiGen allows you to restrict which generators are available. For example, within
48
- RubyGem development environment (as generated by <code>newgem</code>), the <code>script/generator</code>
49
- only shows <code>rubygem</code>-related generators. Rails could restrict <code>script/generator</code>
50
- to only show Rails related generators
51
- # Your framework RubyGem (e.g. <code>newgem</code> or <code>rails</code> RubyGems) needs to add <code>rubigen</code> as a
52
- dependency, so that users of your RubyGem can access the generator framework.
53
-
54
- h1. Creating generators
55
-
56
- There are two types of generators:
57
-
58
- # Application Generators - used by developers of your framework to get started.
59
- Generally, you will create one Application Generator for your framework.
60
- It generates a base stub (such as the <code>rails</code> stub for new Rails applications)
61
- for your framework users.
62
- # Component Generators - used by developers to extend their application.
63
- You may include 1+ built-in generators with your framework.
64
- Developers can also write generators for your framework, and like Rails' generator
65
- install them in various places and have access to their via RubiGen.
66
-
67
- h2. Creating an Application Generator for your Framework
68
-
69
- h3. Easy way
70
-
71
- "newgem":http://newgem.rubyforge.org/ (v0.13.0+) can generate an Application Generator
72
- for a RubyGem.
73
-
74
- # Create new RubyGem: <code>newgem foobar</code>
75
- # Create generator: <code>script/generator application_generator foobar</code>
76
- # Update tests + generator
77
- # Install
78
- # Run with: foobar
79
-
80
- For more documentation, run <code>script/generator application_generator</code>
81
-
82
- h3. DIY
83
-
84
- Without RubiGen, to give your users a head start and create a stub for them, you will
85
- copiously use <code>mkdir_p</code> and <code>File.open</code>. Your script will either be primitive (only
86
- create the bare folders and very few files) or it will be very long and unreadable
87
- (ok, perhaps I'm just talking about the <code>newgem</code> script, which I am dubiously responsible
88
- for... :P).
89
-
90
- With RubiGen, you can create stubs using powerful, yet simple, syntax. Templates are
91
- extracted into a <code>templates</code> folder, and activating the generator from a script requires
92
- only a few lines of code.
93
-
94
- These are the <code>newgem</code> files related to its Application Generator.
95
-
96
- bin/
97
- bin/newgem # Appliction Generator script; Usage: newgem gemname [options]
98
- app_generators/
99
- app_generators/newgem/
100
- app_generators/newgem/newgem_generator.rb
101
- app_generators/newgem/USAGE
102
- app_generators/newgem/templates/
103
- app_generators/newgem/templates/app.rb
104
- app_generators/newgem/templates/History.txt
105
- app_generators/newgem/templates/... lots and lots of templates
106
-
107
- The <code>bin/newgem</code> script is very simple, and looks like:
108
-
109
- <pre syntax="ruby">
110
- require 'rubygems'
111
- require 'rubigen'
112
-
113
- if %w(-v --version).include? ARGV.first
114
- require 'newgem/version'
115
- puts "#{File.basename($0)} #{Newgem::VERSION}"
116
- exit(0)
117
- end
118
-
119
- require 'rubigen/scripts/generate'
120
- RubiGen::Base.use_application_sources!
121
- RubiGen::Scripts::Generate.new.run(ARGV, :generator => 'newgem')
122
- </pre>
123
-
124
- You can copy and paste this for your own generator script, and place it in your RubyGem's <code>bin</code> folder.
125
- Change <code>newgem</code> to your RubyGem's name in the script above (and in all the folders listed above too)
126
-
127
- NOTE: If you leave <code>newgem</code> there, then it will execute the <code>newgem_generator.rb</code> generator;
128
- as the generators are loaded from all RubyGem's having <code>/app_generators</code> folders.
129
-
130
- So, for your RubyGem, you need to keep the <code>/app_generators</code> folder (as you are creating an
131
- Application Generator, not a Component Generator), but change <code>newgem</code> to <code>your gem name</code> in
132
- all the subfolders and files. ESPECIALLY <code>newgem_generator.rb</code> -> <code>yourgem_generator.rb</code>,
133
- as this is how the generator is discovered (via <code>RubiGen::Base.use_application_sources!</code>).
134
-
135
- All the generator work is performed within <code>yourgem_generator.rb</code>. A stub for it will be:
136
-
137
- <pre syntax="ruby">
138
- require 'rbconfig'
139
-
140
- class YourgemGenerator < RubiGen::Base
141
- DEFAULT_SHEBANG = File.join(Config::CONFIG['bindir'],
142
- Config::CONFIG['ruby_install_name'])
143
-
144
- default_options :shebang => DEFAULT_SHEBANG,
145
- :an_option => 'some_default'
146
-
147
- attr_reader :app_name, :module_name
148
-
149
- def initialize(runtime_args, runtime_options = {})
150
- super
151
- usage if args.empty?
152
- @destination_root = args.shift
153
- @app_name = File.basename(File.expand_path(@destination_root))
154
- @module_name = app_name.camelize
155
- extract_options
156
- end
157
-
158
- def manifest
159
- # Use /usr/bin/env if no special shebang was specified
160
- script_options = { :chmod => 0755, :shebang => options[:shebang] == DEFAULT_SHEBANG ? nil : options[:shebang] }
161
- windows = (RUBY_PLATFORM =~ /dos|win32|cygwin/i) || (RUBY_PLATFORM =~ /(:?mswin|mingw)/)
162
-
163
- record do |m|
164
- # Root directory and all subdirectories.
165
- m.directory ''
166
- BASEDIRS.each { |path| m.directory path }
167
-
168
- # Root
169
- m.template_copy_each %w( Rakefile )
170
- m.file_copy_each %w( README.txt )
171
-
172
- # Test helper
173
- m.template "test_helper.rb", "test/test_helper.rb"
174
-
175
- # Scripts
176
- %w( generate ).each do |file|
177
- m.template "script/#{file}", "script/#{file}", script_options
178
- m.template "script/win_script.cmd", "script/#{file}.cmd",
179
- :assigns => { :filename => file } if windows
180
- end
181
-
182
- end
183
- end
184
-
185
- protected
186
- def banner
187
- <<-EOS
188
- Create a stub for #{File.basename $0} to get started.
189
-
190
- Usage: #{File.basename $0} /path/to/your/app [options]"
191
- EOS
192
- end
193
-
194
- def add_options!(opts)
195
- opts.separator ''
196
- opts.separator "#{File.basename $0} options:"
197
- opts.on("-v", "--version", "Show the #{File.basename($0)} version number and quit.")
198
- end
199
-
200
- # Installation skeleton. Intermediate directories are automatically
201
- # created so don't sweat their absence here.
202
- BASEDIRS = %w(
203
- doc
204
- lib
205
- log
206
- script
207
- test
208
- tmp
209
- )
210
- end
211
- </pre>
212
-
213
- Easy peasy.
214
-
215
- h2. Creating a Component Generator for your Framework
216
-
217
- You can include Component Generators in RubyGems, and they will be automatially picked up
218
- by your framework's <code>script/generate</code> script.
219
-
220
- h3. Easy way
221
-
222
- Use "newgem":http://newgem.rubyforge.org/, (v0.13.0+), and run:
223
-
224
- <pre>
225
- script/generate component_generator
226
- </pre>
227
-
228
- and follow the instructions.
229
-
230
- h2. Live at RubyConf 2007
231
-
232
- RubiGen had the 9am, Sunday timeslot at RubyConf 2007 and was "recorded for your viewing pleasure":http://rubyconf2007.confreaks.com/d3t1p1_rubigen.html.
233
-
234
- h2. Forum
235
-
236
- "http://groups.google.com/group/rubigen":http://groups.google.com/group/rubigen
237
-
238
- h2. How to submit patches
239
-
240
- Read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/ and for section "8b: Submit patch to Google Groups":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups, use the Google Group above.
241
-
242
- The source for this project is available via git. You can "browse and/or fork the source":http://github.com/drnic/rubigen/tree/master, or to clone the project locally:
243
-
244
- <pre>git clone git://github.com/drnic/rubigen.git</pre>
245
-
246
- The original Subversion repository is <code>svn://rubyforge.org/var/svn/rubigen/trunk</code> for anonymous access.
247
-
248
- h2. Thanks go to...
249
-
250
- "Jeremy Kemper":http://bitsweat.net/ (bitsweat) who wrote the original "Rails Generator":http://dev.rubyonrails.org.
251
-
252
- h2. License
253
-
254
- This code is free to use under the terms of the MIT license.
255
-
256
- h2. Contact
257
-
258
- Comments are welcome. Send an email to "Dr Nic Williams":mailto:drnicwilliams@gmail.com via the "forum":http://groups.google.com/group/rubigen