guard 1.8.3 → 2.0.0.pre

data/lib/guard/deprecator.rb

@@ -0,0 +1,107 @@
+require 'guard/ui'
+
+module Guard
+  class Deprecator
+
+    MORE_INFO_ON_UPGRADING_TO_GUARD_1_1 = <<-EOS.gsub(/^\s*/, '')
+      For more information on how to update existing Guard plugins, please head over
+      to: https://github.com/guard/guard/wiki/Upgrade-guide-for-existing-guards-to-Guard-v1.1
+    EOS
+
+    MORE_INFO_ON_UPGRADING_TO_GUARD_2 = <<-EOS.gsub(/^\s*/, '')
+      For more information on how to upgrade for Guard 2.0, please head over
+      to: https://github.com/guard/guard/wiki/Upgrading-to-Guard-2.0%s
+    EOS
+
+    ADD_GUARD_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
+      Starting with Guard 2.0 'Guard.add_guard(name, options = {})' is deprecated.
+
+      Please use 'Guard.add_plugin(name, options = {})' instead.
+
+      #{MORE_INFO_ON_UPGRADING_TO_GUARD_2 % '#deprecated-methods'}
+    EOS
+
+    GUARDS_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
+      Starting with Guard 2.0 'Guard.guards(filter)' is deprecated.
+
+      Please use 'Guard.plugins(filter)' instead.
+
+      #{MORE_INFO_ON_UPGRADING_TO_GUARD_2 % '#deprecated-methods'}
+    EOS
+
+    # Deprecator message for the `Guard.get_guard_class` method
+    GET_GUARD_CLASS_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
+      Starting with Guard 2.0 'Guard.get_guard_class(name, fail_gracefully =
+      false)' is deprecated and is now always on.
+
+      Please use 'Guard::PluginUtil.new(name).plugin_class(fail_gracefully:
+      fail_gracefully)' instead.
+
+      #{MORE_INFO_ON_UPGRADING_TO_GUARD_2 % '#deprecated-methods'}
+    EOS
+
+    # Deprecator message for the `Guard.locate_guard` method
+    LOCATE_GUARD_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
+      Starting with Guard 2.0 'Guard.locate_guard(name)' is deprecated.
+
+      Please use 'Guard::PluginUtil.new(name).plugin_location' instead.
+
+      #{MORE_INFO_ON_UPGRADING_TO_GUARD_2 % '#deprecated-methods'}
+    EOS
+
+    # Deprecator message for the `Guard.guard_gem_names` method
+    GUARD_GEM_NAMES_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
+      Starting with Guard 2.0 'Guard.guard_gem_names' is deprecated.
+
+      Please use 'Guard::PluginUtil.plugin_names' instead.
+
+      #{MORE_INFO_ON_UPGRADING_TO_GUARD_2 % '#deprecated-methods'}
+    EOS
+
+    # Deprecator message for the `Guard::Dsl.evaluate_guardfile` method
+    EVALUATE_GUARDFILE_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
+      Starting with Guard 2.0 'Guard::Dsl.evaluate_guardfile(options)' is deprecated.
+
+      Please use 'Guard::Guardfile::Evaluator.new(options).evaluate_guardfile' instead.
+
+      #{MORE_INFO_ON_UPGRADING_TO_GUARD_2 % '#deprecated-methods-1'}
+    EOS
+
+    # Deprecator message for the `Guardfile.create_guardfile` method
+    CREATE_GUARDFILE_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
+      Starting with Guard 2.0 'Guard::Guardfile.create_guardfile(options)' is deprecated.
+
+      Please use 'Guard::Guardfile::Generator.new(options).create_guardfile' instead.
+
+      #{MORE_INFO_ON_UPGRADING_TO_GUARD_2 % '#deprecated-methods-2'}
+    EOS
+
+    # Deprecator message for the `Guardfile.initialize_template` method
+    INITIALIZE_TEMPLATE_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
+      Starting with Guard 2.0 'Guard::Guardfile.initialize_template(plugin_name)' is deprecated.
+
+      Please use 'Guard::Guardfile::Generator.new.initialize_template(plugin_name)' instead.
+
+      #{MORE_INFO_ON_UPGRADING_TO_GUARD_2 % '#deprecated-methods-2'}
+    EOS
+
+    # Deprecator message for the `Guardfile.initialize_all_templates` method
+    INITIALIZE_ALL_TEMPLATES_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
+      Starting with Guard 2.0 'Guard::Guardfile.initialize_all_templates' is deprecated.
+
+      Please use 'Guard::Guardfile::Generator.new.initialize_all_templates' instead.
+
+      #{MORE_INFO_ON_UPGRADING_TO_GUARD_2 % '#deprecated-methods-2'}
+    EOS
+
+    # Deprecator message for when a Guard plugin inherits from Guard::Guard
+    GUARD_GUARD_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
+      Starting with Guard 2.0, Guard::%s should inherit from Guard::Plugin instead of Guard::Guard.
+
+      Please note that the constructor signature has changed from Guard::Guard#initialize(watchers = [], options = {}) to Guard::Plugin#initialize(options = {}).
+
+      #{MORE_INFO_ON_UPGRADING_TO_GUARD_2 % '#changes-in-guardguard'}
+    EOS
+
+  end
+end

