guard 0.8.8 → 0.9.0

data/lib/guard.rb

@@ -21,7 +21,7 @@ module Guard
   class << self
     attr_accessor :options, :interactor, :listener, :lock
 
-    # Creates the initial Guardfile template or add a Guard implementation
+    # Creates the initial Guardfile template and/or add a Guard implementation
     # Guardfile template to an existing Guardfile.
     #
     # @see Guard::Guard.init
@@ -43,45 +43,54 @@ module Guard
       end
     end
 
-    # Initialize the Guard singleton.
+    # Initialize the Guard singleton:
+    #
+    # - Initialize the internal Guard state.
+    # - Create the interactor when necessary for user interaction.
+    # - Select and initialize the file change listener.
     #
     # @option options [Boolean] clear if auto clear the UI should be done
     # @option options [Boolean] notify if system notifications should be shown
-    # @option options [Boolean] debug if debug output should be shown
+    # @option options [Boolean] verbose if verbose output should be shown
     # @option options [Array<String>] group the list of groups to start
     # @option options [String] watchdir the director to watch
     # @option options [String] guardfile the path to the Guardfile
     # @option options [Boolean] watch_all_modifications watches all file modifications if true
     #
     def setup(options = {})
-      @lock = Mutex.new
-
+      @lock       = Mutex.new
       @options    = options
       @guards     = []
       self.reset_groups
-      @interactor = Interactor.new unless @options[:no_interactions]
-      @listener   = Listener.select_and_init(@options[:watchdir] ? File.expand_path(@options[:watchdir]) : Dir.pwd, options)
-
-      @options[:notify] && ENV['GUARD_NOTIFY'] != 'false' ? Notifier.turn_on : Notifier.turn_off
+      @interactor = Interactor.new unless options[:no_interactions]
+      @listener   = Listener.select_and_init(options[:watchdir] && File.expand_path(options[:watchdir]), options)
 
       UI.clear if @options[:clear]
-
-      debug_command_execution if @options[:debug]
+      debug_command_execution if @options[:verbose]
 
       self
     end
 
     # Smart accessor for retrieving a specific guard or several guards at once.
     #
-    # @param [String, Symbol] filter return the guard with the given name, or nil if not found
-    # @param [Regexp] filter returns all guards matching the Regexp, or [] if no guard found
-    # @param [Hash] filter returns all guards matching the given Hash.
-    #   Example: `{ :name => 'rspec', :group => 'backend' }`, or [] if no guard found
-    # @param [NilClass] filter returns all guards
-    #
     # @see Guard.groups
     #
+    # @example Filter Guards by String or Symbol
+    #   Guard.guards('rspec')
+    #   Guard.guards(:rspec)
+    #
+    # @example Filter Guards by Regexp
+    #   Guard.guards(/rsp.+/)
+    #
+    # @example Filter Guards by Hash
+    #   Guard.guards({ :name => 'rspec', :group => 'backend' })
+    #
+    # @param [String, Symbol, Regexp, Hash] filter the filter to apply to the Guards
+    # @return [Array<Guard>] the filtered Guards
+    #
     def guards(filter = nil)
+      @guards ||= []
+
       case filter
       when String, Symbol
         @guards.find { |guard| guard.class.to_s.downcase.sub('guard::', '') == filter.to_s.downcase.gsub('-', '') }
@@ -102,12 +111,18 @@ module Guard
 
     # Smart accessor for retrieving a specific group or several groups at once.
     #
-    # @param [NilClass] filter returns all groups
-    # @param [String, Symbol] filter return the group with the given name, or nil if not found
-    # @param [Regexp] filter returns all groups matching the Regexp, or [] if no group found
-    #
     # @see Guard.guards
     #
+    # @example Filter groups by String or Symbol
+    #   Guard.groups('backend')
+    #   Guard.groups(:backend)
+    #
+    # @example Filter groups by Regexp
+    #   Guard.groups(/(back|front)end/)
+    #
+    # @param [String, Symbol, Regexp] filter the filter to apply to the Groups
+    # @return [Array<Group>] the filtered groups
+    #
     def groups(filter = nil)
       case filter
       when String, Symbol
@@ -129,6 +144,13 @@ module Guard
 
     # Start Guard by evaluate the `Guardfile`, initialize the declared Guards
     # and start the available file change listener.
+    # Main method for Guard that is called from the CLI when guard starts.
+    #
+    # - Setup Guard internals
+    # - Evaluate the `Guardfile`
+    # - Configure Notifiers
+    # - Initialize the declared Guards
+    # - Start the available file change listener
     #
     # @option options [Boolean] clear if auto clear the UI should be done
     # @option options [Boolean] notify if system notifications should be shown
@@ -142,6 +164,8 @@ module Guard
 
       Dsl.evaluate_guardfile(options)
 
+      options[:notify] && ENV['GUARD_NOTIFY'] != 'false' ? Notifier.turn_on : Notifier.turn_off
+
       listener.on_change do |files|
         Dsl.reevaluate_guardfile        if Watcher.match_guardfile?(files)
         listener.changed_files += files if Watcher.match_files?(guards, files)
@@ -172,7 +196,7 @@ module Guard
 
     # Reload all Guards currently enabled.
     #
-    # @param [Hash] An hash with a guard or a group scope
+    # @param [Hash] scopes an hash with a guard or a group scope
     #
     def reload(scopes)
       run do
@@ -184,7 +208,7 @@ module Guard
 
     # Trigger `run_all` on all Guards currently enabled.
     #
-    # @param [Hash] An hash with a guard or a group scope
+    # @param [Hash] scopes an hash with a guard or a group scope
     #
     def run_all(scopes)
       run do
@@ -236,16 +260,17 @@ module Guard
       end
     end
 
-    # Loop through all groups and run the given task (as block) for each Guard.
+    # Loop through all groups and run the given task for each Guard.
     #
     # Stop the task run for the all Guards within a group if one Guard
     # throws `:task_has_failed`.
     #
-    # @param [Hash] An hash with a guard or a group scope
+    # @param [Hash] scopes an hash with a guard or a group scope
+    # @yield the task to run
     #
     def run_on_guards(scopes = {})
-      if guard = scopes[:guard]
-        yield(guard)
+      if scope_guard = scopes[:guard]
+        yield(scope_guard)
       else
         groups = scopes[:group] ? [scopes[:group]] : @groups
         groups.each do |group|
@@ -390,7 +415,17 @@ module Guard
       group
     end
 
-    # Tries to load the Guard main class.
+    # Tries to load the Guard main class. This transforms the supplied Guard
+    # name into a class name:
+    #
+    # * `guardname` will become `Guard::Guardname`
+    # * `dashed-guard-name` will become `Guard::DashedGuardName`
+    # * `underscore_guard_name` will become `Guard::UnderscoreGuardName`
+    #
+    # When no class is found with the strict case sensitive rules, another
+    # try is made to locate the class without matching case:
+    #
+    # * `rspec` will find a class `Guard::RSpec`
     #
     # @param [String] name the name of the Guard
     # @return [Class, nil] the loaded class
@@ -398,10 +433,10 @@ module Guard
     def get_guard_class(name)
       name        = name.to_s
       try_require = false
-      const_name  = name.downcase.gsub('-', '')
+      const_name  = name.gsub(/\/(.?)/) { "::#{ $1.upcase }" }.gsub(/(?:^|[_-])(.)/) { $1.upcase }
       begin
         require "guard/#{ name.downcase }" if try_require
-        self.const_get(self.constants.find { |c| c.to_s.downcase == const_name })
+        self.const_get(self.constants.find { |c| c.to_s == const_name } || self.constants.find { |c| c.to_s.downcase == const_name.downcase })
       rescue TypeError
         unless try_require
           try_require = true
@@ -439,7 +474,7 @@ module Guard
         Gem::Specification.find_all.select { |x| x.name =~ /^guard-/ }
       else
         Gem.source_index.find_name(/^guard-/)
-      end.map { |x| x.name.sub /^guard-/, '' }
+      end.map { |x| x.name.sub(/^guard-/, '') }
     end
 
     # Adds a command logger in debug mode. This wraps common command

data/lib/guard/cli.rb

@@ -25,11 +25,11 @@ module Guard
                   :aliases => '-n',
                   :banner  => 'Notifications feature (growl/libnotify)'
 
-    method_option :debug,
+    method_option :verbose,
                   :type    => :boolean,
                   :default => false,
-                  :aliases => '-d',
-                  :banner  => 'Print debug messages'
+                  :aliases => '-v',
+                  :banner  => 'Show verbose messages'
 
     method_option :group,
                   :type    => :array,
@@ -47,6 +47,12 @@ module Guard
                   :aliases => '-G',
                   :banner  => 'Specify a Guardfile'
 
