torque 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1081effd8b2bc6581372cd2a3bd38540d1b38411
-  data.tar.gz: bab3ee280120bb1e291e7c608aa57034b885e760
+  metadata.gz: 14355f09eb1d9a65345ed81c053ceb353f3990e3
+  data.tar.gz: 7f6e191c2a67318615be764f1f99de4a959abb67
 SHA512:
-  metadata.gz: 3ac460137f176e2720c94544e3d74d930282901e7708ba6ea3e7d7c5d218ee23c14cd2769391a3fb89bd4537ace39f2b0bd5471a26bd006d47595d3cbfcd5ae8
-  data.tar.gz: 561657b3d705c34150fffcf6fe2b09d712e753df97ce7ed1ff07052a75f45d55dc1b7547a90230a853131057952d1aa87eeb0b7e07973d059a5d8801c05ea649
+  metadata.gz: 7641002a1af10500ca46689627c7de5aac7c8d78f8423e17c9506c949ea5d29e653845fb7f2c6fbb3bfafab6111ac8ed807339302bf9b4a412cdbb1699bfc882
+  data.tar.gz: ba240db9ca4829a3f92d90900032b9ab8b93b09118b2a21529253da23cf84d8eae03b40964a97874197976d73752308d903b796ab3aaaea9ef28f037705f67af

data/README.md

@@ -4,18 +4,18 @@ Torque
 Introduction
 ------------
 
-Torque is a command line utility packaged as a Ruby gem. It compiles online data from a Pivotal Tracker project into a set of release notes for that project.
+Torque is a command line utility that compiles data from your Pivotal Tracker project into a set of release notes for that project.
 
-At start, Torque requests a Pivotal Tracker API token, which gives Torque access to information from your Pivotal Tracker projects. Torque then asks the user to choose one of their projects to begin to generate notes from.
+At start, Torque requests a Pivotal Tracker API token, providing it access to info from your Pivotal Tracker projects. It then requests a project for which to generate release notes.
 
-Once configured, Torque requests data on the accepted stories from the current Pivotal project. It then compiles these stories into a first-draft release notes document. Depending on how consistently your team uses Pivotal Tracker, this document will contain:
+After this one time configuration, Torque can begin generating notes. To do this, it requests data on accepted stories from your Pivotal project and compiles these stories into a first-draft release notes document. Depending on how consistently your team uses Pivotal Tracker, this document will contain:
 
 * A record of each feature that was added to the project since the last time Torque was run
 * A description of the feature
 * The date that this feature was accepted
 * A link to the Pivotal Tracker story that tracks this feature
 
-Torque's default behavior is to document all the stories that were accepted since the last time Torque was run. For instance, if Torque was run on June 1st and then on June 10th, it would generate release notes from the stories that were accepted between June 1st and June 10th (inclusive). This is designed to make it easy to generate release notes each time new features are pushed to production: If Torque is run at the time of each new release, then it will generate notes for all the features that were added since the previous release. If needed, Torque can also generate notes for a custom date range.
+Torque's default behavior is to document all the stories that were accepted since the last time it was run. For instance, if Torque was run on June 1st and then on June 10th, it would generate release notes from the stories that were accepted between June 1st and June 10th (inclusive). This is designed to make it easy to generate release notes each time new features are pushed to production: If Torque is run at the time of each new release, then it will generate notes for all the features that were added since the previous release. If needed, Torque can also generate notes for a custom date range or for any number of past project iterations.
 
 Torque was designed and tested in a Ruby 2.0 environment.
 
@@ -23,11 +23,12 @@ Current Features
 ----------------
 
 * Automatically compiles all Pivotal Tracker stories accepted between the current date and the last time Torque was run
+* Store a record of each document on generation
 * Compile stories accepted within a custom date range
-* Stores a record of each document as it's generated
 * Filtering stories by label, owner or story type
+* Generate notes for specific number of completed project iterations
 * Configuration script that automatically sets up a directory to use Torque
-* Project script that automatically displays/switches between your Pivotal Tracker projects
+* Display all of your current Pivotal Tracker projects and easily switch between them
 * Ability to email the finished release notes from a personal email account to a pre-specified mailing list. (Currently can only send from accounts hosted by Gmail)
 
 Note on Confidentiality
@@ -86,6 +87,12 @@ To filter your results by story label, owner or type:
 
 Note: The Pivotal Tracker API currently only supports "AND" searches for these fields. A search for multiple labels, for example, will turn up only the stories that match every label. ("OR" searches may or may not be added with the release of the PT API v5, which should arrive soon.)
 
