github_api 0.1.0.pre

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Piotr Murach
+
+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/README.rdoc

@@ -0,0 +1,159 @@
+= github
+
+A Ruby wrapper for the GitHub REST API v3.
+
+Supports all the API methods(nearly 200). It's build in a modular way, that is, you can either instantiate the whole api wrapper Github.new or use parts of it e.i. Github::Repos.new if working solely with repositories is your main concern.
+
+== Installation
+
+Grab the gem by issuing
+
+  gem install github-api
+
+or in your Gemfile
+
+  gem 'github-api'
+
+== Usage
+
+Create a new client instance
+
+  @github = Github.new
+
+At this stage you can also supply various configuration parameters, such as :user, :repo, :org etc..,
+which are used thoughtout the API
+
+  @github = Github.new :user => 'peter-murach', :repo => 'github-api'
+
+In order to authenticate the user through OAuth2 on GitHub you need to
+
+* visit https://github.com/account/applications/ and register your app
+* authorize your credentials https://github.com/login/oauth/authorize
+* get your token https://github.com/login/oauth/access_token
+
+Once you have your consumer and token keys, configure your github instance following instructions under Configuration.
+
+You can interact with GitHub interface, for example repositories, by issueing following calls
+
+  @github.repos.commits
+  @github.repos.branches
+  @github.repos.contributors
+
+The code base is modular and allows for you to work specifically with a given part of GitHub API e.g. repositories
+
+  @repos = Github::Repos.new
+  @repos.branches 'peter-murach', 'github'
+
+or
+
+  @repos = Github::Repos.new :user => 'peter-murach', :repo => 'github'
+  @repos.branches
+
+The response is of type [Hashie::Mash] and allows to traverse all the json response attributes like method calls e.i.
+
+  @repos = Github::Repos.new :user => 'peter-murach', :repo => 'github'
+  @repos.branches do |branch|
+    puts branch.name
+  end
+
+== API
+
+Main API methods are grouped into the following classes that can be instantiated on their own
+
+  Github         - full API access
+  Github::Gists
+  Github::GitData
+  Github::Issues
+  Github::Orgs
+  Github::PullRequests
+  Github::Repos
+  Github::Users
+
+Some parts of GitHub API v3 require you to be autheticated, for instance the following are examples of API only for the authenticated user
+
+  Github::Users::Emails
+  Github::Users::Keys
+
+All method calls form ruby like sentences and allow for intuitive api navigation, for instance
+
+  @github = Github.new :oauth_token => '...'
+  @github.users.following 'wycats'  # => returns users that 'wycats' is following
+  @github.users.following? 'wycats' # => returns true if following, otherwise false
+
+For specification on all available methods go to http://developer.github.com/v3/ or
+read the rdoc, all methods are documented there with examples of usage.
+
+== MIME Types
+
+Provides support for the following mime types
+
+In order to pass a mime type with your request do
+
+  @github = Github.new :oauth_token
+  @github...
+
+== Configuration
+
+Certain methods require authentication. To get your GitHub OAuth v2 credentials,
+register an app at https://github.com/account/applications/
+
+  Github.configure do |config|
+    config.oauth_token   = YOUR_OAUTH_ACCESS_TOKEN
+  end
+
+or
+
+  Github.new(:oauth_token => YOUR_OAUTH_TOKEN)
+
+All parameters can be overwirtten as per method call. By passing parameters hash...
+
+== Examples
+
+Some api methods require input parameters, these are added simply as a hash properties, for instance
+
+  @issues = Github::Issues.new :user => 'peter-murach', :repo => 'github-api'
+  @issues.milestones :state => 'open', :sort => 'due_date', :direction => 'asc'
+
+Other methods may require inputs as an array of strings
+
+  @users = Github::Users.new :oauth_token => '...'
+  @users.add_email 'email1', 'email2', ..., 'emailn' # => Adds emails to the authenticated user
+
+If a method returns a collection, you can iterator over it by supplying a block parameter,
+
+  @issues = Github::Issues.new :user => 'peter-murach', :repo => 'github-api'
+  @issues.events do |event|
+    puts event.actor.login
+  end
+
+Query requests instead of http responses return boolean values
+
+  @github = Github.new
+  @github.orgs.public_member? 'github', 'technoweenie' # => true
+
+== Caching
+
+== TODO
+
+* Add support for mime types
+* Add request caching - local filestore?, http caching?.
+* Add oauth2 helper methods.
+* Add response processing methods
+* Add helper methods to return iterators over most common collections.
+* Add response set helper methods e.i. pagination.
+* Add DSL falvoured api access
+
+== Contributing to github
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 Piotr Murach. See LICENSE.txt for
+further details.

data/Rakefile

