gwooks 0.0.4 → 0.0.5

data/README.md

@@ -1,9 +1,9 @@
 # Gwooks
 
-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.
+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
 
@@ -21,7 +21,8 @@ Or install it yourself as:
 
 ## Usage
 
-First extend the `Gwooks::Base` class and use the DSL to create actions to be performed in response to a push:
+First extend the `Gwooks::Base` class and use the DSL to create actions to be
+performed in response to a push:
 
 ```ruby
 class MyActions < Gwooks::Base
@@ -31,7 +32,7 @@ class MyActions < Gwooks::Base
     # a push to a repo named "my_cool_project"
 
     # Here you can also access the payload sent by GitHub, parsed to a hash:
-    contributors = payload[:commits].map {|c| c[:author][:name] }
+    contributors = payload[:commits].map {|c| c[:author][:name] }.uniq
     send_email "someone@email.com", "my_cool_project received changes by: #{ contributors.join(', ') }"
   end
 
@@ -52,8 +53,8 @@ class MyActions < Gwooks::Base
 end
 ```
 
-Then set up an application providing an endpoint for the GitHub post-receive webhook 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"
@@ -63,7 +64,8 @@ post "/webhook" do
 end
 ```
 
-Alternatively, you can use the sinatra application provided by the class `Gwooks::App`:
+Alternatively, you can use the sinatra application provided by the class
+`Gwooks::App`:
 
 ```ruby
 # In your config.ru
@@ -76,32 +78,41 @@ Gwooks::App.use_webhook MyActions
 run Gwooks::App
 ```
 
-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.
+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
+### Class methods (DSL)
 
-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"]`).
+Each of the DSL methods matches a corresponding property in the payload object
+(e.g. `repository_owner_email` matches
+`payload["repository"]["owner"]["email"]`). The payload is the one sent by the
+GitHub post-receive hooks, parsed into a hash and with an additional `branch`
+property.
 
-Note that all the methods starting with `commits` are also aliased with the singular `commit`, and
-those starting with `repository` are aliased with `repo` to improve code readability.
+Note that all the methods starting with `commits` are also aliased with the
+singular `commit`, and those starting with `repository` are aliased with
+`repo` to improve code readability.
 
 The signature is identical for all methods:
 
 ```ruby
-dsl_method_name(pattern, &block)
+repository_owner_email(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.
+**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.
+**block** is called once if there is at least one match, and it gets passed
+the match, or an array of matches if the target property is an array (all
+`commits` methods match against the array of commits and their properties). The
+match is a MatchData object when regexp matching is used, or the matched
+pattern otherwise. The block is evaluated in the instance scope, and thus can
+access the `payload` object.
 
-Here is the full list of the DSL methods: 
+Here is the full list of DSL methods: 
 ```
 after
 before
@@ -128,13 +139,43 @@ repository_watchers    (alias: repo_watchers)
 ```
 
 
-## Beta
+## Payload
 
-Please take into consideration that this is a beta release, and as such the API may change
+The payload sent by GitHub is parsed into a hash-like object and is available
+through the `payload` instance method. For convenience, a `branch` property is
+added to it, indicating the branch that received the push (extrapolated from
+the `ref`). The payload property can be indifferently accessed using symbol or
+string keys.
+
+The `payload` object also has a `resolve` method that takes a string key and
+returns the matched property (or array of matched properties) or `nil` if the
+property or one of its parents is not set:
+
+```ruby
+payload.resolve "repository.owner.name"
+# returns the repo owner name, or nil if either payload["repository"],
+# payload["repository"]["owner"] or payload["repository"]["owner"]["name"] are
+# not set.
+
+payload.resolve "commits.author.name"
+# returns the array of each commit's author name
+# Equivalent to `payload["commits"].map {|c| c["author"]["name"]}`, but it
+# does not raise errors if some property is not set.
+```
+
+
+## Alpha release
+
+Please take into consideration that this is an alpha release, and as such the API
+may change frequently.
 
 
 ## Changelog
 
+v0.0.5 - Add `branch` payload property and corresponding DSL method
+
+v0.0.4 - Payload with indifferent access
+
 v0.0.3 - Alias `repository_` methods to `repo_`
 
 v0.0.2 - Alias `commits_` methods to `commit_`

data/lib/gwooks/base.rb

@@ -24,6 +24,7 @@ module Gwooks
       method_names = %w(
         after
         before
+        branch
         commits_added
         commits_author_email
         commits_author_name

data/lib/gwooks/payload.rb

@@ -11,8 +11,17 @@ module Gwooks
           hash[key.to_s] if key.is_a? Symbol
         end
         payload = JSON.parse(payload) if payload.is_a? String
+        set_branch payload
         new_hash.update(payload)
       end
+
+      private
+
+      def set_branch(payload)
+        if payload["ref"] and payload["ref"].start_with? "refs/heads/"
+          payload["branch"] = payload["ref"].gsub(/^refs\/heads\//, "")
+        end
+      end
     end
 
     def resolve(key)
@@ -51,7 +60,7 @@ module Gwooks
       else
         obj
       end
-    end
+    end 
 
   end
 end

data/lib/gwooks/version.rb

@@ -1,3 +1,3 @@
 module Gwooks
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/spec/gwooks/base_spec.rb

@@ -35,6 +35,7 @@ describe "subclass of Gwooks::Base" do
   method_names = %w(
     after
     before
+    branch
     commits_added
     commits_author_email
     commits_author_name

data/spec/gwooks/payload_spec.rb

@@ -13,6 +13,11 @@ describe Gwooks::Payload do
         payload = Gwooks::Payload.new({"foo" => "bar"})
         payload.should == {"foo" => "bar"}
       end
+
+      it "creates the additional 'branch' property from ref" do
+        payload = Gwooks::Payload.new({"ref" => "refs/heads/foo"})
+        payload.should == {"ref" => "refs/heads/foo", "branch" => "foo"}
+      end
     end
   end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: gwooks
 version: !ruby/object:Gem::Version 
-  hash: 23
-  prerelease: false
+  hash: 21
+  prerelease: 
   segments: 
   - 0
   - 0
-  - 4
-  version: 0.0.4
+  - 5
+  version: 0.0.5
 platform: ruby
 authors: 
 - Luca Ongaro
@@ -15,12 +15,9 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-01-15 00:00:00 +01:00
-default_executable: 
+date: 2013-01-19 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: json
-  prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -30,11 +27,11 @@ dependencies:
         segments: 
         - 0
         version: "0"
+  prerelease: false
   type: :runtime
+  name: json
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: sinatra
-  prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -44,11 +41,11 @@ dependencies:
         segments: 
         - 0
         version: "0"
+  prerelease: false
   type: :runtime
+  name: sinatra
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: rspec
-  prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -58,11 +55,11 @@ dependencies:
         segments: 
         - 0
         version: "0"
+  prerelease: false
   type: :development
+  name: rspec
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: rack-test
-  prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -72,7 +69,9 @@ dependencies:
         segments: 
         - 0
         version: "0"
+  prerelease: false
   type: :development
+  name: rack-test
   version_requirements: *id004
 description: A DSL for quickly creating endpoints for GitHub post-receive webhooks.
 email: 
@@ -100,7 +99,6 @@ files:
 - spec/gwooks/payload_spec.rb
 - spec/integration/integration_spec.rb
 - spec/spec_helper.rb
-has_rdoc: true
 homepage: https://github.com/lucaong/gwooks
 licenses: []
 
@@ -130,7 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: A DSL for quickly creating endpoints for GitHub post-receive webhooks. It provides methods for executing blocks of code when GitHub posts a payload matching some conditions in response to a code push.