jiralicious 0.3.0 → 0.4.0

data/lib/jiralicious/issue/watchers.rb

@@ -2,7 +2,8 @@
 module Jiralicious
   class Issue
     ##
-    # The Watchers class is used to manage the watchers on an issue.
+    # The Watchers class is used to manage the
+    # watchers on an issue.
     #
     class Watchers < Jiralicious::Base
       ##
@@ -13,7 +14,7 @@ module Jiralicious
       ##
       # Initialization Method
       #
-      def initialize(decoded_json = nil, default = nil, &blk)
+      def initialize(decoded_json = nil)
         if (decoded_json != nil)
           properties_from_hash(decoded_json)
           super(decoded_json)
@@ -25,6 +26,9 @@ module Jiralicious
         ##
         # Finds all watchers based on the provided Issue Key
         #
+        # [Arguments]
+        # :key    (required)    issue key to find
+        #
         def find_by_key(key)
           response = fetch({:parent => parent_name, :parent_key => key})
           a = new(response)
@@ -35,6 +39,11 @@ module Jiralicious
         ##
         # Adds a new Watcher to the Issue
         #
+        # [Arguments]
+        # :name    (required)    name of the watcher
+        #
+        # :key     (required)    issue key
+        #
         def add(name, key)
           fetch({:method => :post, :body => name, :body_override => true, :parent => parent_name, :parent_key => key})
         end
@@ -42,6 +51,11 @@ module Jiralicious
         ##
         # Removes/Deletes a Watcher from the Issue
         #
+        # [Arguments]
+        # :name    (required)    name of the watcher
+        #
+        # :key     (required)    issue key
+        #
         def remove(name, key)
           fetch({:method => :delete, :body_to_params => true, :body => {:username => name}, :parent => parent_name, :parent_key => key})
         end
@@ -57,6 +71,9 @@ module Jiralicious
       ##
       # Adds a new Watcher to the Issue
       #
+      # [Arguments]
+      # :name    (required)    name of the watcher
+      #
       def add(name)
         self.class.add(name, @jira_key)
       end

data/lib/jiralicious/parsers/field_parser.rb

@@ -1,5 +1,8 @@
 # encoding: utf-8
 module Jiralicious
+  ##
+  # Parsing module contains all of the parser functionality
+  #
   module Parsers
     ##
     # The FieldParser module is an extention that assists in
@@ -9,6 +12,9 @@ module Jiralicious
       ##
       # Parses an Array or Hash into the current class object.
       #
+      # [Arguments]
+      # :fields    (required)    fields to be parsed
+      #
       def parse!(fields)
         unless fields.is_a?(Hash)
           raise ArgumentError
@@ -42,6 +48,9 @@ module Jiralicious
       ##
       # Normalizes key names
       #
+      # [Arguments]
+      # :name    (required)    name to be normalized
+      #
       def normalize(name)
         name.gsub(/(\w+)([A-Z].*)/, '\1_\2').
           gsub(/\W/, "_").
@@ -51,6 +60,9 @@ module Jiralicious
       ##
       # Converts Array or Hash to a Mash object
       #
+      # [Arguments]
+      # :data    (required)    data be be mashified
+      #
       def mashify(data)
         if data.is_a?(Array)
           data.map { |d| mashify(d) }

data/lib/jiralicious/project.rb

@@ -9,7 +9,10 @@ module Jiralicious
     ##
     # Initialization Method
     #
-    def initialize(decoded_json, default = nil, &blk)
+    # [Arguments]
+    # :decoded_json    (optional)    rubyized json object
+    #
+    def initialize(decoded_json)
       @loaded = false
       if decoded_json.is_a? Hash
         properties_from_hash(decoded_json)
@@ -30,6 +33,9 @@ module Jiralicious
       # to only return the issue ID and KEY values to minimize the amount of
       # data being returned This is used in lazy loading methodology.
       #
+      # [Arguments]
+      # :key    (required)    project key
+      #
       def issue_list(key)
         response = Jiralicious.search("project=#{key}", {:fields => ["id", "key"]})
         i_out = Issue.new

data/lib/jiralicious/project/avatar.rb

