ruby-screen 0.9.0

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.
Files changed (45) hide show
  1. data/History.txt +3 -0
  2. data/License.txt +20 -0
  3. data/Manifest.txt +44 -0
  4. data/README.textile +226 -0
  5. data/README.txt +1 -0
  6. data/Rakefile +4 -0
  7. data/bin/ruby-screen +5 -0
  8. data/config/hoe.rb +71 -0
  9. data/config/requirements.rb +17 -0
  10. data/lib/ruby_screen.rb +14 -0
  11. data/lib/ruby_screen/configuration/description.rb +60 -0
  12. data/lib/ruby_screen/configuration/generator.rb +54 -0
  13. data/lib/ruby_screen/configuration/parser.rb +35 -0
  14. data/lib/ruby_screen/configuration/parser/block_processor.rb +43 -0
  15. data/lib/ruby_screen/configuration/parser/iterator.rb +31 -0
  16. data/lib/ruby_screen/configuration/parser/nesting_hash.rb +37 -0
  17. data/lib/ruby_screen/executer.rb +26 -0
  18. data/lib/ruby_screen/preferences_loader.rb +26 -0
  19. data/lib/ruby_screen/version.rb +9 -0
  20. data/log/debug.log +0 -0
  21. data/script/destroy +14 -0
  22. data/script/generate +14 -0
  23. data/script/txt2html +74 -0
  24. data/setup.rb +1585 -0
  25. data/spec/configuration/description_spec.rb +93 -0
  26. data/spec/configuration/generator_spec.rb +49 -0
  27. data/spec/configuration/parser/block_processor_spec.rb +46 -0
  28. data/spec/configuration/parser/iterator_spec.rb +35 -0
  29. data/spec/configuration/parser/nesting_hash_spec.rb +59 -0
  30. data/spec/configuration/parser_spec.rb +73 -0
  31. data/spec/executer_spec.rb +63 -0
  32. data/spec/preferences_loader_spec.rb +46 -0
  33. data/spec/ruby_screen_spec.rb +33 -0
  34. data/spec/spec.opts +1 -0
  35. data/spec/spec_helper.rb +9 -0
  36. data/tasks/deployment.rake +34 -0
  37. data/tasks/environment.rake +7 -0
  38. data/tasks/rspec.rake +21 -0
  39. data/tasks/website.rake +17 -0
  40. data/website/index.html +289 -0
  41. data/website/index.txt +226 -0
  42. data/website/javascripts/rounded_corners_lite.inc.js +285 -0
  43. data/website/stylesheets/screen.css +138 -0
  44. data/website/template.rhtml +48 -0
  45. metadata +111 -0
