subtrigger 0.2.7 → 0.3.0

data/lib/subtrigger/path.rb

@@ -0,0 +1,82 @@
+module Subtrigger
+  # Our own little implementation of the path, allowing us to look up
+  # the location of executable files. This is because Subversion hooks
+  # run in a clean environment, without any environment variables such as
+  # <tt>$PATH</tt>. We therefore need to run (for example)
+  # <tt>/usr/bin/svn update</tt> rather than <tt>svn update</tt>.
+  #
+  # There is a list of default locations that will be searched, but you
+  # may add your own if you want to. This is useful if you've got a custom
+  # installation on your machine you want to use.
+  #
+  # Note: testing whether an executable exists in a given path is done using
+  # the unix program <tt>test</tt>, which will most likely not work on
+  # windows machines (untested).
+  #
+  # @example Getting the path to an executable
+  #   Path.new.to('svn') #=> '/usr/bin'
+  #
+  # @example Adding a preferred location
+  #   path = Path.new
+  #   path << '/opt/local'
+  #   path.to('svn') => '/opt/local'
+  #
+  # @author Arjan van der Gaag
+  # @since 0.3.0
+  class Path
+
+    # The default list of paths to look in, covering most of the use cases.
+    DEFAULT_PATHS = %w{/opt/subversion/bin /usr/sbin /usr/bin}
+
+    # Custom exception raised when a program is not found in any of the
+    # locations known.
+    NotFound = Class.new(Exception)
+
+    # A list of absolute paths on te filesystems to where the svn executables
+    # might be located. These are scanned in order to find the executables
+    # to use.
+    attr_reader :locations
+
+    # Start a new list of paths, starting with the <tt>DEFAULT_PATHS</tt>
+    def initialize
+      @locations = DEFAULT_PATHS.dup # use a copy to prevent global state
+      @exists = Hash.new do |hash, p|
+        hash[p] = system('test -x ' + p)
+      end
+    end
+
+    # Add a new path to the stack before the existing ones.
+    #
+    # @param [String] new_path is a new possible location of executables
+    # @return [Array<String>] the total list of paths
+    def <<(new_path)
+      @locations.unshift(new_path)
+    end
+
+    # Scan all the known paths to find the given program.
+    #
+    # Note: this probably only works on unix-like systems.
+    #
+    # @todo implement memoization per argument
+    # @param [String] program is the name of the executable to find, like
+    #  <tt>svn</tt>
+    # @return [String] the correct path to this program or nil
+    # @raise NotFoundException when the program is not found in any of the
+    #  known locations
+    def to(program)
+      location = locations.find { |path| exists? File.join(path, program) }
+      raise NotFound.new(program) unless location
+      location
+    end
+
+  private
+
+    # Make the actual test if a given path points to an executable file.
+    #
+    # @param [String] path is the absolute path to test
+    # @return [Boolean] whether the path is an executable file
+    def exists?(path)
+      @exists[path]
+    end
+  end
+end

data/lib/subtrigger/revision.rb

