guard 0.8.4 → 0.8.5

data/lib/guard/dsl_describer.rb

@@ -1,60 +1,150 @@
-require 'guard/dsl'
-
-module Guard
-
-  # The DslDescriber overrides methods to create an internal structure
-  # of the Guardfile that is used in some inspection utility methods
-  # like the CLI commands `show` and `list`.
-  #
-  # @see Guard::Dsl
-  # @see Guard::CLI
-  #
-  class DslDescriber < Dsl
-
-    @@guardfile_structure = [ { :guards => [] } ]
-
-    class << self
-
-      # Get the Guardfile structure.
-      #
-      # @return [Array<Hash>] the structure
-      #
-      def guardfile_structure
-        @@guardfile_structure
-      end
-    end
-
-    private
-
-    # Declares a group of guards.
-    #
-    # @param [String] name the group's name called from the CLI
-    # @yield a block where you can declare several guards
-    #
-    # @see Guard::Dsl#group
-    #
-    def group(name)
-      @@guardfile_structure << { :group => name.to_sym, :guards => [] }
-      @group = true
-
-      yield if block_given?
-
-      @group = false
-    end
-
-    # Declares a Guard.
-    #
-    # @param [String] name the Guard name
-    # @param [Hash] options the options accepted by the Guard
-    # @yield a block where you can declare several watch patterns and actions
-    #
-    # @see Guard::Dsl#guard
-    #
-    def guard(name, options = {})
-      node = (@group ? @@guardfile_structure.last : @@guardfile_structure.first)
-
-      node[:guards] << { :name => name, :options => options }
-    end
-
-  end
-end
+require 'guard/dsl'
+
+module Guard
+
+  autoload :UI,    'guard/ui'
+
+  # The DslDescriber overrides methods to create an internal structure
+  # of the Guardfile that is used in some inspection utility methods
+  # like the CLI commands `show` and `list`.
+  #
+  # @see Guard::Dsl
+  # @see Guard::CLI
+  #
+  class DslDescriber < Dsl
+
+    class << self
+
+      # Evaluate the DSL methods in the `Guardfile`.
+      #
+      # @option options [Array<Symbol,String>] groups the groups to evaluate
+      # @option options [String] guardfile the path to a valid Guardfile
+      # @option options [String] guardfile_contents a string representing the content of a valid Guardfile
+      # @raise [ArgumentError] when options are not a Hash
+      #
+      def evaluate_guardfile(options = {})
+        @@guardfile_structure = [{ :guards => [] }]
+        super options
+      end
+
+      # List the Guards that are available for use in your system and marks
+      # those that are currently used in your `Guardfile`.
+      #
+      # @example Guard list output
+      #
+      #   Available guards:
+      #     bundler *
+      #     livereload
+      #     ronn
+      #     rspec *
+      #     spork
+      #
+      #   See also https://github.com/guard/guard/wiki/List-of-available-Guards
+      #   * denotes ones already in your Guardfile
+      #
+      # @param [Hash] options the Guard options
+      #
+      def list(options)
+        evaluate_guardfile(options)
+
+        installed = guardfile_structure.inject([]) do |installed, group|
+          group[:guards].each { |guard| installed << guard[:name] } if group[:guards]
+          installed
+        end
+
+        UI.info 'Available guards:'
+
+        ::Guard.guard_gem_names.sort.uniq.each do |name|
+          UI.info "   #{ name }#{ installed.include?(name) ? '*' : '' }"
+        end
+
+        UI.info ''
+        UI.info 'See also https://github.com/guard/guard/wiki/List-of-available-Guards'
+        UI.info '* denotes ones already in your Guardfile'
+      end
+
+      # Shows all Guards and their options that are defined in
+      # the `Guardfile`.
+      #
+      # @example guard show output
+      #
+      #   (global):
+      #     bundler
+      #     coffeescript: input => "app/assets/javascripts", noop => true
+      #     jasmine
+      #     rspec: cli => "--fail-fast --format Fuubar
+      #
+      # @param [Hash] options the Guard options
+      #
+      def show(options)
+        evaluate_guardfile(options)
+
+        guardfile_structure.each do |group|
+          unless group[:guards].empty?
+            if group[:group]
+              UI.info "Group #{ group[:group] }:"
+            else
+              UI.info '(global):'
+            end
+
+            group[:guards].each do |guard|
+              line = "  #{ guard[:name] }"
+
+              unless guard[:options].empty?
+                line += ": #{ guard[:options].sort.collect { |k, v| "#{ k } => #{ v.inspect }" }.join(', ') }"
+              end
+
+              UI.info line
+            end
+          end
+        end
+
+        UI.info ''
+      end
+
+      private
+
+      # Get the Guardfile structure.
+      #
+      # @return [Array<Hash>] the structure
+      #
+      def guardfile_structure
+        @@guardfile_structure
+      end
+
+    end
+
+    private
+
+    # Declares a group of guards.
+    #
+    # @param [String] name the group's name called from the CLI
+    # @yield a block where you can declare several guards
+    #
+    # @see Guard::Dsl#group
+    #
+    def group(name)
+      @@guardfile_structure << { :group => name.to_sym, :guards => [] }
+      @group = true
+
+      yield if block_given?
+
+      @group = false
+    end
+
+    # Declares a Guard.
+    #
+    # @param [String] name the Guard name
+    # @param [Hash] options the options accepted by the Guard
+    # @yield a block where you can declare several watch patterns and actions
+    #
+    # @see Guard::Dsl#guard
+    #
+    def guard(name, options = { })
+      node = (@group ? @@guardfile_structure.last : @@guardfile_structure.first)
+
+      node[:guards] << { :name => name, :options => options }
+    end
+
+  end
+end