@@ -0,0 +1,126 @@
+# encoding: utf-8
+module Jiralicious
+	class Project
+		##
+		# Avatars in the Project class.
+		#
+		class Avatar < Jiralicious::Base
+
+			##
+			# Initialization Method
+			#
+			# [Arguments]
+			# :decoded_json    (optional)    decoded json object
+			#
+			def initialize(decoded_json = nil)
+				@loaded = false
+				if !decoded_json.nil?
+					if decoded_json.is_a? Hash
+						decoded_json = properties_from_hash(decoded_json)
+						super(decoded_json)
+						parse!(decoded_json)
+						self.each do |k, v|
+							if v.is_a? Hash
+								self[k] = self.class.new(v)
+							elsif v.is_a? Array
+								v.each_index do |i|
+									if v[i].is_a? Hash
+										v[i] = self.class.new(v[i])
+									end
+								end
+								self[k] = v
+							end
+						end
+						@loaded = true
+					else
+						i = 0;
+						decoded_json.each do |list|
+							if !list['id'].nil?
+								if numeric? list['id']
+									id =  :"id_#{list['id']}"
+								else
+									id = :"#{list['id']}"
+								end
+							else
+								id = :"_#{i}"
+								i += 1
+							end
+							self.class.property id
+							self[id] = self.class.new(list)
+						end
+					end
+				end
+			end
+
+			class << self
+				##
+				# Converts the temporary avatar to a real avatar
+				#
+				# [Arguments]
+				# :key               (required)    project key
+				#
+				# :cropperWidth      (optional)    width of the avatar
+				#
+				# :cropperOffsetX    (optional)    X offset on image
+				#
+				# :cropperOffsetY    (optional)    Y offset on image
+				#
+				# :needsCropping     (optional)    boolean if it needs cropping
+				#
+				def post(key, options = {})
+					response = fetch({:method => :post, :parent => true, :parent_key => key, :body => options})
+				end
+
+				##
+				# Update Avatar information
+				#
+				# [Arguments]
+				# :key        (required)    project key
+				#
+				# :options    (optional)    not documented
+				#
+				def put(key, options = {})
+					response = fetch({:method => :put, :parent => true, :parent_key => key, :body => options})
+				end
+
+				##
+				# Creates tempoary avatar
+				#
+				# [Arguments]
+				# :key         (required)    project key
+				#
+				# :filename    (required)    file to upload
+				#
+				# :size        (required)    size of the file
+				#
+				def temporary(key, options = {})
+					response = fetch({:method => :post, :parent => true, :parent_key => key, :key => 'temporary', :body => options})
+					return self.new(response.parsed_response)
+				end
+
+				##
+				# Deletes or removes the avatar from the project
+				#
+				# [Arguments]
+				# :key    (required)    project key
+				#
+				# :id     (required)    avatar id
+				#
+				def remove(key, id)
+					response = fetch({:method => :delete, :body_to_params => true, :parent => true, :parent_key => key, :key => "#{id}"})
+				end
+
+				##
+				# Gets a list of available avatars
+				#
+				# [Arguments]
+				# :key         (required)    project key
+				#
+				def avatars(key, options = {})
+					response = fetch({:method => :get, :url => "#{Jiralicious.rest_path}/#{parent_name}/#{key}/#{endpoint_name}s/", :body_to_params => true, :body => options})
+					return self.new(response.parsed_response)
+				end
+			end
+		end
+	end
+end

data/lib/jiralicious/search.rb

@@ -4,6 +4,15 @@ module Jiralicious
   # Provides the interface to access the JQL search functionality.
   # Uses the same syntax as Rest interface for JQL criteria.
   #
+  # [Arguments]
+  # :jql            (required)    JQL string
+  #
+  # :start_at       (optional)    offset to start at
+  #
+  # :max_results    (optional)    maximum number to return
+  #
+  # :fields         (optional)    field options
+  #
   def search(jql, options = {})
     options[:start_at] ||= 0
     options[:max_results] ||= 50

data/lib/jiralicious/search_result.rb

@@ -12,25 +12,33 @@ module Jiralicious
     #
     # Parses the hash into attributes.
     #
+    # [Arguments]
+    # :search_data    (required)    hash data to be parsed
+    #
     def initialize(search_data)
       @issues      = search_data["issues"]
       @offset      = search_data["startAt"]
       @num_results = search_data["total"]
     end
 
-  ##
-  # Loads the different issues through the map. This is not recommended for large objects
-  # as it can be troublesome to load multiple Issues to locate the desired one. If the user needs to have all of the information available on each issue this method works perfectly for that process.
-  #
+    ##
+    # Loads the different issues through the map. This is not recommended
+    # for large objects as it can be troublesome to load multiple Issues
+    # to locate the desired one. If the user needs to have all of the
+    # information available on each issue this method works perfectly for
+    # that process.
+    #
     def issues
       @issues.map do |issue|
         Jiralicious::Issue.find(issue["key"])
       end
     end
 
-  ##
-  # Returns the Issues attribute without loading the extra information. Ideal for a quick scan of the Hash prior to selecting the correct Issue. This method is also used in the lazy loading methodology.
-  #
+    ##
+    # Returns the Issues attribute without loading the extra information.
+    # Ideal for a quick scan of the Hash prior to selecting the correct
+    # Issue. This method is also used in the lazy loading methodology.
+    #
     def issues_raw
       @issues
     end

data/lib/jiralicious/session.rb

@@ -17,6 +17,11 @@ module Jiralicious
     ##
     # Main access method to request data from the Jira API
     #
