subtrigger 0.2.7 → 0.3.0

data/.gitignore

@@ -19,3 +19,5 @@ rdoc
 pkg
 
 ## PROJECT::SPECIFIC
+.yardoc
+doc

data/README.md

@@ -0,0 +1,158 @@
+# Subtrigger
+
+A simple DSL for defining callbacks to be fired as Subversion hooks with
+built-in support for inspecting the repository and sending out e-mails.
+
+## Example Usage
+
+This library is intended for use as a Subversion post-commit hook. It allows
+you to define callbacks that fire when certain conditions on a revision are
+met. Simply require Subtrigger and define your rules:
+
+    require 'subtrigger'
+
+    on /deploy to (\w+)/ do |revision, matches|
+      puts "Should deploy to #{matches[:message].first}"
+    end
+
+Save this as a file in your Subversion repository, like
+`/path/to/repo/hooks/deploy.rb`. Then in your Subversion commit hook
+file (`/path/to/repo/hooks/post-commit`) simply call the file using
+Ruby:
+
+    /usr/bin/ruby -rubygems /path/to/repo/hooks/deploy.rb "$1" "$2"
+
+You could define triggers to…
+
+* Send out confirmation e-mails to specific developers
+* Auto-update a working copy on a production server
+* Create a back-up archive
+* Whatever else you can do with Ruby…
+
+## Detailed usage
+
+### Matchers
+
+The default usage in the example above uses a regular expression which by
+default will be matched against the log message of the revision that
+triggers the hook. But you can test both other attributes and with other
+objects (basically anything that responds to `#===`).
+
+    # Test on author name
+    # You can use `:author`, `:message`, `:date`,
+    # `:number`
+    on :author => /john|graham|michael|terry/ do
+      puts 'Always look on the bright side of life!'
+    end
+
+    # Test using a matcher object
+    class EvenNumberMatcher
+      def ===(revision)
+        revision.number % 2 == 0
+      end
+    end
+    on :number => EvenNumberMatcher.new do
+      puts 'The revision number is an even number'
+    end
+
+### Sending e-mails
+
+Subtrigger uses Pony to enable the sending of e-mails straigt from your
+triggers. This means you can send an e-mail when a branch is created, just
+to name an example.
+
+    on /confirm via email/ do
+      mail :to      => 'me@example.com',
+           :from    => 'svn@example.com',
+           :subject => 'E-mail confirmation of commit',
+           :body    => 'Your commit has been saved.'
+    end
+
+### Inline templates
+
+To remove long strings from your templates you can define templates right
+in your rules file.
+
+    on /confirm via email/ do |r|
+      mail :to      => 'me@example.com',
+           :from    => 'svn@example.com',
+           :subject => 'E-mail confirmation of commit',
+           :body    => template('E-mail confirmation', r.number)
+    end
+    __END__
+    @@ E-mail confirmation
+    Your commit (%s) has been saved
+    @@ Other template
+    ...
+
+This will result in an e-mail like `Your commit (5299) has been
+saved`.
+
+### Running the triggers
+
+Note that all triggers are run when your rules file ends (using the global
+`at_exit` callback). There's no need to explicitly start this process
+yourself.
+
+## Warnings
+
+Note that subversion calls its hooks in an empty environment, so there's
+no `$PATH` or anything. Always use full absolute paths. Also, hooks are
+notoriously hard to debug, so make sure to write some debugging information
+somewhere so you know what is going on.
+
+## Changes
+
+Note that Subtrigger is still in early stages of development.
+Until it hits 1.0 there are bound to be major changes. 
+
+### 0.3.0
+
+* Complete rewrite of the system
+* Improved documentation
+* Improved test coverage
+* Added matching on more revision attributes
+* Added custom matcher objects
+* Use Pony for e-mail
+* Cleaner rules files
+
+## Credits
+
+* **Author**: Arjan van der Gaag
+* **E-mail**: arjan@arjanvandergaag.nl
+* **URL**: http://arjanvandergaag.nl
+* **Source**: http://github.com/avdgaag/subtrigger
+
+## Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a
+  commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## License
+
+Copyright (c) 2010 Arjan van der Gaag
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -12,6 +12,7 @@ begin
     gem.authors = ["Arjan van der Gaag"]
     gem.add_development_dependency "thoughtbot-shoulda", ">= 0"
     gem.add_development_dependency "mocha", ">= 0"
+    gem.add_dependency 'pony'
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError
@@ -42,12 +43,5 @@ task :test => :check_dependencies
 
 task :default => :test
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "subtrigger #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+require 'yard'
+YARD::Rake::YardocTask.new

data/VERSION

@@ -1 +1 @@
-0.2.7
+0.3.0

data/lib/subtrigger.rb

@@ -1,133 +1,98 @@
-$:.unshift File.dirname(__FILE__)
-# = Subtrigger
-#
-# Subtrigger is a tiny tool for firing callback methods based on triggers in
-# subversion log messages.
-#
-# == Example
-#
-# When somebody makes a commit:
-#
-#   r5410 "Added a sitemap to the website [deploy]"
-#   A  /www.website.tld/trunk/sitemap.xml
-#
-# ...then you can trigger the deployment of that project to a staging server
-# using a +Trigger+:
-#
-#   Subtrigger.on(/\[deploy\]/) do |matches, repo|
-#     # do some smart stuff here
-#   end
-#
-# Your trigger has access to the captured groups in its regular expression
-# matcher, and to all the <tt>svnlook</tt> information from the repository
-# at the revision that fired the hook. This gives you access to changed paths,
-# its author, date, etc.
-#
-# == E-mail notifications
-#
-# Subtrigger allows you to send notification e-mails to developers:
-#
-#   # in your trigger:
-#   Subtrigger::Email.new(:to => "#{repo.author}@company.tld",
-#                         :from => 'svn@company.tld',
-#                         :subject => 'Trigger notification',
-#                         :body => "Dear #{repo.author}, ...")
-#
-# == Usage
-#
-# This library is intended to be used as a Subversion post-commit hook.
-# The best way to use it to create a post-commit hook file that requires this
-# library, sets up one or more triggers and than fires the processing.
-#
-# Here's an example:
-#
-#   #!/usr/local/bin/ruby
-#   require 'rubygems'
-#   require 'subtrigger'
-#   Subtrigger.configure { |c|
-#     c.svn = '/usr/bin/svn'
-#   }.on(/foo/) { |matches, repo|
-#     puts "#{repo.author} comitted foo!"
-#   }.on(/bar/) { |matches, repo|
-#     puts "#{repo.author} comitted bar!"
-#   }.run(*ARGV)
-#
-# === Command Line Usage
-#
-# There is a command-line tool available for running Subtrigger. It simply
-# requires the Subtrigger library and calls +run+. Most of the time, you'll
-# want to write your own script and <tt>require 'subtrigger'</tt> yourself.
-#
-# You can run <tt>subtrigger -v</tt> to see the currently installed version
-# of Subtrigger.
-#
-# === Configuration
-#
-# Since subversion usually calls its hooks in an empty environment (even
-# without a $PATH) you might need to make some settings manually:
-#
-#   Subtrigger.svn = '/path/to/svn'
-#   Subtrigger.sendmail = '/path/to/sendmail'
-#   Subtrigger.svn_args = ''
-#
-# You can alternatively use a block:
-#
-#   Subtrigger.configure do |c|
-#     c.svn = '/path/to/svn'
-#   end
-#
-# This will return Subtrigger itself, so you can chain further commands.
-#
-# The <tt>svn_args</tt> setting is a string appended to every +svn+ command.
-# This allows you to, for example, set a custom username and password. You
-# might also want to apply the <tt>--non-interactive</tt> argument. For
-# example:
-#
-#   Subtrigger.svn_args = '--username my_name --password secret --non-interactive'
-#
-# Make sure your gems are installed and the correct permissions are set. Note
-# that Subversion hooks generate no output, so run your hooks manually for
-# testing purposes.
+# Libraries
+begin
+  require 'pony'
+rescue LoadError
+  puts 'WARNING: Subtrigger requires Pony to send e-mails.'
+end
+require 'time'
+
+# Load internals
+require 'subtrigger/dsl'
+require 'subtrigger/revision'
+require 'subtrigger/rule'
+require 'subtrigger/template'
+require 'subtrigger/path'
+
 module Subtrigger
-  attr_accessor :svn, :sendmail, :svn_args
 
-  def reset
-    self.svn      = nil
-    self.sendmail = nil
-    self.svn_args = nil
+  # Standard exception for all Subtrigger exceptions
+  Exception = Class.new(Exception)
+
+  # Return the current version number as defined in ./VERSION
+  # @return [String] version number (e.g. '0.3.1')
+  def version
+    File.read(File.join(File.dirname(__FILE__), '..', 'VERSION'))
   end
 