data/lib/guard/group.rb

@@ -1,37 +1,37 @@
-module Guard
-
-  # A group of Guards. There are two reasons why you want to group your guards:
-  #
-  # - You can start only certain Groups from the command line by passing the `--group` option.
-  # - Abort task execution chain on failure within a group.
-  #
-  # @example Group that aborts on failure
-  #
-  #   group :frontend, :halt_on_fail => true do
-  #     guard 'coffeescript', :input => 'spec/coffeescripts', :output => 'spec/javascripts'
-  #     guard 'jasmine-headless-webkit' do
-  #       watch(%r{^spec/javascripts/(.*)\..*}) { |m| newest_js_file("spec/javascripts/#{m[1]}_spec") }
-  #     end
-  #   end
-  #
-  # @see Guard::CLI
-  #
-  class Group
-
-    attr_accessor :name, :options
-
-    # Initialize a Group.
-    #
-    # @param [String] name the name of the group
-    # @param [Hash] options the group options
-    # @option options [Boolean] halt_on_fail if a task execution
-    #   should be halted for all Guards in this group if one Guard throws `:task_has_failed`
-    #
-    def initialize(name, options = {})
-      @name    = name.to_sym
-      @options = options
-    end
-
-  end
-
-end
+module Guard
+
+  # A group of Guards. There are two reasons why you want to group your guards:
+  #
+  # - You can start only certain Groups from the command line by passing the `--group` option.
+  # - Abort task execution chain on failure within a group.
+  #
+  # @example Group that aborts on failure
+  #
+  #   group :frontend, :halt_on_fail => true do
+  #     guard 'coffeescript', :input => 'spec/coffeescripts', :output => 'spec/javascripts'
+  #     guard 'jasmine-headless-webkit' do
+  #       watch(%r{^spec/javascripts/(.*)\..*}) { |m| newest_js_file("spec/javascripts/#{m[1]}_spec") }
+  #     end
+  #   end
+  #
+  # @see Guard::CLI
+  #
+  class Group
+
+    attr_accessor :name, :options
+
+    # Initialize a Group.
+    #
+    # @param [String] name the name of the group
+    # @param [Hash] options the group options
+    # @option options [Boolean] halt_on_fail if a task execution
+    #   should be halted for all Guards in this group if one Guard throws `:task_has_failed`
+    #
+    def initialize(name, options = {})
+      @name    = name.to_sym
+      @options = options
+    end
+
+  end
+
+end