+To generate notes for X number of completed iterations of your project:
+
+    # torque --iterations X
+
+Note that a run with iterations currently disables filters, and it is incompatible with custom date ranges.
+
 To email the release notes from a personal email to Torque's mailing list:
 
     # torque --email

data/VERSION

@@ -1,3 +1,3 @@
 major:0
-minor:2
+minor:3
 patch:0

data/lib/torque.rb

@@ -41,24 +41,40 @@ class Torque
     notes_string += "Release Notes\n"
     notes_string += "Project #{@settings.project} - '#{project_name}'\n"
 
-    if @settings.filters_on && !@settings.iterations
-      notes_string += "Filter '#{@settings.filter_string}'\n"
-    end
-
-    if @settings.custom_date_range
+    if @settings.iterations
+      # Past iterations header
+      notes_string += "Last "
+      notes_string += @settings.iterations == 1 \
+                      ? notes_string += "iteration"
+                      : notes_string += "#{@settings.iterations} iterations"
+      notes_string += "\n"
+
+    elsif @settings.custom_date_range
+      # Custom date range header
       notes_string += "(custom "+@settings.accept_from.strftime(@date_format)+" - "+@settings.accept_to.strftime(@date_format)+")\n"
+    
     else
+      # Default date range header
       notes_string += "("+@settings.accept_from.strftime(@date_format)+" - "+@settings.accept_to.strftime(@date_format)+")\n"
     end
+    
+    if @settings.filters_on
+      # Filters header
+      notes_string += "Filter '#{@settings.filter_string}'\n"
+    end
 
     notes_string += "\n"
     notes_string += "These notes were generated with Torque, a Pivotal Tracker command line utility\n"
     notes_string += "\n"
 
+    html_parser = PivotalHTMLParser.new
+    html_parser.add_date_filter(@settings.accept_from, @settings.accept_to) unless @settings.iterations
+    html_parser.add_field_filters(@settings.filters) if @settings.filters_on
+
     if iterations
       # Adds each iteration
       
-      iteration_list = PivotalHTMLParser.new.process_project_iterations(project_html)
+      iteration_list = html_parser.process_project_iterations(project_html)
 
       iteration_list = Iteration.sort_list(iteration_list)
       iteration_list.each do |iteration|
@@ -75,10 +91,16 @@ class Torque
         end
       end
 
+      num_stories = 0
+      iteration_list.each {|iteration| num_stories += iteration.stories.length}
+
+      print_if_verbose "[Torque]"
+      print_if_verbose "[Torque] Added #{num_stories} stories"
+
     else
       # Adds each story
       
-      stories = PivotalHTMLParser.new.process_project_date_filter(project_html, @settings.accept_from, @settings.accept_to)
+      stories = html_parser.process_project(project_html)
 
       stories = Story.sort_list(stories)
       stories.each do |story|
@@ -151,7 +173,7 @@ class Torque
 
     print_if_not_silent "Current project: #{@settings.project} - '#{project_name}'"
 
-    print_if_not_silent "Filter: '#{@settings.filter_string}'" if @settings.filters_on
+    print_if_not_silent "Filter: \"#{@settings.filter_string}\"" if @settings.filters_on
 
     if @settings.iterations
       print_if_not_silent "Generating release notes: Last #{@settings.iterations} iterations..."
@@ -165,18 +187,10 @@ class Torque
     end
 
     pivotal = Pivotal.new(@settings.token)
-
-    project_html = ""
-
     if @settings.iterations
-      puts "WARNING: Filters are currently not supported when running with iterations" if @settings.filters_on
       project_html = pivotal.get_project_iterations(@settings.project, @settings.iterations)
     else
-      if @settings.filters_on
-        project_html = pivotal.get_project_stories(@settings.project, @settings.filter_string)
-      else
-        project_html = pivotal.get_project_stories(@settings.project)
-      end
+      project_html = pivotal.get_project_stories(@settings.project)
     end
     
     iterations_on = (!@settings.iterations.nil?)

data/lib/torque/field_filter.rb

