joshbuddy-guard 0.10.0

data/lib/guard/dsl_describer.rb

@@ -0,0 +1,150 @@
+require 'guard/dsl'
+
+module Guard
+
+  autoload :UI,    'guard/ui'
+
+  # 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`.
+  #
+  # @see Guard::Dsl
+  # @see Guard::CLI
+  #
+  class DslDescriber < Dsl
+
+    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 Guards 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 = guardfile_structure.inject([]) do |installed, group|
+          group[:guards].each { |guard| installed << guard[:name] } if group[:guards]
+          installed
+        end
+
+        UI.info 'Available guards:'
+
+        ::Guard.guard_gem_names.sort.uniq.each do |name|
+          UI.info "   #{ name }#{ installed.include?(name) ? '*' : '' }"
+        end
+
+        UI.info ''
+        UI.info 'See also https://github.com/guard/guard/wiki/List-of-available-Guards'
+        UI.info '* denotes ones already in your Guardfile'
+      end
+
+      # Shows all Guards 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]
+              UI.info "Group #{ group[:group] }:"
+            else
+              UI.info '(global):'
+            end
+
+            group[:guards].each do |guard|
+              line = "  #{ guard[:name] }"
+
+              unless guard[:options].empty?
+                line += ": #{ guard[:options].sort.collect { |k, v| "#{ k } => #{ v.inspect }" }.join(', ') }"
+              end
+
+              UI.info line
+            end
+          end
+        end
+
+        UI.info ''
+      end
+
+      private
+
+      # Get the Guardfile structure.
+      #
+      # @return [Array<Hash>] the structure
+      #
+      def guardfile_structure
+        @@guardfile_structure
+      end
+
+    end
+
+    private
+
+    # Declares a group of guards.
+    #
+    # @param [String] name the group's name called from the CLI
+    # @yield a block where you can declare several guards
+    #
+    # @see Guard::Dsl#group
+    #
+    def group(name)
+      @@guardfile_structure << { :group => name.to_sym, :guards => [] }
+      @group = true
+
+      yield if block_given?
+
+      @group = false
+    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 = { })
+      node = (@group ? @@guardfile_structure.last : @@guardfile_structure.first)
+
+      node[:guards] << { :name => name, :options => options }
+    end
+
+  end
+end

data/lib/guard/group.rb

@@ -0,0 +1,37 @@
+module Guard
+
+  # A group of Guards. There are two reasons why you want to group your guards:
+  #
+  # - You can start only certain Groups from the command line by passing the `--group` option.
+  # - Abort task execution chain on failure within a group.
+  #
+  # @example Group that aborts on failure
+  #
+  #   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
+  #   end
+  #
+  # @see Guard::CLI
+  #
+  class Group
+
+    attr_accessor :name, :options
+
+    # Initialize a Group.
+    #
+    # @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 Guards in this group if one Guard throws `:task_has_failed`
+    #
+    def initialize(name, options = {})
+      @name    = name.to_sym
+      @options = options
+    end
+
+  end
+
+end

data/lib/guard/guard.rb

@@ -0,0 +1,129 @@
+module Guard
+
+  # Base class that every Guard implementation must inherit from.
+  #
+  # Guard will trigger the `start`, `stop`, `reload`, `run_all`, `run_on_change` and
+  # `run_on_deletion` task methods depending on user interaction and file modification.
+  #
+  # 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 I'll be passed to the "_end" hook for further evaluation. You can
+  # throw `:task_has_failed` to indicate that your Guard method was not successful,
+  # and successive guard 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
+  #
+  # Each Guard should provide a template Guardfile located within the Gem
+  # at `lib/guard/guard-name/templates/Guardfile`.
+  #
+  # By default all watchers for a Guard are returning strings of paths to the
+  # Guard, but if your Guard want 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.
+  #
+  class Guard
+    include Hook
+
+    attr_accessor :watchers, :options, :group
+
+    # Initialize a 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
+    #
+    def initialize(watchers = [], options = {})
+      @group = options[:group] ? options.delete(:group).to_sym : :default
+      @watchers, @options = watchers, options
+    end
+
+    # Initialize the Guard. This will copy the Guardfile template inside the Guard 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
+    #
+    def self.init(name)
+      if ::Guard::Dsl.guardfile_include?(name)
+        ::Guard::UI.info "Guardfile already includes #{ name } guard"
+      else
+        content = File.read('Guardfile')
+        guard   = File.read("#{ ::Guard.locate_guard(name) }/lib/guard/#{ name }/templates/Guardfile")
+
+        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
+
+    # Call once when Guard starts. Please override initialize method to init stuff.
+    #
+    # @raise [:task_has_failed] when start has failed
+    # @return [Object] the task result
+    #
+    def start
+    end
+
+    # 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
+    #
+    def stop
+    end
+
+    # 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
+    #
+    def reload
+    end
+
+    # 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
+    #
+    def run_all
+    end
+
+    # Called on file(s) modifications that the Guard watches.
+    #
+    # @param [Array<String>] paths the changes files or paths
+    # @raise [:task_has_failed] when run_on_change has failed
+    # @return [Object] the task result
+    #
+    def run_on_change(paths)
+    end
+
+    # Called on file(s) deletions that the Guard watches.
+    #
+    # @param [Array<String>] paths the deleted files or paths
+    # @raise [:task_has_failed] when run_on_change has failed
+    # @return [Object] the task result
+    #
+    def run_on_deletion(paths)
+    end
+
+  end
+
+end

data/lib/guard/hook.rb

@@ -0,0 +1,118 @@
+module Guard
+
+  # Guard has a hook mechanism that allows you to insert callbacks for individual Guards.
+  # By default, each of the Guard instance methods has a "_begin" and an "_end" hook.
+  # For example, the Guard::Guard#start method has a :start_begin hook that is runs immediately
+  # before Guard::Guard#start, and a :start_end hook that runs immediately after Guard::Guard#start.
+  #
+  # Read more about [hooks and callbacks on the wiki](https://github.com/guard/guard/wiki/Hooks-and-callbacks).
+  #
+  module Hook
+
+    # The Hook module gets included.
+    #
+    # @param [Class] base the class that includes the module
+    #
+    def self.included(base)
+      base.send :include, InstanceMethods
+    end
+
+    # Instance methods that gets included in the base class.
+    #
+    module InstanceMethods
+
+      # When event is a Symbol, {#hook} will generate a hook name
+      # by concatenating the method name from where {#hook} is called
+      # with the given Symbol.
+      #
+      # @example Add a hook with a Symbol
+      #
+      #   def run_all
+      #     hook :foo
+      #   end
+      #
+      # Here, when {Guard::Guard#run_all} is called, {#hook} will notify callbacks
+      # registered for the "run_all_foo" event.
+      #
+      # When event is a String, {#hook} will directly turn the String
+      # into a Symbol.
+      #
+      # @example Add a hook with a String
+      #
+      #   def run_all
+      #     hook "foo_bar"
+      #   end
+      #
+      # When {Guard::Guard#run_all} is called, {#hook} will notify callbacks
+      # registered for the "foo_bar" event.
+      #
+      # @param [Symbol, String] event the name of the Guard event
+      # @param [Array] args the parameters are passed as is to the callbacks registered for the given event.
+      #
+      def hook(event, *args)
+        hook_name = if event.is_a? Symbol
+                      calling_method = caller[0][/`([^']*)'/, 1]
+                      "#{ calling_method }_#{ event }"
+                    else
+                      event
+                    end.to_sym
+
+        UI.debug "Hook :#{ hook_name } executed for #{ self.class }"
+
+        Hook.notify(self.class, hook_name, *args)
+      end
+    end
+
+    class << self
+
+      # Get all callbacks.
+      #
+      def callbacks
+        @callbacks ||= Hash.new { |hash, key| hash[key] = [] }
+      end
+
+      # Add a callback.
+      #
+      # @param [Block] listener the listener to notify
+      # @param [Guard::Guard] guard_class the Guard class to add the callback
+      # @param [Array<Symbol>] events the events to register
+      #
+      def add_callback(listener, guard_class, events)
+        _events = events.is_a?(Array) ? events : [events]
+        _events.each do |event|
+          callbacks[[guard_class, event]] << listener
+        end
+      end
+
+      # Checks if a callback has been registered.
+      #
+      # @param [Block] listener the listener to notify
+      # @param [Guard::Guard] guard_class the Guard class to add the callback
+      # @param [Symbol] event the event to look for
+      #
+      def has_callback?(listener, guard_class, event)
+        callbacks[[guard_class, event]].include?(listener)
+      end
+
+      # Notify a callback.
+      #
+      # @param [Guard::Guard] guard_class the Guard class to add the callback
+      # @param [Symbol] event the event to trigger
+      # @param [Array] args the arguments for the listener
+      #
+      def notify(guard_class, event, *args)
+        callbacks[[guard_class, event]].each do |listener|
+          listener.call(guard_class, event, *args)
+        end
+      end
+
+      # Reset all callbacks.
+      #
+      def reset_callbacks!
+        @callbacks = nil
+      end
+
+    end
+
+  end
+end

data/lib/guard/interactor.rb

@@ -0,0 +1,116 @@
+module Guard
+
+  # The interactor reads user input and triggers
+  # specific action upon them unless its locked.
+  #
+  # 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
+  #
+  # 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
+  #
+  class Interactor
+
+    STOP_ACTIONS   = %w[stop quit exit s q e]
+    RELOAD_ACTIONS = %w[reload r z]
+    PAUSE_ACTIONS  = %w[pause p]
+
+    # Start the interactor in its own thread.
+    #
+    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
+      end
+    end
+
+    # Kill interactor thread if not current
+    #
+    def stop
+      unless Thread.current == @thread
+        @thread.kill
+      end
+    end
+    
+    # Extract guard or group scope and action from Interactor entry
+    #
+    # @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
+    #
+    def extract_scopes_and_action(entry)
+      scopes  = {}
+      entries = entry.split(' ')
+      case entries.length
+      when 1
+        unless action = action_from_entry(entries[0])
+          scopes = scopes_from_entry(entries[0])
+        end
+      when 2
+        scopes = scopes_from_entry(entries[0])
+        action = action_from_entry(entries[1])
+      end
+      action ||= :run_all
+
+      [scopes, action]
+    end
+
+    # 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
+    #
+    def scopes_from_entry(entry)
+      scopes = {}
+      if guard = ::Guard.guards(entry)
+        scopes[:guard] = guard
+      end
+      if group = ::Guard.groups(entry)
+        scopes[:group] = group
+      end
+
+      scopes
+    end
+
+    # Extract action from entry if an existing action is present
+    #
+    # @param [String] Interactor entry gets from $stdin
+    # @return [Symbol] A guard action
+    #
+    def action_from_entry(entry)
+      if STOP_ACTIONS.include?(entry)
+        :stop
+      elsif RELOAD_ACTIONS.include?(entry)
+        :reload
+      elsif PAUSE_ACTIONS.include?(entry)
+        :pause
+      end
+    end
+
+  end
+end