github_api 0.3.5 → 0.3.6

data/lib/github_api/git_data/tags.rb

@@ -0,0 +1,78 @@
+# encoding: utf-8
+
+module Github
+  class GitData
+    # This tags api only deals with tag objects - so only annotated tags, not lightweight tags.
+    module Tags
+
+      VALID_TAG_PARAM_NAMES = %w[
+        tag
+        message
+        object
+        type
+        name
+        email
+        date
+      ]
+
+      VALID_TAG_PARAM_VALUES = {
+        'type' => %w[ blob tree commit ]
+      }
+
+      # Get a tag
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.git_data.tag 'user-name', 'repo-name', 'sha'
+      #
+      def tag(user_name, repo_name, sha, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of sha
+        _normalize_params_keys(params)
+
+        get("/repos/#{user}/#{repo}/git/tags/#{sha}", params)
+      end
+
+      # Create a tag object
+      # Note that creating a tag object does not create the reference that
+      # makes a tag in Git. If you want to create an annotated tag in Git,
+      # you have to do this call to create the tag object, and then create
+      # the <tt>refs/tags/[tag]</tt> reference. If you want to create a lightweight tag, you simply have to create the reference - this call would be unnecessary.
+      #
+      # = Parameters
+      # * <tt>:tag</tt> - String of the tag
+      # * <tt>:message</tt> - String of the tag message
+      # * <tt>:object</tt> - String of the SHA of the git object this is tagging
+      # * <tt>:type</tt> - String of the type of the object we're tagging. Normally this is a <tt>commit</tt> but it can also be a <tt>tree</tt> or a <tt>blob</tt>
+      # * tagger.name:: String of the name of the author of the tag
+      # * tagger.email:: String of the email of the author of the tag
+      # * tagger.date:: Timestamp of when this object was tagged
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.git_data.create_tag 'user-name', 'repo-name',
+      #    "tag" =>  "v0.0.1",
+      #    "message" => "initial version\n",
+      #    "type": "commit",
+      #    "object": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
+      #    "tagger" => {
+      #      "name" =>  "Scott Chacon",
+      #      "email" => "schacon@gmail.com",
+      #      "date" => "2011-06-17T14:53:3"
+      #    }
+      #
+      def create_tag(user_name, repo_name, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _normalize_params_keys(params)
+
+        _filter_params_keys(VALID_TAG_PARAM_NAMES, params)
+        _validate_params_values(VALID_TAG_PARAM_VALUES, params)
+
+        post("/repos/#{user}/#{repo}/git/tags", params)
+      end
+
+    end # Tags
+  end # GitData
+end # Github

data/lib/github_api/git_data/trees.rb

@@ -0,0 +1,89 @@
+# encoding: utf-8
+
+module Github
+  class GitData
+    module Trees
+
+      VALID_TREE_PARAM_NAMES = %w[
+        base_tree
+        tree
+        path
+        mode
+        type
+        sha
+        content
+      ].freeze
+
+      VALID_TREE_PARAM_VALUES = {
+        'mode' => %w[ 100644 100755 040000 160000 120000 ],
+        'type' => %w[ blob tree commit ]
+      }
+
+      # Get a tree
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.git_data.tree 'user-name', 'repo-name', 'sha'
+      #  @github.git_data.tree 'user-name', 'repo-name', 'sha' do |file|
+      #    file.path
+      #  end
+      #
+      def tree(user_name, repo_name, sha, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of sha
+        _normalize_params_keys(params)
+
+        response = if params['recursive']
+          params['recursive'] = 1
+          get("/repos/#{user}/#{repo}/git/trees/#{sha}", params)
+        else
+          get("/repos/#{user}/#{repo}/git/trees/#{sha.to_s}", params)
+        end
+        return response unless block_given?
+        response.tree.each { |el| yield el }
+      end
+
+      # Create a tree
+      #
+      # The tree creation API will take nested entries as well.
+      # If both a tree and a nested path modifying that tree are specified,
+      # it will overwrite the contents of that tree with the new path contents
+      # and write a new tree out.
+      #
+      # = Parameters
+      # * <tt>:base_tree</tt> - optional string of the SHA1 of the tree you want to update with new data
+      # * <tt>:tree</tt> - array of hash objects(of <tt>:path</tt>, <tt>:mode</tt>, <tt>:type</tt> and <tt>sha</tt>)
+      # * tree.path:: String of the file referenced in the tree
+      # * tree.mode:: String of the file mode - one of <tt>100644</tt> for file(blob), <tt>100755</tt> for executable (blob), <tt>040000</tt> for subdirectory (tree), <tt>160000</tt> for submodule (commit) or <tt>120000</tt> for a blob that specifies the path of a symlink
+      # * tree.type:: String of <tt>blob</tt>, <tt>tree</tt>, <tt>commit</tt>
+      # * tree.sha:: String of SHA1 checksum ID of the object in the tree
+      # * tree.content:: String of content you want this file to have - GitHub will write this blob out and use the SHA for this entry. Use either this or <tt>tree.sha</tt>
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.git_data.create_tree 'user-name', 'repo-name',
+      #    "tree" => [
+      #      {
+      #        "path" => "file.rb",
+      #        "mode" => "100644",
+      #        "type" => "blob",
+      #        "sha" => "44b4fc6d56897b048c772eb4087f854f46256132"
+      #      },
+      #      ...
+      #    ]
+      #
+      def create_tree(user_name=nil, repo_name=nil, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _normalize_params_keys(params)
+
+        _filter_params_keys(VALID_TREE_PARAM_NAMES, params['tree'])
+        _validate_params_values(VALID_TREE_PARAM_VALUES, params['tree'])
+
+        post("/repos/#{user}/#{repo}/git/trees", params)
+      end
+
+    end # Trees
+  end # GitData
+end # Github

data/lib/github_api/issues.rb

@@ -0,0 +1,215 @@
+# encoding: utf-8
+
+module Github
+  class Issues < API
+    extend AutoloadHelper
+
+    autoload_all 'github_api/issues',
+      :Comments   => 'comments',
+      :Events     => 'events',
+      :Labels     => 'labels',
+      :Milestones => 'milestones'
+
+    include Github::Issues::Comments
+    include Github::Issues::Events
+    include Github::Issues::Labels
+    include Github::Issues::Milestones
+
+    VALID_ISSUE_PARAM_NAMES = %w[
+      filter
+      state
+      labels
+      sort
+      direction
+      since
+      milestone
+      assignee
+      mentioned
+      title
+      body
+      resource
+      mime_type
+    ].freeze
+
+    VALID_ISSUE_PARAM_VALUES = {
+      'filter'    => %w[ assigned created mentioned subscribed ],
+      'state'     => %w[ open closed ],
+      'sort'      => %w[ created updated comments ],
+      'direction' => %w[ desc asc ],
+      'since'     => %r{\d{4}-\d{2}-\d{5}:\d{2}:\d{3}}
+    }
+
+    # Creates new Issues API
+    def initialize(options = {})
+      super(options)
+    end
+
+    # List your issues
+    #
+    # = Parameters
+    # <tt>:filter</tt>
+    #  * <tt>assigned</tt>: Issues assigned to you (default)
+    #  * <tt>created</tt>: Issues assigned to you (default)
+    #  * <tt>mentioned</tt>: Issues assigned to you (default)
+    #  * <tt>subscribed</tt>: Issues assigned to you (default)
+    # <tt>:state</tt> - <tt>open</tt>, <tt>closed</tt>, default: <tt>open</tt>
+    # <tt>:labels</tt> - String list of comma separated Label names. Example: bug,ui,@high
+    # <tt>:sort</tt> - <tt>created</tt>, <tt>updated</tt>, <tt>comments</tt>, default: <tt>created</tt>
+    # <tt>:direction</tt> - <tt>asc</tt>, <tt>desc</tt>, default: <tt>desc</tt>
+    # <tt>:since</tt> - Optional string of a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
+    #
+    # = Examples
+    #  @github = Github.new :oauth_token => '...'
+    #  @github.issues.issues :since => '2011-04-12312:12:121',
+    #    :filter => 'created',
+    #    :state  => 'open',
+    #    :labels => "bug,ui,bla",
+    #    :sort   => 'comments',
+    #    :direction => 'asc'
+    #
+    def issues(params={})
+      _normalize_params_keys(params)
+      _filter_params_keys(VALID_ISSUE_PARAM_NAMES, params)
+      _merge_mime_type(:issue, params)
+      _validate_params_values(VALID_ISSUE_PARAM_VALUES, params)
+
+      response = get("/issues", params)
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    alias :list_issues :issues
+
+    # List issues for a repository
+    #
+    # = Parameters
+    # <tt>:milestone</tt>
+    #  * Integer Milestone number
+    #  * <tt>none</tt> for Issues with no Milestone.
+    #  * <tt>*</tt> for Issues with any Milestone
+    # <tt>:state</tt> - <tt>open</tt>, <tt>closed</tt>, default: <tt>open</tt>
+    # <tt>:assignee</tt>
+    #  * String User login
+    #  * <tt>none</tt> for Issues with no assigned User.
+    #  * <tt>*</tt> for Issues with any assigned User.
+    # <tt>:mentioned</tt> String User login
+    # <tt>:labels</tt> - String list of comma separated Label names. Example: bug,ui,@high
+    # <tt>:sort</tt> - <tt>created</tt>, <tt>updated</tt>, <tt>comments</tt>, default: <tt>created</tt>
+    # <tt>:direction</tt> - <tt>asc</tt>, <tt>desc</tt>, default: <tt>desc</tt>
+    # <tt>:since</tt> - Optional string of a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
+    # <tt></tt>, default: <tt>due_date</tt>
+    # <tt>:direction</tt> - <tt>asc</tt>, <tt>desc</tt>, default: <tt>desc</tt>
+    #
+    # = Examples
+    #  @github = Github.new :user => 'user-name', :repo => 'repo-name'
+    #  @github.issues.repo_issues :milestone => 1,
+    #    :state  => 'open',
+    #    :assignee => '*',
+    #    :mentioned => 'octocat',
+    #    :labels => "bug,ui,bla",
+    #    :sort   => 'comments',
+    #    :direction => 'asc'
+    #
+    def repo_issues(user_name=nil, repo_name=nil, params={})
+      _update_user_repo_params(user_name, repo_name)
+      _validate_user_repo_params(user, repo) unless user? && repo?
+
+      _normalize_params_keys(params)
+      _filter_params_keys(VALID_ISSUE_PARAM_NAMES, params)
+      _merge_mime_type(:issue, params)
+      _validate_params_values(VALID_ISSUE_PARAM_VALUES, params)
+
+      response = get("/repos/#{user}/#{repo}/issues", params)
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    alias :repository_issues :repo_issues
+    alias :list_repo_issues :repo_issues
+    alias :list_repository_issues :repo_issues
+
+    # Get a single issue
+    #
+    # = Examples
+    #  @github = Github.new
+    #  @github.issues.get_issue 'user-name', 'repo-name', 'issue-id'
+    #
+    def issue(user_name, repo_name, issue_id, params={})
+      _update_user_repo_params(user_name, repo_name)
+      _validate_user_repo_params(user, repo) unless user? && repo?
+      _validate_presence_of issue_id
+
+      _normalize_params_keys(params)
+      _merge_mime_type(:issue, params)
+
+      get("/repos/#{user}/#{repo}/issues/#{issue_id}", params)
+    end
+    alias :get_issue :issue
+
+    # Create an issue
+    #
+    # = Inputs
+    #  <tt>:title</tt> - Required string
+    #  <tt>:body</tt> - Optional string
+    #  <tt>:assignee</tt> - Optional string - Login for the user that this issue should be assigned to.
+    #  <tt>:milestone</tt> - Optional number - Milestone to associate this issue with
+    #  <tt>:labels</tt> - Optional array of strings - Labels to associate with this issue
+    # = Examples
+    #  @github = Github.new :user => 'user-name', :repo => 'repo-name'
+    #  @github.issues.create_issue
+    #    "title" => "Found a bug",
+    #    "body" => "I'm having a problem with this.",
+    #    "assignee" => "octocat",
+    #    "milestone" => 1,
+    #    "labels" => [
+    #      "Label1",
+    #      "Label2"
+    #    ]
+    #
+    def create_issue(user_name=nil, repo_name=nil, params={})
+      _update_user_repo_params(user_name, repo_name)
+      _validate_user_repo_params(user, repo) unless user? && repo?
+
+      _normalize_params_keys(params)
+      _merge_mime_type(:issue, params)
+      _filter_params_keys(VALID_ISSUE_PARAM_NAMES, params)
+
+      raise ArgumentError, "Required params are: :title" unless _validate_inputs(%w[ title ], params)
+
+      post("/repos/#{user}/#{repo}/issues", params)
+    end
+
+    # Edit an issue
+    #
+    # = Inputs
+    #  <tt>:title</tt> - Optional string
+    #  <tt>:body</tt> - Optional string
+    #  <tt>:assignee</tt> - Optional string - Login for the user that this issue should be assigned to.
+    #  <tt>:state</tt> - Optional string - State of the issue:<tt>open</tt> or <tt>closed</tt>
+    #  <tt>:milestone</tt> - Optional number - Milestone to associate this issue with
+    #  <tt>:labels</tt> - Optional array of strings - Labels to associate with this issue. Pass one or more Labels to replace the set of Labels on this Issue. Send an empty array ([]) to clear all Labels from the Issue.
+    #
+    # = Examples
+    #  @github = Github.new
+    #  @github.issues.create_issue 'user-name', 'repo-name', 'issue-id'
+    #    "title" => "Found a bug",
+    #    "body" => "I'm having a problem with this.",
+    #    "assignee" => "octocat",
+    #    "milestone" => 1,
+    #    "labels" => [
+    #      "Label1",
+    #      "Label2"
+    #    ]
+    #
+    def edit_issue(user_name, repo_name, issue_id, params={})
+      _update_user_repo_params(user_name, repo_name)
+      _validate_user_repo_params(user, repo) unless user? && repo?
+      _validate_presence_of issue_id
+
+      _normalize_params_keys(params)
+      _merge_mime_type(:issue, params)
+      _filter_params_keys(VALID_MILESTONE_INPUTS, params)
+
+      patch("/repos/#{user}/#{repo}/issues/#{issue_id}", params)
+    end
+
+  end # Issues
+end # Github

data/lib/github_api/issues/comments.rb

@@ -0,0 +1,123 @@
+# encoding: utf-8
+
+module Github
+  class Issues
+    module Comments
+
+      VALID_ISSUE_COMMENT_PARAM_NAME = %w[
+        body
+        resource
+        mime_type
+      ].freeze
+
+      # List comments on an issue
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.issues.comments 'user-name', 'repo-name', 'issue-id'
+      #  @github.issues.comments 'user-name', 'repo-name', 'issue-id' { |com| ... }
+      #
+      def comments(user_name, repo_name, issue_id, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of issue_id
+
+        _normalize_params_keys(params)
+        _merge_mime_type(:issue_comment, params)
+
+        response = get("/repos/#{user}/#{repo}/issues/#{issue_id}/comments", params)
+        return response unless block_given?
+        response.each { |el| yield el }
+      end
+      alias :issue_comments :comments
+      alias :list_comments :comments
+      alias :list_issue_comments :comments
+
+      # Get a single comment
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.issues.comment 'user-name', 'repo-name', 'comment-id'
+      #
+      def comment(user_name, repo_name, comment_id, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of comment_id
+
+        _normalize_params_keys(params)
+        _merge_mime_type(:issue_comment, params)
+
+        get("/repos/#{user}/#{repo}/issues/comments/#{comment_id}", params)
+      end
+      alias :issue_comment :comment
+      alias :get_comment :comment
+
+      # Create a comment
+      #
+      # = Inputs
+      #  <tt>:body</tt> Required string
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.issues.create_comment 'user-name', 'repo-name', 'issue-id',
+      #     "body" => 'a new comment'
+      #
+      def create_comment(user_name, repo_name, issue_id, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of issue_id
+
+        _normalize_params_keys(params)
+        _merge_mime_type(:issue_comment, params)
+        _filter_params_keys(VALID_ISSUE_COMMENT_PARAM_NAME, params)
+        raise ArgumentError, "Required params are: :body" unless _validate_inputs(%w[ body ], params)
+
+        post("/repos/#{user}/#{repo}/issues/#{issue_id}/comments", params)
+      end
+      alias :create_issue_comment :create_comment
+
+      # Edit a comment
+      #
+      # = Inputs
+      #  <tt>:body</tt> Required string
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.issues.edit_comment 'user-name', 'repo-name', 'comment-id',
+      #     "body" => 'a new comment'
+      #
+      def edit_comment(user_name, repo_name, comment_id, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of comment_id
+
+        _normalize_params_keys(params)
+        _merge_mime_type(:issue_comment, params)
+        _filter_params_keys(VALID_ISSUE_COMMENT_PARAM_NAME, params)
+        raise ArgumentError, "Required params are: :body" unless _validate_inputs(%w[ body ], params)
+
+        patch("/repos/#{user}/#{repo}/issues/comments/#{comment_id}")
+      end
+      alias :edit_issue_comment :edit_comment
+
+      # Delete a comment
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.issues.delete_comment 'user-name', 'repo-name', 'comment-id'
+      #
+      def delete_comment(user_name, repo_name, comment_id, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of comment_id
+
+        _normalize_params_keys(params)
+        _merge_mime_type(:issue_comment, params)
+
+        delete("/repos/#{user}/#{repo}/issues/comments/#{comment_id}", params)
+      end
+      alias :delete_issue_comment :delete_comment
+
+    end # Comments
+  end # Issues
+end # Github