taskmapper 0.8.0

data/lib/taskmapper/comment.rb

@@ -0,0 +1,97 @@
+module TaskMapper::Provider
+  module Base
+    # The comment class
+    #
+    # This will probably one of the most troublesome parts of creating a provider for taskmapper 
+    # since there are so many different ways comments are handled by different APIs.
+    # Keep in mind that if you do need to change/overwrite the methods, you will most likely
+    # only need to overwrite #find_by_id, #find_by_attributes, #search, and possibly #initialize
+    # as long as their parameters conform to what the find method expects.
+    #
+    # Here are the expected attributes:
+    #
+    # * author
+    # * body
+    # * id
+    # * created_at
+    # * updated_at
+    # * ticket_id
+    # * project_id
+    class Comment < Hashie::Mash
+      include TaskMapper::Provider::Common
+      include TaskMapper::Provider::Helper
+      extend TaskMapper::Provider::Helper
+      attr_accessor :system, :system_data
+      API = nil # Replace with your comment's API's Class
+
+      # Find comment
+      # You can also retrieve an array of all comments by not specifying any query.
+      #
+      # * find(<project_id>, <ticket_id>) or find(<project_id>, <ticket_id>, :all) - Returns an array of all comments
+      # * find(<project_id>, <ticket_id>, ##) - Returns a comment based on that id or some other primary (unique) attribute
+      # * find(<project_id>, <ticket_id>, [#, #, #]) - Returns many comments with these ids
+      # * find(<project_id>, <ticket_id>, :first, :name => 'Project name') - Returns the first comment based on the comment's attribute(s)
+      # * find(<project_id>, <ticket_id>, :last, :name => 'Some project') - Returns the last comment based on the comment's attribute(s)
+      # * find(<project_id>, <ticket_id>, :all, :name => 'Test Project') - Returns all comments based on the given attribute(s)
+      def self.find(project_id, ticket_id, *options)
+        first, attributes = options
+        if first.nil? or (first == :all and attributes.nil?)
+          self.find_by_attributes(project_id, ticket_id)
+        elsif first.is_a? Array
+          first.collect { |id| self.find_by_id(project_id, ticket_id, id) }
+        elsif first == :first
+          comments = attributes.nil? ? self.find_by_attributes(project_id, ticket_id) : self.find_by_attributes(project_id, ticket_id, attributes)
+          comments.first
+        elsif first == :last
+          comments = attributes.nil? ? self.find_by_attributes(project_id, ticket_id) : self.find_by_attributes(project_id, ticket_id, attributes)
+          comments.last
+        elsif first == :all
+          self.find_by_attributes(project_id, ticket_id, attributes)
+        else
+          self.find_by_id(project_id, ticket_id, first)
+        end
+      end
+      
+      # The first of whatever comment
+      def self.first(project_id, ticket_id, *options)
+        self.find(project_id, ticket_id, :first, *options)
+      end
+      
+      # The last of whatever comment
+      def self.last(project_id, ticket_id, *options)
+        self.find(project_id, ticket_id, :last, *options)
+      end
+      
+      # Accepts an integer id and returns the single comment instance
+      # Must be defined by the provider
+      def self.find_by_id(project_id, ticket_id, id)
+        if self::API.is_a? Class
+          self.new self::API.find(id, :params => {:project_id => project_id, :ticket_id => ticket_id})
+        else
+          raise TaskMapper::Exception.new("#{self.name}::#{this_method} method must be implemented by the provider")
+        end
+      end
+      
+      # Accepts an attributes hash and returns all comments matching those attributes in an array
+      # Should return all comments if the attributes hash is empty
+      # Must be defined by the provider
+      def self.find_by_attributes(project_id, ticket_id, attributes = {})
+        if self::API.is_a? Class
+          self.search(project_id, ticket_id, attributes)
+        else
+          raise TaskMapper::Exception.new("#{self.name}::#{this_method} method must be implemented by the provider")
+        end
+      end
+      
+      # This is a helper method to find
+      def self.search(project_id, ticket_id, options = {}, limit = 1000)
+        if self::API.is_a? Class
+          comments = self::API.find(:all, :params => {:project_id => project_id, :ticket_id => ticket_id}).collect { |comment| self.new comment }
+          search_by_attribute(comments, options, limit)
+        else
+          raise TaskMapper::Exception.new("#{self.name}::#{this_method} method must be implemented by the provider")
+        end
+      end
+    end
+  end
+end