+    # [Arguments]
+    # :method    (required)    http method type
+    #
+    # :options   (required)    request specific options
+    #
     def request(method, *options)
       if options.last.is_a?(Hash) && options.last[:handler]
         response_handler = options.last.delete(:handler)

data/lib/jiralicious/user.rb

@@ -0,0 +1,154 @@
+# encoding: utf-8
+module Jiralicious
+  ##
+  # The User class rolls up the functionality of user management.
+  # This class contains methods to manage Users from Ruby via the
+  # API.
+  #
+  class User < Jiralicious::Base
+
+    ##
+    # Initialization Method
+    #
+    # [Arguments]
+    # :decoded_json    (optional)    rubyized json object
+    #
+    def initialize(decoded_json = nil)
+      @loaded = false
+	  if !decoded_json.nil?
+        if decoded_json.is_a? Hash
+          decoded_json = properties_from_hash(decoded_json)
+          super(decoded_json)
+          parse!(decoded_json)
+          self.each do |k, v|
+            if v.is_a? Hash
+              self[k] = self.class.new(v)
+            elsif v.is_a? Array
+              v.each_index do |i|
+                if v[i].is_a? Hash
+                  v[i] = self.class.new(v[i])
+                end
+              end
+              self[k] = v
+            end
+          end
+          @loaded = true
+        else
+          i = 0;
+          decoded_json.each do |list|
+            if !list['id'].nil?
+              if numeric? list['id']
+                id =  :"id_#{list['id']}"
+              else
+                id = :"#{list['id']}"
+              end
+            else
+              id = :"_#{i}"
+              i += 1
+            end
+            self.class.property id
+            self[id] = self.class.new(list)
+          end
+        end
+      end
+    end
+
+    class << self
+      ##
+      # Retrieves the user by UserName.
+      #
+      # A valid request will return the user details.
+      # An invalid request will throw an error.
+      #
+      # [Arguments]
+      # :username   (required)    Must be correct username, no partials
+      #
+      def find(username)
+        response = fetch({:url => "#{Jiralicious.rest_path}/#{endpoint_name}", :method => :get, :body_to_params => true, :body => {:username => username}})
+        return self.new(response.parsed_response)
+      end
+
+      ##
+      # Returns a list of users matching the criteria
+      #
+      # [Arguments]
+      # :projectKey (required)    Should be upper case
+      #
+      # :username   (optional)    Must be correct username, no partials
+      #
+      # :startAt    (optional)    Integer
+      #
+      # :maxResults (optional)    Integer
+      #
+      def assignable_multiProjectSearch(projectKeys, options = {})
+        options.merge!({:projectKeys=>projectKeys.upcase})
+        response = fetch({:method => :get, :key => "assignable/multiProjectSearch", :body_to_params => true, :body => options})
+        return self.new(response.parsed_response)
+      end
+
+      ##
+      # Returns a list of users matching the criteria
+      #
+      # [Arguments]
+      # :project            (required)    Should be upper case
+      #
+      #              OR
+      #
+      # :issueKey           (required)    Should be upper case
+      #
+      # :username           (optional)    Must be correct username,
+      #                                     no partials, cannot be by itself
+      #
+      # :startAt            (optional)    Integer
+      #
+      # :maxResults         (optional)    Integer
+      #
+      # :ActionDescriptorId (optional)    Integer
+      #
+      def assignable_search(options = {})
+        options[:project] = options[:project].upcase unless options[:project].nil?
+        options[:issueKey] = options[:issueKey].upcase unless options[:issueKey].nil?
+        response = fetch({:method => :get, :key => "assignable/search", :body_to_params => true, :body => options})
+        return self.new(response.parsed_response)
+      end
+
+      ##
+      # Uses the user picker to find specified users
+      #
+      # [Arguments]
+      # :query         (required)    Name of user or username part or full
+      #
+      # :maxResults    (optional)    Integer
+      #
+      # :showAvatar    (optional)    Boolean, default false
+      #
+      # :exclude       (optional)    Users to exclude
+      #
+      def picker(query, options ={})
+        options.merge!({:query => query})
+        response = fetch({:method => :get, :key => "picker", :body_to_params => true, :body => options})
+        return self.new(response.parsed_response)
+      end
+
+      ##
+      # Uses the user search to find specified users by username
+      #
+      # [Arguments]
+      # :username           (required)    Name of user or username part or full
+      #
+      # :startAt            (optional)    Integer
+      #
+      # :maxResults         (optional)    Integer
+      #
+      # :includeActive      (optional)    Boolean, default true
+      #
+      # :includeInactive    (optional)    Boolean, default true
+      #
+      def search(username, options ={})
+        options.merge!({:username => username})
+        response = fetch({:method => :get, :key => "search", :body_to_params => true, :body => options})
+        return self.new(response.parsed_response)
+      end
+    end
+  end
+end