tinybucket 0.1.7 → 1.0.0

data/lib/tinybucket/model/commit.rb

@@ -1,38 +1,92 @@
 module Tinybucket
   module Model
+    # Commit Resource
+    #
+    # @see https://confluence.atlassian.com/bitbucket/commits-or-commit-resource-389775478.html
+    #   Commit Resource - Bitbucket Cloud REST API document
+    #
+    # @!attribute [rw] hash
+    #   @return [String]
+    # @!attribute [rw] links
+    #   @return [Hash]
+    # @!attribute [rw] repository
+    #   @return [Hash]
+    # @!attribute [rw] author
+    #   @return [Hash]
+    # @!attribute [rw] parents
+    #   @return [Array]
+    # @!attribute [rw] date
+    #   @return [String]
+    # @!attribute [rw] message
+    #   @return [String]
+    # @!attribute [rw] participants
+    #   @return [Array]
+    # @!attribute [rw] uuid
+    #   @return [NillClass]
+    # @!attribute [rw] type
+    #   @return [String]
     class Commit < Base
       include Tinybucket::Model::Concerns::RepositoryKeys
-      include Tinybucket::Model::Concerns::Reloadable
       include Tinybucket::Constants
 
       acceptable_attributes \
         :hash, :links, :repository, :author, :parents, :date,
-        :message, :participants, :uuid
+        :message, :participants, :uuid, :type
 
+      # Get comments which associate with this commit.
+      #
+      # @param options [Hash]
+      # @return [Tinybucket::Enumerator] enumerator to enumerate comments
+      #   as {Tinybucket::Model::Comment} instance.
       def comments(options = {})
-        comments_api(options).list(options)
+        enumerator(
+          comments_api,
+          :list,
+          options
+        ) { |m| block_given? ? yield(m) : m }
       end
 
+      # Get the specific commit comment which associate with this commit.
+      #
+      # @param comment_id [String] comment id
+      # @param options [Hash]
+      # @return [Tinybucket::Model::Comment]
       def comment(comment_id, options = {})
-        comments_api(options).find(comment_id, options)
+        comments_api.find(comment_id, options)
+      end
+
+      # Give approval on this commit.
+      #
+      # @param options [Hash]
+      # @return [true, false]
+      def approve(options = {})
+        commit_api.approve(hash, options)
+      end
+
+      # Revoke approval on this commit.
+      #
+      # @param options [Hash]
+      # @return [true, false]
+      def unapprove(options = {})
+        commit_api.unapprove(hash, options)
       end
 
       private
 
-      def comments_api(options)
+      def comments_api
         raise ArgumentError, MISSING_REPOSITORY_KEY unless repo_keys?
 
-        api = create_api('Comments', repo_keys, options)
+        api = create_api('Comments', repo_keys)
         api.commented_to = self
         api
       end
 
-      def commit_api(options)
-        create_api 'Commits', repo_keys, options
+      def commit_api
+        create_api('Commits', repo_keys)
       end
 
       def load_model
-        commit_api({}).find(hash)
+        commit_api.find(hash)
       end
     end
   end

data/lib/tinybucket/model/concerns.rb

@@ -5,6 +5,7 @@ module Tinybucket
 
       [
         :AcceptableAttributes,
+        :Enumerable,
         :RepositoryKeys,
         :Reloadable
       ].each do |mod_name|

data/lib/tinybucket/model/concerns/enumerable.rb