@@ -0,0 +1,136 @@
+class Torque
+
+  ##
+  # Parses and stores a field filter for stories
+  class FieldFilter
+
+    ##
+    # The field that the FieldFilter filters over
+    attr_reader :field
+
+    ##
+    # The contents of the filter
+    attr_reader :contents
+
+    ##
+    # @param field A symbol representing the field to filter
+    # @param contents The contents of the field filter
+    #
+    # Current options for the field are
+    # * :label
+    # * :owner
+    # * :type
+    #
+    # An :owner filter with no spaces in it will filter separately by first/middle/last name. For instance,
+    # "Adam" would match "Adam Barnes" or "John Adam Smith" or "Joe Quincy Adam".
+    #
+    # The contents should be a list of values speparated by "," or "+", where AND is signified by "+" and OR is signified
+    # by ",", and "+" has a higher precedence than ",". For example,
+    #
+    # "ios+android,ios+web"
+    #
+    # translates to
+    #
+    # (ios AND android) OR (ios AND web)
+    #
+    def initialize(field, contents="")
+      @field = field
+      @contents = contents
+
+      # Represents evaluator as a 2-level array, @evaluator
+      #
+      # (ios AND android) OR (ios AND web) <=>
+      # [["ios", "android"], ["ios", "web"]]
+      parse_contents
+    end
+
+    ##
+    # Returns true if the filter includes the story, false if it excludes it
+    def eval(story)
+
+      # Determines the field to evaluate
+
+      story_field = nil
+      if @field == :label
+        story_field = story.labels
+      elsif @field == :owner
+        story_field = story.owner
+      elsif @field == :type
+        story_field = story.type
+      else
+        # Invalid filter
+        return true
+      end
+
+      # Evaluates the story's field
+
+      or_eval = false
+      @evaluator.each do |or_element|
+        
+        and_eval = true
+        or_element.each do |and_element|
+
+          if @field == :label
+            and_eval &&= (story_field.member? and_element) 
+
+          elsif @field == :owner
+            # Special case: "owner" filter
+            # If the filter element has no spaces in it...
+            # Then it is assumed to be a first/middle/last name, not a full name
+            if !and_element.match(" ")
+              and_eval &&= (story_field.split(" ").member? and_element)
+            else
+              and_eval &&= (story_field == and_element)
+            end
+
+          else # @field == :type
+            and_eval &&= (story_field == and_element)
+          end
+
+        end
+
+        or_eval ||= and_eval
+      end
+
+      or_eval
+
+    end
+
+    ##
+    # Returns a string representation of the FieldFilter
+    def to_s
+      "#{@field}: #{@contents}"
+    end
+
+    
+    private
+
+    # Parses @contents and stores the result in @evaluator, a 2-level array
+    # Returns @evaluator
+    def parse_contents
+
+      # Handles special case: empty contents
+      if @contents == ""
+        @evaluator = [[]]
+        return @evaluator
+      end
+      
+      # Splits all strings into arrays
+      @evaluator = contents
+      @evaluator = @evaluator.split ","
+      @evaluator.length.times do |i|
+        @evaluator[i] = @evaluator[i].split "+"
+      end
+
+      # Strips all array elements
+      @evaluator.each do |element1|
+        element1.each do |element2|
+          element2.strip!
+        end
+      end
+
+      @evaluator
+    end
+
+  end
+end

data/lib/torque/pivotal.rb

@@ -56,7 +56,7 @@ class Torque
       elsif response.code != "200"
         raise PivotalAPIError.new(
           "The Pivotal Tracker API responded with an unexpected error code: #{response.code}. Check your " \
-            "API token, and/or internet connection"
+            "API token, internet connection, and/or pivotaltracker.com"
         )
       end
 
@@ -65,12 +65,11 @@ class Torque
 
     ##
     # @param project The ID of the Pivotal Tracker project from which to get data
-    # @param filter_string A string filter for the stories
     #
     # Sends a request through the Pivotal Tracker API
     #
     # Returns a string of html data from Pivotal Tracker with data on the stories for the given project
-    def get_project_stories(project, filter_string=nil)
+    def get_project_stories(project)
 
       # Polls story data from pivotal tracker
       host="pivotaltracker.com"
@@ -78,7 +77,6 @@ class Torque
       url="http://www.pivotaltracker.com/services/v3/projects/#{project}/stories"
       headers={'X-TrackerToken'=>@token}
 
-      url += "?filter=#{filter_string} includedone:true" if filter_string
       url = URI.escape(url)
 
       response=Net::HTTP.new(host, port).get(url, headers)
@@ -93,7 +91,7 @@ class Torque
       elsif response.code != "200"
         raise PivotalAPIError.new(
           "The Pivotal Tracker API responded with an unexpected error code: #{response.code}. Check your " \
-          + "project ID, API token, and/or internet connection"
+          + "project ID, API token, internet connection, and/or pivotaltracker.com"
         )
         
       end
