scide 0.0.5 → 0.0.6

data/VERSION

@@ -1 +1 @@
-0.0.5
+0.0.6

data/lib/scide/command.rb

@@ -1,69 +1,124 @@
 module Scide
 
+  # A command to be used in a GNU Screen window. There are several
+  # command implementations (show command, run command, tail file, etc).
+  # See under Scide::Commands.
   class Command
 
-    def self.resolve contents, properties = {}, options = {}
+    # The options given to this command. These are built by merging
+    # global options, project options and window options.
+    attr_reader :options
 
+    # Returns a new command for the given window.
+    #
+    # ==== Arguments
+    # * <tt>window</tt> - The window in which the command will be used.
+    #   Command options are retrieved from Scide::Window#options. See
+    #   #initialize.
+    # * <tt>contents</tt> - The command configuration (String or Hash).
+    #
+    # ==== String Initialization
+    # The string must be in the format <tt>COMMAND [CONTENTS]</tt>.
+    #
+    # <tt>TYPE</tt> is the name of the command class under
+    # Scide::Commands, in uppercase camelcase. For example, <tt>TAIL</tt>
+    # corresponds to Scide::Commands::Tail, <tt>MY_COMMAND</tt> would
+    # correspond to Scide::Commands::MyCommand.
+    #
+    # <tt>CONTENTS</tt> is the contents of the command.
+    #
+    # ==== Hash Initialization
+    # The following options can be given:
+    # * <tt>:command => string</tt> is the same <tt>COMMAND</tt> as
+    #   for string initialization above.
+    # * <tt>:contents => string or other</tt> is the same <tt>CONTENTS</tt>
+    #   as for string initialization above. Typically this is only a
+    #   string, but more advanced commands might be initialized with
+    #   arrays or hashes.
+    def self.resolve window, contents
       if contents.kind_of? Hash
-        options = options.merge contents[:options] if contents.key? :options
-        properties = properties.merge contents[:properties] if contents.key? :properties
-      end
-      
-      klass, contents = if contents.kind_of? Hash
-        resolve_from_hash contents, properties, options
+        resolve_from_hash window, contents
       elsif contents.kind_of? String
-        resolve_from_string contents, properties, options
+        resolve_from_string window, contents
+      else
+        raise ArgumentError, 'command must be a string or a hash'
       end
-
-      klass.new contents, properties, build_options(options, klass)
     end
 
-    def initialize contents, properties = {}, options = nil
-      @text ||= contents
-      @properties, @options = properties, options
+    # Returns a new command with the given options.
+    #
+    # ==== Arguments
+    # * <tt>contents</tt> - The contents of the command. Typically this
+    #   is only a string, but more advanced commands might be initialized
+    #   with arrays or hashes. By default, the contents can be retrieved
+    #   as a string with #text_with_options.
+    # * <tt>options</tt> - Options that can be used in the string contents
+    #   of the command. See #text_with_options.
+    def initialize contents, options = {}
+
+      # fill text only if it's not already there, in case a subclass does
+      # some initialization work before calling super
+      @text ||= contents.to_s
+
+      # merge given options to the already initialized ones, if any
+      @options = (@options || {}).merge options
     end
 
+    # Returns a representation of this command as a GNU Screen
+    # configuration fragment.
+    #
+    # This default implementation raises an error and must be
+    # overriden by subclasses.
     def to_screen
       raise 'Use a subclass'
     end
 
