guard 1.8.3 → 2.0.0.pre

data/lib/guard/dsl_describer.rb

@@ -1,86 +1,130 @@
 # encoding: utf-8
+require 'formatador'
+
+require 'guard/guardfile/evaluator'
+require 'guard/ui'
 
 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`.
+  # The DslDescriber evaluates the Guardfile and creates an internal structure
+  # of it that is used in some inspection utility methods like the CLI commands
+  # `show` and `list`.
   #
   # @see Guard::Dsl
   # @see Guard::CLI
   #
-  class DslDescriber < Dsl
-
-    require 'guard/dsl'
-    require 'guard/ui'
-
-    require 'formatador'
-
-    class << self
+  class DslDescriber
+
+    attr_reader :options
+
+    # Initializes a new DslDescriber object.
+    #
+    # @option options [String] guardfile the path to a valid Guardfile
+    # @option options [String] guardfile_contents a string representing the content of a valid Guardfile
+    #
+    # @see Guard::Guardfile::Evaluator#initialize
+    #
+    def initialize(options = {})
+      @options = options
+      ::Guard.reset_groups
+      ::Guard.reset_plugins
+    end
 
-      # Setups groups and plugins state and evaluates 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 = { })
-        ::Guard.options = { :plugin => [], :group => [] }
-        ::Guard.setup_groups
-        ::Guard.setup_guards
+    # List the Guard plugins that are available for use in your system and marks
+    # those that are currently used in your `Guardfile`.
+    #
+    # @see CLI#list
+    #
+    def list
+      _evaluate_guardfile
 
-        super options
+      rows = ::Guard::PluginUtil.plugin_names.sort.uniq.inject([]) do |rows, name|
+        rows << { Plugin: name.capitalize, Guardfile: ::Guard.plugins(name) ? '✔' : '✘' }
       end
 
-      # List the Guard plugins that are available for use in your system and marks
-      # those that are currently used in your `Guardfile`.
-      #
-      # @param [Hash] options the Guard options
-      #
-      def list(options)
-        evaluate_guardfile(options)
+      Formatador.display_compact_table(rows, [:Plugin, :Guardfile])
+    end
 
-        rows = ::Guard.guard_gem_names.sort.uniq.inject([]) do |rows, name|
-          rows << { :Plugin => name.capitalize, :Guardfile => ::Guard.guards(name) ? '✔' : '✘' }
+    # Shows all Guard plugins and their options that are defined in
+    # the `Guardfile`.
+    #
+    # @see CLI#show
+    #
+    def show
+      _evaluate_guardfile
+
+      rows = ::Guard.groups.inject([]) do |rows, group|
+        Array(::Guard.plugins(group: group.name)).each do |plugin|
+          options = plugin.options.inject({}) { |o, (k, v)| o[k.to_s] = v; o }.sort
+
+          if options.empty?
+            rows << :split
+            rows << { Group: group.title, Plugin: plugin.title, Option: '', Value: '' }
+          else
+            options.each_with_index do |(option, value), index|
+              if index == 0
+                rows << :split
+                rows << { Group: group.title, Plugin: plugin.title, Option: option.to_s, Value: value.inspect }
+              else
+                rows << { Group: '', Plugin: '', Option: option.to_s, Value: value.inspect }
+              end
+            end
+          end
         end
 
-        Formatador.display_compact_table(rows, [:Plugin, :Guardfile])
+        rows
       end
 
-      # Shows all Guard plugins and their options that are defined in
-      # the `Guardfile`.
-      #
-      # @param [Hash] options the Guard options
-      #
-      def show(options)
-        evaluate_guardfile(options)
-
-        rows = ::Guard.groups.inject([]) do |rows, group|
-          ::Guard.guards({ :group => group.name }).each do |plugin|
-            options = plugin.options.inject({}) { |o, (k, v)| o[k.to_s] = v; o }.sort
+      Formatador.display_compact_table(rows.drop(1), [:Group, :Plugin, :Option, :Value])
+    end
 
-            if options.empty?
+    # Shows all notifiers and their options that are defined in
+    # the `Guardfile`.
+    #
+    # @see CLI#show
+    #
+    def notifiers
+      _evaluate_guardfile
+
+      rows = ::Guard::Notifier::NOTIFIERS.inject(:merge).inject([]) do |rows, definition|
+        name      = definition[0]
+        clazz     = definition[1]
+        available = clazz.available?(silent: true) ? '✔' : '✘'
+        notifier  = ::Guard::Notifier.notifiers.find{ |n| n[:name] == name }
+        used      = notifier ? '✔' : '✘'
+        options   = notifier ? notifier[:options] : {}
+        defaults  = clazz.const_defined?(:DEFAULTS) ? clazz.const_get(:DEFAULTS) : {}
+        options   = defaults.merge(options)
+        options.delete(:silent)
+
+        if options.empty?
+          rows << :split
+          rows << { Name: name, Available: available, Used: used, Option: '', Value: '' }
+        else
+          options.each_with_index do |(option, value), index|
+            if index == 0
               rows << :split
-              rows << { :Group => group.to_s, :Plugin => plugin.to_s, :Option => '', :Value => '' }
+              rows << { Name: name, Available: available, Used: used, Option: option.to_s, Value: value.inspect }
             else
-              options.each_with_index do |(option, value), index|
-                if index == 0
-                  rows << :split
-                  rows << { :Group => group.to_s, :Plugin => plugin.to_s, :Option => option.to_s, :Value => value.inspect }
-                else
-                  rows << { :Group => '', :Plugin => '', :Option => option.to_s, :Value => value.inspect }
-                end
-              end
+              rows << { Name: '', Available: '', Used: '', Option: option.to_s, Value: value.inspect }
             end
           end
-
-          rows
         end
 
-        Formatador.display_compact_table(rows.drop(1), [:Group, :Plugin, :Option, :Value])
+        rows
       end
 
+      Formatador.display_compact_table(rows.drop(1), [:Name, :Available, :Used, :Option, :Value])
     end
+
+    private
+
+    # Evaluates the `Guardfile` by delegating to
+    #   {Guard::Guardfile::Evaluator#evaluate_guardfile}.
+    #
+    def _evaluate_guardfile
+      ::Guard::Guardfile::Evaluator.new(options).evaluate_guardfile
+    end
+
   end
 end

data/lib/guard/group.rb

@@ -1,14 +1,17 @@
 module Guard
 
-  # A group of Guard plugins. There are two reasons why you want to group your guards:
+  # A group of Guard plugins. There are two reasons why you want to group your
+  # Guard plugins:
   #
-  # - You can start only certain Groups from the command line by passing the `--group` option.
-  # - Abort task execution chain on failure within a group.
+  # * You can start only certain groups from the command line by passing the
+  #   `--group` option to `guard start`.
+  # * Abort task execution chain on failure within a group with the
+  #   `:halt_on_fail` option.
   #
   # @example Group that aborts on failure
   #
-  #   group :frontend, :halt_on_fail => true do
-  #     guard 'coffeescript', :input => 'spec/coffeescripts', :output => 'spec/javascripts'
+  #   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
@@ -32,12 +35,28 @@ module Guard
       @options = options
     end
 
-    # String representation of the Guard group.
+    # Returns the group title.
     #
-    # @return [String] the group name
+    # @example Title for a group named 'backend'
+    #   > Guard::Group.new('backend').title
+    #   => "Backend"
+    #
+    # @return [String]
+    #
+    def title
+      @title ||= name.to_s.capitalize
+    end
+
+    # String representation of the group.
+    #
+    # @example String representation of a group named 'backend'
+    #   > Guard::Group.new('backend').to_s
+    #   => "#<Guard::Group @name=backend @options={}>"
+    #
+    # @return [String] the string representation
     #
     def to_s
-      @name.to_s.capitalize
+      "#<#{self.class} @name=#{name} @options=#{options}>"
     end
 
   end

data/lib/guard/guard.rb

@@ -1,167 +1,42 @@
+require 'guard/plugin/base'
+
 module Guard
 
-  # Base class that every Guard plugin implementation must inherit from.
-  #
-  # Guard will trigger the `start`, `stop`, `reload`, `run_all` and `run_on_changes`
-  # (`run_on_additions`, `run_on_modifications` and `run_on_removals`) task methods
-  # depending on user interaction and file modification.
-  #
-  # `run_on_changes` could be implemented to handle all the changes task case (additions,
-  # modifications, removals) in once, or each task can be implemented separately with a
-  # specific behavior.
-  #
-  # 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 it'll be passed to the "_end" hook for further evaluation. You can
-  # throw `:task_has_failed` to indicate that your Guard plugin method was not successful,
-  # and successive Guard plugin 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
+  # @deprecated Inheriting from `Guard::Guard` is deprecated, please inherit
+  #   from {Plugin} instead. Please note that the constructor signature has
+  #   changed from `Guard::Guard#initialize(watchers = [], options = {})` to
+  #   `Guard::Plugin#initialize(options = {})`.
   #
