timetrello 1.0.0 → 1.0.1

checksums.yaml

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

data/lib/time_trello/activity_record.rb

@@ -17,6 +17,8 @@ module TimeTrello
   class ActivityRecord
     include Comparable
 
+    # Public: This activity id. This is, actually, Trello's Action Identification.
+    attr_accessor :id
     # Public: Task duration
     attr_accessor :duration
     # Public: Task owner
@@ -36,11 +38,12 @@ module TimeTrello
     # 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]
+        @id                = args[0]
+        @duration          = args[1]
+        @owner             = args[2]
+        @project           = args[3]
+        @start_date        = args[4]
+        @task_description  = args[5]
       end
     end
 

data/lib/time_trello/parser.rb

@@ -15,12 +15,9 @@ 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
+    private
     attr :prefix
 
     # Private: Class variable used to hold the workflow pieces that parses the
@@ -47,21 +44,21 @@ module TimeTrello
           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
+          !activity.duration.nil?
         end,
 
         # Parses the comment owner 
         lambda do |action_record, activity|
           activity.owner = action_record[:member].full_name
 
-          activity.owner != nil
+          !activity.owner.nil?
         end,
 
         # Parses the project
         lambda do |action_record, activity|
           activity.project = action_record[:action].data["board"]["name"]
 
-          activity.project != nil
+          !activity.project.nil?
         end,
 
         # Parses the start date
@@ -70,7 +67,7 @@ module TimeTrello
           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
+          !activity.start_date.nil?
         end,
 
         # Parses the task comment
@@ -82,14 +79,18 @@ module TimeTrello
             activity.task_description  = action_record[:action].card.name
           end
 
-          activity.task_description != nil
+          !activity.task_description.nil?
+        end,
+
+        # Parses the task id
+        lambda do |action_record, activity|
+          activity.id = action_record[:action].id
+
+          !activity.id.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:
@@ -98,26 +99,25 @@ module TimeTrello
     #            creator of the action_record with details.
     # prefix - Prefix to use for comment detection
     public
-    def initialize(action_record, prefix)
-      @action_record = action_record
+    def initialize(prefix)
       @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()
+    def parse(action_record)
+      parsed_record = ActivityRecord.new()
 
       for step in self.workflow
-        if !step.call(@action_record, record)
+        if !step.call(action_record, parsed_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
+      parsed_record
     end
     
   end

data/lib/time_trello/report.rb

@@ -14,7 +14,16 @@ module TimeTrello
   # structure. It coordinates efforts with the persistence manager in order to
   # collect data from a given trello board.
   class Report
+    # Private: Getter for trello driver.
+    protected
+    def driver
+      @driver = TrelloDriver.new(@board_id, @prefix) if @driver == nil
+
+      @driver
+    end
+    
     # Public: Prefix for proper filtering
+    public
     attr_accessor :prefix
     # Public: Report start date
     attr_accessor :start_date
@@ -46,8 +55,7 @@ module TimeTrello
     # 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 }
+      result_set = self.driver.activities.find_all { |activity| activity.start_date >= @start_date && activity.start_date <= @end_date }
 
       if filter
         return result_set.find_all &filter  
@@ -55,6 +63,13 @@ module TimeTrello
 
       result_set
     end
+
+    def board_id=(board_id)
+      if board_id != @board_id
+        @board_id = board_id
+        self.driver.reset_cache
+      end
+    end
     
   end
 end

data/lib/time_trello/trello_driver.rb

@@ -23,33 +23,76 @@ module TimeTrello
     def initialize(board_id, prefix)
       @board_id = board_id
       @prefix = prefix
-      @activities = []
+      @activities = nil
       @board = nil
+      @members = nil
+      @parser = nil
     end
 
+    # Public: Getter. Returns a record parser instance
+    def parser
+      @parser = Parser.new(@prefix) if @parser.nil?
+
+      @parser
+    end
+    
     # Public: Getter. Gets a board, based on a board id.
     def board
-      @board = Trello::Board.find(@board_id) if @board == nil
+      retried = false
+
+      begin
+        @board = Trello::Board.find(@board_id) if @board.nil? 
+      rescue
+        if !retried
+          retried = true
+          retry
+        else
+          raise "Failed to connect to Trello API"
+        end 
+      end
 
       @board
     end
 
+    # Public: Getter. Gets all members subscribed to the board under analysis
+    def members
+      retried = false
+
+      begin
+        @members = self.board.members if @members.nil?
+      rescue
+        if !retried
+          retried = true
+          retry
+        else
+          raise "Failed to connect to Trello API"
+        end
+      end
+      
+      @members
+    end
+
     # Public: Getter. Gets all activities for a given board.
     def activities
-      return @activities if @activities != nil && @activities.length > 0
+      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)
+          member = self.members.first
           action_record = {action: action, member: member}