@@ -0,0 +1,95 @@
+module Subtrigger
+  # A simple wrapper around the output of Subversion's <tt>svnlook</tt>
+  # command.
+  #
+  # This class will let you make simple queries against the properties of a
+  # Subversion revision. It parses its output into keys and values so you can
+  # perform operations on them.
+  #
+  # == Attributes
+  #
+  # It knows about the following attributes:
+  #
+  # * Revision number
+  # * Author
+  # * Timestamp
+  # * Log message
+  # * changed directories
+  #
+  # This works by passing in the number of the revision to use, the raw
+  # output of <tt>svnlook info</tt> and the raw output of
+  # <tt>svnlook dirs-changed</tt>.
+  #
+  # == Special attributes
+  #
+  # Revision knows about changed projects. This is extracted from the list
+  # of changed directories. A project is a directory that is directly above
+  # a directory named <tt>trunk</tt>, <tt>branches</tt> or <tt>tags</tt>. So
+  # when a directory <tt>/internal/accounting/trunk</tt> is changed, the
+  # project <tt>/internal/accounting</tt> is reported.
+  #
+  # @example Example of raw input for <tt>info</tt>
+  #   john
+  #   2010-07-05 17:00:00 +0200 (Mon, 01 Jan 2010)
+  #   215
+  #   Description of log
+  #
+  # @example Usage
+  #   @revision = Revision.new('...')
+  #   @revision.author    # => 'john'
+  #   @revision.message   # => 'Description of log'
+  #   @revision.date      # => (instance of Time)
+  #   @revision.projects  # => ['/project1', 'project2', ...]
+  #
+  # @author Arjan van der Gaag
+  # @since 0.3.0
+  class Revision
+    # The raw output of the svnlook command.
+    attr_reader :raw
+
+    # A list of all directories that were changed in this revision
+    attr_reader :dirs_changed
+
+    # the parsed Hash of attributes for this revision
+    attr_reader :attributes
+
+    def initialize(revision_number, info, dirs_changed)
+      @attributes = { :number => revision_number.to_i }
+      @raw = info
+      @dirs_changed = dirs_changed.split
+      parse
+    end
+
+    %w{author date message number}.each do |name|
+      define_method(name) do
+        attributes[name.to_sym]
+      end
+    end
+
+    # Creates a list of directory paths in the repository that have changes
+    # and contain a <tt>trunk</tt>, <tt>branches</tt> or <tt>tags</tt>
+    # directory.
+    #
+    # For example, a changed path in like <tt>/topdir/project_name/trunk</tt>
+    # would result in <tt>/topdir/project_name</tt>.
+    #
+    # @return [Array<String>] list of changed project paths
+    def projects
+      pattern = /\/(trunk|branches|tags)/
+      dirs_changed.grep(pattern).map do |dir|
+        dir.split(pattern, 2).first
+      end.uniq
+    end
+
+  private
+
+    # Parses the raw log of svnlook into a Hash of attributes.
+    def parse
+      raise ArgumentError, 'Could not parse Subversion info: expected at least 4 lines' if raw.split("\n").size < 4
+      author, timestamp, size, message = raw.split("\n", 4)
+      attributes[:author] = author
+      attributes[:date] = Time.parse(timestamp)
+      attributes[:message] = message.chomp
+    end
+  end
+end

data/lib/subtrigger/rule.rb

