github_api_v3 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 971067aab5382fac16ce777598632fc15e967a90
-  data.tar.gz: ef210e058a8dcf7e83e7bbf500ab8c469aafbf69
+  metadata.gz: bd0406fd884e781cfdc83e36808666c83cad39e4
+  data.tar.gz: f4a3414547c49f1c6eb4ca040bb968b6a9a2a92a
 SHA512:
-  metadata.gz: 437519533b96ab76c076e91562a171fe1b84c9fa425c7f10c3e31cc814cb5a011c1e35a8b96b6df0938411b0aed95e02a040a5dcf7f5078013e8734d5cc2e118
-  data.tar.gz: a3af2b6ba0563b841b447b57c96956f94be30d78edf3a4043378bb67d257b5ccc94b775bde27f474392f63a9669fa43a73776211cad0e309ab35eed486f4c697
+  metadata.gz: 29f439a47344bae930b71495dea13f84a8f5da4558a75e71d09e4cac398b74d804a64aac0b2756557a162c99fe9e2a1fe3cce34258d34d7dbc90a635c6753001
+  data.tar.gz: 1c4e26602951983561dab72d654d826ce6d07b27808002ffeeb33b95ef79d8fdfa6aa4cbc848642b9bdc44cb0feaa253ab1d6b625aca704a2f53a18693f14f2b

data/.rspec

@@ -1,2 +1,3 @@
 --color
 --format progress
+--order default

data/README.md