+    method_option :no_vendor,
+                  :type    => :boolean,
+                  :default => false,
+                  :aliases => '-I',
+                  :banner  => 'Ignore vendored dependencies'
+
     method_option :watch_all_modifications,
                   :type => :boolean,
                   :default => false,

data/lib/guard/dsl.rb

@@ -9,6 +9,11 @@ module Guard
   # You can optionally group the Guards with the `group` keyword and ignore certain paths
   # with the `ignore_paths` keyword.
   #
+  # 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.
+  #
   # 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` and `run_on_change`
   # Guards' method. You can even insert more hooks inside these methods.
@@ -25,6 +30,8 @@ module Guard
   #
   # @example A sample of a complex Guardfile
   #
+  #   notification :growl
+  #
   #   group 'frontend' do
   #     guard 'passenger', :ping => true do
   #       watch('config/application.rb')
@@ -102,6 +109,7 @@ module Guard
       def reevaluate_guardfile
         ::Guard.guards.clear
         ::Guard.reset_groups
+        ::Guard::Notifier.notifications.clear
         @@options.delete(:guardfile_contents)
         Dsl.evaluate_guardfile(@@options)
         msg = 'Guardfile has been re-evaluated.'
@@ -131,7 +139,7 @@ module Guard
 
       # Read the current `Guardfile` content.
       #
-      # @param [String] the path to the Guardfile
+      # @param [String] guardfile_path the path to the Guardfile
       #
       def read_guardfile(guardfile_path)
         @@options[:guardfile_path]     = guardfile_path
@@ -224,7 +232,7 @@ module Guard
       # The path to the `Guardfile` that is located at
       # the directory, where Guard has been started from.
       #
-      # @param [String] the path to the local Guardfile
+      # @return [String] the path to the local Guardfile
       #
       def local_guardfile_path
         File.join(Dir.pwd, 'Guardfile')
@@ -233,7 +241,7 @@ module Guard
       # The path to the `.Guardfile` that is located at
       # the users home directory.
       #
-      # @param [String] the path to ~/.Guardfile
+      # @return [String] the path to ~/.Guardfile
       #
       def home_guardfile_path
         File.expand_path(File.join('~', '.Guardfile'))
@@ -242,7 +250,7 @@ module Guard
       # The path to the user configuration `.guard.rb`
       # that is located at the users home directory.
       #
-      # @param [String] the path to ~/.guard.rb
+      # @return [String] the path to ~/.guard.rb
       #
       def user_config_path
         File.expand_path(File.join('~', '.guard.rb'))
@@ -250,6 +258,24 @@ module Guard
 
     end
 
+    # Set notification options for the system notifications.
+    # You can set multiple notification, 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.
+    #
+    # @param [Symbol, String] notifier the name of the notifier to use
+    # @param [Hash] options the notification library options
+    #
+    def notification(notifier, options = {})
+      ::Guard::Notifier.add_notification(notifier.to_sym, options, false)
+    end
+
     # Declares a group of guards to be run with `guard start --group group_name`.
     #
     # @example Declare two groups of Guards
@@ -310,10 +336,11 @@ module Guard
     def guard(name, options = {})
       @watchers  = []
       @callbacks = []
+      @current_group ||= :default
 
       yield if block_given?
 
-      options.update(:group => (@current_group || :default))
+      options.update(:group => @current_group)
       ::Guard.add_guard(name.to_s.downcase, @watchers, @callbacks, options)
     end
 

data/lib/guard/dsl_describer.rb

@@ -47,7 +47,7 @@ module Guard
       def list(options)
         evaluate_guardfile(options)
 
-        installed = guardfile_structure.inject([]) do |installed, group|
+        installed_guards = guardfile_structure.inject([]) do |installed, group|
           group[:guards].each { |guard| installed << guard[:name] } if group[:guards]
           installed
         end
@@ -55,7 +55,7 @@ module Guard
         UI.info 'Available guards:'
 
         ::Guard.guard_gem_names.sort.uniq.each do |name|
-          UI.info "   #{ name }#{ installed.include?(name) ? '*' : '' }"
+          UI.info "   #{ name }#{ installed_guards.include?(name) ? '*' : '' }"
         end
 
         UI.info ''
@@ -141,6 +141,7 @@ module Guard
     # @see Guard::Dsl#guard
     #
     def guard(name, options = { })
+      @group ||= false
       node = (@group ? @@guardfile_structure.last : @@guardfile_structure.first)
 
       node[:guards] << { :name => name, :options => options }

data/lib/guard/guard.rb

