octocat_herder 0.0.2 → 0.1.0

data/.document

@@ -2,4 +2,5 @@ lib/**/*.rb
 bin/*
 - 
 features/**/*.feature
-LICENSE.txt
+LICENSE
+CONTRIBUTING.markdown

data/.travis.yml

@@ -0,0 +1,3 @@
+rvm:
+  - 1.8.7
+  - 1.9.2

data/CONTRIBUTING.markdown

@@ -0,0 +1,93 @@
+Checklist (and a short version for the impatient)
+=================================================
+
+  * Commits:
+
+    - Make commits of logical units.
+
+    - Check for unnecessary whitespace with "git diff --check" before
+      committing.
+
+    - Commit using Unix line endings (check the settings around "crlf"
+      in git-config(1)).
+
+    - Do not check in commented out code or unneeded files.
+
+    - The first line of the commit message should be a short
+      description (50 characters is the soft limit, excluding ticket
+      number(s)), and should skip the full stop.
+
+    - The body should provide a meaningful commit message, which:
+
+      - uses the imperative, present tense: "change", not "changed" or
+        "changes".
+
+      - includes motivation for the change, and contrasts its
+        implementation with the previous behavior.
+
+    - Make sure that you have tests for the bug you are fixing, or
+      feature you are adding.
+
+    - Make sure the test suite passes after your commit (rake spec).
+
+  * Submission:
+
+    - Fork the repository on GitHub.
+
+    - Push your changes to a topic branch in your fork of the
+      repository.
+
+    - Submit a pull request.
+
+The long version
+================
+
+  1.  Make separate commits for logically separate changes.
+
+      Please break your commits down into logically consistent units
+      which include new or changed tests relevent to the rest of the
+      change.  The goal of doing this is to make the diff easier to
+      read for whoever is reviewing your code.  In general, the easier
+      your diff is to read, the more likely someone will be happy to
+      review it and get it into the code base.
+
+      If you're going to refactor a piece of code, please do so as a
+      separate commit from your feature or bug fix changes.
+
+      We also really appreciate changes that include tests to make
+      sure the bug isn't re-introduced, and that the feature isn't
+      accidentally broken.
+
+      Describe the technical detail of the change(s).  If your
+      description starts to get too long, that's a good sign that you
+      probably need to split up your commit into more finely grained
+      pieces.
+
+      Commits which plainly describe the the things which help
+      reviewers check the patch and future developers understand the
+      code are much more likely to be merged in with a minimum of
+      bike-shedding or requested changes.  Ideally, the commit message
+      would include information, and be in a form suitable for
+      inclusion in the release notes.
+
+      Please also check that you are not introducing any trailing
+      whitespaces or other "whitespace errors".  You can do this by
+      running "git diff --check" on your changes before you commit.
+
+  3.  Sending your changes
+
+      To submit your changes via a GitHub pull request, we _highly_
+      recommend that you have them on a topic branch, instead of
+      directly on "master".  It makes things much easier to keep track
+      of, especially if you decide to work on another thing before
+      your first change is merged in.
+
+      GitHub has some pretty good
+      [general documentation](http://help.github.com/) on using
+      their site.  They also have documentation on
+      [creating pull requests](http://help.github.com/send-pull-requests/).
+
+      In general, after pushing your topic branch up to your
+      repository on GitHub, you'll switch to the branch in the GitHub
+      UI and click "Pull Request" towards the top of the page in order
+      to open a pull request.

data/Gemfile

@@ -4,10 +4,12 @@ gem "httparty",    "~> 0.7.8"
 gem "link_header", "~> 0.0.5"
 
 group :development do
-  gem "rspec",   "~> 2.6.0"
-  gem "mocha",   "~> 0.9.12"
-  gem "bundler", "~> 1.0.0"
-  gem "jeweler", "~> 1.6.4"
-  gem "rcov",    ">= 0"
-  gem "rdoc",    ">= 2.4.2"
+  gem "rspec",     "~> 2.6.0"
+  gem "mocha",     "~> 0.9.12"
+  gem "bundler",   "~> 1.0.0"
+  gem "jeweler",   "~> 1.6.4"
+  gem "rcov",      ">= 0"
+  gem "yard",      "~> 0.6.0"
+  gem "rdoc",      "~> 3.8.0"
+  gem "bluecloth", "~>2.1.0"
 end

data/Gemfile.lock

@@ -1,6 +1,7 @@
 GEM
   remote: http://rubygems.org/
   specs:
+    bluecloth (2.1.0)
     crack (0.1.8)
     diff-lcs (1.1.2)
     git (1.2.5)
@@ -23,16 +24,19 @@ GEM
     rspec-expectations (2.6.0)
       diff-lcs (~> 1.1.2)
     rspec-mocks (2.6.0)
+    yard (0.6.8)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  bluecloth (~> 2.1.0)
   bundler (~> 1.0.0)
   httparty (~> 0.7.8)
   jeweler (~> 1.6.4)
   link_header (~> 0.0.5)
   mocha (~> 0.9.12)
   rcov
-  rdoc (>= 2.4.2)
+  rdoc (~> 3.8.0)
   rspec (~> 2.6.0)
+  yard (~> 0.6.0)

data/README.markdown

@@ -0,0 +1,46 @@
+# Octocat Herder [![Build status](http://travis-ci.org/jhelwig/octocat_herder.png)](http://travis-ci.org/jhelwig/octocat_herder)
+
+Octocat Herder is a wrapper for the GitHub v3 API.
+
+## On-line documentation
+
+* [rdoc.info](http://rdoc.info/gems/octocat_herder/frames)
+
+## Requirements
+
+* Gems
+  * link_header
+  * httparty
+
+## Basic usage
+
+Quick start:
+
+    require 'rubygems'
+    => true
+    require 'octocat_herder'
+    => true
+
+    herder = OctocatHerder.new
+    => #<OctocatHerder:0x7f792d3c4918 ...>
+
+    me = herder.user 'jhelwig'
+    => #<OctocatHerder::User:0x7f792d3b6070 ...>
+
+    me.html_url
+    => "https://github.com/jhelwig"
+
+    me.available_attributes.sort
+    => ["avatar_url", "bio", "blog", "company", "created_at", "email", "followers", "following", "hireable", "html_url", "location", "login", "name", "public_gists", "public_repos", "url", "user_id", "user_type"]
+
+    repos = me.repositories
+    => [#<OctocatHerder::Repository:0x7f792d364bf8 ...>, #<OctocatHerder::Repository:0x7f792d364bd0 ..>, #<OctocatHerder::Repository:0x7f792d364ba8 ...>, ...]
+
+
+## Contributing to octocat_herder
+
+See {file:CONTRIBUTING.markdown CONTRIBUTING.markdown} for further details.
+
+## Copyright
+
+Copyright (c) 2011 Jacob Helwig. See {file:LICENSE LICENSE} for further details.

data/Rakefile

@@ -38,12 +38,5 @@ end
 
 task :default => :spec
 
-require 'rdoc/task'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "octocat_herder #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+require 'yard'
+YARD::Rake::YardocTask.new

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.1.0

data/lib/octocat_herder/base.rb

@@ -1,19 +1,50 @@
 require 'cgi'
 require 'link_header'
-require 'parsedate'
+
+begin
+  require 'parsedate'
+rescue LoadError
+end
+
 require 'uri'
 
 require 'octocat_herder/connection'
 
 class OctocatHerder
-  class Base
-    attr_reader :raw, :connection
-
+  # This provides most of the functionality to interact with the
+  # GitHub v3 API.
+  module Base
+    # The re-hydrated JSON retrieved from the GitHub API.
+    #
+    # @since 0.0.1
+    # @return [Hash]
+    attr_reader :raw
+
+    # Our {OctocatHerder::Connection}, so we can make more requests
+    # based on the information we retrieved from the GitHub API.
+    #
+    # @since 0.0.1
+    # @return [OctocatHerder::Connection]
+    attr_reader :connection
+
+    # @api private
+    # @since 0.0.1
+    #
+    # @param [Hash] raw_hash The re-hydrated JSON received from the
+    #   GitHub API via {OctocatHerder::Connection}.
+    #
+    # @param [OctocatHerder::Connection] conn If not provided requests
+    #   will be unauthenticated.
     def initialize(raw_hash, conn = OctocatHerder::Connection.new)
       @connection = conn
       @raw = raw_hash
     end
 
+    # We use the +method_missing+ magic to create accessors for the
+    # information we got back from the GitHub API.  You can get a list
+    # of all of the available things from {#available_attributes}.
+    #
+    # @since 0.0.1
     def method_missing(id, *args)
       unless @raw and @raw.keys.include?(id.id2name)
         raise NoMethodError.new("undefined method #{id.id2name} for #{self}:#{self.class}")
@@ -22,6 +53,13 @@ class OctocatHerder
       @raw[id.id2name]
     end
 
+    # This returns a list of the things that the API request returned
+    # to us.
+    #
+    # @since 0.0.1
+    #
+    # @return [Array<String>] Names of available methods providing
+    #   additional detail about the object.
     def available_attributes
       attrs = []
       attrs += @raw.keys.reject do |k|
@@ -36,53 +74,24 @@ class OctocatHerder
 
     private
 
-    def self.raw_get(conn, end_point, options={})
-      paginated    = options.delete(:paginated)
-      query_params = options.delete(:params) || {}
-
-      query_params[:per_page] = 100 if paginated and query_params[:per_page].nil?
-      query_string = query_string_from_params(query_params)
-
-      result = conn.get(end_point + query_string, options)
-      raise "Unable to retrieve #{end_point}" unless result
-
-      full_result = result.parsed_response
-
-      if paginated
-        if next_page = page_from_headers(result.headers, 'next')
-          query_params[:page] = next_page
-
-          new_options = options.merge(query_params)
-          new_options[:paginated] = true
-
-          full_result += raw_get(conn, end_point, new_options)
-        end
-      end
-
-      full_result
-    end
-
-    def self.page_from_headers(headers, type)
-      link = LinkHeader.parse(headers['link']).find_link(['rel', type])
-      return unless link
-
-      CGI.parse(URI.parse(link.href).query)['page'].first
-    end
-
-    def self.query_string_from_params(params)
-      return '' if params.keys.empty?
-
-      '?' + params.map {|k,v| "#{URI.escape("#{k}")}=#{URI.escape("#{v}")}"}.join('&')
-    end
-
+    # Intended to be overridden in classes using {OctocatHerder::Base},
+    # so they can make the methods they define show up in
+    # {#available_attributes}.
+    #
+    # @since 0.0.1
     def additional_attributes
       []
     end
 
+    # @since 0.0.1
     def parse_date_time(date_time)
       return nil unless date_time
 
-      Time.utc(*ParseDate.parsedate(date_time))
+      if defined? ParseDate
+        Time.utc(*ParseDate.parsedate(date_time))
+      else
+        DateTime.parse date_time
+      end
     end
   end
 end

data/lib/octocat_herder/connection.rb

@@ -2,16 +2,48 @@ require 'httparty'
 require 'link_header'
 
 class OctocatHerder
+  # This implements some additional functionality around HTTParty to
+  # help make working with the GitHub API a little nicer.
   class Connection
     include HTTParty
     base_uri 'https://api.github.com'
 
-    attr_reader :user_name, :password, :oauth2_token
+    # User name to use when doing basic HTTP authentication.
+    #
+    # @since 0.0.1
+    attr_reader :user_name
 
-    def httparty_options
-      @httparty_options || {}
-    end
+    # Password to use when doing basic HTTP authentication.
+    #
+    # @since 0.0.1
+    attr_reader :password
+
+    # The OAuth2 token to use when doing OAuth2 authentication.
+    #
+    # @since 0.0.1
+    attr_reader :oauth2_token
 
+    # If provided a hash of login information, the
+    # {OctocatHerder::Connection} will attempt to make authenticated
+    # requests.
+    #
+    # @example Unauthenticated requests
+    #   connection = OctocatHerder::Connection.new
+    #
+    # @example Providing an OAuth2 token
+    #   connection = OctocatHerder::Connection.new :oauth2_token => 'token'
+    #
+    # @example Providing user name & password
+    #   connection = OctocatHerder::Connection.new :user_name => 'user', :password => 'pass'
+    #
+    # If no hash is provided, then unauthenticated requests will be
+    # made.
+    #
+    # @since 0.0.1
+    # @param [Hash<Symbol => String>] options Login information
+    # @option options [String] :user_name
+    # @option options [String] :password
+    # @option options [String] :oauth2_token
     def initialize(options={})
       raise ArgumentError.new(
         "OctocatHerder::Connection does not accept: #{options.class}"
@@ -29,7 +61,7 @@ class OctocatHerder
       end
 
       if options.keys.include?(:oauth2_token) and options.keys.include?(:user_name)
-        raise ArgumentError.new('Cannot provide both an OAuth2 Token, and a user name and password')
+        raise ArgumentError.new('Cannot provide both an OAuth2 token, and a user name and password')
       end
 
       @user_name    = options[:user_name]
@@ -43,13 +75,120 @@ class OctocatHerder
       end
     end
 
+    # Execute a GET request against the GitHub v3 API.
+    #
+    # @since development
+    #
+    # @param [String] end_point The part of the API URL after
+    #   +'api.github.com'+, including the leading +'/'+.
+    #
+    # @param [Hash] options A Hash of options to be passed down to
+    #   HTTParty, with a couple of extra options.
+    #
+    # @option options [true, false] :paginated Retrieve all pages from
+    #   a paginated end-point.
+    #
+    # @option options [Hash<String, Symbol => String>] :params
+    #   Constructed into a query string using
+    #   {OctocatHerder::Connection#query_string_from_params}.
     def get(end_point, options={})
+      paginated = options.delete(:paginated)
+      options[:params] ||= {}
+
+      options[:params][:per_page] = 100 if paginated and options[:params][:per_page].nil?
+
+      result = raw_get(end_point, options)
+      raise "Unable to retrieve #{end_point}" unless result
+
+      full_result = result.parsed_response
+
+      if paginated
+        if next_page = page_from_headers(result.headers, 'next')
+          options[:params][:page] = next_page
+          options[:paginated]     = true
+
+          full_result += raw_get(end_point, options)
+        end
+      end
+
+      full_result
+    end
+
+    # Small wrapper around HTTParty.get, which handles adding
+    # authentication information to the API request.
+    #
+    # @since development
+    def raw_get(end_point, options={})
+      query_params = options.delete(:params) || {}
+      query_string = query_string_from_params(query_params)
+
       request_options = options.merge(httparty_options)
       if httparty_options.has_key?(:headers) and options.has_key(:headers)
         request_options[:headers] = options[:headers].merge(httparty_options[:headers])
       end
 
-      OctocatHerder::Connection.get(end_point, request_options)
+      OctocatHerder::Connection.get(end_point + query_string, request_options)
+    end
+
+    # Are we making authenticated requests?
+    #
+    # @since development
+    # @return [true, false]
+    def authenticated_requests?
+      if (user_name and password) or oauth2_token
+        true
+      else
+        false
+      end
+    end
+
+    # Retrieve the page number of a given 'Link:' header from a hash
+    # of HTTP Headers
+    #
+    # +type+ can be one of:
+    # ['+next+'] The immediate next page of results.
+    # ['+last+'] The last page of first.
+    # ['+first+'] The first page of results.
+    # ['+prev+'] The immediate previous page of results.
+    #
+    # @since development
+    #
+    # @raise [ArgumentError] If type is not one of the allowed values.
+    #
+    # @param [Hash] headers
+    #
+    # @param ['next', 'last', 'first', 'prev'] type
+    def page_from_headers(headers, type)
+      raise ArgumentError.new(
+        "Unknown type: #{type}"
+      ) unless ['next', 'last', 'first', 'prev'].include? type
+
+      link = LinkHeader.parse(headers['link']).find_link(['rel', type])
+      return unless link
+
+      CGI.parse(URI.parse(link.href).query)['page'].first
+    end
+
+    # Convenience method to generate URL query strings.
+    #
+    # @since development
+    #
+    # @param [Hash] params A Hash of key/values to be turned into a
+    #   URL query string.  Does not support nested data.
+    #
+    # @return [String] Empty string if params is an empty hash,
+    #   otherwise a string of the query parameters with a leading
+    #   +'?'+.
+    def query_string_from_params(params)
+      return '' if params.keys.empty?
+
+      '?' + params.map {|k,v| "#{URI.escape("#{k}")}=#{URI.escape("#{v}")}"}.join('&')
+    end
+
+    private
+
+    def httparty_options
+      @httparty_options || {}
     end
   end
 end

data/lib/octocat_herder/pull_request/repo.rb

@@ -3,32 +3,66 @@ require 'octocat_herder/user'
 require 'octocat_herder/repository'
 
 class OctocatHerder
-  class PullRequest < Base
-    class Repo < ::OctocatHerder::Base
+  class PullRequest
+    # A representation of the repsoitory meta-data returned from the
+    # pull request API.  This is only ever useful when returned from
+    # OctocatHerder::PullRequest#head or
+    # OctocatHerder::PullRequest#base.
+    class Repo
+      include OctocatHerder::Base
+
+      # The login name of the owner of this repository.
+      #
+      # @since 0.0.1
+      # @return [String]
       def user_login
         @raw['user']['login']
       end
 
+      # The ID number of the owner of this repository.
+      #
+      # @since 0.0.1
+      # @return [Integer]
       def user_id
         @raw['user']['id']
       end
 
+      # The URL to the avatar image of the owner of this repository.
+      #
+      # @since 0.0.1
+      # @return [String]
       def user_avatar_url
         @raw['user']['avatar_url']
       end
 
+      # The URL of the owner of this repository.
+      #
+      # @since 0.0.1
+      # @return [String]
       def user_url
         @raw['user']['url']
       end
 
+      # The owner of this repository.
+      #
+      # @note This is cached locally to the instance of OctocatHerder::PullRequest::Repo, but will make an additional API request to populate it initially.
+      #
+      # @since 0.0.1
+      # @return [OctocatHerder::User]
       def user
-        @user = OctocatHerder::User.fetch(@raw['user'], connection)
+        @user ||= OctocatHerder::User.fetch(@raw['user'], connection)
       end
 
+      # The detailed information about the repository.
+      #
+      # @since 0.0.1
+      # @return [OctocatHerder::Repository]
       def repo
-        @repo = OctocatHerder::Repository.new(@raw['repo'], connection)
+        @repo ||= OctocatHerder::Repository.new(@raw['repo'], connection)
       end
 
+      private
+
       def addtional_attributes
         ['user_login', 'user_id', 'user_avatar_url', 'user_url']
       end