timetrello 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 29ddfa611b55bd19230b313aa9d1e0967ad0ebe4
+  data.tar.gz: acd5a81c5aa88d3f767d1f8fc9590bbee00c6295
+SHA512:
+  metadata.gz: 729ca5285e2259d674dce181730c3e28547c0cd75f62d111a89da221c5d18e535676646b88a64d1229edc36f4e5877840c49e796e182bc575a8ec53da86fbbd9
+  data.tar.gz: cdbf70e22bc99c46d0841dc7769e668a913f80f97e62d5f7a50dbbeeb14eb150c2a966fe1769853c447e498c01864e4592fb93f404a186a9e21e99fc92cbbcd6

data/lib/time_trello/activity_record.rb

@@ -0,0 +1,68 @@
+# -*-ruby-*-
+# Copyright (c) 2016 - Formaweb - All rights reserved
+#
+# Author:: Ronaldo Faria Lima
+# Created:: 2016-03-21
+#
+# Defines the structure that holds the activity record grabbed from a trello
+# board.
+
+require 'time_trello/duration';
+
+module TimeTrello
+  
+  # Public: An activity record identifies completely an activity done in
+  # trello. Its main ideia is to be a standard record that can be compared,
+  # sorted and collected, used for reporting purposes.
+  class ActivityRecord
+    include Comparable
+
+    # Public: Task duration
+    attr_accessor :duration
+    # Public: Task owner
+    attr_accessor :owner
+    # Public: Project name (i.e., Trello board)
+    attr_accessor :project
+    # Public: Task start date
+    attr_accessor :start_date
+    # Public: Task comment
+    attr_accessor :task_description
+    
+    # Public: Initializes this class with proper information about a given task
+    #
+    # project - Project name (i.e., the board name)
+    # owner - Name of the duration owner
+    # start_date - When the task started
+    # duration - The task duration
+    def initialize(*args)
+      if args.size != 0
+        @duration          = args[0]
+        @owner             = args[1]
+        @project           = args[2]
+        @start_date        = args[3]
+        @task_description  = args[4]
+      end
+    end
+
+    # Public: Implementation of Comparable mixin. The comparison is done
+    # following this attributes hierarchy:
+    # - project
+    # - owner
+    # - start_date
+    #
+    # other - The other instance of ActivityRecord to compare with.
+    def <=>(other)
+      if other == nil
+        return -1
+      end
+      result = @project <=> other.project
+      result = @owner <=> other.owner if result == 0
+      result = @start_date <=> other.start_date if result == 0
+      
+      result
+    end
+  end
+
+end
+
+

data/lib/time_trello/duration.rb

@@ -0,0 +1,97 @@
+# -*-ruby-*-
+# Copyright (c) 2016 - Formaweb - All rights reserved
+#
+# Author:: Ronaldo Faria Lima
+# Created:: 2016-03-21
+#
+# Describes a duration in hours and minutes and proper operations using those.
+
+module TimeTrello
+
+  # Public: Describes a duration in terms of hours and minutes, representing
+  # data internaly as seconds.
+  class Duration
+    protected
+    attr_accessor :internal_seconds # Internal representation of a duration
+    
+    # Public: Initializes this class with hours, minutes and seconds. You can
+    # provide two different sets of arguments in order to initialize this class.
+    #
+    # hours - Hours as an integer.
+    # minutes - Minutes as an integer using sexagesimal representation.
+    # seconds - Seconds as an integer, using sexagesimal representation.
+    #
+    # or:
+    #
+    # a string containing the duration using the format hh:mm.ss
+    public
+    def initialize(*args)
+      @internal_seconds = 0 
+      time_components = args
+      if args.size == 1 && args[0].class.equal?(String)
+        time_components = args[0].split(/[:.]/)
+      end
+      factor = 3600
+      time_components.each do |component|
+        @internal_seconds += factor * component.to_i
+        factor /= 60
+      end
+    end
+
+    # Public: Getter. Returns the number of hours from a given duration
+    def hours
+      @internal_seconds.abs / 3600
+    end
+
+    # Public: Getter. Returns the number of minutes from the internal representation
+    def minutes
+      (@internal_seconds.abs / 60) % 60
+    end
+
+    # Public: Getter. Returns the number of seconds of a given duration
+    def seconds
+      @internal_seconds.abs % 60
+    end
+
+    # Public: Getter. Returns the number of raw minutes of a given duration
+    #
+    # Important: This is a float value, since it is a raw value
+    def raw_minutes
+      @internal_seconds.abs.to_f / 60.0
+    end
+
+    # Public: Operator overload. Sums up two different instances of Duration
+    #
+    # other - The other operand
+    def +(other)
+      duration = Duration.new(0)
+      duration.internal_seconds = @internal_seconds + other.internal_seconds
+
+      duration
+    end
+
+    # Public: Operator overload. Subtracts two different instances of Duration.
+    #
+    # other - The other operand
+    #
+    # Important: The resultant duration will have its components described
+    # always as positive numbers, even if other is greater than this
+    # instance. It is because the way ruby operates over negative numbers in an
+    # integer division.
+    def -(other)
+      duration = Duration.new(0)
+      duration.internal_seconds = @internal_seconds - other.internal_seconds
+
+      duration
+    end
+
+    # Public: Converts an instance of this class to a string
+    # representation. This is a simple facility for fast representation
+    # on-screen.
+    #
+    def to_s
+      "#{hours}:#{minutes}.#{seconds}"
+    end
+  end
+
+end