@@ -42,8 +42,8 @@ module 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
+    # @option options [Symbol] group the group this Guard belongs to
+    # @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

data/lib/guard/interactor.rb

@@ -1,52 +1,66 @@
+require 'readline'
+
 module Guard
 
   # The interactor reads user input and triggers
   # specific action upon them unless its locked.
   #
+  # It used the readline library for history and
+  # completion support.
+  #
   # Currently the following actions are implemented:
   #
-  # - stop, quit, exit, s, q, e => Exit Guard
-  # - reload, r, z => Reload Guard
-  # - pause, p => Pause Guard
-  # - Everything else => Run all
+  # - h, help         => Show help
+  # - e, exit         => Exit Guard
+  # - r, reload       => Reload Guard
+  # - p, pause        => Toggle file modification listener
+  # - n, notification => Toggle notifications
+  # - <enter>         => Run all
   #
   # It's also possible to scope `reload` and `run all` actions to only a specified group or a guard.
   #
-  # @example `backend reload` will only reload backend group
-  # @example `spork reload` will only reload rspec guard
-  # @example `jasmine` will only run all jasmine specs
+  # @example Reload backend group
+  #   backend reload
+  #
+  # @example Reload rspec guard
+  #   spork reload
+  #
+  # @example Run all jasmine specs
+  #   jasmine
   #
   class Interactor
 
-    STOP_ACTIONS   = %w[stop quit exit s q e]
-    RELOAD_ACTIONS = %w[reload r z]
-    PAUSE_ACTIONS  = %w[pause p]
+    HELP_ENTRIES         = %w[help h]
+    RELOAD_ENTRIES       = %w[reload r]
+    STOP_ENTRIES         = %w[exit e]
+    PAUSE_ENTRIES        = %w[pause p]
+    NOTIFICATION_ENTRIES = %w[notification n]
 
-    # Start the interactor in its own thread.
+    COMPLETION_ACTIONS   = %w[help reload exit pause notification]
+
+    # Initialize the interactor.
     #
-    def start
-      return if ENV["GUARD_ENV"] == 'test'
-
-      if !@thread || !@thread.alive?
-        @thread = Thread.new do
-          while entry = $stdin.gets.chomp
-            scopes, action = extract_scopes_and_action(entry)
-            case action
-            when :stop
-              ::Guard.stop
-            when :pause
-              ::Guard.pause
-            when :reload
-              ::Guard::Dsl.reevaluate_guardfile if scopes.empty?
-              ::Guard.reload(scopes)
-            when :run_all
-              ::Guard.run_all(scopes)
-            end
-          end
-        end
+    def initialize
+      unless defined?(RbReadline) || defined?(JRUBY_VERSION)
+        ::Guard::UI.info 'Please add rb-readline for proper Readline support.'
+      end
+      
+      Readline.completion_proc = proc { |word| auto_complete(word) }
+
+      begin
+        Readline.completion_append_character = ' '
+      rescue NotImplementedError
+        # Ignore, we just don't support it then
       end
     end
 
+    # Start the line reader in its own thread.
+    #
+    def start
+      return if ENV['GUARD_ENV'] == 'test'
+      @thread = Thread.new { read_line } if !@thread || !@thread.alive?
+    end
+
     # Kill interactor thread if not current
     #
     def stop
@@ -54,18 +68,128 @@ module Guard
         @thread.kill
       end
     end