@@ -0,0 +1,165 @@
+module Subtrigger
+  # A <tt>Rule</tt> object knows when to fire some kind of action for some
+  # kind of revision. When the Subversion hook is fired, a Rule can inspect it
+  # and choose whether or not to fire its trigger (a piece code defined by the
+  # user).
+  #
+  # In the first example, the rule will output <tt>fired</tt> whenever a
+  # <tt>Revision</tt> comes along with a message containing <tt>foo</tt>.
+  #
+  # In the second example, we find all applicable rules for a given
+  # <tt>Revision</tt> object. We can then run each of them.
+  #
+  # @example 1: Define a simple Rule
+  #   Rule.new(/foo/) { puts 'fired' }
+  #
+  # @example 2: Finding and firing Rules
+  #   rev = Revision.new
+  #   Rule.matching(rev).map { |rule| rule.run(rev) }
+  #
+  # @since 0.3.0
+  # @author Arjan van der Gaag
+  class Rule
+
+    # Exception for when trying to apply a rule to something other than an
+    # instance of Revision.
+    CannotCompare = Class.new(Exception)
+
+    # A hash of Revision attributes and regular expressions to match against
+    attr_reader :criteria
+
+    # The callback to run on a match
+    attr_reader :block
+
+  private
+
+    @rules = []
+
+    # Keep track of Rule objects that are created in a class instance variable
+    #
+    # @param [Rule] child is the new Rule object
+    # @return [Array<Rule>] the total list of children
+    def self.register(child)
+      @rules << child
+    end
+
+  public
+
+    # Return an array of all rules currently defined.
+    #
+    # @return [Array<Rule>]
+    def self.rules
+      @rules
+    end
+
+    # Reset the list of known rules, deleting all currently known rules.
+    #
+    # @return nil
+    def self.reset
+      @rules = []
+    end
+
+    # Return an array of all existing Rule objects that match the given
+    # revision.
+    #
+    # @param [Revision] revision is the revision to compare rules to.
+    # @return [Array<Rule>] list of all matching rules
+    def self.matching(revision)
+      @rules.select { |child| child === revision }
+    end
+
+    # Create a new Rule object with criteria for different properties of a
+    # Revision. The required block defines the callback to run. It will have
+    # the current Revision object yielded to it.
+    #
+    # Criteria are Ruby objects that should match (`===`) a Revision's
+    # attributes. These would usually be regular expressions, but they
+    # can be strings or custom objects if you want to.
+    #
+    # @overload initialize(pattern, &block)
+    #   Define a rule with a pattern matching the log message
+    #   @param [Regex] pattern is the regular expression to match against
+    #     the revision's log message
+    # @overload initialize(options, &block)
+    #   Define a rule with various criteria in a hash.
+    #   @param [Hash] options defines matching criteria.
+    #   @option options :author  Criterium for Revision#author
+    #   @option options :date    Criterium for Revision#date
+    #   @option options :number  Criterium for Revision#number
+    #   @option options :project Criterium for Revision#project
+    def initialize(pattern_or_options, &block)
+      raise ArgumentError, 'a Rule requires a block' unless block_given?
+
+      # If not given a hash, we build a hash defaulting on message
+      unless pattern_or_options.is_a?(Hash)
+        pattern_or_options = { :message => pattern_or_options }
+      end
+
+      @criteria, @block = pattern_or_options, block
+      @criteria.inspect
+      self.class.register self
+    end
+
+    # Call this Rule's callback method with the give Revision object.
+    # @return [nil]
+    def run(rev)
+      @rev = rev
+      block.call(@rev, collect_captures)
+    end
+
+    # Use {Rule#matches?} to see if this <tt>Rule</tt> matches the given
+    # <tt>Revision</tt>.
+    #
+    # @param [Object] the object to compare to
+    # @return [Boolean]
+    # @see Rule#matches?
+    def ===(other)
+      matches?(other)
+    rescue CannotCompare
+      super
+    end
+
+    # See if the current rule matches a given subversion revision.
+    #
+    # @param [Revision] revision the Revision object to compare to.
+    # @return [Boolean]
+    # @see Rule#===
+    # @raise Subtrigger::Rule::CannotCompare when comparing to something other
+    #   than a revision.
+    def matches?(revision)
+      raise CannotCompare unless @criteria.keys.all? { |k| k == :all || revision.respond_to?(k) }
+      match = @criteria.any?
+      @criteria.each_pair do |key, value|
+        if key == :all
+          match = (value === revision)
+        else
+          match &= (value === revision.send(key.to_sym))
+        end
+      end
+      match
+    end
+
+  private
+
+    # When using regular expressions to match against string values, we
+    # want to be able to get to any captured groups. This method scans all
+    # string values with their Regex matchers and collects all captured
+    # groups into a namespaced hash.
+    #
+    # @example
+    #   Rule.new /hello, (.+)!/ do |revision, matches|
+    #     puts matches.inspect
+    #   end
+    #   # => { :message => ['world'] }
+    #
+    # @return [Hash] all captured groups per Revision attribute tested
+    # @todo this only passes on capture groups, not the entire match ($&)
+    def collect_captures
+      criteria.inject({}) do |output, (key, value)|
+        next if key == :all
+        output[key] = @rev.send(key.to_sym).scan(value).flatten if value.is_a?(Regexp)
+        output
+      end
+    end
+  end
+end

data/lib/subtrigger/template.rb

@@ -0,0 +1,96 @@
+module Subtrigger
+  # Reads, parses and manages inline templates.
+  #
+  # When you define string templates at the end of your rules file, this class
+  # can parse and keep track of them. You can then easily retrieve them again
+  # and optionally format it like with <tt>String#%</tt>.
+  #
+  # You simply define a new template using <tt>@@</tt>, followed by a name and
+  # then the textual contents (see the example below).
+  #
+  # You can read the templates and use them, for example, in e-mails.
+  #
+  # @example Defining templates
+  #   # at the end of your Ruby file:
+  #    __END__
+  #   @@ Template 1
+  #   Foo
+  #   @@ Template 2
+  #   Hello, %s!
+  #
+  # @example Parsing templates
+  #   Template.parse(__DATA__.read)
+  #
+  # @example Using templates
+  #   Template.find('Template 1') # => 'Foo'
+  #
+  # @example Formatting templates
+  #   Template.find('Template 2') # => 'Hello, %s!'
+  #   Template.find('Template 2').format('world') # => 'Hello, world!'
+  #
+  # @author Arjan van der Gaag
+  # @since 0.3.0
+  class Template
+    # The unique identifier for this template
+    attr_reader :name
+
+    # The actual contents of the template
+    attr_reader :string
+
+    # List of defined templates the class tracks
+    @children = []
+
+    # The pattern that separates one template from another
+    TEMPLATE_DELIMITER = /^@@ (.*)\n/
+
+    # Exception raised when a string cannot be parsed into templates,
+    # because the delimiter cannot be found
+    Unparseable = Class.new(Exception)
+
+    # Parse the contents of a string and extract templates from it. These are
+    # tracked so you can use {Template#find} to retrieve them by name.
+    #
+    # @param [String] the contents of your rules file's <tt>__DATA__.read</tt>
+    # @return [nil]
+    def self.parse(string)
+      raise Unparseable, "Could not split into templates: #{string.inspect}" unless string =~ TEMPLATE_DELIMITER
+      string.split(TEMPLATE_DELIMITER).map(&:chomp).slice(1..-1).each_slice(2) do |name, content|
+        @children << new(name, content)
+      end
+      nil
+    end
+
+    # Finds and returns the content of the template by the given name.
+    #
+    # @param [String] name is the name of the template
+    # @return [String] is Template#content
+    def self.find(name)
+      @children.find { |child|
+        child.name == name
+      }
+    end
+
+    # Convert to string using the textual contents of the template
+    # @return [String]
+    def to_s
+      string
+    end
+
+    # Get the contents of the template and interpolate any given
+    # arguments into it.
+    #
+    # @example Getting a template and using interpolation
+    #   template.to_s           # => 'Dear %s...'
+    #   template.format 'John'  # => 'Dear John...'
+    # @return [String] the formatted template contents
+    def format(*args)
+      to_s % [*args]
+    end
+
+    # @param [String] name is the unique identifier of a template
+    # @param [String] string is the contents of the template.
+    def initialize(name, string)
+      @name, @string = name, string
+    end
+  end
+end

data/subtrigger.gemspec

@@ -5,65 +5,65 @@
 
 Gem::Specification.new do |s|
   s.name = %q{subtrigger}
-  s.version = "0.2.7"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Arjan van der Gaag"]
-  s.date = %q{2010-04-23}
-  s.default_executable = %q{subtrigger}
+  s.date = %q{2010-07-16}
   s.description = %q{This gem allows you to create simple Ruby triggers for Subversion commit messages, responding to keywords in your log messages to send e-mails, deploy sites or do whatever you need.}
   s.email = %q{arjan@arjanvandergaag.nl}
-  s.executables = ["subtrigger"]
   s.extra_rdoc_files = [
-    "LICENSE",
-     "README.rdoc"
+    "README.md"
   ]
   s.files = [
     ".document",
      ".gitignore",
-     "LICENSE",
-     "README.rdoc",
+     "README.md",
      "Rakefile",
      "VERSION",
-     "bin/subtrigger",
      "lib/subtrigger.rb",
-     "lib/subtrigger/email.rb",
-     "lib/subtrigger/repository.rb",
-     "lib/subtrigger/trigger.rb",
+     "lib/subtrigger/dsl.rb",
+     "lib/subtrigger/path.rb",
+     "lib/subtrigger/revision.rb",
+     "lib/subtrigger/rule.rb",
+     "lib/subtrigger/template.rb",
      "subtrigger.gemspec",
-     "test/helper.rb",
-     "test/test_email.rb",
-     "test/test_repository.rb",
-     "test/test_subtrigger.rb",
-     "test/test_trigger.rb"
+     "test/test_helper.rb",
+     "test/test_path.rb",
+     "test/test_revision.rb",
+     "test/test_rule.rb",
+     "test/test_template.rb"
   ]
   s.homepage = %q{http://github.com/avdgaag/subtrigger}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.6}
+  s.rubygems_version = %q{1.3.7}
   s.summary = %q{Create post-commit triggers for Subversion commit messages}
   s.test_files = [
-    "test/helper.rb",
-     "test/test_email.rb",
-     "test/test_repository.rb",
-     "test/test_subtrigger.rb",
-     "test/test_trigger.rb"
+    "test/test_helper.rb",
+     "test/test_path.rb",
+     "test/test_revision.rb",
+     "test/test_rule.rb",
+     "test/test_template.rb"
   ]
 
   if s.respond_to? :specification_version then
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
       s.add_development_dependency(%q<mocha>, [">= 0"])
+      s.add_runtime_dependency(%q<pony>, [">= 0"])
     else
       s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
       s.add_dependency(%q<mocha>, [">= 0"])
+      s.add_dependency(%q<pony>, [">= 0"])
     end
   else
     s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
     s.add_dependency(%q<mocha>, [">= 0"])
+    s.add_dependency(%q<pony>, [">= 0"])
   end
 end