executioner 0.3.0 → 0.3.1

data/.gitignore

@@ -1 +1,2 @@
-pkg/
+pkg
+html

data/README.rdoc

@@ -0,0 +1,72 @@
+= Executioner
+
+Executioner is a  module you can include in your classes to run binaries from
+your Ruby code.
+
+  class Recording
+    include Executioner
+    executable :lame, :switch_stdout_and_stderr => true
+    
+    def transcode
+      lame("--abr 128 -m s #{filename} #{filename_as_mp3}")
+    end
+  end
+
+==== Specifying a binary
+
+By default Executioner looks in Executioner::SEARCH_PATHS for the binary.
+
+  executable :sh
+
+If the binary is installed in a specific location you might want to
+specify the entire path to the executable.
+
+  executable :import, :path => App.root_path + 'scripts/import'
+
+And when you need to specify environment variables for the executable you
+can do so as well.
+
+  executable :migrate, :env => { 'ENV' => 'PRODUCTION' }
+
+If you need more elaborate rules to pick a specific path for a binary you
+can specify a block that selects the right one.
+
+  executable :gcc, :select_if => lambda { |path|
+    File.ftype(path) != 'link' and !path.start_with?('/opt')
+  }
+
+==== Reading output
+
+Executioner reads either +stdout+ or +stderr+ and returns it from the call to
+the binary. In the example presented above a call to +lame+ would return the
+entire output to +stderr+ produced by Lame.
+
+  lame("--work") # => "lame: unrecognized option --work"
+
+==== Exceptions
+
+A call to a binary raises a +ProcessError+ when the output stream is empty and
+there is stuff in the error stream. An +ExecutableNotFoundError+ is raised when
+the executable can't be found in the path.
+
+==== Queues
+
+Executioner uses popen3 to run a subprocess with the executable. Starting a
+process takes some time so if you're running lots of short commands you can
+probably win some time by executing them from a queue.
+
+  executable :ppane, :use_queue => true
+
+Now calling +ls+ will queue the command instead of executing it. You can execute
+the entire queue by calling +execute_queued+.
+
+  ppane('add ~/Code/project')
+  ppane('register')
+  execute_queued
+
+==== Logging
+
+If you want to log everything Executioner does, you can assign a logger instance
+to Executioner.logger.
+
+  Executioner.logger = Rails.logger

data/Rakefile

@@ -1,4 +1,5 @@
 require 'rake/testtask'
+require 'rake/rdoctask'
 
 task :default => :test
 
@@ -7,6 +8,14 @@ Rake::TestTask.new do |t|
   t.verbose = true
 end
 
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.title    = 'Executioner'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
 begin
   require 'jeweler'
   Jeweler::Tasks.new do |s|

data/VERSION.yml

@@ -1,5 +1,5 @@
 --- 
+:build: 
 :minor: 3
-:patch: 0
+:patch: 1
 :major: 0
-:build: 