-  # Each Guard plugin should provide a template Guardfile located within the Gem
-  # at `lib/guard/guard-name/templates/Guardfile`.
-  #
-  # By default all watchers for a Guard plugin have to return strings of paths to the
-  # Guard, but if your Guard plugin wants 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.
+  # @see https://github.com/guard/guard/wiki/Upgrading-to-Guard-2.0 How to
+  #   upgrade for Guard 2.0
   #
   class Guard
-    require 'guard/hook'
-    require 'guard/ui'
-
-    include ::Guard::Hook
+    include ::Guard::Plugin::Base
 
-    attr_accessor :watchers, :options, :group
-
-    # Initializes a Guard plugin.
-    # Don't do any work here, especially as Guard plugins get initialized even if they are not in an active group!
+    # @deprecated Inheriting from `Guard::Guard` is deprecated, please inherit
+    #   from {Plugin} instead. Please note that the constructor signature
+    #   has changed from `Guard::Guard#initialize(watchers = [], options = {})`
+    #   to `Guard::Plugin#initialize(options = {})`.
+    #
+    # Initializes a Guard plugin. Don't do any work here,
+    #   especially as Guard plugins get initialized even if they are not in an
+    #   active group!
+    #
+    # @see https://github.com/guard/guard/wiki/Upgrading-to-Guard-2.0 How to
+    #   upgrade for Guard 2.0
     #
     # @param [Array<Guard::Watcher>] watchers the Guard plugin file watchers
     # @param [Hash] options the custom Guard plugin options
     # @option options [Symbol] group the group this Guard plugin belongs to