data/lib/taskmapper/common.rb

@@ -0,0 +1,81 @@
+module TaskMapper::Provider
+  # Common module
+  # contains method definitions common to all or most of the models
+  module Common
+      module ClassMethods
+        # Create a something.
+        # Basically, a .new and .save in the same call. The default method assumes it is passed a
+        # single hash with attribute information
+        def create(*options)
+          if self::API.is_a? Class
+            something = self::API.new(*options)
+            something.save
+            self.new something
+          else
+            raise TaskMapper::Exception.new("#{self.name}::#{this_method} method must be implemented by the provider")
+          end
+        end
+      end
+      
+      # Automatic extension of class methods on include
+      def self.included(base)
+        base.extend ClassMethods
+      end
+      
+      # The initializer
+      # It tries to do a default system for ActiveResource-based api providers
+      def initialize(*options)
+        @system_data ||= {}
+        @cache ||= {}
+        first = options.shift
+        case first
+          when Hash
+            super(first.to_hash)
+          else
+            @system_data[:client] = first
+            self.prefix_options ||= @system_data[:client].prefix_options if @system_data[:client].prefix_options
+            super(first.attributes)
+        end
+      end
+      
+      # Update the something and save
+      # As opposed to update which just updates the attributes
+      def update!(*options)
+        update(*options)
+        save
+      end
+      
+      # Save changes to this project
+      # Returns true (success) or false (failure) or nil (no changes)
+      def save
+        if @system_data and (something = @system_data[:client]) and something.respond_to?(:attributes)
+          changes = 0
+          something.attributes.each do |k, v|
+            if self.send(k) != v
+              something.send(k + '=', self.send(k)) 
+              changes += 1
+            end
+          end
+          something.save if changes > 0
+        else
+          raise TaskMapper::Exception.new("#{self.class.name}::#{this_method} method must be implemented by the provider")
+        end
+      end
+      
+      # Delete this project
+      # Returns true (success) or false(failure)
+      def destroy
+        if @system_data and @system_data[:client] and @system_data[:client].respond_to?(:destroy)
+          return @system_data[:client].destroy
+        else
+          raise TaskMapper::Exception.new("#{self.class.name}::#{this_method} method must be implemented by the provider")
+        end
+      end
+      
+      def respond_to?(symbol, include_private = false)
+        result = super(symbol)
+        return true if result or @system_data.nil? or @system_data[:client].nil?
+        @system_data[:client].respond_to?(symbol, include_private)
+      end
+  end
+end

data/lib/taskmapper/dummy/comment.rb

@@ -0,0 +1,27 @@
+module TaskMapper::Provider
+  module Dummy
+    # This is the Comment class for the Dummy provider
+    class Comment < TaskMapper::Provider::Base::Comment
+      
+            
+      def self.find_by_id(id)
+        self.new({:id => id})
+      end
+      
+      def self.find_by_attributes(*options)
+        [self.new(*options)]
+      end
+            
+      # You don't need to define an initializer, this is only here to initialize dummy data
+      def initialize(project_id, ticket_id, *options)
+        data = {:id => rand(1000), :status => ['lol', 'rofl', 'lmao', 'lamo', 'haha', 'heh'][rand(6)],
+          :priority => rand(10), :summary => 'Tickets ticket ticket ticket', :resolution => false,
+          :created_at => Time.now, :updated_at => Time.now, :description => 'Ticket ticket ticket ticket laughing',
+          :assignee => 'lol-man'}
+        @system = :dummy
+        super(data.merge(options.first || {}))
+      end
+      
+    end
+  end
+end