data/lib/guard/guard.rb

@@ -1,113 +1,129 @@
-module Guard
-
-  # Main class that every Guard implementation must subclass.
-  #
-  # Guard will trigger the `start`, `stop`, `reload`, `run_all`, `run_on_change` and
-  # `run_on_deletion` methods depending on user interaction and file modification.
-  #
-  # In each of these Guard methods you have to implement some work when you want to
-  # support this kind of task. The return value of each Guard method is ignored, but
-  # you can throw `:task_has_failed` to indicate that your Guard method was
-  # not successful. When `:task_has_failed` is thrown, successive guard tasks
-  # can be aborted when the group has set the `:halt_on_fail` option.
-  #
-  # @see Guard::Group
-  #
-  # @example Throw :task_has_failed
-  #
-  #   def run_all
-  #     if !runner.run(['all'])
-  #       throw :task_has_failed
-  #     end
-  #   end
-  #
-  # Each Guard should provide a template Guardfile located within the Gem
-  # at `lib/guard/guard-name/templates/Guardfile`.
-  #
-  # If one of those methods raise an exception other than `:task_has_failed`,
-  # the Guard::GuardName instance will be removed from the active guards.
-  #
-  class Guard
-    include Hook
-
-    attr_accessor :watchers, :options, :group
-
-    # Initialize a Guard.
-    #
-    # @param [Array<Guard::Watcher>] watchers the Guard file watchers
-    # @param [Hash] options the custom Guard options
-    #
-    def initialize(watchers = [], options = {})
-      @group = options[:group] ? options.delete(:group).to_sym : :default
-      @watchers, @options = watchers, options
-    end
-
-    # Initialize the Guard. This will copy the Guardfile template inside the Guard gem.
-    # The template Guardfile must be located within the Gem at `lib/guard/guard-name/templates/Guardfile`.
-    #
-    # @param [String] name the name of the Guard
-    #
-    def self.init(name)
-      if ::Guard::Dsl.guardfile_include?(name)
-        ::Guard::UI.info "Guardfile already includes #{ name } guard"
-      else
-        content = File.read('Guardfile')
-        guard   = File.read("#{ ::Guard.locate_guard(name) }/lib/guard/#{ name }/templates/Guardfile")
-        File.open('Guardfile', 'wb') do |f|
-          f.puts(content)
-          f.puts("")
-          f.puts(guard)
-        end
-        ::Guard::UI.info "#{name} guard added to Guardfile, feel free to edit it"
-      end
-    end
-
-    # Call once when Guard starts. Please override initialize method to init stuff.
-    #
-    # @raise [:task_has_failed] when start has failed
-    #
-    def start
-    end
-
-    # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits).
-    #
-    # @raise [:task_has_failed] when stop has failed
-    #
-    def stop
-    end
-
-    # Called when `reload|r|z + enter` is pressed.
-    # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
-    #
-    # @raise [:task_has_failed] when reload has failed
-    #
-    def reload
-    end
-
-    # Called when just `enter` is pressed
-    # This method should be principally used for long action like running all specs/tests/...
-    #
-    # @raise [:task_has_failed] when run_all has failed
-    #
-    def run_all
-    end
-
-    # Called on file(s) modifications that the Guard watches.
-    #
-    # @param [Array<String>] paths the changes files or paths
-    # @raise [:task_has_failed] when run_on_change has failed
-    #
-    def run_on_change(paths)
-    end
-
-    # Called on file(s) deletions that the Guard watches.
-    #
-    # @param [Array<String>] paths the deleted files or paths
-    # @raise [:task_has_failed] when run_on_change has failed
-    #
-    def run_on_deletion(paths)
-    end
-
-  end
-
-end
+module Guard
+
+  # Base class that every Guard implementation must inherit from.
+  #
+  # Guard will trigger the `start`, `stop`, `reload`, `run_all`, `run_on_change` and
+  # `run_on_deletion` task methods depending on user interaction and file modification.
+  #
+  # In each of these Guard task methods you have to implement some work when you want to
+  # support this kind of task. The return value of each Guard task method is not evaluated
+  # by Guard, but I'll be passed to the "_end" hook for further evaluation. You can
+  # throw `:task_has_failed` to indicate that your Guard method was not successful,
+  # and successive guard tasks will be aborted when the group has set the `:halt_on_fail`
+  # option.
+  #
+  # @see Guard::Hook
+  # @see Guard::Group
+  #
+  # @example Throw :task_has_failed
+  #
+  #   def run_all
+  #     if !runner.run(['all'])
+  #       throw :task_has_failed
+  #     end
+  #   end
+  #
+  # Each Guard should provide a template Guardfile located within the Gem
+  # at `lib/guard/guard-name/templates/Guardfile`.
+  #
+  # By default all watchers for a Guard are returning strings of paths to the
+  # Guard, but if your Guard want to allow any return value from a watcher,
+  # you can set the `any_return` option to true.
+  #
+  # If one of those methods raise an exception other than `:task_has_failed`,
+  # the Guard::GuardName instance will be removed from the active guards.
+  #
+  class Guard
+    include Hook
+
+    attr_accessor :watchers, :options, :group
+
+    # Initialize a Guard.
+    #
+    # @param [Array<Guard::Watcher>] watchers the Guard file watchers
+    # @param [Hash] options the custom Guard options
+    # @options [Symbol] group the group this Guard belongs to
+    # @options [Boolean] any_return allow any object to be returned from a watcher
+    #
+    def initialize(watchers = [], options = {})
+      @group = options[:group] ? options.delete(:group).to_sym : :default
+      @watchers, @options = watchers, options
+    end
+
+    # Initialize the Guard. This will copy the Guardfile template inside the Guard gem.
+    # The template Guardfile must be located within the Gem at `lib/guard/guard-name/templates/Guardfile`.
+    #
+    # @param [String] name the name of the Guard
+    #
+    def self.init(name)
+      if ::Guard::Dsl.guardfile_include?(name)
+        ::Guard::UI.info "Guardfile already includes #{ name } guard"
+      else
+        content = File.read('Guardfile')
+        guard   = File.read("#{ ::Guard.locate_guard(name) }/lib/guard/#{ name }/templates/Guardfile")
+
+        File.open('Guardfile', 'wb') do |f|
+          f.puts(content)
+          f.puts("")
+          f.puts(guard)
+        end
+
+        ::Guard::UI.info "#{ name } guard added to Guardfile, feel free to edit it"
+      end
+    end
+
+    # Call once when Guard starts. Please override initialize method to init stuff.
+    #
+    # @raise [:task_has_failed] when start has failed
+    # @return [Object] the task result
+    #
+    def start
+    end
+
+    # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits).
+    #
+    # @raise [:task_has_failed] when stop has failed
+    # @return [Object] the task result
+    #
+    def stop
+    end
+
+    # Called when `reload|r|z + enter` is pressed.
+    # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
+    #
+    # @raise [:task_has_failed] when reload has failed
+    # @return [Object] the task result
+    #
+    def reload
+    end
+
+    # Called when just `enter` is pressed
+    # This method should be principally used for long action like running all specs/tests/...
+    #
+    # @raise [:task_has_failed] when run_all has failed
+    # @return [Object] the task result
+    #
+    def run_all
+    end
+
+    # Called on file(s) modifications that the Guard watches.
+    #
+    # @param [Array<String>] paths the changes files or paths
+    # @raise [:task_has_failed] when run_on_change has failed
+    # @return [Object] the task result
+    #
+    def run_on_change(paths)
+    end
+
+    # Called on file(s) deletions that the Guard watches.
+    #
+    # @param [Array<String>] paths the deleted files or paths
+    # @raise [:task_has_failed] when run_on_change has failed
+    # @return [Object] the task result
+    #
+    def run_on_deletion(paths)
+    end
+
+  end
+
+end