data/spec/ruby_screen_spec.rb ADDED
@@ -0,0 +1,33 @@
1
+ require File.dirname(__FILE__) + '/spec_helper.rb'
2
+
3
+ describe RubyScreen do
4
+ before do
5
+ RubyScreen::Executer.stub!(:new) # don't want it to actually call Kernel#exec!
6
+ end
7
+
8
+ def process(arguments = [])
9
+ RubyScreen.process(arguments)
10
+ end
11
+
12
+ it "should call RubyScreen::PreferencesLoader::load" do
13
+ RubyScreen::PreferencesLoader.should_receive(:load).and_return({})
14
+ process
15
+ end
16
+
17
+ it "should pass hash from PreferencesLoader and arguments to Configuration::Parser.parse" do
18
+ preferences_hash = mock("mock preferences hash")
19
+ RubyScreen::PreferencesLoader.stub!(:load).and_return(preferences_hash)
20
+
21
+ arguments = mock("mock passed-in arguments")
22
+ RubyScreen::Configuration::Parser.should_receive(:parse).with(arguments, preferences_hash)
23
+ process(arguments)
24
+ end
25
+
26
+ it "should pass Configuration::Description to new Configuration::Executer" do
27
+ RubyScreen::PreferencesLoader.stub!(:load)
28
+ mock_configuration = mock("Mock Configuration::Description")
29
+ RubyScreen::Configuration::Parser.stub!(:parse).and_return(mock_configuration)
30
+ RubyScreen::Executer.should_receive(:new).with(mock_configuration)
31
+ process
32
+ end
33
+ end
data/spec/spec.opts ADDED
@@ -0,0 +1 @@
1
+ --colour
data/spec/spec_helper.rb ADDED
@@ -0,0 +1,9 @@
1
+ begin
2
+ require 'spec'
3
+ rescue LoadError
4
+ require 'rubygems'
5
+ gem 'rspec'
6
+ require 'spec'
7
+ end
8
+
9
+ require 'lib/ruby_screen'
data/tasks/deployment.rake ADDED
@@ -0,0 +1,34 @@
1
+ desc 'Release the website and new gem version'
2
+ task :deploy => [:check_version, :website, :release] do
3
+ puts "Remember to create SVN tag:"
4
+ puts "svn copy svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/trunk " +
5
+ "svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/tags/REL-#{VERS} "
6
+ puts "Suggested comment:"
7
+ puts "Tagging release #{CHANGES}"
8
+ end
9
+
10
+ desc 'Runs tasks website_generate and install_gem as a local deployment of the gem'
11
+ task :local_deploy => [:website_generate, :install_gem]
12
+
13
+ task :check_version do
14
+ unless ENV['VERSION']
15
+ puts 'Must pass a VERSION=x.y.z release version'
16
+ exit
17
+ end
18
+ unless ENV['VERSION'] == VERS
19
+ puts "Please update your version.rb to match the release version, currently #{VERS}"
20
+ exit
21
+ end
22
+ end
23
+
24
+ desc 'Install the package as a gem, without generating documentation(ri/rdoc)'
25
+ task :install_gem_no_doc => [:clean, :package] do
26
+ sh "#{'sudo ' unless Hoe::WINDOZE }gem install pkg/*.gem --no-rdoc --no-ri"
27
+ end
28
+
29
+ namespace :manifest do
30
+ desc 'Recreate Manifest.txt to include ALL files'
31
+ task :refresh do
32
+ `rake check_manifest | patch -p0 > Manifest.txt`
33
+ end
34
+ end
data/tasks/environment.rake ADDED
@@ -0,0 +1,7 @@
1
+ task :ruby_env do
2
+ RUBY_APP = if RUBY_PLATFORM =~ /java/
3
+ "jruby"
4
+ else
5
+ "ruby"
6
+ end unless defined? RUBY_APP
7
+ end
data/tasks/rspec.rake ADDED
@@ -0,0 +1,21 @@
1
+ begin
2
+ require 'spec'
3
+ rescue LoadError
4
+ require 'rubygems'
5
+ require 'spec'
6
+ end
7
+ begin
8
+ require 'spec/rake/spectask'
9
+ rescue LoadError
10
+ puts <<-EOS
11
+ To use rspec for testing you must install rspec gem:
12
+ gem install rspec
13
+ EOS
14
+ exit(0)
15
+ end
16
+
17
+ desc "Run the specs under spec/models"
18
+ Spec::Rake::SpecTask.new do |t|
19
+ t.spec_opts = ['--options', "spec/spec.opts"]
20
+ t.spec_files = FileList['spec/**/*_spec.rb']
21
+ end
data/tasks/website.rake ADDED
@@ -0,0 +1,17 @@
1
+ desc 'Generate website files'
2
+ task :website_generate => :ruby_env do
3
+ (Dir['website/**/*.txt'] - Dir['website/version*.txt']).each do |txt|
4
+ sh %{ #{RUBY_APP} script/txt2html #{txt} > #{txt.gsub(/txt$/,'html')} }
5
+ end
6
+ end
7
+
8
+ desc 'Upload website files to rubyforge'
9
+ task :website_upload do
10
+ host = "#{rubyforge_username}@rubyforge.org"
11
+ remote_dir = "/var/www/gforge-projects/#{PATH}/"
12
+ local_dir = 'website'
13
+ sh %{rsync -aCv #{local_dir}/ #{host}:#{remote_dir}}
14
+ end
15
+
16
+ desc 'Generate and upload website files'
17
+ task :website => [:website_generate, :website_upload, :publish_docs]
data/website/index.html ADDED
@@ -0,0 +1,289 @@
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
+ RubyScreen
9
+ </title>
10
+ <script src="javascripts/rounded_corners_lite.inc.js" type="text/javascript"></script>
11
+ <style>
12
+
13
+ </style>
14
+ <script type="text/javascript">
15
+ window.onload = function() {
16
+ settings = {
17
+ tl: { radius: 10 },
18
+ tr: { radius: 10 },
19
+ bl: { radius: 10 },
20
+ br: { radius: 10 },
21
+ antiAlias: true,
22
+ autoPad: true,
23
+ validTags: ["div"]
24
+ }
25
+ var versionBox = new curvyCorners(settings, document.getElementById("version"));
26
+ versionBox.applyCornersToAll();
27
+ }
28
+ </script>
29
+ </head>
30
+ <body>
31
+ <div id="main">
32
+
33
+ <h1>RubyScreen</h1>
34
+ <div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/ruby_screen"; return false'>
35
+ <p>Get Version</p>
36
+ <a href="http://rubyforge.org/projects/ruby_screen" class="numbers">0.9.0</a>
37
+ </div>
38
+ <p>RubyScreen is a utility for managing and launching <span class="caps">GNU</span> Screen configurations. Though written in Ruby and requiring a valid Ruby installation, it should be useful for a developer in any language. If you often find yourself opening up the same multiple windows and running various commands, or juggling multiple similar Screen configurations with various window setups, this may help.</p>
39
+
40
+
41
+ <p>Usage is best described through a few examples, which are followed by detailed information on the available elements in the configuration file.</p>
42
+
43
+
44
+ <h2>Installation</h2>
45
+
46
+
47
+ <p>RubyScreen is packaged as a Ruby Gem, and requires a valid installation of Ruby along with the RubyGems package manager. Rather than document that process, you&#8217;re likely to find more helpful instructions for installing those two components <a href="http://www.rubyonrails.org/down">here</a> at the Ruby on Rails installation page.</p>
48
+
49
+
50
+ <p>Once you have gems, you&#8217;re just a command away:</p>
51
+
52
+
53
+ <pre><code>gem install ruby-screen</code></pre>
54
+
55
+
56
+ <p>On non-Windows systems, you may need to use <strong>sudo</strong> to elevate you privileges.</p>
57
+
58
+
59
+ <p>To verify installation, try <strong>ruby-screen</strong> at your command prompt. You should see a helpful message about your lack of configuration file. You can build your own configuration file after reading the documentation below.</p>
60
+
61
+
62
+ <h2>Examples</h2>
63
+
64
+
65
+ <p>RubyScreen consists of a <a href="http://www.yaml.org/"><span class="caps">YAML</span></a> configuration file and a command line utility. The configuration file must be located in your home directory and named <em>.ruby-screen.yml</em>. The simplest example:</p>
66
+
67
+
68
+ <pre><code>
69
+ startup_message: off
70
+ defscrollback: 5000
71
+ </pre></code>
72
+
73
+ <p>The command for launching RubyScreen is <strong>ruby-screen</strong>. It will load your <span class="caps">YAML</span> configuration file and launch Screen with the appropriate options. With the configuration file above, you&#8217;ll have no splash screen and a 5000 line scroll buffer. Not exactly revolutionary.</p>
74
+
75
+
76
+ <p>Let&#8217;s say you&#8217;re a web developer working on a cool new project. You&#8217;re using your favorite text editor, watching some logs, keeping a window open for miscellaneous tasks. Your configuration file would look something like this:</p>
77
+
78
+
79
+ <pre><code>
80
+ startup_message: off
81
+ defscrollback: 5000
82
+
83
+ cool_site:
84
+ working_directory: ~/web_projects/cool_site
85
+ windows:
86
+ -
87
+ title: Editor
88
+ command: vim .
89
+ -
90
+ title: Misc
91
+ -
92
+ title: Logs
93
+ number: 9
94
+ command: tail -f /var/log/web_server.log
95
+ </pre></code>
96
+
97
+ <p>Now you still have your generic configuration, along with an additional configuration for your cool project. Running <strong>ruby-screen cool_site</strong> will move into your projects&#8217; directory and start a text editor, a window with a fresh command line, and a window tailing your server log. The first two windows take whatever number Screen assigns to them (0 and 1 in this case), while the log window will always be assigned to number 9.</p>
98
+
99
+
100
+ <p>That&#8217;s great, but you are working on more than just that one cool project. You have multiple sites located in ~<em>/web_projects</em>, and they all have they all have similar needs: an editor, a terminal, and a log viewer.</p>
101
+
102
+
103
+ <pre><code>
104
+ startup_message: off
105
+ defscrollback: 5000
106
+
107
+ web_work:
108
+ working_directory: ~/web_projects
109
+ windows:
110
+ -
111
+ title: Editor
112
+ command: vim .
113
+ -
114
+ title: Misc
115
+ -
116
+ title: Logs
117
+ number: 9
118
+ command: tail -f /var/log/web_server.log
119
+ </pre></code>
120
+
121
+ <p>This configuration is identical to the last, except that it is a bit more generic. The configuration named <em>cool_site</em> is now <em>web_work</em>, and the <strong>working_directory</strong> now points to your generic projects directory. When you use the <strong>ruby-screen</strong> command line utility, the first argument is usually going to refer to the name of one of your nested configurations, with any additional arguments being tacked on as directories relative to the <strong>working_directory</strong> specified in that configuration.</p>
122
+
123
+
124
+ <p>If you had a couple of web projects you are working on, like ~<em>/web_projects/cool_project</em>, or ~<em>/web_projects/legacy_work</em>, those specific projects can be launched using the generic <em>web_work</em> configuration by typing <strong>ruby-screen web_work cool_project</strong> and <strong>ruby-screen web_work legacy_work</strong> respectively. Any new projects added to ~<em>/web_projects</em> can be launched by name through the <strong>web_work</strong> configuration.</p>
125
+
126
+
127
+ <p>Finally, let&#8217;s return to your cool site. You have added some fancy new chat functionality to it, but that requires the chat server to be running during every development session. Aside from the chat server, it&#8217;s the same as all of your other web projects.</p>
128
+
129
+
130
+ <pre><code>
131
+ startup_message: off
132
+ defscrollback: 5000
133
+
134
+ web_work:
135
+ working_directory: ~/web_projects
136
+ windows:
137
+ -
138
+ title: Editor
139
+ command: vim .
140
+ -
141
+ title: Misc
142
+ -
143
+ title: Logs
144
+ number: 9
145
+ command: tail -f /var/log/web_server.log
146
+
147
+ cool_site:
148
+ relative_directory: cool_site
149
+ windows:
150
+ -
151
+ title: Chat Server
152
+ command: /bin/my_awesome_chat_server
153
+ </pre></code>
154
+
155
+ <p>You&#8217;ve added on to the previous example and added a nested configuration, called <em>cool_site</em>. It&#8217;s under <em>web_work</em>, and inherits all the Customizations and Windows defined above it, while defining a new window that will launch your chat server. This nested configuration can be launched from the command line with <strong>ruby-screen cool_site</strong>.</p>
156
+
157
+
158
+ <h2>The Configuration File</h2>
159
+
160
+
161
+ <p>RubyScreen looks for a file in your home directory named <strong>.ruby-screen.yml</strong>. It must be a valid <span class="caps">YAML</span> file. It can contain multiple elements that will be translated into a Screen-compatible plain text configuration file, depending on the command line arguments that are passed in when RubyScreen is launched.</p>
162
+
163
+
164
+ <h3>Customizations</h3>
165
+
166
+
167
+ <p>The simplest element, customizations consist of simple key/value pairs. Valid customizations can be found in the &#8220;Customization&#8221; section of the Screen manpage.</p>
168
+
169
+
170
+ <pre><code>
171
+ startup_message: off
172
+ defscrollback: 5000
173
+ </pre></code>
174
+
175
+ <p>This will result in a Screen configuration without the welcoming splash page, with a 5000 line scroll buffer.</p>
176
+
177
+
178
+ <p>(YAML veterans may wonder that the &#8216;off&#8217; value need not be quoted. Pay no attention to the man behind the curtain. It just doesn&#8217;t.)</p>
179
+
180
+
181
+ <h3>Windows</h3>
182
+
183
+
184
+ <p>Windows in Screen are somewhat analogous to tabs in a browser. You can use window definitions to specify the windows you want open at launch. You can optionally title and number them, as well as giving them an initial command to execute at launch.</p>
185
+
186
+
187
+ <pre><code>
188
+ windows:
189
+ -
190
+ title: Miscellaneous
191
+ -
192
+ number: 0
193
+ title: First Window
194
+ -
195
+ number: 1
196
+ title: Processes
197
+ command: top
198
+ </pre></code>
199
+
200
+ <p>This would result in 3 windows at launch. Window 0 would be named <em>First Window</em> with a fresh command prompt, window 1 would be named <em>Processes</em> and would be running the <em>top</em> command. A third window, named <em>Miscellaneous</em> would have a fresh command prompt, and be assigned to the first available number by Screen.</p>
201
+
202
+
203
+ <p>The <strong>title</strong>, <strong>number</strong>, and <strong>command</strong> definitions are all optional, though you must supply one. The value of the <strong>command</strong> is executed by Screen on launch, as-is. If you decide that <em>rm -FR</em> is your command, it&#8217;s not going to stop you.</p>
204
+
205
+
206
+ <h3>Nested Configurations</h3>
207
+
208
+
209
+ <p>A nested configuration can be called by name from the ruby-screen command line utility. They can contain the same elements as a top-level configuration.</p>
210
+
211
+
212
+ <pre><code>
213
+ startup_message: off
214
+ defscrollback: 5000
215
+
216
+ generic:
217
+ windows:
218
+ -
219
+ title: Miscellaneous
220
+ -
221
+ number: 1
222
+ title: Other Window
223
+
224
+ specific:
225
+ defscrollback: 1000
226
+ windows:
227
+ -
228
+ number: 1
229
+ title: Nested Window
230
+ </pre></code>
231
+
232
+ <p>Nested configuration names are passed as the first argument to the <strong>ruby-screen</strong> command line utility. When this happens, the programs processes the configuration from the highest level down through the hierarchy to the configuration you specified, merging customizations and windows as it goes. Any customization keys or numbered windows that are duplicated deeper in the hierarchy will override those above them.</p>
233
+
234
+
235
+ <p>Calling the nested configuration named <em>specific</em> above would use the Windows and Customizations specified in the top level and <em>generic</em> configurations, but would override the number of lines of scroll buffer and the name of Window 1.</p>
236
+
237
+
238
+ <p>There is no limit on how far you can nest, apart from your own sanity.</p>
239
+
240
+
241
+ <h3>Paths</h3>
242
+
243
+
244
+ <p>Use <strong>working_directory</strong> and <strong>relative_directory</strong> in instances where you will always want a certain configuration to launch with a specific working directory. This is the equivalent to manually traversing to the intended directory before launching the Screen command.</p>
245
+
246
+
247
+ <pre><code>
248
+ startup_message: off
249
+
250
+ web_server_edit:
251
+ working_directory: /usr/local/my_web_server
252
+ windows:
253
+ -
254
+ name: Config
255
+ command: vim conf/my_web_server.conf
256
+ -
257
+ name: Log
258
+ command: tail -f server.log
259
+ </pre></code>
260
+
261
+ <p>When running the <strong>web_server_edit</strong> configuration above, the commands will be executed in <em>/usr/local/my_web_server</em>. Any new windows you open within Screen will also default to that directory.</p>
262
+
263
+
264
+ <p>The working directory can also begin with a tilde character to indicate your home directory. <em>~/projects</em> on a Linux system would translate to <em>/home/your_username/projects</em>. It is suggested that you use the tilde or a full path for your <strong>working_directory</strong> settings, so that RubyScreen can work as intended no matter where it is called from.</p>
265
+
266
+
267
+ <p>The <strong>relative_directory</strong> setting can be used in nested configurations and will be appended to the end of the current working directory.</p>
268
+
269
+
270
+ <h3> Misc</h3>
271
+
272
+
273
+ <p>Before your configuration file is loaded by the <span class="caps">YAML</span> library it is processed by <span class="caps">ERB</span>, a Ruby templating system. Information on its syntax is available <a href="http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/">here</a>. Any Ruby can be executed inside of <span class="caps">ERB</span>, so review any configuration files before executing.</p>
274
+
275
+
276
+ <h2>Thanks</h2>
277
+
278
+
279
+ <p>Thanks to the author of <a href="http://mikeburnscoder.wordpress.com/2007/06/21/my-rails-development-environment-version-1-vim-and-screen/">this</a> blog posting, which got the ball rolling for me on launching Screen with predefined windows and commands.</p>
280
+ <p class="coda">
281
+ Don Petersen, 4th June 2008<br>
282
+ Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
283
+ </p>
284
+ </div>
285
+
286
+ <!-- insert site tracking codes here, like Google Urchin -->
287
+
288
+ </body>
289
+ </html>
data/website/index.txt ADDED
@@ -0,0 +1,226 @@
1
+ h1. RubyScreen
2
+
3
+ RubyScreen is a utility for managing and launching GNU Screen configurations. Though written in Ruby and requiring a valid Ruby installation, it should be useful for a developer in any language. If you often find yourself opening up the same multiple windows and running various commands, or juggling multiple similar Screen configurations with various window setups, this may help.
4
+
5
+ Usage is best described through a few examples, which are followed by detailed information on the available elements in the configuration file.
6
+
7
+ h2. Installation
8
+
9
+ RubyScreen is packaged as a Ruby Gem, and requires a valid installation of Ruby along with the RubyGems package manager. Rather than document that process, you're likely to find more helpful instructions for installing those two components "here":http://www.rubyonrails.org/down at the Ruby on Rails installation page.
10
+
11
+ Once you have gems, you're just a command away:
12
+
13
+ gem install ruby-screen
14
+
15
+ On non-Windows systems, you may need to use *sudo* to elevate you privileges.
16
+
17
+ To verify installation, try *ruby-screen* at your command prompt. You should see a helpful message about your lack of configuration file. You can build your own configuration file after reading the documentation below.
18
+
19
+ h2. Examples
20
+
21
+ RubyScreen consists of a "YAML":http://www.yaml.org/ configuration file and a command line utility. The configuration file must be located in your home directory and named _.ruby-screen.yml_. The simplest example:
22
+
23
+ <pre><code>
24
+ startup_message: off
25
+ defscrollback: 5000
26
+ </pre></code>
27
+
28
+ The command for launching RubyScreen is *ruby-screen*. It will load your YAML configuration file and launch Screen with the appropriate options. With the configuration file above, you'll have no splash screen and a 5000 line scroll buffer. Not exactly revolutionary.
29
+
30
+ Let's say you're a web developer working on a cool new project. You're using your favorite text editor, watching some logs, keeping a window open for miscellaneous tasks. Your configuration file would look something like this:
31
+
32
+ <pre><code>
33
+ startup_message: off
34
+ defscrollback: 5000
35
+
36
+ cool_site:
37
+ working_directory: ~/web_projects/cool_site
38
+ windows:
39
+ -
40
+ title: Editor
41
+ command: vim .
42
+ -
43
+ title: Misc
44
+ -
45
+ title: Logs
46
+ number: 9
47
+ command: tail -f /var/log/web_server.log
48
+ </pre></code>
49
+
50
+ Now you still have your generic configuration, along with an additional configuration for your cool project. Running *ruby-screen cool_site* will move into your projects' directory and start a text editor, a window with a fresh command line, and a window tailing your server log. The first two windows take whatever number Screen assigns to them (0 and 1 in this case), while the log window will always be assigned to number 9.
51
+
52
+ That's great, but you are working on more than just that one cool project. You have multiple sites located in <notextile>~</notextile>_/web_projects_, and they all have they all have similar needs: an editor, a terminal, and a log viewer.
53
+
54
+ <pre><code>
55
+ startup_message: off
56
+ defscrollback: 5000
57
+
58
+ web_work:
59
+ working_directory: ~/web_projects
60
+ windows:
61
+ -
62
+ title: Editor
63
+ command: vim .
64
+ -
65
+ title: Misc
66
+ -
67
+ title: Logs
68
+ number: 9
69
+ command: tail -f /var/log/web_server.log
70
+ </pre></code>
71
+
72
+ This configuration is identical to the last, except that it is a bit more generic. The configuration named _cool_site_ is now _web_work_, and the *working_directory* now points to your generic projects directory. When you use the *ruby-screen* command line utility, the first argument is usually going to refer to the name of one of your nested configurations, with any additional arguments being tacked on as directories relative to the *working_directory* specified in that configuration.
73
+
74
+ If you had a couple of web projects you are working on, like <notextile>~</notextile>_/web_projects/cool_project_, or <notextile>~</notextile>_/web_projects/legacy_work_, those specific projects can be launched using the generic _web_work_ configuration by typing *ruby-screen web_work cool_project* and *ruby-screen web_work legacy_work* respectively. Any new projects added to <notextile>~</notextile>_/web_projects_ can be launched by name through the *web_work* configuration.
75
+
76
+ Finally, let's return to your cool site. You have added some fancy new chat functionality to it, but that requires the chat server to be running during every development session. Aside from the chat server, it's the same as all of your other web projects.
77
+
78
+ <pre><code>
79
+ startup_message: off
80
+ defscrollback: 5000
81
+
82
+ web_work:
83
+ working_directory: ~/web_projects
84
+ windows:
85
+ -
86
+ title: Editor
87
+ command: vim .
88
+ -
89
+ title: Misc
90
+ -
91
+ title: Logs
92
+ number: 9
93
+ command: tail -f /var/log/web_server.log
94
+
95
+ cool_site:
96
+ relative_directory: cool_site
97
+ windows:
98
+ -
99
+ title: Chat Server
100
+ command: /bin/my_awesome_chat_server
101
+ </pre></code>
102
+
103
+ You've added on to the previous example and added a nested configuration, called _cool_site_. It's under _web_work_, and inherits all the Customizations and Windows defined above it, while defining a new window that will launch your chat server. This nested configuration can be launched from the command line with *ruby-screen cool_site*.
104
+
105
+ h2. The Configuration File
106
+
107
+ RubyScreen looks for a file in your home directory named *.ruby-screen.yml*. It must be a valid YAML file. It can contain multiple elements that will be translated into a Screen-compatible plain text configuration file, depending on the command line arguments that are passed in when RubyScreen is launched.
108
+
109
+ h3. Customizations
110
+
111
+ The simplest element, customizations consist of simple key/value pairs. Valid customizations can be found in the "Customization" section of the Screen manpage.
112
+
113
+ <pre><code>
114
+ startup_message: off
115
+ defscrollback: 5000
116
+ </pre></code>
117
+
118
+ This will result in a Screen configuration without the welcoming splash page, with a 5000 line scroll buffer.
119
+
120
+ (YAML veterans may wonder that the 'off' value need not be quoted. Pay no attention to the man behind the curtain. It just doesn't.)
121
+
122
+ h3. Windows
123
+
124
+ Windows in Screen are somewhat analogous to tabs in a browser. You can use window definitions to specify the windows you want open at launch. You can optionally title and number them, as well as giving them an initial command to execute at launch.
125
+
126
+ <pre><code>
127
+ windows:
128
+ -
129
+ title: Miscellaneous
130
+ -
131
+ number: 0
132
+ title: First Window
133
+ -
134
+ number: 1
135
+ title: Processes
136
+ command: top
137
+ </pre></code>
138
+
139
+ This would result in 3 windows at launch. Window 0 would be named _First Window_ with a fresh command prompt, window 1 would be named _Processes_ and would be running the _top_ command. A third window, named _Miscellaneous_ would have a fresh command prompt, and be assigned to the first available number by Screen.
140
+
141
+ The *title*, *number*, and *command* definitions are all optional, though you must supply one. The value of the *command* is executed by Screen on launch, as-is. If you decide that _rm -FR_ is your command, it's not going to stop you.
142
+
143
+ h3. Nested Configurations
144
+
145
+ A nested configuration can be called by name from the ruby-screen command line utility. They can contain the same elements as a top-level configuration.
146
+
147
+ <pre><code>
148
+ startup_message: off
149
+ defscrollback: 5000
150
+
151
+ generic:
152
+ windows:
153
+ -
154
+ title: Miscellaneous
155
+ -
156
+ number: 1
157
+ title: Other Window
158
+
159
+ specific:
160
+ defscrollback: 1000
161
+ windows:
162
+ -
163
+ number: 1
164
+ title: Nested Window
165
+ </pre></code>
166
+
167
+ Nested configuration names are passed as the first argument to the *ruby-screen* command line utility. When this happens, the programs processes the configuration from the highest level down through the hierarchy to the configuration you specified, merging customizations and windows as it goes. Any customization keys or numbered windows that are duplicated deeper in the hierarchy will override those above them.
168
+
169
+ Calling the nested configuration named _specific_ above would use the Windows and Customizations specified in the top level and _generic_ configurations, but would override the number of lines of scroll buffer and the name of Window 1.
170
+
171
+ There is no limit on how far you can nest, apart from your own sanity.
172
+
173
+ h3. Paths
174
+
175
+ Use *working_directory* and *relative_directory* in instances where you will always want a certain configuration to launch with a specific working directory. This is the equivalent to manually traversing to the intended directory before launching the Screen command.
176
+
177
+ <pre><code>
178
+ startup_message: off
179
+
180
+ web_server_edit:
181
+ working_directory: /usr/local/my_web_server
182
+ windows:
183
+ -
184
+ name: Config
185
+ command: vim conf/my_web_server.conf
186
+ -
187
+ name: Log
188
+ command: tail -f server.log
189
+ </pre></code>
190
+
191
+ When running the *web_server_edit* configuration above, the commands will be executed in _/usr/local/my_web_server_. Any new windows you open within Screen will also default to that directory.
192
+
193
+ The working directory can also begin with a tilde character to indicate your home directory. _~/projects_ on a Linux system would translate to _/home/your_username/projects_. It is suggested that you use the tilde or a full path for your *working_directory* settings, so that RubyScreen can work as intended no matter where it is called from.
194
+
195
+ The *relative_directory* setting can be used in nested configurations and will be appended to the end of the current working directory.
196
+
197
+ h3. Misc
198
+
199
+ Before your configuration file is loaded by the YAML library it is processed by ERB, a Ruby templating system. Information on its syntax is available "here":http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/. Any Ruby can be executed inside of ERB, so review any configuration files before executing.
200
+
201
+ h2. Thanks
202
+
203
+ Thanks to the author of "this":http://mikeburnscoder.wordpress.com/2007/06/21/my-rails-development-environment-version-1-vim-and-screen/ blog posting, which got the ball rolling for me on launching Screen with predefined windows and commands.
204
+
205
+ h2. License
206
+
207
+ Copyright (c) 2008
208
+
209
+ Permission is hereby granted, free of charge, to any person obtaining
210
+ a copy of this software and associated documentation files (the
211
+ 'Software'), to deal in the Software without restriction, including
212
+ without limitation the rights to use, copy, modify, merge, publish,
213
+ distribute, sublicense, and/or sell copies of the Software, and to
214
+ permit persons to whom the Software is furnished to do so, subject to
215
+ the following conditions:
216
+
217
+ The above copyright notice and this permission notice shall be
218
+ included in all copies or substantial portions of the Software.
219
+
220
+ THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
221
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
222
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
223
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
224
+ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
225
+ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
226
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.