-    # @option options [Boolean] any_return allow any object to be returned from a watcher
+    # @option 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
+      ::Guard::UI.deprecation(::Guard::Deprecator::GUARD_GUARD_DEPRECATION % title)
 
-    # Specify the source for the Guardfile template.
-    # Each Guard plugin can redefine this method to add its own logic.
-    #
-    # @param [String] The plugin name
-    #
-    def self.template(name)
-      File.read("#{ ::Guard.locate_guard(name) }/lib/guard/#{ name }/templates/Guardfile")
-    end
-
-    # Initialize the Guard plugin. This will copy the Guardfile template inside the Guard plugin 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 plugin
-    #
-    def self.init(name)
-      if ::Guard::Dsl.guardfile_include?(name)
-        ::Guard::UI.info "Guardfile already includes #{ name } guard"
-      else
-        content = File.read('Guardfile')
-        guard = template(name)
-
-        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
-
-    # Called once when Guard starts. Please override initialize method to init stuff.
-    #
-    # @raise [:task_has_failed] when start has failed
-    # @return [Object] the task result
-    #
-    # @!method start
-
-    # 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
-    #
-    # @!method stop
-
-    # 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
-    #
-    # @!method  reload
-
-    # 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
-    #
-    # @!method run_all
-
-    # Default behaviour on file(s) changes that the Guard plugin watches.
-    #
-    # @param [Array<String>] paths the changes files or paths
-    # @raise [:task_has_failed] when run_on_changes has failed
-    # @return [Object] the task result
-    #
-    # @!method run_on_changes(paths)
-
-    # Called on file(s) additions that the Guard plugin watches.
-    #
-    # @param [Array<String>] paths the changes files or paths
-    # @raise [:task_has_failed] when run_on_additions has failed
-    # @return [Object] the task result
-    #
-    # @!method run_on_additions(paths)
-
-    # Called on file(s) modifications that the Guard plugin watches.
-    #
-    # @param [Array<String>] paths the changes files or paths
-    # @raise [:task_has_failed] when run_on_modifications has failed
-    # @return [Object] the task result
-    #
-    # @!method run_on_modifications(paths)
-
-    # Called on file(s) removals that the Guard plugin watches.
-    #
-    # @param [Array<String>] paths the changes files or paths
-    # @raise [:task_has_failed] when run_on_removals has failed
-    # @return [Object] the task result
-    #
-    # @!method run_on_removals(paths)
-
-    # Convert plugin to string representation. The
-    # default just uses the plugin class name and
-    # removes the Guard module name.
-    #
-    # @return [String] the string representation
-    #
-    def to_s
-      self.class.to_s.downcase.sub('guard::', '').capitalize
+      _set_instance_variables_from_options(options.merge(watchers: watchers))
+      _register_callbacks
     end
 
   end
-
 end

data/lib/guard/guardfile.rb

@@ -1,94 +1,44 @@
+require 'guard/guardfile/evaluator'
+require 'guard/guardfile/generator'
+require 'guard/ui'
+
 module Guard
 
-  # The Guardfile is responsible for generating the Guardfile
-  # and adding guards' template into it.
+  # @deprecated Use instance methods of {Guardfile::Evaluator} and
+  #  {Guardfile::Generator} instead.
   #
-  # @see Guard::CLI
+  # @see Guardfile::Evaluator
+  # @see Guardfile::Generator
   #
-  class Guardfile
-
-    require 'guard'
-    require 'guard/ui'
-
-    class << self
-
-      # Creates the initial Guardfile template when it does not
-      # already exist.
-      #
-      # @see Guard::CLI.init
-      #
-      # @param [Hash] options The options for creating a Guardfile
-      # @option options [Boolean] :abort_on_existence Whether to abort or not when a Guardfile already exists
-      #
-      def create_guardfile(options = {})
-        if !File.exist?('Guardfile')
-          ::Guard::UI.info "Writing new Guardfile to #{ Dir.pwd }/Guardfile"
-          FileUtils.cp(GUARDFILE_TEMPLATE, 'Guardfile')
-        elsif options[:abort_on_existence]
-          ::Guard::UI.error "Guardfile already exists at #{ Dir.pwd }/Guardfile"
-          abort
-        end
-      end
-
-      # Opens an existing guardfile and searches for redundant definitions
-      # if extraneous defintions are found, it warns the user
-      #
-      # @see Guard::CLI.init
-      #
-      # @param [String] class name of gem definition that you would like to search for in the Guardfile
-      # @param [String] contents of existing guardfile
-      #
-      def duplicate_definitions?(guard_class, guard_file)
-        matches = guard_file.to_s.scan(/guard\s[\'|\"]#{guard_class}[\'|\"]\sdo/)
-        if matches.count > 1
-          ::Guard::UI.info "There are #{matches.count.to_s} definitions in your Guardfile for '#{guard_class}', you may want to clean up your Guardfile as this could cause issues."
-          return true
-        else
-          return false
-        end
-      end
-
-      # Adds the Guardfile template of a Guard implementation
-      # to an existing Guardfile.
-      #
-      # @see Guard::CLI.init
-      #
-      # @param [String] guard_name the name of the Guard or template to initialize
-      #
-      def initialize_template(guard_name)
-        guard_class = ::Guard.get_guard_class(guard_name, true)
-
-        if guard_class
-          guard_class.init(guard_name)
-          guardfile_name = 'Guardfile'
-          guard_file = File.read(guardfile_name) if File.exists?(guardfile_name)
-          duplicate_definitions?(guard_name, guard_file)
-        elsif File.exist?(File.join(HOME_TEMPLATES, guard_name))
-          content  = File.read('Guardfile')
-          template = File.read(File.join(HOME_TEMPLATES, guard_name))
-
-          File.open('Guardfile', 'wb') do |f|
-            f.puts(content)
-            f.puts('')
-            f.puts(template)
-          end
-
-          ::Guard::UI.info "#{ guard_name } template added to Guardfile, feel free to edit it"
-        else
-          const_name = guard_name.downcase.gsub('-', '')
-          UI.error "Could not load 'guard/#{ guard_name.downcase }' or '~/.guard/templates/#{ guard_name.downcase }' or find class Guard::#{ const_name.capitalize }"
-        end
-      end
+  module Guardfile
+
+    # @deprecated Use {Guardfile::Generator#create_guardfile} instead.
+    #
+    # @see https://github.com/guard/guard/wiki/Upgrading-to-Guard-2.0 How to upgrade for Guard 2.0
+    #
+    def self.create_guardfile(options = {})
+      ::Guard::UI.deprecation(::Guard::Deprecator::CREATE_GUARDFILE_DEPRECATION)
+      Generator.new(options).create_guardfile
+    end
 
-      # Adds the templates of all installed Guard implementations
-      # to an existing Guardfile.
-      #
-      # @see Guard::CLI.init
-      #
-      def initialize_all_templates
-        ::Guard.guard_gem_names.each { |g| initialize_template(g) }
-      end
+    # @deprecated Use {Guardfile::Generator#initialize_template} instead.
+    #
+    # @see https://github.com/guard/guard/wiki/Upgrading-to-Guard-2.0 How to upgrade for Guard 2.0
+    #
+    def self.initialize_template(plugin_name)
+      ::Guard::UI.deprecation(::Guard::Deprecator::INITIALIZE_TEMPLATE_DEPRECATION)
+      Generator.new.initialize_template(plugin_name)
+    end
 
+    # @deprecated Use {Guardfile::Generator#initialize_all_templates} instead.
+    #
+    # @see https://github.com/guard/guard/wiki/Upgrading-to-Guard-2.0 How to upgrade for Guard 2.0
+    #
+    def self.initialize_all_templates
+      ::Guard::UI.deprecation(::Guard::Deprecator::INITIALIZE_ALL_TEMPLATES_DEPRECATION)
+      Generator.new.initialize_all_templates
     end
+
   end
+
 end