-  def configure(&block)
-    yield self and return self
+  # Run the current file of rules.
+  #
+  # This method is called after all the rules have been defined. It takes
+  # the command line arguments that come from subversion.
+  #
+  # @param [String] repository_path is the path to the repository to query
+  # @param [String] revision_number is the revision number that triggered the
+  #   hook.
+  # @return nil
+  def run(repository_path, revision_number)
+    Template.parse(DATA.read)
+    rev = Revision.new(
+      revision_number,
+      svnlook('info', repository_path),
+      svnlook('dirs-changed', repository_path)
+    )
+    Rule.matching(rev).each { |r| r.run(rev) }
   end
 
-  # Output the version number for this gem by reading /VERSION
-  def version
-    File.read(File.join(File.dirname(__FILE__), *%w{.. VERSION}))
+  # Make a system call to <tt>svn</tt> with the given arguments. The
+  # executable that used is the first found by {Path#to}.
+  #
+  # @example Using multiple arguments
+  #   svn 'update', 'foo', '--ignore-externals'
+  #   # => '/usr/bin/svn update foo --ignore-externals'
+  # @return [String] output from the command
+  def svn(*args)
+    `svn #{[*args].join(' ')}`
   end
 
-  # This is the main spark in the program.
-  # It runs all available triggers on the repository object created with the
-  # two command line arguments: the path to the repository and its revision
-  # number.
+  # Make a system call to <tt>svnlook</tt> with the given arguments. The
+  # executable # that used is the first found in
+  # <tt>POSSIBLE_PATHS</tt>.
   #
-  # If an exception occurs, the program will quit with its error message.
-  def run(*args)
-    Trigger.run(Repository.new(*args))
-  rescue Exception => e
-    puts "Error: #{e}" and exit(1)
+  # @example Using multiple arguments
+  #   svnlook 'youngest', '/path/to/repo'
+  #   # => '/usr/bin/svnlook youngest /path/to/repo
+  # @return [String] output from the command
+  def svnlook(*args)
+    `svnlook #{[*args].join(' ')}`
+  end
+
+  # @see Path#initialize
+  # @return [Path] The 'global' Path object
+  def path
+    @path ||= Path.new
   end
 
-  # Define a new +Trigger+ object -- shortcut method to
-  # <tt>Trigger#define</tt>. To enable method chaining this method returns
-  # itself.
-  def on(pattern, &block)
-    Trigger.define(pattern, &block)
-    self
+private
+
+  # Override Kernel#` to prefix our commands with the path to subversion
+  # @param [String] arg is the command to run
+  # @return [String] the command's output
+  # @todo maybe build a check to only prefix the path when actually calling
+  #  svn or svnlook or something.
+  def `(arg)
+    super(path_to('svn') + '/' + arg)
   end
+
   extend self
 end
 
-require 'subtrigger/email'
-require 'subtrigger/trigger'
-require 'subtrigger/repository'
+# Make the DSL available in the top-level domain
+include Subtrigger::Dsl
+
+# At the end of the rules file perfrom the actual {Subtrigger#run}
+at_exit do
+  unless $prevent_subtrigger_run
+    raise ArgumentError unless ARGV.size == 2
+    Subtrigger.run(*ARGV)
+  end
+end

data/lib/subtrigger/dsl.rb

@@ -0,0 +1,42 @@
+module Subtrigger
+  # The Dsl module provides some nice-looking methods that can be used to
+  # perform the most important Subtrigger operations.
+  #
+  # This is intended to be included in the top-level namespace, so a script
+  # can call these functions directly.
+  #
+  # @author Arjan van der Gaag
+  # @since 0.3.0
+  module Dsl
+    # Define a new trigger on incoming Revision.
+    #
+    # @see Rule#initialize
+    # @return [nil]
+    def on(*args, &block)
+      Rule.new(*args, &block)
+    end
+
+    # Create and deliver a new Mail object using Pony. See its documentation
+    # for more information.
+    # @return [nil]
+    def mail(*args)
+      ::Pony.mail(*args)
+    end
+
+    # Call Subversion commands using the configured svn executable.
+    #
+    # @see Subtrigger#svn
+    # @return [String] the command's output
+    def svn(*args)
+      Subtrigger.svn(*args)
+    end
+
+    # Get a template defined inline and format it using the given arguments.
+    #
+    # @see Template#format
+    # @return [String] the formatted template
+    def template(name, *format_arguments)
+      Template.find(name).format [*format_arguments]
+    end
+  end
+end