data/lib/taskmapper/dummy/dummy.rb

@@ -0,0 +1,28 @@
+module TaskMapper::Provider
+  # This is the Dummy Provider
+  #
+  # It doesn't really do anything, it exists in order to test the basic functionality of taskmapper 
+  # and to provide an example the basics of what is to be expected from the providers.
+  # 
+  # Note that the initial provider name is a module rather than a class. TaskMapper.new
+  # extends on an instance-based fashion. If you would rather initialize using code that is 
+  # closer to:
+  # 
+  #    TaskMapper::Provider::Dummy.new(authentication)
+  #
+  # You will have to do a little magic trick and define new on the provider as a wrapper
+  # around the TaskMapper.new call.
+  module Dummy
+    include TaskMapper::Provider::Base
+    # An example of what to do if you would like to do TaskMapper::Provider::Dummy.new(...)
+    # rather than TaskMapper.new(:dummy, ...)
+    def self.new(authentication = {})
+      TaskMapper.new(:dummy, authentication)
+      # maybe do some other stuff
+    end
+  end
+end
+
+%w| project ticket comment |.each do |f|
+  require File.dirname(__FILE__) + '/' + f +'.rb'
+end

data/lib/taskmapper/dummy/project.rb

@@ -0,0 +1,42 @@
+module TaskMapper::Provider
+  module Dummy
+    # This is the Project class for the Dummy provider
+    class Project < TaskMapper::Provider::Base::Project
+      
+      def self.find_by_id(id)
+        self.new({:id => id})
+      end
+      
+      def self.find_by_attributes(*options)
+        [self.new(*options)]
+      end
+      
+      def self.create(*attributes)
+        self.new(*attributes)
+      end
+      
+      # You should define @system and @system_data here.
+      # The data stuff is just to initialize fake data. In a real provider, you would use the API
+      # to grab the information and then initialize based on that info.
+      # @system_data would hold the API's model/instance for reference
+      def initialize(*options)
+        data = {:id => rand(1000).to_i, :name => 'Dummy', :description => 'Mock!-ing Bird',
+          :created_at => Time.now, :updated_at => Time.now}
+        @system = :dummy
+        super(data.merge(options.first || {}))
+      end
+      
+      # Nothing to save so we always return true
+      # ...unless it's an odd numbered second on Friday the 13th. muhaha!
+      def save
+        time = Time.now
+        !(time.wday == 5 and time.day == 13 and time.to_i % 2 == 1)
+      end
+      
+      # Nothing to update, so we always return true
+      def update!(*options)
+        return true
+      end
+    end
+  end
+end

data/lib/taskmapper/dummy/ticket.rb

@@ -0,0 +1,43 @@
+module TaskMapper::Provider
+  module Dummy
+    # The Dummy Provider's Ticket class
+    class Ticket < TaskMapper::Provider::Base::Ticket
+      @system = :dummy
+      
+      def self.find_by_id(project_id, ticket_id)
+        self.new(project_id, {:id => ticket_id})
+      end
+      
+      def self.find_by_attributes(*ticket_attributes)
+        [self.new(*ticket_attributes)]
+      end
+    
+      # You don't need to define an initializer, this is only here to initialize dummy data
+      def initialize(project_id, *options)
+        data = {:id => rand(1000), :status => ['lol', 'rofl', 'lmao', 'lamo', 'haha', 'heh'][rand(6)],
+          :priority => rand(10), :summary => 'Tickets ticket ticket ticket', :resolution => false,
+          :created_at => Time.now, :updated_at => Time.now, :description => 'Ticket ticket ticket ticket laughing',
+          :assignee => 'lol-man', :project_id => project_id}
+        @system = :dummy
+        super(data.merge(options.first || {}))
+      end
+      
+      # Nothing to save so we always return true
+      # ...unless it's the Ides of March and the second is divisible by three. muhaha!
+      def save
+        time = Time.now
+        !(time.wday == 15 and time.day == 3 and time.to_i % 3 == 0)
+      end
+      
+      # Nothing to close, so we always return true
+      def close
+        true
+      end
+      
+      # Nothing to destroy so we always return true
+      def destroy
+        true
+      end
+    end
+  end
+end

data/lib/taskmapper/exception.rb

@@ -0,0 +1,2 @@
+class TaskMapper::Exception < Exception
+end

data/lib/taskmapper/helper.rb

@@ -0,0 +1,72 @@
+module TaskMapper::Provider
+  # Contains a series of helper methods
+  module Helper
+  
+    # Current method name reflection
+    # http://www.ruby-forum.com/topic/75258#895630
+    # Call when raising 'implemented by the provider' exceptions
+    def this_method
+      caller[0][/`([^']*)'/, 1]
+    end
+    
+    # A helper method for easy finding
+    def easy_finder(api, symbol, options, at_index = 0)
+      if api.is_a? Class
+        return api if options.length == 0 and symbol == :first
+        options.insert(at_index, symbol) if options[at_index].is_a?(Hash)
+        api.find(*options)
+      else
+        raise TaskMapper::Exception.new("#{Helper.name}::#{this_method} method must be implemented by the provider")
+      end
+    end
+    
+    # This is a search filter that all parameters are passed through
+    # Redefine this method in your classes if you need specific functionality
+    def search_filter(k)
+      k
+    end
+    
+    def provider_parent(klass)
+      TaskMapper::Provider.const_get(klass.to_s.split('::')[-2])
+    end
+    
+    # Goes through all the things and returns results that match the options attributes hash
+    def search_by_attribute(things, options = {}, limit = 1000)
+      things.find_all do |thing|
+        options.inject(true) do |memo, kv|
+          break unless memo
+          key, value = kv
+          begin
+            memo &= thing.send(key) == value
+          rescue NoMethodError
+            memo = false
+          end
+          memo
+        end and (limit -= 1) > 0
+      end
+    end
+    
+    # Returns a filter-like string from a hash
+    # If array_join is given, arrays are joined rather than having their own separated key:values
+    # 
+    # ex: filter_string({:name => 'some value', :tags => ['abc', 'def']}) = "name:'some value' tag:abc tag:def"
+    def filter_string(filter = {}, array_join = nil)
+        filter.inject('') do |mem, kv|
+          key, value = kv
+          if value.is_a?(Array)
+            if !array_join.nil?
+              mem += value.inject('') { |m, v|
+              v = "\"#{v}\"" if v.to_s.include?(' ')
+              m+= "#{key}:#{v}"
+              }
+              return mem
+            else
+              value = value.join(array_join)
+            end
+          end
+            value = "\"#{value}\"" if value.to_s.include?(' ')
+            mem += "#{key}:#{value} "
+        end
+    end
+  end
+end

data/lib/taskmapper/project.rb

@@ -0,0 +1,145 @@
+module TaskMapper::Provider
+  module Base
+    # This is the base Project class for providers
+    #
+    # Providers should inherit this class and redefine the methods
+    # 
+    # Each provider should have their own @system defined.
+    # For example, taskmapper-unfuddle's @system is :unfuddle and taskmapper-lighthouse's
+    # @system is :lighthouse.
+    #
+    # Methods that must be implemented by the provider
+    #
+    # * self.find_by_id
+    # * self.find_by_attributes
+    #
+    # Methods that might need to be implemented by the provider
+    # * tickets
+    # * ticket
+    # * initialize
+    # * update
+    # * destroy
+    # * self.create
+    #
+    # Methods that would probably be okay if the provider left it alone:
+    #
+    # * self.find - although you can define your own to optimize it a bit
+    # * update!
+    #
+    # A provider should define as many attributes as feasibly possible. The list below are 
+    # some guidelines as to what attributes are necessary, if your provider's api does not
+    # implement them, point it to an attribute that is close to it. (for example, a name
+    # can point to title. Remember to alias it in your class!)
+    # 
+    # * id
+    # * name
+    # * created_at
+    # * updated_at
+    # * description
+    class Project < Hashie::Mash
+      include TaskMapper::Provider::Common
+      include TaskMapper::Provider::Helper
+      extend TaskMapper::Provider::Helper
+      attr_accessor :system, :system_data
+      API = nil #Replace with your api digestor's class.
+
+      # Find project
+      # You can also retrieve an array of all projects by not specifying any query.
+      #
+      # * find() or find(:all) - Returns an array of all projects
+      # * find(##) - Returns a project based on that id or some other primary (unique) attribute
+      # * find([#, #, #]) - Returns many projects with these ids
+      # * find(:first, :name => 'Project name') - Returns the first project based on the project's attribute(s)
+      # * find(:last, :name => 'Some project') - Returns the last project based on the project's attribute(s)
+      # * find(:all, :name => 'Test Project') - Returns all projects based on the given attribute(s)
+      def self.find(*options)
+        first = options.shift
+        attributes = options.shift
+        if first.nil? or (first == :all and attributes.nil?)
+          self.find_by_attributes
+        elsif first.is_a? Array
+          first.collect { |id| self.find_by_id(id) }
+        elsif first == :first
+          projects = attributes.nil? ? self.find_by_attributes : self.find_by_attributes(attributes)
+          projects.first
+        elsif first == :last
+          projects = attributes.nil? ? self.find_by_attributes : self.find_by_attributes(attributes)
+          projects.last
+        elsif first == :all
+          self.find_by_attributes(attributes)
+        else
+          self.find_by_id(first)
+        end
+      end
+      
+      # The first of whatever project
+      def self.first(*options)
+        self.find(:first, *options)
+      end
+      
+      # The last of whatever project
+      def self.last(*options)
+        self.find(:last, *options)
+      end
+      
+      # Accepts an integer id and returns the single project instance
+      # Must be defined by the provider
+      def self.find_by_id(id)
+        if self::API.is_a? Class
+          self.new self::API.find(id)
+        else
+          raise TaskMapper::Exception.new("#{self.name}::#{this_method} method must be implemented by the provider")
+        end
+      end
+      
+      # Accepts an attributes hash and returns all projects matching those attributes in an array
+      # Should return all projects if the attributes hash is empty
+      # Must be defined by the provider
+      def self.find_by_attributes(attributes = {})
+        if self::API.is_a? Class
+          self.search(attributes)
+        else
+          raise TaskMapper::Exception.new("#{self.name}::#{this_method} method must be implemented by the provider")
+        end
+      end
+      
+      # This is a helper method to find
+      def self.search(options = {}, limit = 1000)
+        if self::API.is_a? Class
+          projects = self::API.find(:all).collect { |project| self.new project }
+          search_by_attribute(projects, options, limit)
+        else
+          raise TaskMapper::Exception.new("#{self.name}::#{this_method} method must be implemented by the provider")
+        end
+      end
+
+      # Asks the provider's api for the tickets associated with the project,
+      # returns an array of Ticket objects.
+      def tickets(*options)
+        options.insert 0, id
+        easy_finder(provider_parent(self.class)::Ticket, :all, options, 1)
+      end
+      
+      # Very similar to tickets, and is practically an alias of it
+      # however this returns the ticket class if no parameter is given
+      # unlike tickets which returns an array of all tickets when given no parameters
+      def ticket(*options)
+        options.insert(0, id) if options.length > 0
+        easy_finder(provider_parent(self.class)::Ticket, :first, options, 1)
+      end
+      
+      # Create a ticket
+      def ticket!(*options)
+        options[0].merge!(:project_id => id) if options.first.is_a?(Hash)
+        provider_parent(self.class)::Ticket.create(*options)
+      end
+      
+      # Define some provider specific initalizations
+      def initialize(*options)
+        # @system_data = {'some' => 'data}
+        super(*options)
+      end
+      
+    end
+  end
+end