data/lib/guard/dsl.rb

@@ -1,347 +1,159 @@
+require 'guard/guardfile'
+require 'guard/interactor'
+require 'guard/notifier'
+require 'guard/ui'
+require 'guard/watcher'
+
 module Guard
 
-  # The DSL class provides the methods that are used in each `Guardfile` to describe
-  # the behaviour of Guard.
+  # The Dsl class provides the methods that are used in each `Guardfile` to
+  # describe the behaviour of Guard.
   #
-  # The main keywords of the DSL are `guard` and `watch`. These are necessary to define
-  # the used Guard plugins and the file changes they are watching.
+  # The main keywords of the DSL are {#guard} and {#watch}. These are necessary
+  # to define the used Guard plugins and the file changes they are watching.
   #
-  # You can optionally group the Guard plugins with the `group` keyword and ignore and filter certain paths
-  # with the `ignore` and `filter` keywords.
+  # You can optionally group the Guard plugins with the {#group} keyword and
+  # ignore and filter certain paths with the {#ignore} and {#filter} keywords.
   #
-  # You can set your preferred system notification library with `notification` and pass
-  # some optional configuration options for the library. If you don't configure a library,
-  # Guard will automatically pick one with default options (if you don't want notifications,
-  # specify `:off` as library). @see ::Guard::Notifier for more information about the supported libraries.
+  # You can set your preferred system notification library with {#notification}
+  # and pass some optional configuration options for the library. If you don't
+  # configure a library, Guard will automatically pick one with default options
+  # (if you don't want notifications, specify `:off` as library). Please see
+  # {Notifier} for more information about the supported libraries.
   #
-  # A more advanced DSL use is the `callback` keyword that allows you to execute arbitrary
-  # code before or after any of the `start`, `stop`, `reload`, `run_all`, `run_on_changes`,
-  # `run_on_additions`, `run_on_modifications` and `run_on_removals` Guard plugins method.
-  # You can even insert more hooks inside these methods.
-  # Please [checkout the Wiki page](https://github.com/guard/guard/wiki/Hooks-and-callbacks) for more details.
+  # A more advanced DSL use is the {#callback} keyword that allows you to
+  # execute arbitrary code before or after any of the {Plugin::Base#start},
+  # {Plugin::Base#stop}, {Plugin::Base#reload}, {Plugin::Base#run_all},
+  # {Plugin::Base#run_on_changes}, {Plugin::Base#run_on_additions},
+  # {Plugin::Base#run_on_modifications} and {Plugin::Base#run_on_removals}
+  # Guard plugins method.
+  # You can even insert more hooks inside these methods. Please [checkout the
+  # Wiki page](https://github.com/guard/guard/wiki/Hooks-and-callbacks) for
+  # more details.
   #
   # The DSL will also evaluate normal Ruby code.
   #
   # There are two possible locations for the `Guardfile`:
-  # - The `Guardfile` in the current directory where Guard has been started
-  # - The `.Guardfile` in your home directory.
   #