@@ -4,8 +4,14 @@
 
 This is a simple wrapper for GitHub's v3 API. It is in the EARLY stages of development. Knowing a little about [GitHub's API](http://developer.github.com/) will aid in its use.
 
+## Documentation
+
+Full documentation for the gem can be found at [rdoc.info/gems/github_api_v3/frames/index](http://rdoc.info/gems/github_api_v3/frames/index).
+
 ## Installation
 
+To install the gem, issue the following command:
+
 ```bash
 $ gem install github_api_v3
 ```
@@ -14,72 +20,169 @@ $ gem install github_api_v3
 
 ```ruby
 require 'github_api_v3'
-# => true
 ```
 
 ### Unauthenticated Requests
 
-There are multiple different unauthenticated requests to the API. Examples are shown below.
+There are multiple different unauthenticated requests to the API. These are performed when no credentials are given, and usually start with `GitHub`.
 
-#### User
 
-Returns a Hash containing information about a user.
+### Authenticated Requests
+
+Some methods, such as retrieving private repos or emails, require authentication. To create one of these requests, you'll need to pass in your login and access token. You can create a personal access token on your [account page](https://github.com/settings/applications).
 
 ```ruby
+client = GitHub::Client.new(login: 'username', access_token: 'abcdefghijklmnopqrstuvwxyz12345')
+client.emails # => ["email@example.com", "email2@example.com"]
+client.repos  # => #<Array:0x007fb8aa0d1a00>
+client.follow('matz') # => true
+client.user   # => #<Hash:0x007fb8a9109d70>
+```
+
+Anytime a method is shown below starting with `client`, it is an authenticated method.
+
+### Sample usage
+
+#### Users
+
+The following are some sample usages of the Users module.
+
+```ruby
+# Retrieve a single user
 user = GitHub.user('caseyscarborough')
 user.login     # => "caseyscarborough"
 user.name      # => "Casey Scarborough"
 user.html_url  # => "https://github.com/caseyscarborough"
 user.following # => 23
-# etc...
-```
-You can find the available attributes [here](http://developer.github.com/v3/users/#get-a-single-user).
 
-#### Events
+# Retrieve an array of all GitHub users
+GitHub.users
 
-Returns an array of events for a particular user.
+# Get emails for authenticated user
+client.emails
 
-```ruby
-events = GitHub.events('caseyscarborough')
-events.each { |e| puts e.type }
-```
+# Follow/unfollow a user
+client.follow('caseyscarborough')
+client.unfollow('caseyscarborough')
 
-#### Followers
+# Check if a user follows another user
+GitHub.follows?('caseyscarborough','matz')
 
-Returns an array of followers for a user.
+# Get a list of an unauthenticated user's followers
+GitHub.followers('caseyscarborough')
 
-```ruby
-followers = GitHub.followers('caseyscarborough')
-followers.each { |f| puts f.login }
+# Get a list of an authenticated user's followers
+client.followers
+
+# Get a list of user's a user is following
+GitHub.following('caseyscarborough')
+
+# See if authenticated user is following another user
+client.following?('caseyscarborough')
+
+# Get events for a user
+GitHub.events('caseyscarborough')
+
+# etc...
 ```
+You can find the available attributes [here](http://developer.github.com/v3/users/#get-a-single-user). Check the [Users documentation](http://rdoc.info/gems/github_api_v3/GitHub/Client/Users) for the gem for a complete list and more examples.
 
 #### Repositories
 
-Returns an array of repositories that belong to a user.
+The following are some sample usages for the Repos module.
 
 ```ruby
-repos = GitHub.repos('caseyscarborough')
-repos.each { |r| puts r.name }
+# Get repos for an unauthenticated/authenticated user
+GitHub.repos('caseyscarborough')
+client.repos
+
+# Get all public repos on GitHub
+GitHub.all_repos
+
+# Get a specific repo
+GitHub.repo('owner','repo-name')
+
+# Create a repo
+client.create_repo('new-repo', description: 'New repository.', private: true)
+
+# Delete a repo
+client.delete_repo('repo-name')
+
+# Get a repository's contributors/languages/tags/branches/collaborators
+GitHub.contributors('caseyscarborough','github')
+GitHub.languages('caseyscarborough','github')
+GitHub.tags('caseyscarborough','github')
+GitHub.branches('caseyscarborough','github')
+GitHub.collaborators('caseyscarborough','github')
+
+# Get a specific branch
+GitHub.branch('caseyscarborough','github','master')
+
+# Add/remove collaborator
+client.add_collaborator('owner','repo-name','user-to-add')
+client.remove_collaborator('owner','repo-name','user-to-remove')
 ```
+For a full list with descriptions, see the [Repos documentation](http://rdoc.info/gems/github_api_v3/GitHub/Client/Repos) for the gem.
 
-### Authenticated Requests
+#### Gists
 
-Some methods, such as retrieving private repos or emails, require authentication. To create one of these requests, you'll need to pass in your login and access token. You can create a personal access token on your [account page](https://github.com/settings/applications).
+The following are sample uses for the Gists module.
 
 ```ruby
-client = GitHub::Client.new(login: 'username', access_token: 'abcdefghijklmnopqrstuvwxyz12345')
-client.emails # => ["email@example.com", "email2@example.com"]
-client.repos  # => #<Array:0x007fb8aa0d1a00>
-client.follow('matz') # => true
-client.user   # => #<Hash:0x007fb8a9109d70>
+# Get all gists for a user
+GitHub.gists('caseyscarborough')
+
+# Get all gists for authenticated user
+client.gists
+
+# Get all public gists
+GitHub.gists
+
+# Get a gist by id
+GitHub.gist(1234567)
+
+# Create a gist
+client.create_gist(
+  files: {"file1.txt" => { content: "File contents" }}, 
+  description: "Gist description", 
+  public: "false"
+)
+
+# Check if a gist is starred
+client.gist_starred?(1234567)
+
+# Star/unstar/fork/delete a gist
+client.star_gist(1234567)
+client.unstar_gist(1234567)
+client.fork_gist(1234567)
+client.delete_gist(1234567)
 ```
+Check out the [Gist documentation](http://rdoc.info/gems/github_api_v3/GitHub/Client/Gists) for more information.
+
+## Running the Test Suite
+
+The test suite can be run by issuing the following command from the root of the directory:
 
-More functionality to come.
+```bash
+$ rspec spec/
+```
 
 ## To Do
 
 The better question is... What's not to do? Any functionality of the API listed at [developer.github.com](http://developer.github.com/) that isn't currently in effect.
 
+Some main missing functionality:
+* A good bit of the [Repos API](http://developer.github.com/v3/repos/), such as:
+  * Comments
+  * Commits
+  * Hooks
+  * Forks
+  * etc.
+* Markdown
+* Editing Gists
+* Editing Repos
+* Updating User keys
+
 ## Contributing
 
 1. Fork it

data/lib/github_api_v3/client/gists.rb

@@ -1,6 +1,9 @@
 module GitHub
   class Client
 
+    # Contains methods for the Gists API.
+    #
+    # @see http://developer.github.com/v3/gists/
     module Gists
       
       # List gists.
@@ -60,7 +63,7 @@ module GitHub
       # @return [Boolean] True if it is starred, false if not.
       # @see http://developer.github.com/v3/gists/#check-if-a-gist-is-starred
       def gist_starred?(id)
-        get "/gists/#{id}/star", auth_params, true
+        boolean_get "/gists/#{id}/star", auth_params
       end
 
       # Star a gist.
@@ -73,7 +76,7 @@ module GitHub
       # @example
       #   client.star_gist(5928712)
       def star_gist(id)
-        put "/gists/#{id}/star", auth_params, true
+        boolean_put "/gists/#{id}/star", auth_params
       end
 
       # Unstar a gist.
@@ -86,7 +89,7 @@ module GitHub
       # @example
       #   client.unstar_gist(5928712)
       def unstar_gist(id)
-        delete "/gists/#{id}/star", auth_params, true
+        boolean_delete "/gists/#{id}/star", auth_params
       end
 
       # Fork a gist.
@@ -99,7 +102,7 @@ module GitHub
       # @example
       #   client.fork_gist(5928712)
       def fork_gist(id)
-        post "/gists/#{id}/fork", auth_params, {}, true
+        boolean_post "/gists/#{id}/fork", auth_params, {}
       end
 
       # Delete a gist.
@@ -111,8 +114,75 @@ module GitHub
       # @example
       #   client.delete_gist(5928712)
       def delete_gist(id)
-        delete "/gists/#{id}", auth_params, true
+        boolean_delete "/gists/#{id}", auth_params
       end
+
+      # List comments on a gist.
+      #
+      # @param id [Integer] The Gist ID.
+      # @return [Array] An array of comments.
+      # @see http://developer.github.com/v3/gists/comments/#list-comments-on-a-gist
+      # @example
+      #   GitHub.gist_comments(5928712)
+      def gist_comments(id)
+        get "/gists/#{id}/comments"
+      end
+
+      # Get a single comment on a gist.
+      #
+      # @param id [Integer] The Gist ID.
+      # @param comment_id [Integer] The comment ID.
+      # @return [Hash] The comment data.
+      # @see http://developer.github.com/v3/gists/comments/#get-a-single-comment
+      # @example
+      #   GitHub.gist_comment(5928712, 889239)
+      def gist_comment(id, comment_id)
+        get "/gists/#{id}/comments/#{comment_id}"
+      end
+
+      # Create a gist comment.
+      #
+      # Requires authentication.
+      #
+      # @param id [Integer] The Gist ID.
+      # @param comment [String] The comment text.
+      # @return [Hash] The Gist information.
+      # @see http://developer.github.com/v3/gists/comments/#create-a-comment
+      # @example
+      #   client.create_gist_comment(5928712, 'Awesome!')
+      def create_gist_comment(id, comment)
+        post "/gists/#{id}/comments", auth_params, { body: comment }
+      end
+
+      # Edit an existing gist comment.
+      #
+      # Requires authentication.
+      #
+      # @param id [Integer] The Gist ID.
+      # @param comment_id [Integer] The ID of the comment to edit.
+      # @param comment [String] The comment text.
+      # @return [Hash] The Gist information.
+      # @see http://developer.github.com/v3/gists/comments/#edit-a-comment
+      # @example
+      #   client.edit_gist_comment(5928712, 889239, 'Even more awesome!')
+      def edit_gist_comment(id, comment_id, comment)
+        patch "/gists/#{id}/comments/#{comment_id}", auth_params, { body: comment }
+      end
+
+      # Delete a gist comment.
+      #
+      # Requires authentication.
+      #
+      # @param id [Integer] The Gist ID.
+      # @param comment_id [Integer] The ID of the comment to delete.
+      # @return [Boolean] True if successful, false if not.
+      # @see http://developer.github.com/v3/gists/comments/#delete-a-comment
+      # @example
+      #   client.delete_gist_comment(5928712, 889239)
+      def delete_gist_comment(id, comment_id)
+        boolean_delete "/gists/#{id}/comments/#{comment_id}", auth_params
+      end
+      
     end
 
   end

data/lib/github_api_v3/client/gitignore.rb

@@ -0,0 +1,33 @@
+module GitHub
+  class Client
+
+    # Contains methods for the Gitignore API.
+    #
+    # @see http://developer.github.com/v3/gitignore/
+    module Gitignore
+
+      # Lists available .gitignore templates.
+      #
+      # @return [Array] List of template names.
+      # @see http://developer.github.com/v3/gitignore/#listing-available-templates
+      # @example
+      #   GitHub.gitignore_list
+      def gitignore_list
+        get '/gitignore/templates'
+      end
+
+      # Gets a single .gitignore template.
+      #
+      # @param name [String] The template name.
+      # @return [String] The template contents.
+      # @see http://developer.github.com/v3/gitignore/#get-a-single-template
+      # @example
+      #   GitHub.gitignore("Ruby")
+      def gitignore(name)
+        get "/gitignore/templates/#{name}"
+      end
+
+    end
+
+  end
+end

data/lib/github_api_v3/client/markdown.rb

@@ -0,0 +1,29 @@
+module GitHub
+  class Client
+
+    # Contains methods for the Markdown API.
+    #
+    # @see http://developer.github.com/v3/markdown/
+    module Markdown
+
+      # Render a markdown document.
+      #
+      # @param text [String] The Markdown text to render.
+      # @param options [Hash] The optional options.
+      # @option options [String] :mode The rendering mode.
+      # @option options [String] :context The repository context, only used when in 'gfm' mode.
+      # @return [String] The rendered text.
+      # @see http://developer.github.com/v3/markdown/#render-an-arbitrary-markdown-document
+      # @example
+      #   GitHub.markdown('# Hello World! ## H2 **yeah**!')
+      # @example
+      #   GitHub.markdown('# GitHub', mode: 'gfm', context: 'caseyscarborough/github')
+      def markdown(text, options={mode: 'markdown'})
+        options.merge!(text: text)
+        post "/markdown", {}, options
+      end
+
+    end
+
+  end
+end

data/lib/github_api_v3/client/repos.rb

@@ -1,6 +1,9 @@
 module GitHub
   class Client
 
+    # Contains methods for the Repos API.
+    #
+    # @see http://developer.github.com/v3/repos/
     module Repos
       
       # List all repositories
@@ -77,7 +80,7 @@ module GitHub
       # @example
       #   client.delete_repo('repo-name')
       def delete_repo(owner, repo)
-        delete "/repos/#{owner}/#{repo}", auth_params, true
+        boolean_delete "/repos/#{owner}/#{repo}", auth_params
       end
 
       # Get organization repositories.
@@ -135,7 +138,7 @@ module GitHub
       #
       # @param owner [String] Owner of repository.
       # @param repo [String] Repository name.
-      # @return [Array] List of brances and their information. 
+      # @return [Array] List of branches and their information. 
       # @see http://developer.github.com/v3/repos/#list-branches
       # @example
       #   GitHub.branches('caseyscarborough','github')
@@ -177,7 +180,7 @@ module GitHub
       # @example
       #   GitHub.collaborator?('caseyscarborough','github','caseyscarborough')
       def collaborator?(owner, repo, user)
-        get "/repos/#{owner}/#{repo}/collaborators/#{user}", {}, true
+        boolean_get "/repos/#{owner}/#{repo}/collaborators/#{user}"
       end
 
       # Add a collaborator to a repository.
@@ -189,7 +192,7 @@ module GitHub
       # @param user [String] User to add.
       # @see http://developer.github.com/v3/repos/collaborators/#add-collaborator
       def add_collaborator(owner, repo, user)
-        put "/repos/#{owner}/#{repo}/collaborators/#{user}", auth_params, true
+        boolean_put "/repos/#{owner}/#{repo}/collaborators/#{user}", auth_params
       end
 
       # Remove a collaborator from a repository.
@@ -201,7 +204,7 @@ module GitHub
       # @param user [String] User to remove.
       # @see http://developer.github.com/v3/repos/collaborators/#remove-collaborator
       def remove_collaborator(owner, repo, user)
-        delete "/repos/#{owner}/#{repo}/collaborators/#{user}", auth_params, true
+        boolean_delete "/repos/#{owner}/#{repo}/collaborators/#{user}", auth_params
       end
 
     end

data/lib/github_api_v3/client/users.rb

@@ -54,7 +54,7 @@
       # @example
       #   client.follow('caseyscarborough')
       def follow(username)
-        put "/user/following/#{username}", auth_params, true
+        boolean_put "/user/following/#{username}", auth_params
       end
 
       # Checks to see if a user is following another user.
@@ -124,7 +124,7 @@
       # @example
       #   client.unfollow('matz')
       def unfollow(username)
-        delete "/user/following/#{username}", auth_params, true
+        boolean_delete "/user/following/#{username}", auth_params
       end
 
       # Get a list of public keys for a user.
@@ -166,7 +166,7 @@
       # @example
       #   client.delete_key(123)
       def delete_key(id)
-        delete "/user/keys/#{id}", auth_params, true
+        boolean_delete "/user/keys/#{id}", auth_params
       end
       
       def events(username)

data/lib/github_api_v3/client.rb

@@ -2,16 +2,26 @@ require 'json'
 require 'github_api_v3/client/users'
 require 'github_api_v3/client/repos'
 require 'github_api_v3/client/gists'
+require 'github_api_v3/client/markdown'
+require 'github_api_v3/client/gitignore'
 
 module GitHub
+
+  # The main client for the API.
+  #
+  # @see http://developer.github.com/v3/
   class Client
 
     include HTTParty
+
+    # Default base uri for the API functionality.
     base_uri Default::API_ENDPOINT
 
     include GitHub::Client::Users
     include GitHub::Client::Repos
     include GitHub::Client::Gists
+    include GitHub::Client::Markdown
+    include GitHub::Client::Gitignore
 
     attr_reader :login, :access_token
 
@@ -23,38 +33,120 @@ module GitHub
 
     private
 
-      def get(url, params={}, boolean=false)
+      # Perform a get request.
+      #
+      # @return [Hash, Array, String]
+      def get(url, params={})
         response = self.class.get url, query: params
         handle_response(response)
-        boolean ? response.code == 204 : response.parsed_response
+        response.parsed_response
+      end
+
+      # Perform a get request with boolean return type.
+      #
+      # @return [Boolean]
+      def boolean_get(url, params={})
+        response = self.class.get url, query: params
+        response.code == 204
+      rescue GitHub::NotFound
+        false
       end
 
-      def put(url, params={}, boolean=false)
+      # Perform a put request.
+      #
+      # @return [Hash, Array, String]
+      def put(url, params={})
         response = self.class.put url, query: params
         handle_response(response)
-        boolean ? response.code == 204 : response.parsed_response
+        response.parsed_response
       end
 
-      def post(url, params={}, body={}, boolean=false)
+      # Perform a put request with boolean return type.
+      #
+      # @return [Boolean]
+      def boolean_put(url, params={})
+        response = self.class.put url, query: params
+        response.code == 204
+      rescue GitHub::NotFound
+        false
+      end
+
+      # Perform a post request.
+      #
+      # @return [Hash, Array, String]
+      def post(url, params={}, body={})
         response = self.class.post url, query: params, body: body.to_json
         handle_response(response)
-        boolean ? response.code == 204 : response.parsed_response
+        response.parsed_response
       end
 
-      def delete(url, params={}, boolean=false)
+      # Perform a post request with boolean return type.
+      #
+      # @return [Boolean]
+      def boolean_post(url, params={}, body={})
+        response = self.class.post url, query: params, body: body.to_json
+        response.code == 204
+      rescue GitHub::NotFound
+        false
+      end
+
+      # Perform a patch request.
+      #
+      # @return [Hash, Array, String]
+      def patch(url, params={}, body={})
+        response = self.class.patch url, query: params, body: body.to_json
+        handle_response(response)
+        response.parsed_response
+      end
+
+      # Perform a patch request with boolean return type.
+      #
+      # @return [Boolean]
+      def boolean_patch(url, params={}, body={})
+        response = self.class.patch url, query: params, body: body.to_json
+        response.code == 204
+      rescue GitHub::NotFound
+        false
+      end
+
+      # Perform a delete request.
+      #
+      # @return [Hash, Array, String]
+      def delete(url, params={})
         response = self.class.delete url, query: params
         handle_response(response)
-        boolean ? response.code == 204 : response.parsed_response
+        response.parsed_response
+      end
+
+      # Perform a delete request with boolean return type.
+      #
+      # @return [Boolean]
+      def boolean_delete(url, params={})
+        response = self.class.delete url, query: params
+        response.code == 204
+      rescue GitHub::NotFound
+        false
       end
 
+      # Return a hash with client's login and password.
+      #
+      # @return [Hash]
       def basic_params
         @password.nil? ? {} : { login: @login, password: @password }
       end
 
+      # Return a hash with client's login and access token.
+      #
+      # @return [Hash]
       def auth_params
         @login.nil? ? {} : { login: @login, access_token: @access_token }
       end
 
+      # Handle HTTP responses.
+      #
+      # Raise proper exceptions based on the response code.
+      #
+      # @return [HTTParty::Response]
       def handle_response(response)
         case response.code
         when 401 then raise Unauthorized

data/lib/github_api_v3/default.rb

@@ -1,6 +1,11 @@
 module GitHub
+
+  # Default configuration information.
   module Default
+
+    # The default API endpoint for GitHub's API.
     API_ENDPOINT = "https://api.github.com".freeze
+    
   end
 end