-    
-    # Extract guard or group scope and action from Interactor entry
+
+    # Read a line from stdin with Readline.
+    #
+    def read_line
+      while line = Readline.readline(prompt, true)
+        process_input(line)
+      end
+    end
+
+    # Auto complete the given word.
+    #
+    # @param [String] word the partial word
+    # @return [Array<String>] the matching words
+    #
+    def auto_complete(word)
+      completion_list.grep(/^#{ Regexp.escape(word) }/)
+    end
+
+    # Get the auto completion list.
+    #
+    # @return [Array<String>] the list of words
+    #
+    def completion_list
+      groups = ::Guard.groups.map { |group| group.name.to_s }
+      guards = ::Guard.guards.map { |guard| guard.class.to_s.downcase.sub('guard::', '') }
+
+      COMPLETION_ACTIONS + groups + guards - ['default']
+    end
+
+    # The current interactor prompt
+    #
+    # @return [String] the prompt to show
+    #
+    def prompt
+      ::Guard.listener.paused? ? 'p> ' : '> '
+    end
+
+    # Process the input from readline.
+    #
+    # @param [String] line the input line
+    #
+    def process_input(line)
+      if line =~ /^\s*$/ or Readline::HISTORY.to_a[-2] == line
+        Readline::HISTORY.pop
+      end
+
+      scopes, action = extract_scopes_and_action(line)
+
+      case action
+      when :help
+        help
+      when :stop
+        ::Guard.stop
+      when :pause
+        ::Guard.pause
+      when :reload
+        reload(scopes)
+      when :run_all
+        ::Guard.run_all(scopes)
+      when :notification
+        toggle_notification
+      else
+        ::Guard::UI.error "Unknown command #{ line }"
+      end
+    end
+
+    # Execute the reload action.
+    #
+    # @param [Hash] scopes the reload scopes
+    #
+    def reload(scopes)
+      ::Guard::UI.info 'Reload'
+      ::Guard::Dsl.reevaluate_guardfile if scopes.empty?
+      ::Guard.reload(scopes)
+    end
+
+    # Toggle the system notifications on/off
+    #
+    def toggle_notification
+      if ENV['GUARD_NOTIFY'] == 'true'
+        ::Guard::UI.info 'Turn off notifications'
+        ::Guard::Notifier.turn_off
+      else
+        ::Guard::Notifier.turn_on
+      end
+    end
+
+    # Show the help.
+    #
+    def help
+      puts ''
+      puts 'e, exit          Exit Guard'
+      puts 'p, pause         Toggle file modification listener'
+      puts 'r, reload        Reload Guard'
+      puts 'n, notification  Toggle notifications'
+      puts '<enter>          Run all Guards'
+      puts ''
+      puts 'You can scope the reload action to a specific guard or group:'
+      puts ''
+      puts 'rspec reload     Reload the RSpec Guard'
+      puts 'backend reload   Reload the backend group'
+      puts ''
+      puts 'You can also run only a specific Guard or all Guards in a specific group:'
+      puts ''
+      puts 'jasmine          Run the jasmine Guard'
+      puts 'frontend         Run all Guards in the frontend group'
+      puts ''
+    end
+
+    # Extract the Guard or group scope and action from the
+    # input line.
     #
     # @example `spork reload` will only reload rspec
     # @example `jasmine` will only run all jasmine specs
     #
-    # @param [String] Interactor entry gets from $stdin
-    # @return [Array] entry group or guard scope hash and action
+    # @param [String] line the readline input
+    # @return [Array] the group or guard scope and the action
     #
-    def extract_scopes_and_action(entry)
-      scopes  = {}
-      entries = entry.split(' ')
+    def extract_scopes_and_action(line)
+      scopes  = { }
+      entries = line.split(' ')
+
       case entries.length
       when 1
         unless action = action_from_entry(entries[0])
@@ -75,18 +199,21 @@ module Guard
         scopes = scopes_from_entry(entries[0])
         action = action_from_entry(entries[1])
       end
-      action ||= :run_all
+
+      action = :run_all if !action && (!scopes.empty? || entries.empty?)
 
       [scopes, action]
     end
 
+    private
+
     # Extract guard or group scope from entry if valid
     #
-    # @param [String] Interactor entry gets from $stdin
-    # @return [Hash] An hash with a guard or a group scope
+    # @param [String] entry the possible scope entry
+    # @return [Hash] a hash with a Guard or a group scope
     #
     def scopes_from_entry(entry)
-      scopes = {}
+      scopes = { }
       if guard = ::Guard.guards(entry)
         scopes[:guard] = guard
       end
@@ -97,18 +224,22 @@ module Guard
       scopes
     end
 
-    # Extract action from entry if an existing action is present
+    # Find the action for the given input entry.
     #
-    # @param [String] Interactor entry gets from $stdin
-    # @return [Symbol] A guard action
+    # @param [String] entry the possible action entry
+    # @return [Symbol] a Guard action
     #
     def action_from_entry(entry)
-      if STOP_ACTIONS.include?(entry)
+      if STOP_ENTRIES.include?(entry)
         :stop
-      elsif RELOAD_ACTIONS.include?(entry)
+      elsif RELOAD_ENTRIES.include?(entry)
         :reload
-      elsif PAUSE_ACTIONS.include?(entry)
+      elsif PAUSE_ENTRIES.include?(entry)
         :pause
+      elsif HELP_ENTRIES.include?(entry)
+        :help
+      elsif NOTIFICATION_ENTRIES.include?(entry)
+        :notification
       end
     end