-  # In addition, if a user configuration `.guard.rb` in your home directory is found, it will
-  # be appended to the current project `Guardfile`.
+  # * The `Guardfile` in the current directory where Guard has been started
+  # * The `.Guardfile` in your home directory.
+  #
+  # In addition, if a user configuration `.guard.rb` in your home directory is
+  # found, it will be appended to the current project `Guardfile`.
   #
   # @see https://github.com/guard/guard/wiki/Guardfile-examples
   #
   class Dsl
 
-    require 'guard'
-    require 'guard/dsl'
-    require 'guard/interactor'
-    require 'guard/notifier'
-    require 'guard/ui'
-    require 'guard/watcher'
-
-    # Deprecation message for the `ignore_paths` method
-    IGNORE_PATHS_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
-      Starting with Guard v1.1 the use of the 'ignore_paths' Guardfile DSL method is deprecated.
-
-      Please replace that method with the better 'ignore' or/and 'filter' methods.
-      Documentation on the README: https://github.com/guard/guard#ignore
-    EOS
-
-    # Deprecation message for the `interactor` method
-    INTERACTOR_DEPRECATION = <<-EOS.gsub(/^\s*/, '')
-      Starting with Guard v1.4 the use of the 'interactor' Guardfile DSL method is only used to
-      disable or pass options to the Pry interactor. All other usages are deprecated.
-    EOS
-
-    class << self
-
-      attr_accessor :options
-
-      # 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 = {})
-        raise ArgumentError.new('No option hash passed to evaluate_guardfile!') unless options.is_a?(Hash)
-
-        self.options = options.dup
-
-        fetch_guardfile_contents
-        instance_eval_guardfile(guardfile_contents_with_user_config)
-      end
-
-      # Re-evaluate the `Guardfile` to update the current Guard configuration.
-      #
-      def reevaluate_guardfile
-        before_reevaluate_guardfile
-        ::Guard::Dsl.evaluate_guardfile(options)
-        after_reevaluate_guardfile
-      end
-
-      # Stop Guard and clear internal state
-      # before the Guardfile will be re-evaluated.
-      #
-      def before_reevaluate_guardfile
-        ::Guard.runner.run(:stop)
-        ::Guard.guards.clear
-        ::Guard.setup_groups
-        ::Guard::Notifier.clear_notifications
-
-        options.delete(:guardfile_contents)
-      end
-
-      # Start Guard and notification and show a message
-      # after the Guardfile has been re-evaluated.
-      #
-      def after_reevaluate_guardfile
-        ::Guard::Notifier.turn_on if ::Guard::Notifier.enabled?
-
-        if ::Guard.guards.empty?
-          ::Guard::Notifier.notify('No guards found in Guardfile, please add at least one.', :title => 'Guard re-evaluate', :image => :failed)
-        else
-          msg = 'Guardfile has been re-evaluated.'
-          ::Guard::UI.info(msg)
-          ::Guard::Notifier.notify(msg, :title => 'Guard re-evaluate')
-
-          ::Guard.runner.run(:start)
-        end
-      end
-
-      # Evaluate the content of the `Guardfile`.
-      #
-      # @param [String] contents the content to evaluate.
-      #
-      def instance_eval_guardfile(contents)
-        new.instance_eval(contents, options[:guardfile_path], 1)
-      rescue
-        ::Guard::UI.error "Invalid Guardfile, original error is:\n#{ $! }"
-      end
-
-      # Test if the current `Guardfile` contains a specific Guard plugin.
-      #
-      # @param [String] guard_name the name of the Guard
-      # @return [Boolean] whether the Guard has been declared
-      #
-      def guardfile_include?(guard_name)
-        guardfile_contents.match(/^guard\s*\(?\s*['":]#{ guard_name }['"]?/)
-      end
-
-      # Read the current `Guardfile` content.
-      #
-      # @param [String] guardfile_path the path to the Guardfile
-      #
-      def read_guardfile(guardfile_path)
-        options[:guardfile_path]     = guardfile_path
-        options[:guardfile_contents] = File.read(guardfile_path)
-      rescue
-        ::Guard::UI.error("Error reading file #{ guardfile_path }")
-        exit 1
-      end
-
-      # Get the content to evaluate and stores it into
-      # the options as `:guardfile_contents`.
-      #
-      def fetch_guardfile_contents
-        if options[:guardfile_contents]
-          ::Guard::UI.info 'Using inline Guardfile.'
-          options[:guardfile_path] = 'Inline Guardfile'
-
-        elsif options[:guardfile]
-          if File.exist?(options[:guardfile])
-            read_guardfile(options[:guardfile])
-            ::Guard::UI.info "Using Guardfile at #{ options[:guardfile] }."
-          else
-            ::Guard::UI.error "No Guardfile exists at #{ options[:guardfile] }."
-            exit 1
-          end
-
-        else
-          if File.exist?(guardfile_default_path)
-            read_guardfile(guardfile_default_path)
-          else
-            ::Guard::UI.error 'No Guardfile found, please create one with `guard init`.'
-            exit 1
-          end
-        end
-
-        unless guardfile_contents_usable?
-          ::Guard::UI.error 'No Guard plugins found in Guardfile, please add at least one.'
-        end
-      end
-
-      # Get the content of the `Guardfile`.
-      #
-      # @return [String] the Guardfile content
-      #
-      def guardfile_contents
-        options ? options[:guardfile_contents] : ''
-      end
-
-      # Get the content of the `Guardfile` and the global
-      # user configuration file.
-      #
-      # @see #user_config_path
-      #
-      # @return [String] the Guardfile content
-      #
-      def guardfile_contents_with_user_config
-        config = File.read(user_config_path) if File.exist?(user_config_path)
-        [guardfile_contents, config].join("\n")
-      end
-
-      # Get the file path to the project `Guardfile`.
-      #
-      # @return [String] the path to the Guardfile
-      #
-      def guardfile_path
-        options ? options[:guardfile_path] : ''
-      end
-
-      # Tests if the current `Guardfile` content is usable.
-      #
-      # @return [Boolean] if the Guardfile is usable
-      #
-      def guardfile_contents_usable?
-        guardfile_contents && guardfile_contents.size >= 'guard :a'.size # Smallest Guard definition
-      end
-
-      # Gets the default path of the `Guardfile`. This returns the `Guardfile`
-      # from the current directory when existing, or the global `.Guardfile`
-      # at the home directory.
-      #
-      # @return [String] the path to the Guardfile
-      #
-      def guardfile_default_path
-        File.exist?(local_guardfile_path) ? local_guardfile_path : home_guardfile_path
-      end
-
-      private
-
-      # The path to the `Guardfile` that is located at
-      # the directory, where Guard has been started from.
-      #
-      # @return [String] the path to the local Guardfile
-      #
-      def local_guardfile_path
-        File.join(Dir.pwd, 'Guardfile')
-      end
-
-      # The path to the `.Guardfile` that is located at
-      # the users home directory.
-      #
-      # @return [String] the path to ~/.Guardfile
-      #
-      def home_guardfile_path
-        File.expand_path(File.join('~', '.Guardfile'))
-      end
-
-      # The path to the user configuration `.guard.rb`
-      # that is located at the users home directory.
-      #
-      # @return [String] the path to ~/.guard.rb
-      #
-      def user_config_path
-        File.expand_path(File.join('~', '.guard.rb'))
-      end
-
+    # @deprecated Use
+    #   `Guard::Guardfile::Evaluator.new(options).evaluate_guardfile` instead.
+    #
+    # @see https://github.com/guard/guard/wiki/Upgrading-to-Guard-2.0 How to
+    #   upgrade for Guard 2.0
+    #
+    def self.evaluate_guardfile(options = {})
+      ::Guard::UI.deprecation(::Guard::Deprecator::EVALUATE_GUARDFILE_DEPRECATION)
+      ::Guard::Guardfile::Evaluator.new(options).evaluate_guardfile
     end
 
     # Set notification options for the system notifications.
-    # You can set multiple notification, which allows you to show local
+    # You can set multiple notifications, which allows you to show local
     # system notifications and remote notifications with separate libraries.
     # You can also pass `:off` as library to turn off notifications.
     #
     # @example Define multiple notifications
     #   notification :growl_notify
-    #   notification :ruby_gntp, :host => '192.168.1.5'
-    #
-    # @see Guard::Notifier for available notifier and its options.
+    #   notification :ruby_gntp, host: '192.168.1.5'
     #
     # @param [Symbol, String] notifier the name of the notifier to use
     # @param [Hash] options the notification library options
     #
+    # @see Guard::Notifier for available notifier and its options.
+    #
     def notification(notifier, options = {})
-      ::Guard::Notifier.add_notification(notifier.to_sym, options, false)
+      ::Guard::Notifier.add_notifier(notifier.to_sym, options.merge(silent: false))
     end
 
-    # Sets the interactor to use.
+    # Sets the interactor options or disable the interactor.
+    #
+    # @example Pass options to the interactor
+    #   interactor option1: 'value1', option2: 'value2'
     #
     # @example Turn off interactions
     #   interactor :off
     #
-    # @param [Symbol,Hash] options either `:off` or a Hash with interactor options
+    # @param [Symbol, Hash] options either `:off` or a Hash with interactor
+    #   options
     #
     def interactor(options)
-      if options == :off
+      case options
+      when :off
         ::Guard::Interactor.enabled = false
-
-      elsif options.is_a?(Hash)
+      when Hash
         ::Guard::Interactor.options = options
-
-      else
-        ::Guard::UI.deprecation(INTERACTOR_DEPRECATION)
       end
     end
 
-    # Declares a group of Guard plugins to be run with `guard start --group group_name`.
+    # Declares a group of Guard plugins to be run with `guard start --group
+    #   group_name`.
     #
     # @example Declare two groups of Guard plugins
-    #
-    #   group 'backend' do
-    #     guard 'spork'
-    #     guard 'rspec'
+    #   group :backend do
+    #     guard :spork
+    #     guard :rspec
     #   end
     #
-    #   group 'frontend' do
-    #     guard 'passenger'
-    #     guard 'livereload'
+    #   group :frontend do
+    #     guard :passenger
+    #     guard :livereload
     #   end
     #
     # @param [Symbol, String] name the group name called from the CLI
     # @param [Hash] options the options accepted by the group
-    # @yield a block where you can declare several guards
+    # @yield a block where you can declare several Guard plugins
     #
+    # @see Group
     # @see Guard.add_group
-    # @see Dsl#guard
-    # @see Guard::DslDescriber
+    # @see #guard
     #
     def group(name, options = {})
-      name = name.to_sym
+      raise ArgumentError, "'all' is not an allowed group name!" if name.to_sym == :all
 
       if block_given?
-        ::Guard.add_group(name.to_s.downcase, options)
+        ::Guard.add_group(name, options)
         @current_group = name
 
-        yield if block_given?
+        yield
 
         @current_group = nil
+      else
+        ::Guard::UI.error "No Guard plugins found in the group '#{ name }', please add at least one."
       end
     end
 
-    # Declare a Guard plugin to be used when running `guard start`.
+    # Declares a Guard plugin to be used when running `guard start`.
     #
     # The name parameter is usually the name of the gem without
     # the 'guard-' prefix.
     #
     # The available options are different for each Guard implementation.
     #
-    # @example Declare a Guard
+    # @example Declare a Guard without `watch` patterns
+    #   guard :rspec
     #
-    #   guard 'rspec' do
+    # @example Declare a Guard with a `watch` pattern
+    #   guard :rspec do
+    #     watch %r{.*_spec.rb}
     #   end
     #
-    # @param [String] name the Guard name
-    # @param [Hash] options the options accepted by the Guard
+    # @param [String] name the Guard plugin name
+    # @param [Hash] options the options accepted by the Guard plugin
     # @yield a block where you can declare several watch patterns and actions
     #
-    # @see Guard.add_guard
-    # @see Dsl#group
-    # @see Dsl#watch
-    # @see Guard::DslDescriber
+    # @see Plugin
+    # @see Guard.add_plugin
+    # @see #watch
+    # @see #group
     #
     def guard(name, options = {})
       @watchers  = []
@@ -350,129 +162,137 @@ module Guard
 
       yield if block_given?
 
-      options.update(:group => @current_group)
-      ::Guard.add_guard(name.to_s.downcase, @watchers, @callbacks, options)
+      options.merge!(group: @current_group, watchers: @watchers, callbacks: @callbacks)
+      ::Guard.add_plugin(name, options)
     end
 
-    # Define a pattern to be watched in order to run actions on file modification.
+    # Defines a pattern to be watched in order to run actions on file modification.
     #
     # @example Declare watchers for a Guard
-    #
-    #   guard 'rspec' do
+    #   guard :rspec do
     #     watch('spec/spec_helper.rb')
     #     watch(%r{^.+_spec.rb})
     #     watch(%r{^app/controllers/(.+).rb}) { |m| 'spec/acceptance/#{m[1]}s_spec.rb' }
     #   end
     #
-    # @param [String, Regexp] pattern the pattern to be watched by the guard
+    # @param [String, Regexp] pattern the pattern that Guard must watch for modification
     # @yield a block to be run when the pattern is matched
     # @yieldparam [MatchData] m matches of the pattern
     # @yieldreturn a directory, a filename, an array of directories / filenames, or nothing (can be an arbitrary command)
     #
     # @see Guard::Watcher
-    # @see Dsl#guard
+    # @see #guard
     #
     def watch(pattern, &action)
       @watchers << ::Guard::Watcher.new(pattern, action)
     end
 
-    # Define a callback to execute arbitrary code before or after any of
-    # the `start`, `stop`, `reload`, `run_all`, `run_on_changes` `run_on_additions`, `run_on_modifications`
-    # and `run_on_removals` plugin method.
+    # Defines a callback to execute arbitrary code before or after any of
+    # the `start`, `stop`, `reload`, `run_all`, `run_on_changes`,
+    # `run_on_additions`, `run_on_modifications` and `run_on_removals` plugin
+    # method.
     #
-    # @param [Array] args the callback arguments
-    # @yield a block with listeners
+    # @example Define a callback that'll be called before the `reload` action.
+    #   callback(:reload_begin) { puts "Let's reload!" }
     #
-    # @see Guard::Hook
+    # @example Define a callback that'll be called before the `start` and `stop` actions.
+    #   my_lambda = lambda { |plugin, event, *args| puts "Let's #{event} #{plugin} with #{args}!" }
+    #   callback(my_lambda, [:start_begin, :start_end])
     #
-    def callback(*args, &listener)
-      listener, events = args.size > 1 ? args : [listener, args[0]]
-      @callbacks << { :events => events, :listener => listener }
-    end
-
-    # @deprecated Ignore certain paths globally.
-    #
-    # @example Ignore some paths
-    #   ignore_paths ".git", ".svn"
+    # @param [Array] args the callback arguments
+    # @yield a callback block
     #
-    # @param [Array] paths the list of paths to ignore
+    # @see Guard::Hooker
     #
-    def ignore_paths(*paths)
-      ::Guard::UI.deprecation(IGNORE_PATHS_DEPRECATION)
+    def callback(*args, &block)
+      block, events = if args.size > 1
+        # block must be the first argument in that case, the yielded block is
+        # ignored
+        args
+      else
+        [block, args[0]]
+      end
+      @callbacks << { events: events, listener: block }
     end
 
-    # Ignore certain paths globally.
+    # Ignores certain paths globally.
     #
     # @example Ignore some paths
     #   ignore %r{^ignored/path/}, /man/
     #
-    # @param [Regexp] regexps a pattern for ignoring paths
+    # @param [Regexp] regexps a pattern (or list of patterns) for ignoring paths
     #
     def ignore(*regexps)
       ::Guard.listener = ::Guard.listener.ignore(*regexps) if ::Guard.listener
     end
 
-    # Replace ignored paths globally
+    # Replaces ignored paths globally
     #
     # @example Ignore only these paths
     #   ignore! %r{^ignored/path/}, /man/
     #
-    # @param [Regexp] regexps a pattern for ignoring paths
+    # @param [Regexp] regexps a pattern (or list of patterns) for ignoring paths
     #
     def ignore!(*regexps)
       ::Guard.listener = ::Guard.listener.ignore!(*regexps) if ::Guard.listener
     end
 
-    # Filter certain paths globally.
+    # Filters certain paths globally.
     #
     # @example Filter some files
     #   filter /\.txt$/, /.*\.zip/
     #
-    # @param [Regexp] regexps a pattern for filtering paths
+    # @param [Regexp] regexps a pattern (or list of patterns) for filtering
+    #   paths
     #
     def filter(*regexps)
       ::Guard.listener = ::Guard.listener.filter(*regexps) if ::Guard.listener
     end
 
-    # Replace filtered paths globally.
+    # Replaces filtered paths globally.
     #
     # @example Filter only these files
     #   filter! /\.txt$/, /.*\.zip/
     #
-    # @param [Regexp] regexps a pattern for filtering paths
+    # @param [Regexp] regexps a pattern (or list of patterns) for filtering
+    #   paths
     #
     def filter!(*regexps)
       ::Guard.listener = ::Guard.listener.filter!(*regexps) if ::Guard.listener
     end
 
-    # Configure the Guard logger.
+    # Configures the Guard logger.
     #
     # * Log level must be either `:debug`, `:info`, `:warn` or `:error`.
-    # * Template supports the following placeholders: `:time`, `:severity`, `:progname`, `:pid`, `:unit_of_work_id` and `:message`
-    # * Time format directives are the same as Time#strftime or :milliseconds
-    # * The `:only` and `:except` options must be a RegExp.
+    # * Template supports the following placeholders: `:time`, `:severity`,
+    #   `:progname`, `:pid`, `:unit_of_work_id` and `:message`.
+    # * Time format directives are the same as `Time#strftime` or
+    #   `:milliseconds`.
+    # * The `:only` and `:except` options must be a `RegExp`.
     #
     # @example Set the log level
-    #   logger :level => :warn
+    #   logger level: :warn
     #
     # @example Set a custom log template
-    #   logger :template => '[Guard - :severity - :progname - :time] :message'
+    #   logger template: '[Guard - :severity - :progname - :time] :message'
     #
     # @example Set a custom time format
-    #   logger :time_format => '%h'
+    #   logger time_format: '%h'
     #
     # @example Limit logging to a Guard plugin
-    #   logger :only => :jasmine
+    #   logger only: :jasmine
     #
     # @example Log all but not the messages from a specific Guard plugin
-    #   logger :except => :jasmine
+    #   logger except: :jasmine
     #
     # @param [Hash] options the log options
     # @option options [String, Symbol] level the log level
     # @option options [String] template the logger template
     # @option options [String, Symbol] time_format the time format
-    # @option options [RegExp] only show only messages from the matching Guard plugin
-    # @option options [RegExp] except does not show messages from the matching Guard plugin
+    # @option options [Regexp] only show only messages from the matching Guard
+    #   plugin
+    # @option options [Regexp] except does not show messages from the matching
+    #   Guard plugin
     #
     def logger(options)
       if options[:level]
@@ -499,35 +319,29 @@ module Guard
         end
       end
 
-      ::Guard::UI.options = ::Guard::UI.options.merge options
+      ::Guard::UI.options = ::Guard::UI.options.marshal_dump.merge options
     end
 
     # Sets the default scope on startup
     #
     # @example Scope Guard to a single group
-    #   scope :group => :frontend
+    #   scope group: :frontend
     #
     # @example Scope Guard to multiple groups
-    #   scope :groups => [:specs, :docs]
+    #   scope groups: [:specs, :docs]
     #
     # @example Scope Guard to a single plugin
-    #   scope :plugin => :test
+    #   scope plugin: :test
     #
     # @example Scope Guard to multiple plugins
-    #   scope :plugins => [:jasmine, :rspec]
+    #   scope plugins: [:jasmine, :rspec]
     #
     # @param [Hash] scopes the scope for the groups and plugins
     #
-    def scope(scopes = {})
-      if ::Guard.options[:plugin].empty?
-        ::Guard.options[:plugin] = [scopes[:plugin]] if scopes[:plugin]
-        ::Guard.options[:plugin] = scopes[:plugins]  if scopes[:plugins]
-      end
-
-      if ::Guard.options[:group].empty?
-        ::Guard.options[:group] = [scopes[:group]] if scopes[:group]
-        ::Guard.options[:group] = scopes[:groups]  if scopes[:groups]
-      end
+    def scope(scope = {})
+      scope[:plugins] = Array(scope[:plugins] || scope[:plugin] || [])
+      scope[:groups] = Array(scope[:groups] || scope[:group] || [])
+      ::Guard.setup_scope(scope)
     end
 
   end