@@ -107,7 +105,7 @@ class Torque
     #
     # Sends a request throgh the Pivotal Tracker API
     #
-    # Returns a string of html data from Pivotal Tracker with data on previous finished project iterations
+    # Returns a string of html data from Pivotal Tracker with data on finished iterations of a project
     def get_project_iterations(project, number=1)
 
       # Polls story data from pivotal tracker
@@ -130,7 +128,7 @@ class Torque
       elsif !(["2","3"].member? response.code[0])
         raise PivotalAPIError.new(
           "The Pivotal Tracker API responded with an unexpected error code: #{response.code}. Check your " \
-          + "project ID, API token, and/or internet connection"
+          + "project ID, API token, internet connection, and/or pivotaltracker.com"
         )
         
       end

data/lib/torque/pivotal_html_parser.rb

@@ -10,35 +10,41 @@ require_relative 'story'
 class Torque
   class PivotalHTMLParser
 
-    ##
-    # @param project_html_string An html string containing the story data for a Pivotal Tracker project
-    # @param accept_from A Date marking the lower bound for the date_accepted field of a story
-    # @param accept_to A Date marking the upper bound for the date_accepted field of a story
-    # 
-    # Returns a list of Story objects parsed from project_html_string whose date_accepted fields are within acceptable
-    # bounds (least recent to most recent date accepted)
-    def process_project_date_filter(project_html_string, accept_from, accept_to)
-
-      story_list = process_project(project_html_string)
-      story_list.select! {
-        |story|
-        (!story.date_accepted.nil? \
-          && story.date_accepted >= accept_from \
-          && story.date_accepted <= accept_to)
-      }
+    def initialize
+      @date_filter = false
+      @field_filters = false
+    end
 
-      story_list
+    ##
+    # @param accept_from A Date marking the lower bound for the date_accepted field of a story (inclusive)
+    # @param accept_to A Date marking the upper bound for the date_accepted field of a story (inclusive)
+    #
+    # Adds a date filter to stories, excluding them if they lie outside the provided dates
+    def add_date_filter(accept_from, accept_to)
+      @date_filter = true
+      @accept_from = accept_from
+      @accept_to = accept_to
+    end
 
+    ##
+    # @param field_filter_list A list of FieldFilter objects to use
+    #
+    # Adds field filters to stories, excluding them if they do not pass all filters in field_filter_list
+    def add_field_filters(field_filter_list)
+      @field_filters = true
+      @field_filter_list = field_filter_list
     end
 
     ##
     # @param project_html_string An html string containing the story data for a Pivotal Tracker project
     #
     # Returns a list of all Story objects parsed from project_html_string (least recent to most recent date accepted)
+    #
+    # Applies during processing any filters that have been added
     def process_project(project_html_string)
 
       project_element = Nokogiri::HTML(project_html_string)
-      process_project_element(project_element)
+      process_stories_element(project_element)
     end
 
 
@@ -62,7 +68,7 @@ class Torque
 
     private
 
-    # story_element: A Nokogiri::XML::Element representing a story (root element - "story")
+    # story_element: A Nokogiri::XML::Element representing a story (root element "story")
     #
     # Returns a Story object based off the information in the element
     def process_story_element(story_element)
@@ -77,23 +83,26 @@ class Torque
       Story.create(story_hash)
     end
 
-    # project_element: A Nokogiri::XML::Element representing a project (root element - "stories")
+    # stories_element: A Nokogiri::XML::Element representing a collection of stories (root element "stories")
     #
     # Returns a list of all Story objects parsed from project_element (least recent to most recent date accepted)
-    def process_project_element(project_element)
+    #
+    # Excludes stories that fall outside of any added filters
+    def process_stories_element(stories_element)
 
-      story_html_array = project_element.search('story')
+      story_html_array = stories_element.search('story')
       story_list = []
 
       story_html_array.each do
         |story_element|
-        story_list << process_story_element(story_element)
+        story = process_story_element(story_element)
+        story_list << story if passes_filters(story)
       end
 
       story_list
     end
 
-    # iteraton_element: A Nokogiri::XML::Element representing an iteration (root element - "iteration")
+    # iteraton_element: A Nokogiri::XML::Element representing an iteration (root element "iteration")
     #
     # Returns an Interation object based off the object in the element
     def process_iteration_element(iteration_element)
@@ -106,12 +115,32 @@ class Torque
         if child.name == "id"
           iter_number = child.children[0].text
         elsif child.name == "stories"
-          stories = process_project_element(child)
+          stories = process_stories_element(child)
         end
       end
 
       Iteration.new(iter_number, stories)
     end
 
+    # story: A Story object
+    # 
+    # True if story passes the list of filters, else false
+    def passes_filters(story)
+
+      if @date_filter        
+        return false if story.date_accepted.nil?
+        return false unless (story.date_accepted <= @accept_to)
+        return false unless (story.date_accepted >= @accept_from)
+      end
+
+      if @field_filters
+        @field_filter_list.each do |filter|
+          return false unless filter.eval(story)
+        end
+      end
+
+      return true
+    end
+
   end
 end

data/lib/torque/settings.rb

@@ -1,5 +1,6 @@
 require 'date'
 require_relative 'date_settings'
+require_relative 'field_filter'
 require_relative 'file_system'
 require_relative 'record_pathname_settings'
 require_relative 'torque_info_parser'
@@ -50,15 +51,15 @@ class Torque
     attr_reader :email_to
 
     ##
-    # True if filters are being used for the stories, else false
+    # A string representing the current filter
     attr_reader :filter_string
 
     ##
-    # A hash (field => contents) of the filters being used
+    # A list of field filters in use
     attr_reader :filters
 
     ##
-    # True if filters are being used for the stories, else false
+    # True if field filters are being used for stories, else false
     attr_reader :filters_on
 
     ##
@@ -123,26 +124,15 @@ class Torque
 
       # Parses story filters from the options
 
-      @filters = {}
-
-      @filters[:label] = @options[:label] if @options[:label]
-      @filters[:owner] = @options[:owner] if @options[:owner]
-      @filters[:type]  = @options[:type]  if @options[:type]
+      @filters = []
+      
+      @filters << FieldFilter.new(:label, @options[:label]) if @options[:label]
+      @filters << FieldFilter.new(:owner, @options[:owner]) if @options[:owner]
+      @filters << FieldFilter.new(:type, @options[:type])  if @options[:type]
 
       @filters_on = !@filters.empty?
 
-      # Generates a filter string from the story filters
-
-      @filter_string = ""
-      @filters.each do |field, args|
-        args.split(",").each do |arg|
-          arg.strip!
-          @filter_string += "#{field}:"
-          @filter_string += ( (arg.include? " ") ? "\"#{arg}\" " : "#{arg} " )
-        end
-      end
-
-      @filter_string.strip!
+      @filter_string = @filters.map {|f| f.to_s}.join ", "
 
       # Parses and processes data from .torqueinfo.yaml
 

data/lib/torque/story.rb

@@ -28,6 +28,10 @@ class Torque
     # The name of the story
     attr_reader :name
 
+    ##
+    # The owner of the story
+    attr_reader :owner
+
     ##
     # The ID of the story's project
     attr_reader :project_id
@@ -77,6 +81,7 @@ class Torque
       @estimate = -1
       @labels = "" # Will be an array
       @name = ""
+      @owner = ""
       @project_id = -1
       @story_id = -1
       @type = ""
@@ -84,8 +89,9 @@ class Torque
       @current_state = handle_nil(@current_state, html_hash["current_state"])
       @description = handle_nil(@description, html_hash["description"])
       @name = handle_nil(@name, html_hash["name"])
+      @owner = handle_nil(@owner, html_hash["owned_by"])
       @type = handle_nil(@type, html_hash["story_type"])
-      
+
       @estimate = Integer(handle_nil(@estimate, html_hash["estimate"]))      
       @project_id = Integer(handle_nil(@project_id, html_hash["project_id"]))
       @story_id = Integer(handle_nil(@story_id, html_hash["id"]))
@@ -109,9 +115,5 @@ class Torque
       sorted
     end
 
-    def to_s
-      return "Story("+@name+", "+"#{@story_id}"+")"
-    end
-
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: torque
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Nico Adams, Scrimmage
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-07 00:00:00.000000000 Z
+date: 2013-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -102,6 +102,7 @@ files:
 - lib/torque/error/missing_token_error.rb
 - lib/torque/error/missing_torque_info_file_error.rb
 - lib/torque/error/pivotal_api_error.rb
+- lib/torque/field_filter.rb
 - lib/torque/file_system.rb
 - lib/torque/iteration.rb
 - lib/torque/mailer.rb