RubyScreen

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.

Usage is best described through a few examples, which are followed by detailed information on the available elements in the configuration file.

Installation

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 at the Ruby on Rails installation page.

Once you have gems, you’re just a command away:

gem install ruby-screen

On non-Windows systems, you may need to use sudo to elevate you privileges.

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.

Examples

RubyScreen consists of a YAML 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:


startup_message: off
defscrollback: 5000

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.

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:


startup_message: off
defscrollback: 5000

cool_site:
  working_directory: ~/web_projects/cool_site
  windows:
    -
      title: Editor
      command: vim .
    -
      title: Misc
    -
      title: Logs
      number: 9
      command: tail -f /var/log/web_server.log

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.

That’s great, but you are working on more than just that one cool project. You have multiple sites located in ~/web_projects, and they all have they all have similar needs: an editor, a terminal, and a log viewer.


startup_message: off
defscrollback: 5000

web_work:
  working_directory: ~/web_projects
  windows:
    -
      title: Editor
      command: vim .
    -
      title: Misc
    -
      title: Logs
      number: 9
      command: tail -f /var/log/web_server.log

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 *workingdirectory* specified in that configuration.

If you had a couple of web projects you are working on, like ~/web_projects/cool_project_, or ~/web_projects/legacywork, 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 ~/web_projects can be launched by name through the web_work configuration.

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.


startup_message: off
defscrollback: 5000

web_work:
  working_directory: ~/web_projects
  windows:
    -
      title: Editor
      command: vim .
    -
      title: Misc
    -
      title: Logs
      number: 9
      command: tail -f /var/log/web_server.log

  cool_site:
    relative_directory: cool_site
    windows:
      -
        title: Chat Server
        command: /bin/my_awesome_chat_server

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 coolsite*.

The Configuration File

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.

Customizations

The simplest element, customizations consist of simple key/value pairs. Valid customizations can be found in the “Customization” section of the Screen manpage.


startup_message: off
defscrollback: 5000

This will result in a Screen configuration without the welcoming splash page, with a 5000 line scroll buffer.

(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.)

Windows

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.


windows:
  -
    title: Miscellaneous
  -
    number: 0
    title: First Window
  -
    number: 1
    title: Processes
    command: top

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.

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.

Nested Configurations

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.


startup_message: off
defscrollback: 5000

generic:
  windows:
    -
      title: Miscellaneous
    -
      number: 1
      title: Other Window

  specific:
    defscrollback: 1000
    windows:
      -
        number: 1
        title: Nested Window

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.

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.

There is no limit on how far you can nest, apart from your own sanity.

Paths

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.


startup_message: off

web_server_edit:
  working_directory: /usr/local/my_web_server
  windows:
    -
      name: Config
      command: vim conf/my_web_server.conf
    -
      name: Log
      command: tail -f server.log

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.

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 *workingdirectory* settings, so that RubyScreen can work as intended no matter where it is called from.

The relative_directory setting can be used in nested configurations and will be appended to the end of the current working directory.

Misc

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. Any Ruby can be executed inside of ERB, so review any configuration files before executing.

Thanks

Thanks to the author of this blog posting, which got the ball rolling for me on launching Screen with predefined windows and commands.

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.