data/executioner.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{executioner}
-  s.version = "0.3.0"
+  s.version = "0.3.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Eloy Duran"]
-  s.date = %q{2009-12-09}
+  s.date = %q{2011-04-21}
   s.description = %q{Execute CLI utilities}
   s.email = %q{eloy@fngtps.com}
   s.extra_rdoc_files = [
@@ -26,15 +26,17 @@ Gem::Specification.new do |s|
      "executioner.gemspec",
      "lib/executioner.rb",
      "test/executioner_test.rb",
+     "test/scripts/load_executioner_without_home.rb",
      "test/test_helper.rb"
   ]
   s.homepage = %q{http://fingertips.github.com}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.5}
+  s.rubygems_version = %q{1.3.7}
   s.summary = %q{Execute CLI utilities}
   s.test_files = [
     "test/executioner_test.rb",
+     "test/scripts/load_executioner_without_home.rb",
      "test/test_helper.rb"
   ]
 
@@ -42,7 +44,7 @@ Gem::Specification.new do |s|
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
     else
     end
   else

data/lib/executioner.rb

@@ -5,9 +5,14 @@ module Executioner
   class ProcessError < ExecutionerError; end
   class ExecutableNotFoundError < ExecutionerError; end
   
-  SEARCH_PATHS = %W{ #{File.expand_path('~/bin')} /bin /usr/bin /usr/local/bin /opt/homebrew/bin /opt/local/bin }
+  SEARCH_PATHS = %w(/bin /usr/bin /usr/local/bin /opt/homebrew/bin /opt/local/bin)
+  begin
+    SEARCH_PATHS.unshift(File.expand_path('~/bin'))
+  rescue ArgumentError
+  end
   
   class << self
+    # Assign a logger if you want to log commands and options.
     attr_accessor :logger
     
     def included(klass)
@@ -55,6 +60,36 @@ module Executioner
   end
   
   module ClassMethods
+    # Register an executable with the class.
+    #
+    #   executable :ppane
+    #
+    # You can configure the environment to use for each call to the executable.
+    #
+    #   executable :rails, :env => { 'RAILS_ENV' => 'production' }
+    #
+    # In case the executable is outside regular paths, you can specify a
+    # particular path.
+    #
+    #   executable :heap, :path => '/Developer/usr/bin/heap'
+    #
+    # The method you use to call the binary returns it's output in a a string
+    # sometimes the useful information is in +stderr+ instead of +stdout+.
+    # This happens sometimes in application which show progress. You can
+    # switch the output streams to capture +stderr+ instead of +stdout+.
+    #
+    #   executable :lame, :switch_stdout_and_stderr => true
+    #
+    # If you have some particular need to select a specific path over another
+    # you can select it using a proc.
+    #
+    #   executable :gcc, :select_if => { |e| File.ftype(e) != 'link' }
+    #   executable :gcc, :select_if => { |e| e.start_with?('/Developer') }
+    #
+    # Both symbols and strings are allowed for names.
+    #
+    #   executable 'aclocal-1.10'
+    #
     def executable(executable, options={})
       options[:switch_stdout_and_stderr] ||= false
       options[:use_queue]                ||= false
@@ -85,12 +120,13 @@ module Executioner
       class_eval "def #{executable.gsub(/-/, '_')}(args, options = {}); #{body}; end", __FILE__, __LINE__
     end
     
+    # Finds the first occurence of the specified executable in Executioner::SEARCH_PATHS
     def find_executable(executable, advance_from = nil)
       search_paths = Executioner::SEARCH_PATHS
       search_paths = search_paths[(search_paths.index(advance_from) + 1)..-1] if advance_from
       
-      if executable_in_path = search_paths.find { |path| File.exist? File.join(path, executable) }
-        File.join executable_in_path, executable
+      if executable_in_path = search_paths.find { |path| File.exist?(File.join(path, executable)) }
+        File.join(executable_in_path, executable)
       end
     end
     module_function :find_executable

data/test/executioner_test.rb

@@ -195,4 +195,11 @@ describe "Executioner, class methods" do
       @object.doesnotexistforsure 'right?'
     }.should.raise Executioner::ExecutableNotFoundError
   end
+  
+  it "should work when there is no home directory in the environment" do
+    ruby = File.join(Config::CONFIG['bindir'], Config::CONFIG['ruby_install_name'])
+    lambda {
+      @object.execute("#{ruby} #{File.expand_path('../scripts/load_executioner_without_home.rb', __FILE__)}")
+    }.should.not.raise
+  end
 end

data/test/scripts/load_executioner_without_home.rb

@@ -0,0 +1,3 @@
+ENV.delete('HOME')
+$:.unshift File.expand_path('../../../lib', __FILE__)
+require 'executioner'

metadata

@@ -1,7 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: executioner
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  hash: 17
+  prerelease: false
+  segments: 
+  - 0
+  - 3
+  - 1
+  version: 0.3.1
 platform: ruby
 authors: 
 - Eloy Duran
@@ -9,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-09 00:00:00 +01:00
+date: 2011-04-21 00:00:00 +02:00
 default_executable: 
 dependencies: []
 
@@ -32,6 +38,7 @@ files:
 - executioner.gemspec
 - lib/executioner.rb
 - test/executioner_test.rb
+- test/scripts/load_executioner_without_home.rb
 - test/test_helper.rb
 has_rdoc: true
 homepage: http://fingertips.github.com
@@ -43,24 +50,31 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.5
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Execute CLI utilities
 test_files: 
 - test/executioner_test.rb
+- test/scripts/load_executioner_without_home.rb
 - test/test_helper.rb