data/lib/time_trello/parser.rb

@@ -0,0 +1,125 @@
+# -*-ruby-*-
+# Copyright (c) 2016 - Formaweb - All rights reserved
+#
+# Author:: Ronaldo Faria Lima
+# Created:: 2016-03-26
+#
+# Parser for ActivityRecord conversion from Trello data
+
+require 'date'
+
+require 'time_trello/activity_record'
+
+module TimeTrello
+
+  # Public: Parser for Trello::Action to ActivityRecord conversion. See
+  # ruby-trello for Trello::Action class specification. 
+  class Parser
+    # Private: Instance of Trello::Action to analize
+    private
+    attr :action_record
+
+    # Private: Prefix to use in detecting if a given comment is really an
+    # expected one
+    attr :prefix
+
+    # Private: Class variable used to hold the workflow pieces that parses the
+    # Trello::Action into TimeTrello::ActivityRecord. Each workflow step is a
+    # block that takes two parameters:
+    #
+    # action_record - Hash containing Trello::Action and Trello::Member instances
+    # record - TimeTrello::ActivityRecord instance to build
+    #
+    # Return:: true if parsing was flawless and false otherwise
+    #
+    protected
+    def workflow
+      [
+        # Detects if a given action_record is the one we are looking for.
+        lambda do |action_record, activity|
+          return action_record[:action].data['text'].starts_with?(@prefix) unless action_record[:action].data['text'] == nil
+
+          false
+        end,
+        
+        # Parses the duration
+        lambda do |action_record, activity|
+          txt_duration = action_record[:action].data['text'].scan(/[0-9]+:[0-9]+/)
+          activity.duration = Duration.new(txt_duration[0]) unless txt_duration.size == 0
+
+          activity.duration != nil
+        end,
+
+        # Parses the comment owner 
+        lambda do |action_record, activity|
+          activity.owner = action_record[:member].full_name
+
+          activity.owner != nil
+        end,
+
+        # Parses the project
+        lambda do |action_record, activity|
+          activity.project = action_record[:action].data["board"]["name"]
+
+          activity.project != nil
+        end,
+
+        # Parses the start date
+        lambda do |action_record, activity|
+          activity.start_date = action_record[:action].date
+          txt_date = action_record[:action].data["text"].scan(/\[[A-Z0-9:. -]+\]/)
+          activity.start_date = DateTime.parse(txt_date[0].to_s).to_time unless txt_date.size == 0
+
+          activity.start_date != nil
+        end,
+
+        # Parses the task comment
+        lambda do |action_record, activity|
+          txt_comment = action_record[:action].data["text"].scan(/"[a-zA-Z0-9]+"/)
+          if txt_comment.size != 0
+            activity.task_description = txt_comment[0]
+          else
+            activity.task_description  = action_record[:action].card.name
+          end
+
+          activity.task_description != nil
+        end
+      ]
+    end
+    
+    # Private: List of steps that parses the action_record, loading fields of a
+    # provided ActivityRecord instance. It is used as a workflow.
+
+    # Public: Initializes the parser, setting it to the proper state.
+    #
+    # action_record - Hash containing the following elements:
+    #          - :action_record - An instance of Trello::Action_Record class
+    #          - :member - An instance of Trello::Member class, which is the
+    #            creator of the action_record with details.
+    # prefix - Prefix to use for comment detection
+    public
+    def initialize(action_record, prefix)
+      @action_record = action_record
+      @prefix = prefix
+    end
+
+    # Public: Parses the action_record, building an instance of ActivityRecord. This
+    # parser is based on a workflow defined by a constant array of blocks. Each
+    # block is a step that will be executed in sequence.
+    def parse
+      record = ActivityRecord.new()
+
+      for step in self.workflow
+        if !step.call(@action_record, record)
+          # Workflow was interrupted. Not necessarily an error. Possibly the
+          # action_record was not the one we are looking for.
+          return nil
+        end
+      end
+
+      record
+    end
+    
+  end
+
+end

data/lib/time_trello/report.rb