@@ -0,0 +1,18 @@
+module Tinybucket
+  module Model
+    module Concerns
+      module Enumerable
+        extend ActiveSupport::Concern
+
+        included do
+          protected
+
+          def enumerator(api_client, method, *args, &block)
+            iter = Tinybucket::Iterator.new(api_client, method, *args)
+            Tinybucket::Enumerator.new(iter, block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tinybucket/model/error_response.rb

@@ -1,6 +1,21 @@
 module Tinybucket
   module Model
-    class ErrorResponse < Base
+    # ErrorResponse
+    #
+    # @see https://confluence.atlassian.com/bitbucket/version-2-423626329.html#Version2-Standardizederrorresponses
+    #   Standardized error responses - Bitbucket Cloud REST API document
+    #
+    # @!attribute [rw] message
+    #   @return [String]
+    # @!attribute [rw] fields
+    #   @return [Hash]
+    # @!attribute [rw] detail
+    #   @return [String]
+    # @!attribute [rw] id
+    #   @return [String]
+    # @!attribute [rw] uuid
+    #   @return [NillClass]
+    class ErrorResponse
       acceptable_attributes :message, :fields, :detail, :id, :uuid
     end
   end

data/lib/tinybucket/model/page.rb

@@ -1,66 +1,42 @@
 module Tinybucket
   module Model
+    # Page
+    #
+    # @see https://confluence.atlassian.com/bitbucket/version-2-423626329.html#Version2-Pagingthroughobjectcollections
+    #   Paging through object collections - Bitbucket Cloud REST API document
+    #
+    # @!attribute [r] attrs
+    #   This attribute is a Hash object which contains
+    #   'size', 'page', 'pagelen', 'next', 'previous' key/value pairs.
+    #   @return [Hash]
+    # @!attribute [r] items
+    #   This attribute is a array of model instance created with
+    #   'values' attribute in json.
     class Page
-      # attr_reader :size, :page, :pagelen, :next, :previous
       attr_reader :attrs
       attr_reader :items
-      attr_writer :next_proc
 
+      # Initialize with json and Model class.
+      #
+      # @param json [Hash]
+      # @param item_klass [Class]
       def initialize(json, item_klass)
-        @attrs = {}
-        %w(size page pagelen next previous).each do |attr|
-          @attrs[attr.intern] = json[attr]
-        end
-
-        @items = if json['values'].present? && json['values'].is_a?(Array)
-                   json['values'].map { |hash| item_klass.new(hash) }
-                 else
-                   []
-                 end
-      end
-
-      def size
-        @attrs[:size]
-      end
-
-      def each(options = {})
-        loop do
-          start = (@attrs[:page] - 1) * @attrs[:pagelen]
-
-          @items.each_with_index do |m, i|
-            pos = start + i
-            yield(m, pos)
-
-            raise StopIteration if \
-              (!options[:limit].nil? && pos == (options[:limit] - 1))
-          end
-
-          break unless next_page?
-
-          load_next
-        end
-
-      rescue StopIteration
-        return
+        @attrs = parse_attrs(json)
+        @items = parse_values(json, item_klass)
       end
 
       private
 
-      def next_page?
-        @attrs[:next].present?
+      def parse_attrs(json)
+        %w(size page pagelen next previous).map do |attr|
+          { attr.to_sym => json[attr] }
+        end.reduce(&:merge)
       end
 
-      def load_next
-        raise StopIteration if @attrs[:next].nil? || @next_proc.nil?
-
-        unescaped_query = URI.unescape(URI.parse(@attrs[:next]).query)
-        query = Hash[*unescaped_query.split(/&|=/)]
-        list = @next_proc.call(query)
-
-        raise StopIteration if list.items.empty?
+      def parse_values(json, item_klass)
+        return [] if json['values'].nil? || !json['values'].is_a?(Array)
 
-        @attrs = list.attrs
-        @items = list.items
+        json['values'].map { |hash| item_klass.new(hash) }
       end
     end
   end

data/lib/tinybucket/model/profile.rb

@@ -1,36 +1,84 @@
 module Tinybucket
   module Model
+    # Profile
+    #
+    # @see https://confluence.atlassian.com/bitbucket/users-endpoint-423626336.html#usersEndpoint-GETtheuserprofile
+    #   users Endpoint - Bitbucket Cloud REST API document
+    #
+    # @!attribute [rw] username
+    #   @return [String]
+    # @!attribute [rw] kind
+    #   @return [NillClass]
+    # @!attribute [rw] website
+    #   @return [String]
+    # @!attribute [rw] display_name
+    #   @return [String]
+    # @!attribute [rw] links
+    #   @return [Hash]
+    # @!attribute [rw] created_on
+    #   @return [String]
+    # @!attribute [rw] location
+    #   @return [String]
+    # @!attribute [rw] type
+    #   @return [String]
+    # @!attribute [rw] uuid
+    #   @return [String]
     class Profile < Base
-      include Tinybucket::Model::Concerns::Reloadable
-
       acceptable_attributes \
         :username, :kind, :website, :display_name,
         :links, :created_on, :location, :type, :uuid
 
+      # Get this user's followers
+      #
+      # @param options [Hash]
+      # @return [Tinybucket::Enumerator] enumerator to enumerate followers
+      #   as {Tinybucket::Model::Profile} instance.
       def followers(options = {})
-        user_api(options).followers(options)
+        enumerator(
+          user_api,
+          :followers,
+          options
+        ) { |m| block_given? ? yield(m) : m }
       end
 
+      # Get users which this user is following
+      #
+      # @param options [Hash]
+      # @return [Tinybucket::Enumerator] an enumerator to enumerate followings
+      #   as {Tinybucket::Model::Profile} instance.
       def following(options = {})
-        user_api(options).following(options)
+        enumerator(
+          user_api,
+          :following,
+          options
+        ) { |m| block_given? ? yield(m) : m }
       end
 
+      # Get this user's repositories
+      #
+      # @param options [Hash]
+      # @return [Tinybucket::Enumerator] an enumerator to enumerate repositories
+      #   as {Tinybucket::Model::Repository} instance.
       def repos(options = {})
-        user_api(options).repos(options)
+        enumerator(
+          user_api,
+          :repos,
+          options
+        ) { |m| block_given? ? yield(m) : m }
       end
 
       private
 
-      def user_api(options)
+      def user_api
         return @user if @user
 
-        @user = create_instance 'User', options
+        @user = create_instance('User')
         @user.username = username
         @user
       end
 
       def load_model
-        user_api({}).profile
+        user_api.profile
       end
     end
   end

data/lib/tinybucket/model/pull_request.rb

@@ -1,71 +1,167 @@
 module Tinybucket
   module Model
+    # PullRequest
+    #
+    # @see https://confluence.atlassian.com/bitbucket/pullrequests-resource-423626332.html#pullrequestsResource-Overview
+    #   pullrequest resource - Bitbucket Cloud REST API document
+    #
+    # @!attribute [rw] state
+    #   @return [String]
+    # @!attribute [rw] description
+    #   @return [String]
+    # @!attribute [rw] links
+    #   @return [Hash]
+    # @!attribute [rw] title
+    #   @return [String]
+    # @!attribute [rw] task_count
+    #   @return [Fixnum]
+    # @!attribute [rw] comment_count
+    #   @return [Fixnum]
+    # @!attribute [rw] close_source_branch
+    #   @return [true, false]
+    # @!attribute [rw] destination
+    #   @return [Hash]
+    # @!attribute [rw] reason
+    #   @return [String]
+    # @!attribute [rw] id
+    #   @return [Fixnum]
+    # @!attribute [rw] source
+    #   @return [Hash]
+    # @!attribute [rw] created_on
+    #   @return [String]
+    # @!attribute [rw] author
+    #   @return [Hash]
+    # @!attribute [rw] updated_on
+    #   @return [String]
+    # @!attribute [rw] merge_commit
+    #   @return [Hash]
+    # @!attribute [rw] closed_by
+    #   @return [Hash]
+    # @!attribute [rw] reviewers
+    #   @return [Array]
+    # @!attribute [rw] participants
+    #   @return [Array]
+    # @!attribute [rw] uuid
+    #   @return [NillClass]
+    # @!attribute [rw] type
+    #   @return [String]
     class PullRequest < Base
       include Tinybucket::Model::Concerns::RepositoryKeys
-      include Tinybucket::Model::Concerns::Reloadable
       include Tinybucket::Constants
 
       acceptable_attributes \
-        :state, :description, :links, :title, :close_source_branch,
-        :destination, :reason, :id, :source, :created_on, :author, :updated_on,
-        :merge_commit, :closed_by, :reviewers, :participants, :uuid
-
+        :state, :description, :links, :title, :task_count, :comment_count,
+        :close_source_branch, :destination, :reason, :id, :source,
+        :created_on, :author, :updated_on, :merge_commit, :closed_by,
+        :reviewers, :participants, :uuid, :type
+
+      # Create a new pull request.
+      #
+      # @todo to be implemented.
+      # @raise [NotImplementedError] to be implemented.
       def create(_params)
         raise NotImplementedError
       end
 
+      # Update this pull request.
+      #
+      # @todo to be implemented.
+      # @raise [NotImplementedError] to be implemented.
       def update(_params)
         raise NotImplementedError
       end
 
+      # Decline or reject this pull request.
+      #
+      # @param options [Hash]
+      # @return [true,false]
       def decline(options = {})
-        pull_request_api(options).decline(id, options)
+        pull_request_api.decline(id, options)
       end
 
+      # Give approval on this pull request.
+      #
+      # @param options [Hash]
+      # @return [true, false]
       def approve(options = {})
-        pull_request_api(options).approve(id, options)
+        pull_request_api.approve(id, options)
       end
 
+      # Revoke approval on this pull request.
+      #
+      # @param options [Hash]
+      # @return [true, false]
       def unapprove(options = {})
-        pull_request_api(options).unapprove(id, options)
+        pull_request_api.unapprove(id, options)
       end
 
+      # Get commits associated with this pull request.
+      #
+      # @param options [Hash]
+      # @return [Tinybucket::Enumerator] enumerator to enumerate commits
+      #   as {Tinybucket::Model::Commit} instance.
       def commits(options = {})
-        pull_request_api(options).commits(id, options)
+        enumerator(
+          pull_request_api,
+          :commits,
+          id,
+          options
+        ) { |m| block_given? ? yield(m) : m }
       end
 
+      # Get comments on this pull request.
+      #
+      # @param options [Hash]
+      # @return [Tinybucket::Enumerator] enumerator to enumerate comments
+      #   as {Tinybucket::Model::Comment} instance.
       def comments(options = {})
-        comment_api(options).list(options)
+        enumerator(
+          comment_api,
+          :list,
+          options
+        ) { |m| block_given? ? yield(m) : m }
       end
 
+      # Get the specific comment on this pull request.
+      #
+      # @param options [Hash]
+      # @return [Tinybucket::Model::Comment]
       def comment(comment_id, options = {})
-        comment_api(options).find(comment_id, options)
+        comment_api.find(comment_id, options)
       end
 
+      # Get the diff for this pull request.
+      #
+      # @param options [Hash]
+      # @return [String] diff as raw text.
       def diff(options = {})
-        pull_request_api(options).diff(id, options)
+        pull_request_api.diff(id, options)
       end
 
+      # Accept and merge this pull request.
+      #
+      # @param options [Hash]
+      # @return [true, false]
       def merge(options = {})
-        pull_request_api(options).merge(id, options)
+        pull_request_api.merge(id, options)
       end
 
       private
 
-      def comment_api(options)
-        api = create_api('Comments', repo_keys, options)
+      def comment_api
+        api = create_api('Comments', repo_keys)
         api.commented_to = self
         api
       end
 
-      def pull_request_api(options)
+      def pull_request_api
         raise ArgumentError, MISSING_REPOSITORY_KEY unless repo_keys?
 
-        create_api('PullRequests', repo_keys, options)
+        create_api('PullRequests', repo_keys)
       end
 
       def load_model
-        pull_request_api({}).find(id)
+        pull_request_api.find(id)
       end
     end
   end