spackle 0.0.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Rick Lee-Morlang
+
+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.

data/README.rdoc

@@ -0,0 +1,166 @@
+= Spackle
+
+<em>Smoothing out the gaps between the Rubyist and the Ruby.</em>
+
+Well, honestly, it only fills in the gaps between RSpec and Vim right now,
+but that's a good start. Cucumber support is in the works, and perhaps a
+few other surprises if I make the time.
+
+Patches supporting other editors gladly accepted. Most people aren't very 
+editor-agnostic, but Spackle doesn't care! (Or, at least, it wouldn't if
+you patched it with support for your amazing editor that's surely better
+than mine.)
+
+== Elevator Pitch
+
+Spackle tells your editor about the errors in your code. No more need to 
+visually scan your test output for errors, filenames, and line numbers.
+Just tell your editor to jump to the next error location.
+
+== Features
+
+* custom RSpec formatters that generate output compatible with 
+  Vim's quickfix functionality
+* a simple Vim plugin to allow a quickfix list to be loaded 
+  from a file
+* shell scripts to glue Spackle's output and Vim together
+* easy to use?
+
+== Quick Installation
+
+  gem install spackle --source http://gemcutter.org
+  spackle --install vim  # described below
+  echo 'Spackle.configuration.set_defaults_for :vim' > ~/.spackle
+
+== Configuration and Usage
+
+For a tool that doesn't do a heck of alot, it's pretty configurable.
+If it <b>could</b> do something else, it'd be easy to tell it how to do
+it with either a <tt>.spackle</tt> file in your home directory, or a 
+<tt>.spackle</tt> file in your project's root directory. 
+
+If Spackle is useful to you, I'd love to hear about it.
+
+=== PATH
+
+Spackle installs a few utility scripts in the bin directory where
+executables are installed by your system's Rubygems. If you've installed
+Spackle as root, this should be fine. If you've installed Spackle as a
+regular user, you need to make sure the appropriate bin directory is
+in your path. 
+
+To test your configuration, run +which spackle+ in your terminal. If
+you don't see any output, your PATH variable is not correctly configured
+for use with user-installed gems.
+
+See your Rubygems documentation for more information about this.
+
+=== Spackle dotfile
+
+Without a dotfile configured, Spackle won't do anything. This is so
+you can make Spackle a dependency of your project and integrate it
+into your code, yet leave its usage up to each individual developer.
+
+Spackle reads its configuration from a <tt>.spackle</tt> file, which it looks
+for in your home directory first, and in the root directory of your
+project second. Spackle configuration in your project directory takes
+precedence over any in your home directory, so you can override global
+settings on a per-project basis if you like.
+
+Example <tt>.spackle</tt> for Vim users.
+
+  Spackle.configure do |c|
+    c.set_defaults_for :vim
+  end
+
+See Spackle::Configuration for more information.
+
+=== RSpec
+
+Add to your spec_helper.rb:
+
+  require "spackle"
+  Spackle.init :with => :spec_formatter
+
+Now whenever RSpec runs, Spackle will listen in to your test results and
+relay information about any errors to your editor.
+
+=== Vim 
+
+Spackle needs a tiny Vim plugin installed to function properly with Vim.
+Simply run +spackle install vim+ and Spackle will copy its plugin into
+your <tt>.vim/plugins</tt> directory.
+
+<b>Optional:</b>
+Spackle also comes with a helper script for invoking Vim with a session
+named after your project's parent directory. It's called <tt>spackle-vim-open</tt>. 
+If you'd like to use it, you'll probably want to add an alias to your 
+<tt>.profile</tt> or <tt>.bashrc</tt>. Example:
+
+  alias e='spackle-vim-open'
+
+== Architecture
+
+Spackle's architecture consists of three components. 
+
+NOTE: Some of this information looks forward to a future version of Spackle
+that, at the moment, is fictional. So if you go looking for some of the things
+referenced here and you can't find them, that's probably why. (Or it could be
+an error in this document!)
+
+Error Parser Adapters
+* integrate with test harnesses like RSpec and Cucumber
+* or integrate with Ruby's standard Error API
+* or parse Ruby's standard backtrace output
+* convert error output into a generic intermediary Spackle::Error format
+* pass the errors to Spackle's core for reformatting and output
+* found in Spackle::Spec, Spackle::Cucumber and Spackle::Ruby
+ 
+Spackle Core
+* glues all the pieces together
+* loads user configuration 
+* tries to do as much as it can automagically
+* tries to stay out of your way
+* routes Spackle::Error objects from the Adapters, through an 
+  Output Formatter, and finally to an output file
+* triggers a callback after every test run that can send error
+  information to your editor
+
+Output Formatters
+* convert the generic Error format into an output-specific format
+  for your callback to handle
+* found in Spackle::Output
+
+Spackle's core configuration, tries to do as much automagically as it can, 
+and tries to stay out of the way. It aids the models by routing Errors to the
+configured output formatter.
+
+== Known Issues
+
+* Spackle assumes you're using something UNIXy. If you're not, it likely 
+  won't work. I have no interest in working on this, but I'll gladly 
+  pull your patches.
+* Spackle's current implementation only catches test failures from RSpec.
+  Other hooks are in the works.
+
+== Credits
+
+Spackle was inspired by https://wincent.com/blog/running-rspec-specs-from-inside-vim
+
+== Note on Patches/Pull Requests
+
+This section was generated by Jeweler's boilerplate, but it seems 
+pretty sensible.
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but
+  bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2009 Rick Lee-Morlang. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "spackle"
+    gem.summary = %Q{Spackle tells your editor about the errors in your code}
+    gem.description = %Q{
+Spackle tells your editor about the errors in your code. No more need to 
+visually scan your test output for errors, filenames, and line numbers.
+Just tell your editor to jump to the next error location.
+		}
+    gem.email = "rick@lee-morlang.com"
+    gem.homepage = "http://github.com/rleemorlang/spackle"
+    gem.authors = ["Rick Lee-Morlang"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "spackle #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/bin/ruby-project-root

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+spackle_dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(spackle_dir) unless $LOAD_PATH.include?(spackle_dir)
+
+require 'spackle/helpers/ruby_project_root'
+
+project_root = Spackle::Helpers::RubyProjectRoot.search Dir.pwd
+
+if project_root.nil?
+  exit 1
+else
+  puts project_root
+end
+

data/bin/spackle

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+spackle_dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(spackle_dir) unless $LOAD_PATH.include?(spackle_dir)
+
+require 'spackle'
+require 'spackle/commandline'
+
+begin
+  Spackle::Commandline.parse ARGV
+rescue => err
+  STDERR.puts err.message 
+  exit 1
+end
+

data/bin/spackle-vim-load-quickfix

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+spackle_dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(spackle_dir) unless $LOAD_PATH.include?(spackle_dir)
+
+require 'spackle/helpers/ruby_project_root'
+
+# Load a Vim Quickfix file in an active vim session.
+#
+# Usage:
+# spackle-vim-load-quickfix [servername] quickfix_file
+#
+# If servername is specified, try to use it as the vim
+# server. Otherwise, assume the name for the vim server
+# is the from ruby-project-root -basename, if
+# successful. If no Ruby project root was found, use
+# DEFAULT as the servername.
+#
+# If the server doesn't exist, we'll create a new
+# gvim session.
+#
+
+def servername_from_arguments
+  ARGV.shift if ARGV.count == 2
+end
+
+def servername_from_project_root
+  project_root = Spackle::Helpers::RubyProjectRoot.search Dir.pwd
+  File.basename(project_root) if project_root
+end
+
+def servername
+  @servername ||= servername_from_arguments || servername_from_project_root || "DEFAULT"
+end
+
+def server_running?
+  !`gvim --serverlist`.grep(/#{servername}/i).empty?
+end
+
+unless server_running?
+  system %{gvim --servername #{servername}}
+  sleep 1
+end
+
+system %{gvim --servername #{servername} --remote-send "<ESC>" &> /dev/null}
+system %{gvim --servername #{servername} --remote-expr "LoadSpackleQuickfix('#{ARGV.first}')" &> /dev/null}
+system %{gvim --servername #{servername} --remote-send "<ESC><C-W>p" &> /dev/null}
+

data/bin/spackle-vim-open

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+spackle_dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(spackle_dir) unless $LOAD_PATH.include?(spackle_dir)
+
+require 'spackle/helpers/ruby_project_root'
+
+# Load a Vim Quickfix file in an active vim session.
+#
+# Usage:
+# spackle-vim-load-quickfix [servername] quickfix_file
+#
+# If servername is specified, try to use it as the vim
+# server. Otherwise, assume the name for the vim server
+# is the from ruby-project-root -basename, if
+# successful. If no Ruby project root was found, use
+# DEFAULT as the servername.
+#
+# If the server doesn't exist, we'll create a new
+# gvim session.
+#
+
+def servername_from_arguments
+  ARGV.count.times do |index|
+    if ARGV[index] == "--servername"
+      ARGV.delete_at index
+      return ARGV.delete_at_index
+    end
+  end
+  nil
+end
+
+def servername_from_project_root
+  project_root = Spackle::Helpers::RubyProjectRoot.search Dir.pwd
+  File.basename(project_root) if project_root
+end
+
+def servername
+  servername_from_arguments || servername_from_project_root || "DEFAULT"
+end
+
+def arguments
+  arguments = ['gvim', '--servername', servername]
+  unless ARGV.empty?
+    arguments << "--remote-silent"
+    arguments += ARGV
+  end
+end
+  
+system *arguments

data/lib/spackle/commandline.rb

@@ -0,0 +1,53 @@
+require 'optparse'
+require 'fileutils'
+
+
+module Spackle
+  class Commandline
+    class << self
+      def install(mod)
+        case mod.to_sym
+        when :vim
+          src = File.join(File.dirname(__FILE__), "/../../support/vim/spackle.vim")
+          dest = File.expand_path "~/.vim/plugin"
+          raise "No such directory #{dest} -- cannot install Vim plugin" unless File.directory?(dest)
+          FileUtils.copy src, dest
+          puts "spackle.vim installed in #{dest}"
+        else
+          raise "Unrecognized module '#{mod}' -- cannot install"
+        end
+      end
+
+      def show_error(message)
+        puts message
+      end
+
+      def parse(options)
+        opts = OptionParser.new do |opts|
+          opts.banner = "Usage: spackle --install vim\n" +
+                        "       spackle [rubyscript] [args_for_script]"
+
+          opts.separator " "
+          opts.separator "Options:"
+
+          opts.on("-i", "--install MODULE", "Install a Spackle module.", "Choices: vim") do |mod|
+            install(mod)
+          end
+
+          opts.on("-h", "--help", "-?", "this help screen") do 
+            puts opts
+            exit
+          end
+        end
+
+        if options.empty?
+          puts opts
+        else
+          opts.parse!(options)
+        end
+
+        raise "Spackle's wrapper mode is not yet implement" unless options.empty?
+      end
+    end
+  end
+end

data/lib/spackle/configuration.rb

@@ -0,0 +1,37 @@
+module Spackle
+  class Configuration
+    # The command to invoke when Spackle finds errors. It will receive
+    # a single argument, being the path to the Spackle errors file.
+    # If left unspecified, no command is invoked.
+    attr_accessor :callback_command
+
+    # Where to store the Spackle error files. If unspecified, Spackle will
+    # default to /tmp
+    attr_accessor :tempdir
+
+    # Which ErrorFormatter class to use when formatting errors. Specified
+    # as a symbol or string matching a class in spackle/error_formatters.
+    # i.e. config.error_formatter = :vim_quickfix
+    attr_accessor :error_formatter
+
+    # Filename to use when writing the formatted Spackle results. If 
+    # unspecified, defaults to a filename based on the name of your 
+    # project's root directory, or "default.spackle" it can't figure out
+    # where your root directory is
+    attr_accessor :spackle_file
+
+    # Configure Spackle with defaults. Currently only accepts :vim as an
+    # argument.
+    def set_defaults_for(mode)
+      case mode.to_sym
+      when :vim
+        self.callback_command = "spackle-vim-load-quickfix"
+        self.error_formatter  = :vim_quickfix
+      else
+        raise ArgumentError.new("unknown Spackle mode: '#{mode}'")
+      end
+    end
+
+
+  end
+end

data/lib/spackle/error.rb

@@ -0,0 +1,31 @@
+module Spackle
+  class BacktraceEntry
+    attr_reader :file, :line
+    def initialize(file, line)
+      @file, @line = file, line
+    end
+  end
+
+  class Error
+    attr_reader :message, :backtrace
+
+    def initialize(message)
+      @message = message
+      @backtrace = []
+      yield self if block_given?
+    end
+
+    def add_error(error_or_file, line = nil)
+      case error_or_file
+      when Error
+        @backtrace << error_or_file
+      when String
+        @backtrace << BacktraceEntry.new(error_or_file, line)
+      else
+        raise ArgumentError.new("unrecognized error input '#{error_or_file}'. Should be a filename or a Spackle::BacktraceEntry")
+      end
+    end
+
+  end
+end
+

data/lib/spackle/helpers/ruby_project_root.rb

@@ -0,0 +1,34 @@
+module Spackle
+  module Helpers
+    module RubyProjectRoot
+      class << self
+        # Search recursively from the current working directory up for something
+        # that looks like the root directory of a Ruby project.
+        #
+        # Returns the path to the found project dir, if any. Nil otherwise.
+        #
+        # Stops looking when it reaches the top of the tree, or the user's
+        # home directory.
+        #
+        # Detects a project dir via any of:
+        #  * a config/environment.rb file
+        #  * a spec/spec_helper.rb file
+        #  * a features/step_definitions directory
+        def search(directory)
+          directory = File.expand_path(directory)
+          while directory != '/'
+            return directory if is_project_dir?(directory)
+            directory = File.expand_path(directory + '/..')
+          end
+          nil
+        end
+
+        def is_project_dir?(path)
+          File.exists?(File.join(path, "config/environment.rb")) ||
+            File.exists?(File.join(path, "spec/spec_helper.rb")) ||
+            File.directory?(File.join(path, "features/step_definitions"))
+        end
+      end
+    end
+  end
+end

data/lib/spackle/output/base.rb

@@ -0,0 +1,44 @@
+module Spackle::Output
+  # This is the foundation of all Spackle::Output classes, but by itself
+  # it does nothing.
+  #
+  # Using an Output class should be simple:
+  # (assuming errors is an Array of Spackle::Error objects)
+  # puts Spackle::Output::VimQuickfix.format(errors)
+  #
+  # The child class (VimQuickfix) only needs to implement the
+  # format_backtrace instance method.
+  #
+  # Spackle::Output::Base is responsible for things like:
+  # * iterating over the backtrace collection
+  # * making pathnames relative
+  # * limiting the number of errors that are output
+  # * filtering the backtrace output by filename
+  #
+  # Spackle::Output::Base interacts with Spackle's Configuration
+  #
+  # If you're writing your own Output class, it should be quite
+  # easy to override some of the Configuration handling if your
+  # class requires it.
+  #
+  class Base
+    attr_accessor :error
+    def initialize(error = nil)
+      self.error = error || Spackle.current_error
+    end
+
+    def formatted_lines
+      error.backtrace.map do |bt|
+        format_backtrace_line error.message, bt.file, bt.line
+      end
+    end
+
+    def format    
+      formatted_lines.join("\n") + "\n"
+    end
+
+    def self.format(error = nil)
+      new(error || Spackle.current_error).format
+    end
+  end
+end

data/lib/spackle/output/vim_quickfix.rb

@@ -0,0 +1,7 @@
+module Spackle::Output
+  class VimQuickfix < Base
+    def format_backtrace_line(message, file, line)
+      "%s:%d: %s" % [ file, line.to_i, message.gsub(/\n/, ' ') ] 
+    end
+  end
+end

data/lib/spackle/output.rb

@@ -0,0 +1,2 @@
+require 'spackle/output/base'
+require 'spackle/output/vim_quickfix'

data/lib/spackle/spec/base_formatter.rb

@@ -0,0 +1,22 @@
+require 'spec/runner/formatter/base_formatter'
+
+# This is just a slightly-refactored and cut down version of RSpec's 
+# BaseTextFormatter.
+
+module Spackle::Spec
+  class BaseFormatter < ::Spec::Runner::Formatter::BaseFormatter
+    attr_reader :output, :options
+    attr_accessor :errors
+
+    def initialize(options, output)
+      # we ignore output, for now
+      Spackle.init
+      @options = options
+      self.errors = []
+    end
+
+    def close      
+      Spackle.test_finished errors
+    end
+  end
+end

data/lib/spackle/spec/spackle_formatter.rb

@@ -0,0 +1,14 @@
+require 'spackle/spec/base_formatter'
+
+module Spackle::Spec
+  class SpackleFormatter < BaseFormatter
+    def example_failed(example, counter, failure)
+      error = Spackle::Error.new failure.exception.message 
+      failure.exception.backtrace.each do |frame|
+        file, line = frame.match(/^([^:]+):([0-9]+)/)[1,2]
+        error.add_error file, line 
+      end
+      self.errors << error
+    end
+  end
+end

data/lib/spackle/spec.rb

@@ -0,0 +1 @@
+require 'spackle/spec/spackle_formatter'