@@ -0,0 +1,60 @@
+# -*-ruby-*-
+# Copyright (c) 2016 - Formaweb - All rights reserved
+#
+# Author:: Ronaldo Faria Lima
+# Created:: 2016-03-21
+#
+# Reporting engine. Used to select and build a result set to the caller.
+
+require 'time_trello/trello_driver'
+
+module TimeTrello
+
+  # Public: This class represents a report manager on the time trello
+  # structure. It coordinates efforts with the persistence manager in order to
+  # collect data from a given trello board.
+  class Report
+    # Public: Prefix for proper filtering
+    attr_accessor :prefix
+    # Public: Report start date
+    attr_accessor :start_date
+    # Public: Report end date
+    attr_accessor :end_date
+    # Public: board identification for reporting
+    attr_accessor :board_id
+
+    # Public: Initializes this class providing initial filter information
+    #
+    # start_date - Used to limit the result set. It is the start of time records
+    # end_date - Used to limit the result set. It is the end of time records
+    # board_id - Identification of the given board. Used to grab information
+    # from an specific board.
+    def initialize(start_date, end_date, board_id, prefix)
+      @start_date = start_date
+      @end_date = end_date
+      @board_id = board_id
+      @prefix = prefix
+    end
+
+    # Public: Generates the report based on a filter, if provided. The filter is
+    # a block that will filter the result set accordingly. The result set is
+    # always an array containing instances of ActivityRecord. See::
+    # ActivityRecord
+    #
+    # filter - Block used to filter the result set even further. It must follow
+    # the same format for the block passed as parameter to Array.find_all
+    # method. Each element on the array is, in fact, an instance of
+    # TimeTrello::ActivityRecord
+    def find_all &filter
+      driver = TrelloDriver.new(@board_id, @prefix)
+      result_set = driver.activities.find_all { |activity| activity.start_date >= @start_date && activity.start_date <= @end_date }
+
+      if filter
+        return result_set.find_all &filter  
+      end
+
+      result_set
+    end
+    
+  end
+end

data/lib/time_trello/trello_driver.rb

@@ -0,0 +1,55 @@
+# -*-ruby-*-
+# Copyright (c) 2016 - Formaweb - All rights reserved
+#
+# Author:: Ronaldo Faria Lima
+# Created:: 2016-03-22
+#
+# Trello driver, used to access trello and convert records to an internal
+# representation
+
+require 'trello'
+
+require 'time_trello/activity_record'
+require 'time_trello/parser'
+
+module TimeTrello
+
+  # Public: Driver responsible to convert data gathered from Trello to an
+  # internal representation.
+  class TrelloDriver
+    attr_accessor :board_id
+    attr_accessor :prefix
+
+    def initialize(board_id, prefix)
+      @board_id = board_id
+      @prefix = prefix
+      @activities = []
+      @board = nil
+    end
+
+    # Public: Getter. Gets a board, based on a board id.
+    def board
+      @board = Trello::Board.find(@board_id) if @board == nil
+
+      @board
+    end
+
+    # Public: Getter. Gets all activities for a given board.
+    def activities
+      return @activities if @activities != nil && @activities.length > 0
+      
+      @activities = []
+      self.board.cards.each do |card|
+        card.actions.each do |action|
+          member = Trello::Member.find(action.member_creator_id)
+          action_record = {action: action, member: member}
+          activity = (Parser.new(action_record, @prefix)).parse
+          @activities.push(activity) unless activity == nil
+        end
+      end
+      
+      @activities
+    end
+
+  end
+end

data/lib/time_trello/version.rb

@@ -0,0 +1,3 @@
+module TimeTrello
+  VERSION = '1.0.0'
+end

data/lib/time_trello.rb

@@ -0,0 +1,46 @@
+# -*-ruby-*-
+# Copyright (c) 2016 - Formaweb - All rights reserved
+#
+# Author:: Ronaldo Faria Lima
+# Created:: 2016-03-21
+#
+# Main gem module
+
+require 'trello'
+
+require 'time_trello/version'
+require 'time_trello/report'
+require 'time_trello/duration'
+require 'time_trello/activity_record'
+
+module TimeTrello
+  # Private: Prefix for comment detection/parsing
+  private
+  attr_accessor :prefix
+
+  # Public: Initializes this module with the proper trello client configuration.
+  #
+  # public_key - Trello public key used for authentication.
+  # member_token - Trello member token, used for authentication.
+  public
+  def self.initialize(public_key, member_token, prefix = ':clock12:')
+    @prefix = prefix
+    Trello.configure do |config|
+      config.developer_public_key = public_key
+      config.member_token = member_token
+    end
+  end
+
+  # Public: Generates the report based on the provided parameters.
+  #
+  # start_date - The start date to limit the results.
+  # end_date - The end date to limit the results.
+  # board_id - Identification of the board that should be parsed in order to
+  #            return results.
+  # filter - A block containing a filter for the results. The block must receive
+  #          a parameter which is an instance of ActivityRecord.
+  def self.find_all(start_date, end_date, board_id, &filter)
+    (Report.new(start_date, end_date, board_id, @prefix)).find_all(&filter)
+  end
+  
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: timetrello
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Caio Tarifa
+- Ronaldo Faria Lima
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-03-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby-trello
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.1
+description: Trello time tracking.
+email:
+- caiotarifa@gmail.com
+- ronaldo@nineteen.com.br
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/time_trello.rb
+- lib/time_trello/activity_record.rb
+- lib/time_trello/duration.rb
+- lib/time_trello/parser.rb
+- lib/time_trello/report.rb
+- lib/time_trello/trello_driver.rb
+- lib/time_trello/version.rb
+homepage: http://www.formaweb.com.br
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Trello time tracking with Ruby.
+test_files: []