capit 0.2.0 → 0.2.1

data/.gitignore

@@ -4,5 +4,6 @@ Gemfile.lock
 pkg/*
 doc/*
 coverage/*
+tmp/*
 .yardoc
 .DS_STORE

data/.rvmrc

@@ -0,0 +1 @@
+rvm ruby-1.9.2

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "CapIt Documentation" --protected

data/Gemfile

@@ -4,6 +4,8 @@ source "http://rubygems.org"
 
 group :test do
   gem 'rspec', '~> 2.5.0'
+  gem 'yard', '~> 0.6.5'
+  
   gem 'simplecov', '~> 0.4.0', :require => false
   gem 'guard', '~> 0.3.0'
   gem 'growl', '~> 1.0.3'

data/README.md

@@ -33,10 +33,5 @@ Usage
     require 'capit'
     capit = CapIt::Capture("http://www.github.com")
 
-Notes
------
-Don't use this yet.
-
 [1]: http://cutycapt.sourceforge.net/ "CutyCapt"
 [2]: http://daveelkins.com/2009/04/10/setting-up-headless-xserver-and-cutycapt-on-ubuntu/ "Setting up Headless XServer and CutyCapt on Ubuntu"
-

data/Rakefile

@@ -5,4 +5,10 @@ require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
 task :test    => :spec
-task :default => :spec
+task :default => :spec
+
+require 'yard'
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb']
+end

data/capit.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Ezekiel Templin"]
   s.email       = ["ezkl@me.com"]
-  s.date        = %q{2011-03-26}
+  s.date        = %q{2011-03-27}
   s.homepage    = "http://github.com/meadvillerb/capit"
   s.summary     = %q{Easy screen captures with the help of CutyCapt}
   s.description = %q{CapIt provides a simple Ruby interface to Björn Höhrmann's CutyCapt.}

data/lib/capit/capture.rb

@@ -13,6 +13,15 @@ module CapIt
     end
   end
   
+  # This class provides the screen capture functionality.
+  #
+  # @example
+  #   capit = CapIt::Capture.new("http://mdvlrb.com", :filename => "mdvlrb.png")
+  #   capit.max_wait = 5000
+  #   capit.folder = "/home/user/screenshots"
+  #   capit.capture
+  #   capit.output = "/home/user/screenshots/mdvlrb.png"
+  #
   class Capture
     
     # All extensions CutyCapt can use to infer format of output
@@ -21,22 +30,25 @@ module CapIt
     # The URL of the page to be captured
     attr_reader   :url
     
-    
-    attr_accessor :folder, :filename, :user_agent, :max_wait, 
-                  :delay, :output
+    attr_accessor :folder, :filename, :user_agent, :max_wait, :delay, :output
     
     # Initialize a new Capture
+    # @param [String] url The URL we want to capture.
+    # @param [Hash] options Various options we can set.
     #
-    # @example
-    #   capit = CapIt::Capture.new("http://mdvlrb.com", :filename => "mdvlrb.png")
-    #   capit.max_wait = 5000
-    #   capit.folder = "/home/user/screenshots"
+    # @return [Object]
+    #
+    # @see CapIt::Capture#cutycapt_installed?
+    # @see CapIt::Capture#valid_extension?
+    #
+    # @raise CutyCaptError
+    # @raise InvalidExtensionError
     #
     def initialize url, options = {}
       cutycapt_installed?
       @url        = url              
       @folder     = options[:folder] || Dir.pwd
-      @filename   = options[:filename] || "capit.jpg"
+      @filename   = options[:filename] || "capit.jpeg"
       @user_agent = options[:user_agent] || "CapIt! [http://github.com/meadvillerb/capit]"
       @max_wait   = options[:max_wait] || 15000
       @delay      = options[:delay]
@@ -52,27 +64,36 @@ module CapIt
     #
     # @return [String, false]
     # 
+    # @see CapIt::Capture#successful? 
+    #
     def capture      
       `#{capture_command}`
       successful?
     end
     
+    # Overloads #filename= to ensure that filenames have valid extensions.
+    #
+    # @param [String] filename
+    # @see CapIt::Capture#valid_extension?
+    # 
     def filename=(filename)
       valid_extension?(filename)
       @filename = filename 
     end
     
+    # Compares filename against EXTENSIONS. Raises InvalidExtensionError if the extension is invalid.
+    # 
+    # @param [String] filename
+    #
     def valid_extension?(filename)
-      unless !filename[EXTENSIONS].nil?
-        raise InvalidExtensionError, "You must supply a valid extension!"
-      end
+      raise InvalidExtensionError, "You must supply a valid extension!" if filename[EXTENSIONS].nil?
     end
   
     # Determines whether the capture was successful
     # by checking for the existence of the output file.
-    # Sets {@output} if true.
+    # Sets CapIt::Capture#output if true.
     #
-    # @return [true, false]
+    # @return [String, false]
     #
     def successful?
       if FileTest.exists?("#{@folder}/#{@filename}")
@@ -85,8 +106,7 @@ module CapIt
     # @return [String]
     #
     def capture_command        
-      cmd = "CutyCapt"
-      cmd += " --url='#{@url}'"
+      cmd = "CutyCapt --url='#{@url}'"
       cmd += " --out='#{@folder}/#{@filename}'"
       cmd += " --max-wait=#{@max_wait}"
       cmd += " --delay=#{@delay}" if @delay
@@ -104,6 +124,7 @@ module CapIt
     # Not foolproof, but good enough for the time being.
     # 
     # @return [Symbol]
+    # @raise [InvalidOSError]
     # 
     def determine_os
       case RUBY_PLATFORM
@@ -113,6 +134,11 @@ module CapIt
       end
     end
     
+    # Checks to see if CutyCapt is available in PATH.
+    # Raises CutyCaptError if not.
+    # 
+    # @return
+    # 
     def cutycapt_installed?
       raise CutyCaptError, "CutyCapt must be installed and available on PATH" if `which CutyCapt`.empty?
     end

data/lib/capit/version.rb

@@ -5,5 +5,5 @@ module CapIt
   # 
   # The version number
   # 
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/spec/capit/capture_spec.rb

@@ -1,92 +1,95 @@
 # encoding: UTF-8
 require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
 
-describe CapIt::Capture do  
-  describe "Convenience Method" do
-    it "should have a Convenience Method" do
-      @folder = Dir.pwd + '/spec/temporary'
-      `mkdir #{@folder}`
-      @capit = CapIt::Capture("http://mdvlrb.com/", :filename => 'mdvlrb.png', :folder => @folder).should == @folder + "/mdvlrb.png"
-      `rm -rf #{@folder}`
-    end
+describe CapIt do  
+  it "should have a Convenience Method" do
+    @folder = setup_temporary_folder
+    @capit = CapIt::Capture("http://mdvlrb.com/", :filename => 'mdvlrb.png', :folder => @folder).should == @folder + "/mdvlrb.png"
+    destroy_temporary_folder(@folder)
   end
-  
-  describe "Capture Class" do
-    subject { CapIt::Capture.new("http://mdvlrb.com/", :filename => 'mdvlrb.png') }
+    
+  describe CapIt::Capture do
+    before { @capit = CapIt::Capture.new("http://mdvlrb.com/") }
+    subject { @capit }
     
     describe "#initialize" do
-      it "should have defaults" do
-        subject.folder.should == Dir.pwd
-        subject.filename.should == "mdvlrb.png"
-        subject.user_agent.should == "CapIt! [http://github.com/meadvillerb/capit]"
-        subject.max_wait.should == 15000
+      it { should respond_to :url, :folder, :filename, :user_agent, :max_wait, :delay }
+      
+      context "defaults" do
+        specify { @capit.folder.should == Dir.pwd }
+        specify { @capit.filename.should == "capit.jpeg" }
+        specify { @capit.user_agent.should == "CapIt! [http://github.com/meadvillerb/capit]" }
+        specify { @capit.max_wait.should == 15000 }
       end
-
-      it "should respond to input" do
-        subject.should respond_to :url, :folder, :filename, :user_agent, :max_wait, :delay
+    end
+    
+    describe ":filename" do
+      context "when valid" do
+        before { @capit.filename = "mdvlrb.png" }
+        specify { @capit.filename.should == "mdvlrb.png" }
       end
       
-      it "should allow filename to be changed if extension is valid" do
-        @capit = CapIt::Capture.new("http://mdvlrb.com/")
-        @capit.filename = "mdvlrb.png"
-        @capit.filename.should == "mdvlrb.png"
+      context "when invalid" do
+        it "should raise an error" do
+          expect { @capit.filename = "capit.foo" }.to raise_error(/valid extension/)
+        end
       end
     end
     
+    
     describe "#capture" do
       before(:all) do
-        @folder = Dir.pwd + '/spec/temporary'
-        @capit = CapIt::Capture.new("http://mdvlrb.com/", :filename => 'mdvlrb.jpeg', :folder => @folder)
-        `mkdir #{@folder}`
-      end
-      
-      it "should return the full path to the screenshot" do
-        @capit.capture.should == @folder + "/mdvlrb.jpeg"
+        @folder = setup_temporary_folder
+        @capture = CapIt::Capture.new("http://mdvlrb.com", :folder => @folder)
       end
-      
-      it "should capture the proper screenshot" do
-        @capit.output.should == @folder + "/mdvlrb.jpeg"
+
+      context "when screen capture is successful" do
+        specify { @capture.capture.should == @folder + "/capit.jpeg" }
+        specify { @capture.output.should == @folder + "/capit.jpeg" }
       end
-      
+            
       after(:all) do
-        `rm -rf #{@folder}`
+        destroy_temporary_folder(@folder)
       end
     end
     
     describe "#capture_command" do
-      it "should prefix xvfb when platform is Linux" do
-        @capit = CapIt::Capture.new("http://mdvlrb.com/")
-        RUBY_PLATFORM = "linux"
-        @capit.capture_command.should match /^xvfb/
-      end
-      
-      it "shouldn't prefix anything when platform is Mac" do
-        @capit = CapIt::Capture.new("http://mdvlrb.com/")
-        RUBY_PLATFORM = "darwin"
-        @capit.capture_command.should match /^CutyCapt/
+      before { @capit = CapIt::Capture.new("http://mdvlrb.com/") }
+      subject { @capit }
+    
+      context "when platform is Linux" do
+        it "should add the xvfb prefix" do
+          with_constants :RUBY_PLATFORM => "linux" do
+            @capit.capture_command.should match /^xvfb/
+          end
+        end
       end
-      
+    
+      context "when platform is Mac" do
+        it "should not add the xvfb prefix" do
+          with_constants :RUBY_PLATFORM => "darwin" do 
+            @capit.capture_command.should match /^CutyCapt/
+          end
+        end
+      end  
     end
     
-    describe "Errors" do
-      
-      it "should raise an error if CutyCapt isn't available" do
-        path = ENV['PATH']
-        expect { ENV['PATH'] = ""; CapIt::Capture.new("http://mdvlrb.com/") }.to raise_error(/CutyCapt/)
-        ENV['PATH'] = path
+    describe "Fatal Errors" do
+      context "when platform is unknown" do
+        it "should raise an error" do
+          with_constants :RUBY_PLATFORM => "mingw" do
+           expect { @capit.determine_os }.should raise_error(/platforms/)
+          end
+        end
       end
-      
-      it "should raise an error if OS isn't Linux or Mac" do
-        RUBY_PLATFORM = "mingw"
-        expect { subject.determine_os }.to raise_error(/platforms/)
-        RUBY_PLATFORM = "darwin"
-      end
-      
-      it "should not accept filenames without a valid extension" do
-        expect { CapIt::Capture.new("http://mdvlrb.com/", :filename => 'capit.foo') }.to raise_error(/valid extension/)
-        expect { subject.filename = "capit.foo" }.to raise_error(/valid extension/)
+
+      context "when CutyCapt executable is unavailable" do
+        it "should raise an error" do
+          with_environment_variable 'PATH' => "" do
+            expect { CapIt::Capture.new("http://mdvlrb.com/") }.to raise_error(/CutyCapt/)
+          end
+        end
       end
-    end
-    
+    end    
   end
 end

data/spec/capit_spec.rb

@@ -2,9 +2,8 @@
 require 'spec_helper'
 
 describe CapIt do
-  describe "Basic Module" do
-    it "should have a VERSION" do
-      CapIt::VERSION.should_not be_nil
-    end    
-  end
+  context "Constants" do
+    subject { CapIt::VERSION }
+    it { should_not be_nil }
+  end    
 end

data/spec/spec_helper.rb

@@ -3,8 +3,12 @@ require 'simplecov'
 
 SimpleCov.start do
   coverage_dir 'coverage'
-  add_filter '/spec/'
+  add_filter 'spec/'
 end
 
 require 'rspec'
+require 'support/with_constants'
+require 'support/deferred_garbage_collection' # http://makandra.com/notes/950-speed-up-rspec-by-deferring-garbage-collection
+require 'support/temporary_folder_helper'
+
 require 'capit'

data/spec/support/deferred_garbage_collection.rb

@@ -0,0 +1,26 @@
+class DeferredGarbageCollection
+  DEFERRED_GC_THRESHOLD = (ENV['DEFER_GC'] || 10.0).to_f
+  @@last_gc_run = Time.now
+  def self.start
+    GC.disable if DEFERRED_GC_THRESHOLD > 0
+  end
+
+  def self.reconsider
+    if DEFERRED_GC_THRESHOLD > 0 && Time.now - @@last_gc_run >= DEFERRED_GC_THRESHOLD
+      GC.enable
+      GC.start
+      GC.disable
+      @@last_gc_run = Time.now
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.before(:all) do
+    DeferredGarbageCollection.start
+  end
+  
+  config.after(:all) do
+    DeferredGarbageCollection.reconsider
+  end
+end

data/spec/support/temporary_folder_helper.rb

@@ -0,0 +1,9 @@
+def setup_temporary_folder
+  folder = Dir.pwd + '/spec/temporary'
+  `mkdir -p #{folder}`
+  folder
+end
+
+def destroy_temporary_folder(folder)
+  `rm -rf #{folder}`
+end

data/spec/support/with_constants.rb

@@ -0,0 +1,52 @@
+# Borrowing Rails monkeypatch: http://api.rubyonrails.org/classes/Kernel.html
+# Make sure we don't redefine it if its already defined.
+#
+unless Kernel.method_defined?(:silence_warnings)
+  module Kernel
+    def silence_warnings
+      with_warnings(nil) { yield }
+    end
+
+    def with_warnings(flag)
+      old_verbose, $VERBOSE = $VERBOSE, flag
+      yield
+    ensure
+      $VERBOSE = old_verbose
+    end
+  end
+end
+
+# From: http://digitaldumptruck.jotabout.com/?p=551
+def with_constants(constants, &block)
+  saved_constants = {}
+  
+  constants.each do |constant, val|
+    saved_constants[ constant ] = Object.const_get( constant )
+    Kernel::silence_warnings { Object.const_set( constant, val ) }
+  end
+ 
+  begin
+    block.call
+  ensure
+    constants.each do |constant, val|
+      Kernel::silence_warnings { Object.const_set( constant, saved_constants[ constant ] ) }
+    end
+  end
+end
+
+def with_environment_variable(variables, &block)
+  saved_variables = {}
+  
+  variables.each do |variable, value|
+    saved_variables[variable] = ENV[variable]
+    Kernel::silence_warnings { ENV[variable] = value }
+  end
+  
+  begin
+    block.call
+  ensure
+    variables.each do |variable, value|
+      Kernel::silence_warnings { ENV[variable] = saved_variables[variable] }
+    end
+  end
+end

metadata

@@ -2,7 +2,7 @@
 name: capit
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Ezekiel Templin
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-26 00:00:00 -04:00
+date: 2011-03-27 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -92,6 +92,8 @@ extra_rdoc_files:
 files: 
 - .gemtest
 - .gitignore
+- .rvmrc
+- .yardopts
 - Gemfile
 - Guardfile
 - LICENSE
@@ -104,6 +106,9 @@ files:
 - spec/capit/capture_spec.rb
 - spec/capit_spec.rb
 - spec/spec_helper.rb
+- spec/support/deferred_garbage_collection.rb
+- spec/support/temporary_folder_helper.rb
+- spec/support/with_constants.rb
 has_rdoc: true
 homepage: http://github.com/meadvillerb/capit
 licenses: []
@@ -136,3 +141,6 @@ test_files:
 - spec/capit/capture_spec.rb
 - spec/capit_spec.rb
 - spec/spec_helper.rb
+- spec/support/deferred_garbage_collection.rb
+- spec/support/temporary_folder_helper.rb
+- spec/support/with_constants.rb