From d66a872f4a2be7ce0ddff65a91a57f629af5a307 Mon Sep 17 00:00:00 2001 From: Michael Kessler Date: Tue, 20 Sep 2011 11:40:47 +0200 Subject: [PATCH] Initial yardoc for Guard. --- lib/guard.rb | 124 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 97 insertions(+), 27 deletions(-) diff --git a/lib/guard.rb b/lib/guard.rb index 8f225ee..2943ea8 100644 --- a/lib/guard.rb +++ b/lib/guard.rb @@ -12,7 +12,16 @@ module Guard class << self attr_accessor :options, :guards, :groups, :interactor, :listener - # initialize this singleton + # Initialize the Guard singleton. + # + # @param [Hash] options the Guard options. + # @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 [Array] group the list of groups to start + # @option options [String] watchdir the director to watch + # @option options [String] guardfile the path to the Guardfile + # def setup(options = {}) @options = options @guards = [] @@ -20,7 +29,7 @@ module Guard @interactor = Interactor.new @listener = Listener.select_and_init(@options[:watchdir] ? File.expand_path(@options[:watchdir]) : Dir.pwd) - @options[:notify] && ENV["GUARD_NOTIFY"] != 'false' ? Notifier.turn_on : Notifier.turn_off + @options[:notify] && ENV['GUARD_NOTIFY'] != 'false' ? Notifier.turn_on : Notifier.turn_off UI.clear if @options[:clear] debug_command_execution if @options[:debug] @@ -28,6 +37,17 @@ module Guard self end + # Start Guard by evaluate the `Guardfile`, initialize the declared Guards + # and start the available file change listener. + # + # @param [Hash] options the Guard options. + # @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 [Array] group the list of groups to start + # @option options [String] watchdir the director to watch + # @option options [String] guardfile the path to the Guardfile + # def start(options = {}) setup(options) @@ -38,55 +58,70 @@ module Guard listener.changed_files += files if Watcher.match_files?(guards, files) end - UI.info "Guard is now watching at '#{listener.directory}'" + UI.info "Guard is now watching at '#{ listener.directory }'" guards.each { |guard| supervised_task(guard, :start) } interactor.start listener.start end + # Stop Guard listening to file changes + # def stop - UI.info "Bye bye...", :reset => true + UI.info 'Bye bye...', :reset => true listener.stop guards.each { |guard| supervised_task(guard, :stop) } abort end + # Reload all Guards currently enabled. + # def reload run do guards.each { |guard| supervised_task(guard, :reload) } end end + # Trigger `run_all` on all Guards currently enabled. + # def run_all run do guards.each { |guard| supervised_task(guard, :run_all) } end end + # Pause Guard listening to file changes. + # def pause if listener.locked - UI.info "Un-paused files modification listening", :reset => true + UI.info 'Un-paused files modification listening', :reset => true listener.clear_changed_files listener.unlock else - UI.info "Paused files modification listening", :reset => true + UI.info 'Paused files modification listening', :reset => true listener.lock end end + # Trigger `run_on_change` on all Guards currently enabled and + # def run_on_change(files) run do guards.each do |guard| paths = Watcher.match_files(guard, files) unless paths.empty? - UI.debug "#{guard.class.name}#run_on_change with #{paths.inspect}" + UI.debug "#{ guard.class.name }#run_on_change with #{ paths.inspect }" supervised_task(guard, :run_on_change, paths) end end end end + # Run a block where the listener and the interactor is + # blocked. + # + # @yield the block to run + # def run listener.lock interactor.lock @@ -99,24 +134,40 @@ module Guard listener.unlock end - # Let a guard execute its task but - # fire it if his work leads to a system failure + # Let a Guard execute its task, but fire it + # if his work leads to a system failure. + # + # @param [Guard::Guard] the guard to execute + # @param [Symbol] task_to_supervise the task to run + # @params [Array] args the arguments for the task + # @return [Boolean, Exception] the result of the Guard + # def supervised_task(guard, task_to_supervise, *args) - guard.hook("#{task_to_supervise}_begin", *args) + guard.hook("#{ task_to_supervise }_begin", *args) result = guard.send(task_to_supervise, *args) - guard.hook("#{task_to_supervise}_end", result) + guard.hook("#{ task_to_supervise }_end", result) + result + rescue Exception => ex - UI.error("#{guard.class.name} failed to achieve its <#{task_to_supervise.to_s}>, exception was:" + - "\n#{ex.class}: #{ex.message}\n#{ex.backtrace.join("\n")}") + UI.error("#{ guard.class.name } failed to achieve its <#{ task_to_supervise.to_s }>, exception was:" + + "\n#{ ex.class }: #{ ex.message }\n#{ ex.backtrace.join("\n") }") guards.delete guard - UI.info("\n#{guard.class.name} has just been fired") - return ex + UI.info("\n#{ guard.class.name } has just been fired") + + ex end + # Add a Guard to use. + # + # @param [String] name the Guard name + # @param [Array] watchers the list of declared watchers + # @param [Array] callbacks the list of callbacks + # @param [Hash] the Guard options + # def add_guard(name, watchers = [], callbacks = [], options = {}) if name.to_sym == :ego - UI.deprecation("Guard::Ego is now part of Guard. You can remove it from your Guardfile.") + UI.deprecation('Guard::Ego is now part of Guard. You can remove it from your Guardfile.') else guard_class = get_guard_class(name) callbacks.each { |callback| Hook.add_callback(callback[:listener], guard_class, callback[:events]) } @@ -124,42 +175,58 @@ module Guard end end + # Add a Guard group. + # + # @param [String] name the group name + # def add_group(name) @groups << name.to_sym unless name.nil? end + # Tries to load the Guard main class. + # + # @param [String] name the name of the Guard + # @return [Class, nil] the loaded class + # def get_guard_class(name) name = name.to_s try_require = false const_name = name.downcase.gsub('-', '') begin - require "guard/#{name.downcase}" if try_require + require "guard/#{ name.downcase }" if try_require self.const_get(self.constants.find { |c| c.to_s.downcase == const_name }) rescue TypeError unless try_require try_require = true retry else - UI.error "Could not find class Guard::#{const_name.capitalize}" + UI.error "Could not find class Guard::#{ const_name.capitalize }" end rescue LoadError => loadError - UI.error "Could not load 'guard/#{name.downcase}' or find class Guard::#{const_name.capitalize}" + UI.error "Could not load 'guard/#{ name.downcase }' or find class Guard::#{ const_name.capitalize }" UI.error loadError.to_s end end + # Locate a path to a Guard gem. + # + # @param [String] name the name of the Guard without the prefix `guard-` + # @return [String] the full path to the Guard gem + # def locate_guard(name) if Gem::Version.create(Gem::VERSION) >= Gem::Version.create('1.8.0') - Gem::Specification.find_by_name("guard-#{name}").full_gem_path + Gem::Specification.find_by_name("guard-#{ name }").full_gem_path else - Gem.source_index.find_name("guard-#{name}").last.full_gem_path + Gem.source_index.find_name("guard-#{ name }").last.full_gem_path end rescue - UI.error "Could not find 'guard-#{name}' gem path." + UI.error "Could not find 'guard-#{ name }' gem path." end - ## # Returns a list of guard Gem names installed locally. + # + # @return [Array] a list of guard gem names + # def guard_gem_names if Gem::Version.create(Gem::VERSION) >= Gem::Version.create('1.8.0') Gem::Specification.find_all.select { |x| x.name =~ /^guard-/ } @@ -168,16 +235,19 @@ module Guard end.map { |x| x.name.sub /^guard-/, '' } end + # Adds a command logger in debug mode. This wraps common command + # execution functions and logs the executed command before execution. + # def debug_command_execution Kernel.send(:alias_method, :original_system, :system) Kernel.send(:define_method, :system) do |command, *args| - ::Guard::UI.debug "Command execution: #{command} #{args.join(' ')}" + ::Guard::UI.debug 'Command execution: #{command} #{args.join(' ')}' original_system command, *args end - Kernel.send(:alias_method, :original_backtick, :"`") - Kernel.send(:define_method, :"`") do |command| - ::Guard::UI.debug "Command execution: #{command}" + Kernel.send(:alias_method, :original_backtick, :'`') + Kernel.send(:define_method, :'`') do |command| + ::Guard::UI.debug 'Command execution: #{command}' original_backtick command end end