gwooks 0.0.1 → 0.0.2

data/README.md

@@ -1,6 +1,9 @@
 # Gwooks
 
-A DSL for quickly creating endpoints for [GitHub post-receive webhooks](https://help.github.com/articles/post-receive-hooks).
+A DSL for quickly creating endpoints for
+[GitHub post-receive webhooks](https://help.github.com/articles/post-receive-hooks).
+It makes it easy to perform some actions whenever one of your GitHub repos receives a push matching someone
+custom conditions.
 
 ## Installation
 
@@ -18,38 +21,45 @@ Or install it yourself as:
 
 ## Usage
 
-Extend the `Gwooks::Base` class and use the dsl to create you hooks:
+First extend the `Gwooks::Base` class and use the DSL to create actions to be performed in response to a push:
 
 ```ruby
-class MyHooks < Gwooks::Base
+class MyHookHandler < Gwooks::Base
   
-  repository_name "gwooks" do
-    # this block gets called when a post-receive webhook
-    # notifies a push to a repo named "gwooks"
+  repository_name "my_cool_project" do
+    # this block gets executed when GitHub receives
+    # a push to a repo named "my_cool_project"
+
+    # Here you can also access the payload sent by GitHub:
+    contributors = payload["commits"].map { |c| c["author"]["name"] }
+    send_email "someone@email.com", "my_cool_project received changes by: #{ contributors.join(', ') }"
   end
 
-  commits_message /Bump new version v(\d+\.\d+\.\d+)/ do |matches|
-    # this block gets called when a post-receive webhook
-    # notifies a push with at least one commit message
-    # matching the Regexp. The block gets passed an array of
-    # MatchData objects, one for every match.
+  commit_message /Bump new version v(\d+\.\d+\.\d+)/ do |matches|
+    # this block gets called when GitHub receives a push
+    # with at least one commit message matching the Regexp.
     matches.each do |match|
-      # assuming a publish_tweet method was defined somewhere
-      # we can tweet about the new version released:
-      publish_tweet("New version released: #{match[1]}")
+      send_email("someone@email.com", "New version released: #{match[1]}")
     end
   end
+  
+  private
+  
+  def send_email(to, msg)
+    # assume we define here a method to send an email
+  end
 
 end
 ```
 
-Then set up an application providing an endpoint for the post-receive webhooks and make use of the class you created:
+Then set up an application providing an endpoint for the GitHub post-receive webhook and make use of the
+class you created:
 
 ```ruby
 require "sinatra"
 
 post "/webhook" do
-  MyHooks.call(params[:payload])
+  MyHookHandler.call(params[:payload])
 end
 ```
 
@@ -57,26 +67,51 @@ Alternatively, you can use the sinatra application provided by the class `Gwooks
 
 ```ruby
 # In your config.ru
+require "gwooks"
 
-Gwooks::App.use_webhook MyHooks
-use Gwooks::App
+# Tell Gwooks::App to use your class
+Gwooks::App.use_webhook MyHookHandler
+
+# Gwooks::App sets up an endpoint on POST /"
+run Gwooks::App
 ```
 
-### Matcher methods
+Finally [set up your GitHub repo](https://help.github.com/articles/post-receive-hooks) to trigger a
+post-receive hook pointing to your endpoint. Whenever GitHub receives a push, your endpoint will be
+notified, and _all_ the matching actions will be performed.
+
+### DSL methods
+
+Each DSL method matches a corresponding property in the payload sent by the GitHub post-receive hooks
+(e.g. `repository_owner_email` matches `payload["repository"]["owner"]["email"]`). Note that all the methods
+starting with `commits` are also aliased with the singular `commit` to improve code readability.
+
+The signature is identical for all methods:
 
-The full list of matcher methods is the following:
+```ruby
+dsl_method_name(pattern, &block)
+```
+
+**pattern** can be any object. If it is a Regexp, it is matched against
+the target property in the payload, otherwise it is checked for equality.
+
+**block** is called passing the match, or array of matches if the target
+property is an array (which is, in all commit* methods). The match is a
+MatchData object when regexp matching is used, or the matched pattern otherwise.
+
+Here is the full list of the DSL methods: 
 ```
 after
 before
-commits_added
-commits_author_email
-commits_author_name
-commits_id
-commits_message
-commits_modified
-commits_removed
-commits_timestamp
-commits_url
+commits_added        (alias: commit_added)
+commits_author_email (alias: commit_author_email)
+commits_author_name  (alias: commit_author_name)
+commits_id           (alias: commit_id)
+commits_message      (alias: commit_message)
+commits_modified     (alias: commit_modified)
+commits_removed      (alias: commit_removed)
+commits_timestamp    (alias: commit_timestamp)
+commits_url          (alias: commit_url)
 ref
 repository_description
 repository_forks
@@ -89,3 +124,7 @@ repository_private
 repository_url
 repository_watchers
 ```
+
+## Beta
+
+Please take into consideration that this is a beta release, and as such the API may change

data/lib/gwooks/base.rb

@@ -54,6 +54,10 @@ module Gwooks
         end
       end
 
+      method_names.select { |n| n.start_with? "commits_" }.each do |method_name|
+        alias_method method_name.gsub(/^commits_/, "commit_"), method_name
+      end
+
     end
 
     attr_reader :payload

data/lib/gwooks/version.rb

@@ -1,3 +1,3 @@
 module Gwooks
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/gwooks/base_spec.rb

@@ -61,6 +61,17 @@ describe "subclass of Gwooks::Base" do
       end
     end
   end
+
+  method_names.select { |n| n.start_with? "commits_" }.each do |method_name|
+    aliased_method_name = method_name.gsub(/^commits_/, "commit_")
+
+    describe aliased_method_name do
+      it "is an alias for #{method_name}" do
+        aliased_method = GwooksBaseSub.method(aliased_method_name.to_sym)
+        aliased_method.should == GwooksBaseSub.method(method_name.to_sym)
+      end
+    end
+  end
  
   describe "instance" do
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: gwooks
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: 
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Luca Ongaro
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-01-13 00:00:00 Z
+date: 2013-01-14 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   requirement: &id001 !ruby/object:Gem::Requirement