-    def invalid_config err
-      Scide.fail :invalid_config, "ERROR: #{self.class.name} configuration is invalid.\n   #{err}"
+    # Returns the text of this command with filtered option placeholders.
+    #
+    # ==== Examples
+    #   com_text = 'tail %{tail} -f file.txt -c %{foo}'
+    #   com = Scide::Command.new com_text, :tail => '-n 1000', :foo => 400
+    #   
+    #   com.text_with_options   #=> 'tail -n 1000 -f file.txt -c 400'
+    def text_with_options
+      @text.dup.tap do |s|
+        @options.each_pair do |key, value|
+          s.gsub! /\%\{#{Regexp.escape key}\}/, value.to_s
+        end
+      end
     end
 
     private
 
-    def self.resolve_from_hash contents, properties = {}, options = {}
-      klass = Scide::Commands.const_get contents[:command].downcase.capitalize
-      [ klass, contents[:contents] ]
+    # Returns a new command for the given window. The given
+    # contents are a hash. See Scide::Command.resolve.
+    def self.resolve_from_hash window, contents
+      begin
+        klass = Scide::Commands.const_get contents[:command].downcase.camelize
+        klass.new contents[:contents], window.options.dup
+      rescue NameError => err
+        raise ArgumentError, "unknown '#{contents[:command]}' command type"
+      end
     end
 
-    def self.resolve_from_string contents, properties = {}, options = {}
+    # Returns a new command for the given window. The given
+    # contents are a string. See Scide::Command.resolve.
+    def self.resolve_from_string window, contents
       klass_name, text = contents.split /\s+/, 2
-      klass = Scide::Commands.const_get klass_name.downcase.capitalize
-      [ klass, text ]
-    end
-
-    def self.build_options options, klass
-      klass_name = klass.name.demodulize.downcase
-      current_options = options.try(:[], klass_name)
-      current_klass = klass
-      while current_klass != Scide::Command and current_options.blank?
-        current_klass = current_klass.superclass
-        current_options = options.try(:[], current_klass.name.demodulize.downcase)
+      begin
+        klass = Scide::Commands.const_get klass_name.downcase.camelize
+        klass.new text, window.options.dup
+      rescue NameError => err
+        raise ArgumentError, "unknown '#{klass_name}' command type"
       end
-      current_options
     end
+  end
 
-    def text_with_properties
-      @text.dup.tap do |s|
-        @properties.each_pair do |key, value|
-          s.gsub! /\%\{#{key}\}/, value
-        end
-      end
-    end
+  # Module containing scide command classes.
+  module Commands
   end
 end
 
+# load pre-defined commands
 deps_dir = File.join File.dirname(__FILE__), 'commands'
-%w( run tail show edit ).each{ |dep| require File.join(deps_dir, dep) }
+%w( show run tail edit ).each{ |dep| require File.join(deps_dir, dep) }

data/lib/scide/commands/edit.rb

@@ -2,11 +2,35 @@ module Scide
 
   module Commands
 
+    # Edits a file with the default editor (<tt>$EDITOR</tt>).
+    #
+    # ==== Configuration Example
+    #   # this YAML configuration,
+    #   projects:
+    #     project1:
+    #       options:
+    #         edit: '-c MyVimCommand'
+    #       windows:
+    #         - "window1 EDIT $HOME/fubar.txt"
+    #
+    #   # will produce the following command in window1:
+    #   $EDITOR -c MyVimCommand $HOME/fubar.txt
     class Edit < Scide::Commands::Run
 
-      def initialize contents, properties = {}, options = nil
-        super contents, properties, options
-        @text = [ '$EDITOR', options.to_s, @text.to_s ].select(&:present?).join(' ')
+      # Returns a new edit command.
+      #
+      # See class definition for examples.
+      #
+      # ==== Arguments
+      # * <tt>contents</tt> - The file to edit.
+      # * <tt>options</tt> - Options that can be used in the contents
+      #   of the command.
+      #
+      # ==== Options
+      # * <tt>:edit => string</tt> - Arguments to the editor.
+      def initialize contents, options = {}
+        super contents, options
+        @text = [ '$EDITOR', options[:edit].to_s, @text.to_s ].select(&:present?).join(' ')
       end
     end
   end

data/lib/scide/commands/run.rb

@@ -2,10 +2,23 @@ module Scide
 
   module Commands
     
-    class Run < Scide::Command
+    # Runs a command.
+    #
+    # ==== Configuration Example
+    #   # this YAML configuration,
+    #   projects:
+    #     project1:
+    #       windows:
+    #         - "window1 RUN rails server"
+    #
+    #   # will produce the following command in window1:
+    #   rails server
+    class Run < Scide::Commands::Show
 
-      def to_screen
-        %|stuff "#{text_with_properties}\\012"\n|
+      # Appends a carriage return to the command so that
+      # it will not only be shown but also executed.
+      def text_with_options
+        "#{super}\\012"
       end
     end
   end

data/lib/scide/commands/show.rb

@@ -2,10 +2,31 @@ module Scide
 
   module Commands
     
+    # Prepares and shows a command but do not run it.
+    #
+    # ==== Configuration Example
+    #   # this YAML configuration,
+    #   projects:
+    #     project1:
+    #       options:
+    #         host: 127.0.0.1
+    #       windows:
+    #         - "window1 SHOW ssh %{host}"
+    #
+    #   # will produce the following command in window1:
+    #   ssh 127.0.0.1
     class Show < Scide::Command
 
+      def initialize contents, options = {}
+        super contents, options
+      end
+
+      # Returns a configuration fragment that will put
+      # this command GNU \Screen window without running it.
+      # This will use screen's <tt>stuff</tt> command to
+      # put the text in the window.
       def to_screen
-        %|stuff "#{text_with_properties}"\n|
+        %|stuff "#{text_with_options}"|
       end
     end
   end

data/lib/scide/commands/tail.rb

@@ -2,11 +2,35 @@ module Scide
 
   module Commands
     
+    # Tails a file.
+    #
+    # ==== Configuration Example
+    #   # this YAML configuration,
+    #   projects:
+    #     project1:
+    #       options:
+    #         tail: '-n 1000'
+    #       windows:
+    #         - "window1 TAIL $HOME/fubar.txt"
+    #
+    #   # will produce the following command in window1:
+    #   tail -n 1000 -f $HOME/fubar.txt
     class Tail < Scide::Commands::Run
       
-      def initialize contents, properties = {}, options = nil
-        super contents, properties, options
-        @text = [ 'tail', options.to_s, '-f', @text.to_s ].select(&:present?).join(' ')
+      # Returns a new tail command.
+      #
+      # See class definition for examples.
+      #
+      # ==== Arguments
+      # * <tt>contents</tt> - The file to tail.
+      # * <tt>options</tt> - Options that can be used in the
+      #   contents of the command.
+      #
+      # ==== Options
+      # * <tt>tail => string</tt> - Arguments to tail.
+      def initialize contents, options = {}
+        super contents, options
+        @text = [ 'tail', options[:tail].to_s, '-f', @text.to_s ].select(&:present?).join(' ')
       end
     end
   end

data/lib/scide/config.rb

@@ -1,18 +1,47 @@
 require 'yaml'
 
-CONFIG_FILE = File.join File.expand_path('~'), '.scide', 'config.yml'
-
 module Scide
 
+  # Complete scide configuration as an object graph.
   class Config
+    
+    # The file from which the configuration is normally loaded.
+    # This defaults to <tt>$HOME/.scide/config.yml</tt>.
+    DEFAULT_CONFIG_FILE = File.join File.expand_path('~'), '.scide', 'config.yml'
+
+    # The file from which this configuration will be loaded.
     attr_accessor :file
-    attr_reader :global, :projects, :screen
+    
+    # GNU Screen options. Accessible after calling #load!.
+    attr_reader :screen
 
+    # The global configuration. Accessible after calling #load!.
+    attr_reader :global
+    
+    # The project definitions (windows, option overrides, etc). Accessible
+    # after calling #load!.
+    attr_reader :projects
+
+    # Returns an empty configuration.
+    #
+    # ==== Arguments
+    # * <tt>file</tt> - The file from which to load the configuration. If not
+    #   given, this defaults to DEFAULT_CONFIG_FILE.
     def initialize file = nil
-      @file = file.try(:to_s) || CONFIG_FILE
+      @file = file.try(:to_s) || DEFAULT_CONFIG_FILE
     end
 
-    def load
+    # Loads this configuration. This will read from #file and parse the contents
+    # as YAML. Configuration elements can then be retrieved with #global,
+    # #projects and #screen.
+    #
+    # ==== Errors
+    # * <tt>config_not_found</tt> - #file does not exist.
+    # * <tt>config_not_readable</tt> - #file cannot be read by the user running scide.
+    # * <tt>malformed_config</tt> - #file contains malformed YAML.
+    # * <tt>invalid_config</tt> - #file contains invalid configuration (see README).
+    # * <tt>unexpected</tt> - #file could not be read.
+    def load!
   
       Scide.fail :config_not_found, "ERROR: expected to find configuration at #{@file}" unless File.exists? @file
       Scide.fail :config_not_readable, "ERROR: configuration #{@file} is not readable" unless File.readable? @file
@@ -34,26 +63,27 @@ module Scide
       # laziness
       @config = HashWithIndifferentAccess.new @config
 
+      invalid_config 'screen configuration must be a hash' unless @config[:screen].nil? or @config[:screen].kind_of?(Hash)
+      invalid_config 'projects configuration must be a hash' unless @config[:projects].nil? or @config[:projects].kind_of?(Hash)
+
       begin
-        validate
-      rescue StandardError => err
+        @screen = @config[:screen]
+        @global = Scide::Global.new @config[:global]
+        @projects = @config[:projects].inject(HashWithIndifferentAccess.new) do |memo,obj|
+          memo[obj[0]] = Scide::Project.new @global, obj[0], obj[1]; memo
+        end
+      rescue ArgumentError => err
         invalid_config err
       end
-
-      @global = Scide::Global.new @config[:global]
-      @screen = @config[:screen]
-      @projects = @config[:projects].inject(HashWithIndifferentAccess.new) do |memo,obj|
-        memo[obj[0].to_sym] = Scide::Project.new obj[1], obj[0], @global; memo
-      end
     end
 
-    def validate
-      raise 'global configuration must be a hash' if @config[:global] and !@config[:global].kind_of?(Hash)
-      raise 'configuration must contain a hash of projects' unless @config[:projects].kind_of? Hash
-    end
+    private
 
-    def invalid_config err
-      Scide.fail :invalid_config, "ERROR: configuration #{@file} is invalid.\n   #{err}"
+    # Causes scide to fail with an <tt>invalid_config</tt> error (see Scide#fail).
+    # Builds a complete error message containing the full path to the
+    # configuration file and the given message.
+    def invalid_config msg
+      Scide.fail :invalid_config, "ERROR: configuration #{@file} is invalid.\n   #{msg}"
     end
   end
 end

data/lib/scide/global.rb

@@ -1,13 +1,28 @@
 module Scide
 
+  # Global scide options (base path for all projects,
+  # shared options).
   class Global
-    attr_accessor :path, :properties, :options
+    
+    # The path under which all projects reside by default.
+    # (Can be overriden at the project level.)
+    attr_reader :path
+
+    # Global options shared by all projects.
+    attr_reader :options
   
+    # Builds global options.
+    #
+    # ==== Arguments
+    # * <tt>contents</tt> - The global options hash.
     def initialize contents
-      @properties = contents[:properties]
-      @options = contents[:options]
+      raise ArgumentError, 'global configuration must be a hash' unless contents.kind_of? Hash
+
+      @options = contents[:options] || {}
 
+      # default to home directory
       @path = contents[:path].try(:to_s) || File.expand_path('~')
+      # expand from home directory unless absolute
       @path = File.join File.expand_path('~'), @path unless @path.match /^\//
     end
   end

data/lib/scide/opts.rb

@@ -1,7 +1,10 @@
 module Scide
 
+  # Pre-configured scide option parser.
   class Opts < Upoj::Opts
 
+    # Returns the scide option parser. Run scide with <tt>--usage</tt>
+    # to see available options.
     def initialize
       super({
         :banner => {
@@ -17,6 +20,10 @@ module Scide
       help!.usage!
     end
 
+    # Parses the given arguments.
+    #
+    # Causes scide to fail with an <tt>invalid_argument</tt> error (see Scide#fail)
+    # if an argument is invalid.
     def parse! args
       begin
         super args

data/lib/scide/overmind.rb

@@ -1,27 +1,51 @@
 module Scide
 
+  # Utility class to run scide in a script.
   class Overmind
 
+    # Awakens the overmind.
     def initialize
       @cli = Scide::Opts.new
       @config = Scide::Config.new
     end
 
+    # Parses command-line arguments and loads the configuration file.
+    # Any error will be run through Scide.fail.
     def brood
       @cli.parse! ARGV
       @config.file = @cli.funnel[:config] if @cli.funnel.key? :config
-      @config.load
+      @config.load!
       @initialized = true
       self
     end
 
+    # Runs GNU \Screen with the project given as argument.
+    # The <tt>--dry-run</tt> option will cause scide to print the
+    # resulting configuration instead of running it.
+    #
+    # ==== Errors
+    # * <tt>not_initialized</tt> - If #brood was not called.
+    # * <tt>unknown_project</tt> - If the given project is not found
+    #   in the configuration file.
+    # * <tt>screen_not_found</tt> - If the GNU \Screen binary is not
+    #   found with <tt>which</tt>.
     def dominate
 
-      Scide.fail :not_initialized, 'ERROR: call #brood to initialize' unless @initialized
+      Scide.fail :not_initialized, 'ERROR: call #brood to initialize.' unless @initialized
     
       project_key = ARGV.shift
-      screen = Scide::Screen.new @config, @cli, project_key
-      screen.validate
+      
+      if project_key.blank?
+        available_projects = @config.projects.keys.join(', ')
+        Scide.fail :invalid_argument, "You must choose a project. Available projects: #{available_projects}."
+      end
+
+      unless @config.projects.key? project_key
+        Scide.fail :unknown_project, "ERROR: there is no project '#{project_key}' in configuration #{@config.file}."
+      end
+
+      screen = Scide::Screen.new @config.projects[project_key], @config.screen
+      screen.check_binary
 
       if @cli.funnel[:'dry-run']
         puts

data/lib/scide/project.rb

@@ -1,29 +1,64 @@
 module Scide
 
+  # Scide configuration for one project.
   class Project
-    attr_accessor :properties, :options, :path
 
-    def initialize contents, key, global
-      @global = global
+    # The project key in the projects configuration hash.
+    attr_reader :key
 
+    # The path where the project is located. See #initialize.
+    attr_reader :path
+
+    # Project-specific options. Can be used by commands. See #initialize.
+    attr_reader :options
+
+    # Returns a project configuration.
+    #
+    # If not given in the project hash, #path is built by joining
+    # the global path and <tt>key</tt>.
+    #
+    # ==== Arguments
+    # * <tt>global</tt> - The global configuration.
+    # * <tt>key</tt> - The key identifying the project. This is the
+    #   key in the projects hash.
+    # * <tt>contents</tt> - The project hash.
+    #
+    # ==== Project Options
+    #
+    # #options is built by merging the options given in the project
+    # hash with the global options.
+    #
+    # The following default options are added if not given:
+    # * <tt>name</tt> - Defaults to the project key.
+    # * <tt>path</tt> - The path where the project is located.
+    def initialize global, key, contents
+      raise ArgumentError, "project '#{key}' must be a hash" unless contents.kind_of? Hash
+      raise ArgumentError, "windows of project '#{key}' must be an array" unless contents[:windows].nil? or contents[:windows].kind_of?(Array)
+      raise ArgumentError, "options of project '#{key}' must be a hash" unless contents[:options].nil? or contents[:options].kind_of?(Hash)
+
+      @global, @key = global, key
+
+      # path defaults to project key
       @path = contents[:path].try(:to_s) || key.to_s
+      # expand from home directory if not absolute
       @path = File.join global.path, @path unless @path.match /^\//
 
-      @properties = global.properties.merge(contents[:properties] || {})
-      @properties['name'] ||= key
-
-      @options = global.options.merge(contents[:options] || {})
+      @options = global.options.dup.merge(contents[:options] || {})
+      @options[:name] ||= key
+      @options[:path] ||= @path
 
-      @windows = []
-      contents[:windows].each do |w|
-        @windows << Scide::Window.new(w, self)
-      end
+      @windows = contents[:windows].collect{ |w| Scide::Window.new self, w }
     end
 
+    # Returns a representation of this project as a GNU Screen
+    # configuration fragment. Returns nil if this project has
+    # no configured windows.
     def to_screen
+      return nil if @windows.blank?
       String.new.tap do |s|
         @windows.each_with_index do |w,i|
           s << w.to_screen(i)
+          s << "\n" if i != @windows.length - 1
         end
       end
     end

data/lib/scide/screen.rb

@@ -1,57 +1,91 @@
 require 'tempfile'
 
-DEFAULT_HARDSTATUS = '%{= kG}[ %{G}%H %{g}][%= %{=kw}%?%-Lw%?%{r}(%{W}%n*%f%t%?(%u)%?%{r})%{w}%?%+Lw%?%?%= %{g}][%{B}%Y-%m-%d %{W}%c %{g}]'
-
 module Scide
 
+  # Configuration of a GNU Screen session (windows for a specific project).
+  #
+  # The configuration will disable the startup message and display a hardstatus line.
+  # It will also display the windows of the given project.
   class Screen
+    
+    # The default screen hardstatus line.
+    DEFAULT_HARDSTATUS = '%{= kG}[ %{G}%H %{g}][%= %{=kw}%?%-Lw%?%{r}(%{W}%n*%f%t%?(%u)%?%{r})%{w}%?%+Lw%?%?%= %{g}][%{B}%Y-%m-%d %{W}%c %{g}]'
 
-    def initialize config, cli, project_key
-      @config, @cli = config, cli
+    # Returns a screen configuration for the given project.
+    #
+    # ==== Arguments
+    # * <tt>project</tt> - The project.
+    # * <tt>options</tt> - Screen-specific options (see below).
+    #
+    # ==== Options
+    # * <tt>binary</tt> - Screen binary (defaults to <tt>screen</tt>).
+    # * <tt>args</tt> - Command-line arguments that will be given to screen (e.g. <tt>-U</tt> for unicode).
+    # * <tt>hardstatus</tt> - Hardstatus line configuration (defaults to #DEFAULT_HARDSTATUS).
+    def initialize project, options
+      raise ArgumentError, 'screen configuration must be a hash' unless options.nil? or options.kind_of?(Hash)
 
-      unless @config.projects.key? project_key
-        Scide.fail :unknown_project, "ERROR: there is no project '#{project_key}' in configuration #{@config.file}."
-      end
-      @project = config.projects[project_key]
+      @project = project
+      @options = options || {}
     end
 
+    # Runs screen with this configuration.
+    #
+    # The configuration is saved to a temporary file, then removed.
     def run
       file = Tempfile.new 'scide'
-      save file
+      save file.path
       system to_command(file.path)
       file.unlink
     end
 
+    # Returns the command that will be used to run screen with this configuration.
+    #
+    # ==== Arguments
+    # * <tt>tmp_file</tt> - The temporary file in which the configuration will be stored.
+    #   (Optional for dry-run.)
     def to_command tmp_file = 'TEMPORARY_FILE'
-      "cd #{@project.path} && #{binary} #{options} -c #{tmp_file}"
+      "cd #{@project.path} && #{binary} #{args} -c #{tmp_file}"
     end
 
-    def validate
+    # Verifies that the screen binary is there. If not, causes scide
+    # to fail with a <tt>screen_not_found</tt> error (see Scide#fail}.
+    def check_binary
       Scide.fail :screen_not_found, "ERROR: #{binary} not found" unless system("which #{binary}", { [ :out, :err ] => :close })
     end
 
+    # Returns a representation of this configuration as a string.
     def to_s
       String.new.tap do |s|
         s << "startup_message off\n"
         s << "hardstatus on\n"
         s << "hardstatus alwayslastline\n"
-        s << "hardstatus string '#{DEFAULT_HARDSTATUS}'\n\n"
+        s << "hardstatus string '#{hardstatus}'\n\n"
         s << @project.to_screen
       end
     end
 
     private
 
+    # Returns the screen hardstatus line given as option, or
+    # the default #DEFAULT_HARDSTATUS.
+    def hardstatus
+      @options[:hardstatus] || DEFAULT_HARDSTATUS
+    end
+
+    # Returns the screen binary given as option, or the
+    # default (<tt>screen</tt>).
     def binary
-      @config.screen.try(:[], :binary) || 'screen'
+      @options[:binary] || 'screen'
     end
 
-    def options
-      @config.screen.try(:[], :options)
+    # Returns the screen command-line arguments given as options.
+    def args
+      @options[:args]
     end
 
+    # Saves this configuration to the file at the given path.
     def save file
-      File.open(file.path, 'w'){ |f| f.write to_s }
+      File.open(file, 'w'){ |f| f.write to_s }
     end
   end
 end

data/lib/scide/window.rb

@@ -1,35 +1,80 @@
 module Scide
 
+  # Configuration of a GNU Screen window (name, command).
   class Window
+
+    # Window-specific options. Can be used by commands. See #initialize.
+    attr_reader :options
     
-    def initialize contents, project
+    # Returns a window for the given project.
+    #
+    # ==== Arguments
+    # * <tt>project</tt> - The project owning this window.
+    # * <tt>contents</tt> - The window configuration (String or Hash).
+    #
+    # ==== String Initialization
+    # The string must be in the format <tt>NAME [COMMAND]</tt> where
+    # <tt>NAME</tt> is the window name and <tt>COMMAND</tt> (optional)
+    # is the command configuration (see Scide::Command).
+    #
+    # ==== Hash Initialization
+    # The following options can be given:
+    # * <tt>:name => string</tt> - The window name.
+    # * <tt>:options => hash</tt> - Window-specific options (will be
+    #   merged to the project options).
+    # * <tt>:command => string</tt> - The command to use for this window
+    #   (will be built using Scide::Command#resolve).
+    # * <tt>:string => string</tt> - If given, <tt>:name</tt> and <tt>:command</tt>
+    #   are ignored and string initialization will be performed with <tt>string</tt>.
+    #   <tt>:options</tt> can still be used to override project options.
+    def initialize project, contents
       @project = project
+
       if contents.kind_of? Hash
-        init_from_hash contents
+        init_from_hash! contents
       elsif contents.kind_of? String
-        init_from_string contents
+        init_from_string! contents
+      else
+        raise ArgumentError, "window '#{contents}' must be a string or a hash"
       end
     end
 
+    # Returns a representation of this window as a GNU Screen
+    # configuration frament.
+    #
+    # ==== Arguments
+    # * <tt>index</tt> - The position of the window (zero-based).
     def to_screen index
       String.new.tap do |s|
-        s << "screen -t #{@name} #{index}\n"
-        s << @command.to_screen if @command
+        s << "screen -t #{@name} #{index}"
+        s << "\n#{@command.to_screen}" if @command
       end
     end
 
     private
 
-    def init_from_hash contents
-      @name = contents.delete :name
-      @command = Command.resolve contents, @project.properties, @project.options if contents.key? :command
+    # Initializes this window from a hash. See #initialize for options.
+    def init_from_hash! contents
+      raise ArgumentError, "options of window '#{@name}' must be a hash" unless contents[:options].nil? or contents[:options].kind_of?(Hash)
+      @options = @project.options.dup.merge(contents[:options] || {})
+
+      if contents[:string].present?
+        init_from_string! contents[:string]
+      else
+        raise ArgumentError, "window '#{contents}' must have a name" unless contents[:name].present?
+        @name = contents[:name]
+        @command = Command.resolve self, contents if contents.key? :command
+      end
     end
 
-    def init_from_string contents
+    # Initializes this window from a string. See #initialize for format.
+    def init_from_string! contents
+      raise ArgumentError, "window '#{contents}' must not be an empty string" unless contents.present?
       content_parts = contents.split /\s+/, 2
       @name = content_parts[0]
+      @options ||= @project.options.dup
       if content_parts.length == 2
-        @command = Command.resolve content_parts[1], @project.properties, @project.options
+        @command = Command.resolve self, content_parts[1]
       end
     end
   end

data/lib/scide.rb

@@ -1,26 +1,74 @@
 require 'paint'
 require 'upoj-rb'
 
+# Generator of GNU Screen configuration files.
 module Scide
+
+  # Current version.
   VERSION = File.open(File.join(File.dirname(__FILE__), '..', 'VERSION'), 'r').read
+
+  # Exit status codes.
+  #
+  # ==== Codes
+  # * <tt>unexpected</tt> - 1.
+  # * <tt>invalid_argument</tt> - 2.
+  # * <tt>not_initialized</tt> - 3.
+  # * <tt>screen_not_found</tt> - 4.
+  # * <tt>config_not_found</tt> - 10.
+  # * <tt>config_not_readable</tt> - 11.
+  # * <tt>malformed_config</tt> - 12.
+  # * <tt>invalid_config</tt> - 13.
+  # * <tt>unknown_project</tt> - 14.
   EXIT = {
     :unexpected => 1,
     :invalid_argument => 2,
     :not_initialized => 3,
     :screen_not_found => 4,
-    :config_not_found => 13,
-    :config_not_readable => 14,
-    :malformed_config => 15,
-    :invalid_config => 16,
-    :unknown_project => 17
+    :config_not_found => 10,
+    :config_not_readable => 11,
+    :malformed_config => 12,
+    :invalid_config => 13,
+    :unknown_project => 14
   }
 
+  # Prints a message on <tt>stderr</tt> and exits.
+  # If #condition is a key from #EXIT, the corresponding value
+  # will be used as the exit code. Otherwise, scide exits with
+  # status 1.
   def self.fail condition, msg
-    puts
-    warn Paint[msg, :yellow]
-    puts
-    EXIT.key?(condition) ? exit(EXIT[condition]) : exit(1)
+    if @@exit_on_fail
+      puts
+      warn Paint[msg, :yellow]
+      puts
+      EXIT.key?(condition) ? exit(EXIT[condition]) : exit(1)
+    else
+      raise Scide::Error.new condition, msg
+    end
   end
+
+  # By default, scide is meant to be used as a standalone script
+  # and exits if an error occurs. If <tt>exit_on_fail</tt> is
+  # false, a Scide::Error will be raised instead. Scide can then
+  # be used by another script.
+  def self.exit_on_fail= exit_on_fail
+    @@exit_on_fail = exit_on_fail
+  end
+
+  # Scide error. Can be raised if #exit_on_fail is set to false.
+  class Error < StandardError
+    attr_reader :condition
+
+    # Returns a new error.
+    def initialize condition, msg
+      super msg
+      @condition = condition
+    end
+  end
+
+  private
+
+  @@exit_on_fail = true
 end
 
+# load scide components
 %w( command config global opts overmind project screen window ).each{ |dep| require File.join(File.dirname(__FILE__), 'scide', dep) }

data/scide.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "scide"
-  s.version = "0.0.5"
+  s.version = "0.0.6"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["AlphaHydrae"]
-  s.date = "2011-10-01"
+  s.date = "2011-10-02"
   s.description = "Utility to generate GNU screen configuration files."
   s.email = "hydrae.alpha@gmail.com"
   s.executables = ["scide"]
@@ -42,6 +42,11 @@ Gem::Specification.new do |s|
     "lib/scide/screen.rb",
     "lib/scide/window.rb",
     "scide.gemspec",
+    "spec/command_spec.rb",
+    "spec/commands/edit_spec.rb",
+    "spec/commands/run_spec.rb",
+    "spec/commands/show_spec.rb",
+    "spec/commands/tail_spec.rb",
     "spec/helper.rb"
   ]
   s.homepage = "http://github.com/AlphaHydrae/scide"

data/spec/command_spec.rb

@@ -0,0 +1,87 @@
+require 'helper'
+
+module Scide
+  module Commands
+    class FuBar < Scide::Commands::Show
+    end
+  end
+end
+
+describe Scide::Command do
+
+  it "should be abstract" do
+    com = Scide::Command.new 'fubar'
+    lambda{ com.to_screen }.should raise_error(StandardError)
+  end
+
+  it "should use given contents as text" do
+    com = Scide::Command.new 'fubar'
+    com.text_with_options.should == 'fubar'
+  end
+
+  it "should take options" do
+    com = Scide::Command.new 'fubar %{foo} %{bar}', :foo => 1, :bar => 2
+    com.text_with_options.should == 'fubar 1 2'
+  end
+
+  describe 'Class' do
+    before :each do
+      @options = { :a => 1, :b => true }
+      @window = double('window')
+      @window.stub(:options){ @options }
+    end
+    
+    it "should resolve command with a string" do
+      com = Scide::Command.resolve @window, 'SHOW fubar'
+      com.should be_a_kind_of(Scide::Commands::Show)
+    end
+
+    it "should use second part of string as contents when resolving a command with a string" do
+      com = Scide::Command.resolve @window, 'SHOW fubar'
+      com.text_with_options.should == 'fubar'
+    end
+
+    it "should resolve command with a hash" do
+      com = Scide::Command.resolve @window, :command => 'SHOW', :contents => 'fubar'
+      com.should be_a_kind_of(Scide::Commands::Show)
+    end
+
+    it "should give duplicated window options to the resolved string command" do
+      @window.should_receive :options
+      com = Scide::Command.resolve @window, 'SHOW fubar'
+      com.options.should == @options
+      com.options.should_not equal(@options)
+    end
+
+    it "should give duplicated window options to the resolved hash command" do
+      @window.should_receive :options
+      com = Scide::Command.resolve @window, :command => 'SHOW', :contents => 'fubar'
+      com.options.should == @options
+      com.options.should_not equal(@options)
+    end
+
+    it "should resolve camel-case command class names with a string" do
+      puts Scide::Commands::FuBar
+      com = Scide::Command.resolve @window, 'FU_BAR'
+      com.should be_a_kind_of(Scide::Commands::FuBar)
+    end
+
+    it "should resolve camel-case command class names with a hash" do
+      com = Scide::Command.resolve @window, :command => 'FU_BAR'
+      com.should be_a_kind_of(Scide::Commands::FuBar)
+    end
+
+    it "should raise an error when type of contents is unknown" do
+      lambda{ Scide::Command.resolve(@window, []) }.should raise_error(ArgumentError)
+    end
+
+    it "should raise an error when trying to resolve a blank string" do
+      lambda{ Scide::Command.resolve(@window, '   ') }.should raise_error(ArgumentError)
+    end
+
+    it "should raise an error when trying to resolve an unknown command" do
+      lambda{ Scide::Command.resolve(@window, 'SHW fubar') }.should raise_error(ArgumentError)
+      lambda{ Scide::Command.resolve(@window, :command => 'SHW', :contents => 'fubar') }.should raise_error(ArgumentError)
+    end
+  end
+end

data/spec/commands/edit_spec.rb

@@ -0,0 +1,19 @@
+require 'helper'
+
+describe Scide::Commands::Edit do
+
+  it "should use the preferred editor" do
+    com = Scide::Commands::Edit.new nil
+    com.text_with_options.should == '$EDITOR\012'
+  end
+
+  it "should use given contents as arguments to the editor" do
+    com = Scide::Commands::Edit.new 'fubar'
+    com.text_with_options.should == '$EDITOR fubar\012'
+  end
+
+  it "should use the :edit option as arguments to the editor" do
+    com = Scide::Commands::Edit.new 'fubar', :edit => '-c MyCommand'
+    com.text_with_options.should == '$EDITOR -c MyCommand fubar\012'
+  end
+end

data/spec/commands/run_spec.rb

@@ -0,0 +1,9 @@
+require 'helper'
+
+describe Scide::Commands::Run do
+
+  it "should use given contents and a carriage return as text" do
+    com = Scide::Commands::Run.new 'fubar'
+    com.text_with_options.should == 'fubar\012'
+  end
+end

data/spec/commands/show_spec.rb

@@ -0,0 +1,15 @@
+require 'helper'
+
+describe Scide::Commands::Show do
+
+  it "should produce a GNU Screen stuff command" do
+    com = Scide::Commands::Show.new 'fubar'
+    com.to_screen.should == 'stuff "fubar"'
+  end
+
+  it "should use #text_with_options as argument to stuff" do
+    com = Scide::Commands::Show.new 'fubar'
+    text_with_options = com.text_with_options
+    com.to_screen.should == %|stuff "#{text_with_options}"|
+  end
+end

data/spec/commands/tail_spec.rb

@@ -0,0 +1,14 @@
+require 'helper'
+
+describe Scide::Commands::Tail do
+
+  it "should use given contents as argument -f of tail" do
+    com = Scide::Commands::Tail.new 'fubar'
+    com.text_with_options.should == 'tail -f fubar\012'
+  end
+
+  it "should use the :tail option as arguments to tail" do
+    com = Scide::Commands::Tail.new 'fubar', :tail => '-n 1000'
+    com.text_with_options.should == 'tail -n 1000 -f fubar\012'
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scide
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-10-01 00:00:00.000000000Z
+date: 2011-10-02 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: upoj-rb
-  requirement: &2157494940 !ruby/object:Gem::Requirement
+  requirement: &2156558600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 0.0.4
   type: :runtime
   prerelease: false
-  version_requirements: *2157494940
+  version_requirements: *2156558600
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2157494400 !ruby/object:Gem::Requirement
+  requirement: &2156558080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2157494400
+  version_requirements: *2156558080
 - !ruby/object:Gem::Dependency
   name: shoulda
-  requirement: &2157493840 !ruby/object:Gem::Requirement
+  requirement: &2156557480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2157493840
+  version_requirements: *2156557480
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2157493320 !ruby/object:Gem::Requirement
+  requirement: &2156556880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *2157493320
+  version_requirements: *2156556880
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &2157486420 !ruby/object:Gem::Requirement
+  requirement: &2156556280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,10 +65,10 @@ dependencies:
         version: 1.6.4
   type: :development
   prerelease: false
-  version_requirements: *2157486420
+  version_requirements: *2156556280
 - !ruby/object:Gem::Dependency
   name: rcov
-  requirement: &2157485920 !ruby/object:Gem::Requirement
+  requirement: &2156555680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2157485920
+  version_requirements: *2156555680
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &2157485140 !ruby/object:Gem::Requirement
+  requirement: &2156555080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,7 +87,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2157485140
+  version_requirements: *2156555080
 description: Utility to generate GNU screen configuration files.
 email: hydrae.alpha@gmail.com
 executables:
@@ -121,6 +121,11 @@ files:
 - lib/scide/screen.rb
 - lib/scide/window.rb
 - scide.gemspec
+- spec/command_spec.rb
+- spec/commands/edit_spec.rb
+- spec/commands/run_spec.rb
+- spec/commands/show_spec.rb
+- spec/commands/tail_spec.rb
 - spec/helper.rb
 homepage: http://github.com/AlphaHydrae/scide
 licenses:
@@ -137,7 +142,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 4252834099400613658
+      hash: 1145488263121204374
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: