guard 1.4.0 → 2.18.0

data/lib/guard/dsl_describer.rb

@@ -1,150 +1,160 @@
-module Guard
+# encoding: utf-8
+require "formatador"
+
+require "guard/ui"
+require "guard/notifier"
+require "guard"
+
+require "set"
+require "ostruct"
 
-  # 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`.
+module Guard
+  # 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'
-
-    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 Guard plugins 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_guards = guardfile_structure.inject([]) do |installed, group|
-          group[:guards].each { |guard| installed << guard[:name].to_s } if group[:guards]
-          installed
-        end
-
-        ::Guard::UI.info 'Available guards:'
-
-        ::Guard.guard_gem_names.sort.uniq.each do |name|
-          ::Guard::UI.info "   #{ name }#{ installed_guards.include?(name) ? '*' : '' }"
-        end
+  class DslDescriber
+    def initialize(options = nil)
+      fail "options passed to DslDescriber are ignored!" unless options.nil?
+    end
 
-        ::Guard::UI.info ''
-        ::Guard::UI.info 'See also https://github.com/guard/guard/wiki/List-of-available-Guards'
-        ::Guard::UI.info '* denotes ones already in your Guardfile'
+    # 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
+      # TODO: remove dependency on Guard in this whole file
+      # collect metadata
+      data = PluginUtil.plugin_names.sort.inject({}) do |hash, name|
+        hash[name.capitalize] = Guard.state.session.plugins.all(name).any?
+        hash
       end
 
-      # Shows all Guard plugins 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]
-              ::Guard::UI.info "Group #{ group[:group] }:"
-            else
-              ::Guard::UI.info '(global):'
-            end
-
-            group[:guards].each do |guard|
-              line = "  #{ guard[:name] }"
+      # presentation
+      header = [:Plugin, :Guardfile]
+      final_rows = []
+      data.each do |name, used|
+        final_rows << { Plugin: name, Guardfile: used ? "✔" : "✘" }
+      end
 
-              unless guard[:options].empty?
-                line += ": #{ guard[:options].inject({}) { |options, (k, v)| options[k.to_s] = v; options }.sort.collect { |k, v| "#{ k } => #{ v.inspect }" }.join(', ') }"
-              end
+      # render
+      Formatador.display_compact_table(final_rows, header)
+    end
 
-              ::Guard::UI.info line
-            end
+    # Shows all Guard plugins and their options that are defined in
+    # the `Guardfile`.
+    #
+    # @see CLI#show
+    #
+    def show
+      # collect metadata
+      groups = Guard.state.session.groups.all
+
+      objects = []
+
+      empty_plugin = OpenStruct.new
+      empty_plugin.options = [["", nil]]
+
+      groups.each do |group|
+        plugins = Array(Guard.state.session.plugins.all(group: group.name))
+        plugins = [empty_plugin] if plugins.empty?
+        plugins.each do |plugin|
+          options = plugin.options
+          options = [["", nil]] if options.empty?
+          options.each do |option, raw_value|
+            value = raw_value.nil? ? "" : raw_value.inspect
+            objects << [group.title, plugin.title, option.to_s, value]
           end
         end
-
-        ::Guard::UI.info ''
       end
 
-      private
-
-      # Get the Guardfile structure.
-      #
-      # @return [Array<Hash>] the structure
-      #
-      def guardfile_structure
-        @@guardfile_structure
+      # presentation
+      rows = []
+      prev_group = prev_plugin = prev_option = prev_value = nil
+      objects.each do |group, plugin, option, value|
+        group_changed = prev_group != group
+        plugin_changed = (prev_plugin != plugin || group_changed)
+
+        rows << :split if group_changed || plugin_changed
+
+        rows << {
+          Group: group_changed ? group : "",
+          Plugin: plugin_changed ? plugin : "",
+          Option: option,
+          Value: value
+        }
+
+        prev_group = group
+        prev_plugin = plugin
+        prev_option = option
+        prev_value = value
       end
 
+      # render
+      Formatador.display_compact_table(
+        rows.drop(1),
+        [:Group, :Plugin, :Option, :Value]
+      )
     end
 
-    private
-
-    # Declares a group of guards.
+    # Shows all notifiers and their options that are defined in
+    # the `Guardfile`.
     #
-    # @param [String] name the group's name called from the CLI
-    # @yield a block where you can declare several guards
+    # @see CLI#show
     #
-    # @see Guard::Dsl#group
-    #
-    def group(name)
-      @@guardfile_structure << { :group => name.to_sym, :guards => [] }
-      @group = true
+    def notifiers
+      supported = Notifier.supported
+      Notifier.connect(notify: true, silent: true)
+      detected = Notifier.detected
+      Notifier.disconnect
+
+      detected_names = detected.map { |item| item[:name] }
+
+      final_rows = supported.each_with_object([]) do |(name, _), rows|
+        available = detected_names.include?(name) ? "✔" : "✘"
+
+        notifier = detected.detect { |n| n[:name] == name }
+        used = notifier ? "✔" : "✘"
+
+        options = notifier ? notifier[:options] : {}
+
+        if options.empty?
+          rows << :split
+          _add_row(rows, name, available, used, "", "")
+        else
+          options.each_with_index do |(option, value), index|
+            if index == 0
+              rows << :split
+              _add_row(rows, name, available, used, option.to_s, value.inspect)
+            else
+              _add_row(rows, "", "", "", option.to_s, value.inspect)
+            end
+          end
+        end
 
-      yield if block_given?
+        rows
+      end
 
-      @group = false
+      Formatador.display_compact_table(
+        final_rows.drop(1),
+        [:Name, :Available, :Used, :Option, :Value]
+      )
     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 = { })
-      @group ||= false
-      node = (@group ? @@guardfile_structure.last : @@guardfile_structure.first)
+    private
 
-      node[:guards] << { :name => name, :options => options }
+    def _add_row(rows, name, available, used, option, value)
+      rows << {
+        Name: name,
+        Available: available,
+        Used: used,
+        Option: option,
+        Value: value
+      }
     end
-
   end
 end

data/lib/guard/dsl_reader.rb

@@ -0,0 +1,51 @@
+require "guard/dsl"
+
+module Guard
+  # TODO: this should probably be a base class for Dsl instead (in Guard 3.x)
+  class DslReader < Dsl
+    attr_reader :plugin_names
+
+    def initialize
+      super
+      @plugin_names = []
+    end
+
+    def guard(name, _options = {})
+      @plugin_names << name.to_s
+    end
+
+    # Stub everything else
+    def notification(_notifier, _opts = {})
+    end
+
+    def interactor(_options)
+    end
+
+    def group(*_args)
+    end
+
+    def watch(_pattern, &_action)
+    end
+
+    def callback(*_args, &_block)
+    end
+
+    def ignore(*_regexps)
+    end
+
+    def ignore!(*_regexps)
+    end
+
+    def logger(_options)
+    end
+
+    def scope(_scope = {})
+    end
+
+    def directories(_directories)
+    end
+
+    def clearing(_on)
+    end
+  end
+end

data/lib/guard/group.rb

@@ -1,23 +1,27 @@
 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") }
+  #       watch(%r{^spec/javascripts/(.*)\..*}) do |m|
+  #       newest_js_file("spec/javascripts/#{m[1]}_spec")
+  #     end
   #     end
   #   end
   #
   # @see Guard::CLI
   #
   class Group
-
     attr_accessor :name, :options
 
     # Initializes a Group.
@@ -25,20 +29,36 @@ module Guard
     # @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 Guard plugins in this group if a Guard plugin throws `:task_has_failed`
+    #   should be halted for all Guard plugins in this group if a Guard plugin
+    #   throws `:task_has_failed`
     #
     def initialize(name, options = {})
-      @name    = name.to_sym
+      @name = name.to_sym
       @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"
     #
-    def to_s
-      "#{@name} group"
+    # @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
+      "#<#{self.class} @name=#{name} @options=#{options}>"
+    end
   end
 end

data/lib/guard/guardfile/evaluator.rb

@@ -0,0 +1,232 @@
+require "guard/config"
+require "guard/deprecated/evaluator" unless Guard::Config.new.strict?
+
+require "guard/options"
+require "guard/plugin"
+
+require "guard/dsl"
+require "guard/dsl_reader"
+
+module Guard
+  module Guardfile
+    # This class is responsible for evaluating the Guardfile. It delegates to
+    # Guard::Dsl for the actual objects generation from the Guardfile content.
+    #
+    # @see Guard::Dsl
+    #
+    # TODO: rename this to a Locator or Loader or something
+    class Evaluator
+      Deprecated::Evaluator.add_deprecated(self) unless Config.new.strict?
+
+      DEFAULT_GUARDFILES = %w(
+        guardfile.rb
+        Guardfile
+        ~/.Guardfile
+      ).freeze
+
+      ERROR_NO_GUARDFILE = "No Guardfile found,"\
+        " please create one with `guard init`."
+
+      attr_reader :options, :guardfile_path
+
+      ERROR_NO_PLUGINS = "No Guard plugins found in Guardfile,"\
+        " please add at least one."
+
+      class Error < RuntimeError
+      end
+
+      class NoGuardfileError < Error
+      end
+
+      class NoCustomGuardfile < Error
+      end
+
+      class NoPluginsError < Error
+      end
+
+      def guardfile_source
+        @source
+      end
+
+      # Initializes a new Guard::Guardfile::Evaluator object.
+      #
+      # @option opts [String] guardfile the path to a valid Guardfile
+      # @option opts [String] contents a string representing the
+      # content of a valid Guardfile
+      #
+      def initialize(opts = {})
+        @type = nil
+        @path = nil
+        @user_config = nil
+
+        opts = _from_deprecated(opts)
+
+        if opts[:contents]
+          @type = :inline
+          @contents = opts[:contents]
+        elsif opts[:guardfile]
+          @type = :custom
+          @path = Pathname.new(opts[:guardfile]) # may be updated by _read
+        end
+      end
+
+      # Evaluates the DSL methods in the `Guardfile`.
+      #
+      # @example Programmatically evaluate a Guardfile
+      #   Guard::Guardfile::Evaluator.new.evaluate
+      #
+      # @example Programmatically evaluate a Guardfile with a custom Guardfile
+      # path
+      #
+      #   options = { guardfile: '/Users/guardfile/MyAwesomeGuardfile' }
+      #   Guard::Guardfile::Evaluator.new(options).evaluate
+      #
+      # @example Programmatically evaluate a Guardfile with an inline Guardfile
+      #
+      #   options = { contents: 'guard :rspec' }
+      #   Guard::Guardfile::Evaluator.new(options).evaluate
+      #
+      def evaluate
+        inline? || _use_provided || _use_default!
+
+        contents = _guardfile_contents
+        fail NoPluginsError, ERROR_NO_PLUGINS unless /guard/m =~ contents
+
+        Dsl.new.evaluate(contents, @path || "", 1)
+      end
+
+      # Tests if the current `Guardfile` contains a specific Guard plugin.
+      #
+      # @example Programmatically test if a Guardfile contains a specific Guard
+      # plugin
+      #
+      #   File.read('Guardfile')
+      #   => "guard :rspec"
+      #
+      #   Guard::Guardfile::Evaluator.new.guardfile_include?('rspec)
+      #   => true
+      #
+      # @param [String] plugin_name the name of the Guard
+      # @return [Boolean] whether the Guard plugin has been declared
+      #
+      # TODO: rename this method to it matches RSpec examples better
+      def guardfile_include?(plugin_name)
+        reader = DslReader.new
+        reader.evaluate(@contents, @path || "", 1)
+        reader.plugin_names.include?(plugin_name)
+      end
+
+      attr_reader :path
+
+      def custom?
+        @type == :custom
+      end
+
+      # Gets the content of the `Guardfile` concatenated with the global
+      # user configuration file.
+      #
+      # @example Programmatically get the content of the current Guardfile
+      #   Guard::Guardfile::Evaluator.new.guardfile_contents
+      #   => "guard :rspec"
+      #
+      # @return [String] the Guardfile content
+      #
+      def guardfile_contents
+        config = File.read(_user_config_path) if File.exist?(_user_config_path)
+        [_guardfile_contents_without_user_config, config].compact.join("\n")
+      end
+
+      def inline?
+        @type == :inline
+      end
+
+      private
+
+      def _guardfile_contents_without_user_config
+        @guardfile_contents || ""
+      end
+
+      def _instance_eval_guardfile(contents)
+        Dsl.new.evaluate(contents, @guardfile_path || "", 1)
+      rescue => ex
+        UI.error "Invalid Guardfile, original error is:\n#{ $! }"
+        raise ex
+      end
+
+      def _fetch_guardfile_contents
+        _use_inline || _use_provided || _use_default
+        @evaluated = true
+
+        return if _guardfile_contents_usable?
+        UI.error "No Guard plugins found in Guardfile,"\
+          " please add at least one."
+      end
+
+      def _use_inline
+        source_from_option = @source.nil? && options[:guardfile_contents]
+        inline = @source == :inline
+
+        return false unless source_from_option || inline
+
+        @source = :inline
+        @guardfile_contents = options[:guardfile_contents]
+
+        UI.info "Using inline Guardfile."
+        true
+      end
+
+      def _use_provided
+        return unless custom?
+        @path, @contents = _read(@path)
+        true
+      rescue Errno::ENOENT
+        fail NoCustomGuardfile, "No Guardfile exists at #{ @path }."
+      end
+
+      def _use_default!
+        DEFAULT_GUARDFILES.each do |guardfile|
+          begin
+            @path, @contents = _read(guardfile)
+            @type = :default
+            break
+          rescue Errno::ENOENT
+            if guardfile == DEFAULT_GUARDFILES.last
+              fail NoGuardfileError, ERROR_NO_GUARDFILE
+            end
+          end
+        end
+      end
+
+      def _read(path)
+        full_path = Pathname.new(path.to_s).expand_path
+        [full_path, full_path.read]
+      rescue Errno::ENOENT
+        fail
+      rescue SystemCallError => e
+        UI.error "Error reading file #{full_path}:"
+        UI.error e.inspect
+        UI.error e.backtrace
+        abort
+      end
+
+      def _guardfile_contents
+        @user_config ||= Pathname.new("~/.guard.rb").expand_path.read
+        [@contents, @user_config].compact.join("\n")
+      rescue Errno::ENOENT
+        @contents || ""
+      end
+
+      def _guardfile_contents_usable?
+        guardfile_contents && guardfile_contents =~ /guard/m
+      end
+
+      def _from_deprecated(opts)
+        res = opts.dup
+        if opts.key?(:guardfile_contents)
+          res[:contents] = opts[:guardfile_contents]
+        end
+        res
+      end
+    end
+  end
+end