@@ -0,0 +1,52 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "github"
+  gem.homepage = "http://github.com/peter-murach/github"
+  gem.license = "MIT"
+  gem.summary = %Q{TODO: one-line summary of your gem}
+  gem.description = %Q{TODO: longer description of your gem}
+  gem.email = ""
+  gem.authors = ["Piotr Murach"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+require 'cucumber/rake/task'
+Cucumber::Rake::Task.new(:features)
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "github #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/features/github.feature

@@ -0,0 +1,9 @@
+Feature: something something
+  In order to something something
+  A user something something
+  something something something
+
+  Scenario: something something
+    Given inspiration
+    When I create a sweet new gem
+    Then everyone should see how awesome I am

data/features/support/env.rb

@@ -0,0 +1,13 @@
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../../lib')
+require 'github'
+
+require 'rspec/expectations'

data/lib/github_api.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+
+require 'github_api/version'
+require 'github_api/configuration'
+require 'github_api/connection'
+
+module Github
+  extend Configuration
+
+  class << self
+    # Alias for Github::Client.new
+    #
+    # @return [Github::Client]
+    def new(options = {})
+      Github::Client.new(options)
+    end
+
+    # Delegate to Github::Client
+    #
+    def method_missing(method, *args, &block)
+      return super unless new.respond_to?(method)
+      new.send(method, *args, &block)
+    end
+
+    def respond_to?(method, include_private = false)
+      new.respond_to?(method, include_private) || super(method, include_private) 
+    end
+  end
+
+  module AutoloadHelper
+
+    def autoload_all(prefix, options)
+      options.each do |const_name, path|
+        autoload const_name, File.join(prefix, path)
+      end
+    end
+  end
+
+  extend AutoloadHelper
+
+  autoload_all 'github_api',
+    :API          => 'api',
+    :Client       => 'client',
+    :Repos        => 'repos',
+    :Request      => 'request',
+    :Response     => 'response',
+    :Error        => 'error',
+    :Issues       => 'issues',
+    :Gists        => 'gists',
+    :GitData      => 'git_data',
+    :Orgs         => 'orgs',
+    :PullRequests => 'pull_requests',
+    :Users        => 'users'
+
+end # Github

data/lib/github_api/api.rb

@@ -0,0 +1,133 @@
+# encoding: utf-8
+
+require 'github_api/configuration'
+require 'github_api/connection'
+require 'github_api/request'
+
+module Github
+  # @private
+  class API
+    include Connection
+    include Request
+
+    VALID_API_KEYS = [
+      :per_page,
+      :pagination
+    ]
+
+    attr_reader *Configuration::VALID_OPTIONS_KEYS
+    attr_accessor *VALID_API_KEYS
+
+    # Callback to update global configuration options
+    class_eval do
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        define_method "#{key}=" do |arg|
+          self.instance_variable_set("@#{key}", arg)
+          Github.send("#{key}=", arg)
+        end
+      end
+    end
+
+    # Creates new API
+    def initialize(options = {})
+      options = Github.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+      @cached = Hash.new
+    end
+
+    private
+
+    # Responds to attribute query
+    def method_missing(method, *args, &block)
+      if method.to_s =~ /^(.*)\?$/
+        return !self.send($1.to_s).nil?
+      else
+        super
+      end
+    end
+
+    def _validate_inputs(required, provided)
+      required.all? do |key|
+        provided.has_key? key
+      end
+    end
+
+    def _validate_presence_of(*params)
+      params.each do |param|
+        raise ArgumentError, "parameter cannot be nil" if param.nil?
+      end
+    end
+
+    def _validate_user_repo_params(user_name, repo_name)
+      raise ArgumentError, "[user] parameter cannot be nil" if user_name.nil?
+      raise ArgumentError, "[repo] parameter cannot be nil" if repo_name.nil?
+    end
+
+    def _update_user_repo_params(user_name, repo_name=nil)
+      self.user = user_name || self.user
+      self.repo = repo_name || self.repo
+    end
+
+    def _merge_user_into_params!(params)
+      params.merge!({ 'user' => self.user }) if user?
+    end
+
+    def _merge_user_repo_into_params!(params)
+      { 'user' => self.user, 'repo' => self.repo }.merge!(params)
+    end
+
+    def _normalize_params_keys(params)
+      case params
+      when Hash
+        params.keys.each do |k|
+          params[k.to_s] = params.delete(k)
+          _normalize_params_keys(params[k.to_s])
+        end
+      when Array
+        params.map! { |el| el.to_s }
+      else
+        params
+      end
+      return params
+    end
+
+    def _filter_params_keys(keys, params)
+      params.reject! { |k,v| !keys.include? k }
+    end
+
+    def _validate_params_values(options, params)
+      params.each do |k, v|
+        next unless options.keys.include?(k)
+        if options[k].is_a?(Array) && !options[k].include?(params[k])
+          raise ArgumentError, "Wrong value for #{k}, allowed: #{options[k].join(', ')}"
+        elsif options[k].is_a?(Regexp) && !(options[k] =~ params[k])
+          raise ArgumentError, "String does not match the parameter value."
+        end
+      end
+    end
+
+    def _merge_parameters(params)
+    end
+
+    def _extract_parameters(array)
+      if array.last.is_a?(Hash) && array.last.instance_of?(Hash)
+        pop
+      else
+        {}
+      end
+    end
+
+    # Passes configuration options to instantiated class
+    # TODO implement 
+    # @private
+    def _create_instance(klass)
+      klass.new(options)
+    end
+
+    def _token_required
+    end
+
+  end # API
+end # Github