-          activity = (Parser.new(action_record, @prefix)).parse
-          @activities.push(activity) unless activity == nil
+          activity = self.parser.parse(action_record)
+          @activities.push(activity) unless activity.nil?
         end
       end
       
       @activities
     end
 
+    # Public: Resets the driver caches
+    def reset_cache
+      @activities = nil
+      @board = nil
+    end
   end
 end

data/lib/time_trello/version.rb

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

data/lib/time_trello.rb

@@ -17,7 +17,7 @@ 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.
@@ -40,7 +40,21 @@ module TimeTrello
   # 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)
+    self.report(start_date, end_date, board_id).find_all(&filter)
+  end
+
+  # Private: Getter for a report instance. Guarantees only one single instance
+  # available for caching optimization.
+  def self.report(start_date, end_date, board_id)
+    if @report == nil
+      @report = Report.new(start_date, end_date, board_id, @prefix)
+    else
+      # Updates report parameters
+      @report.start_date = start_date
+      @report.end_date = end_date
+      @report.board_id = board_id
+    end
+    
+    @report
   end
-  
 end

data/readme.md

@@ -0,0 +1,104 @@
+# TimeTrello
+
+**TimeTrello** is a simple gem that can interpret special trello comments. Those
+comments are then converted to a record type that makes it easy to integrate a
+time tracking application with Trello.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'timetrello'
+```
+
+And then execute:
+
+```console
+bundle
+```
+
+Or install it yourself as:
+
+```console
+gem install timetrello
+```
+
+
+## Usage
+
+You use the module directly.
+
+### Trello
+
+All time tracking annotations must follow the specification below in order to be
+understood and consolidated by **TimeTrello**.
+
+**PREFIX** **DURATION** [**START_DATE**] "**COMMENT**"
+
+See some valid examples:
+
+- :clock12: 0:35
+- :clock12: 102:22 "A comment example."
+- :clock12: 00:05 [2016-04-01]
+- :clock12: 007:59 [2012-03-17 21:50Z] "Other comment example."
+
+The default prefix which identifies the proper comment is :clock12:
+(`:clock12:`) emoticon. If no start date is provided through the comment, the
+comment timestamp is used.
+
+### Ruby
+
+```ruby
+require 'time_trello'
+
+TimeTrello.initialize('your trello public key here', 'your trello token here', ':clock12:')
+tasks = TimeTrello.find_all(Time.new(2012, 1, 1), Time.new(2016, 4, 1), 'Board ID you want to evaluate')
+
+tasks.each do |task|
+  # ...
+end
+```
+
+## Methods
+
+### `initialize`
+
+Initializes the **TimeTrello** subsystem, providing information necessary for its
+proper workings.
+
+#### Parameters
+
+```ruby
+TimeTrello.initialize(public_key, token, prefix=':clock12:')
+```
+
+| Parameter | Type | Description |
+|---|:---:|---|
+| **`public_key`** | `String` | Your Trello developer key |
+| **`token`** | `String` | The connection token provided by Trello due to its authorization process |
+| **`prefix`** | `String` | Prefix to use for comment detection. Defaults to `:clock12:` |
+
+### `find_all`
+
+Queries Trello, parsing comments which have the required format for consolidation.
+
+#### Parameters
+
+```ruby
+TimeTrello.find_all (start_date, end_date, board_id, &filter)
+```
+
+| Parameter | Type | Description |
+|---|:---:|---|
+| **`start_date`** | `Time` | Start date to use for limiting the result set |
+| **`end_date`** | `Time` | End date to use for limiting the result set |
+| **`board_id`** | `String` | Trello's board identification to query for |
+| **`filter`** | `Proc` | Block to use for extra data filtering |
+
+The `filter` block receives as parameter an instance of
+`TimeTrello::ActivityRecord`. It must return a boolean:
+
+- `true`: the entry will be on the final result set
+- `false`: the entry will de discarded from final result set
+
+See the `example.rb` file for a usage example.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timetrello
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Caio Tarifa
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-29 00:00:00.000000000 Z
+date: 2016-04-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-trello
@@ -37,7 +37,8 @@ email:
 - ronaldo@nineteen.com.br
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- readme.md
 files:
 - lib/time_trello.rb
 - lib/time_trello/activity_record.rb
@@ -46,12 +47,14 @@ files:
 - lib/time_trello/report.rb
 - lib/time_trello/trello_driver.rb
 - lib/time_trello/version.rb
-homepage: http://www.formaweb.com.br
+- readme.md
+homepage: http://formaweb.github.io/timetrello
 licenses:
 - MIT
 metadata: {}
 post_install_message: 
-rdoc_options: []
+rdoc_options:
+- "--charset=UTF-8"
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement