lib/executioner.rb in executioner-0.3.0 vs lib/executioner.rb in executioner-0.3.1

@@ -3,13 +3,18 @@
 module Executioner
   class ExecutionerError < StandardError; end
   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)
       klass.extend ClassMethods
     end
@@ -53,10 +58,40 @@
     execute(queued_commands, options)
     @commands = []
   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
       
       executable = executable.to_s if executable.is_a? Symbol
@@ -83,15 +118,16 @@
       end
       
       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
   end
 end
\ No newline at end of file