torque 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1c7055b042760f90fba0fe791442b4ba857bec52
-  data.tar.gz: 2e386cca466678b01c5f3e8dc7b45606285c672b
+  metadata.gz: 1081effd8b2bc6581372cd2a3bd38540d1b38411
+  data.tar.gz: bab3ee280120bb1e291e7c608aa57034b885e760
 SHA512:
-  metadata.gz: eace72e27669cb57a907a3155a522d2159dcf12e592c4aa062ce89a4d053f3d7727c5483a322e020794d4235992584422044513c4eec863c0f0b6dac5e982443
-  data.tar.gz: a3c738c870d46ffbc8d84fb1fb7f09ffdcdc566de1ce9ac01ffa807fff82d49fa294be4d11918ff70c766274e3dbb21327dc2511e84bef330362df7b485196e8
+  metadata.gz: 3ac460137f176e2720c94544e3d74d930282901e7708ba6ea3e7d7c5d218ee23c14cd2769391a3fb89bd4537ace39f2b0bd5471a26bd006d47595d3cbfcd5ae8
+  data.tar.gz: 561657b3d705c34150fffcf6fe2b09d712e753df97ce7ed1ff07052a75f45d55dc1b7547a90230a853131057952d1aa87eeb0b7e07973d059a5d8801c05ea649

data/VERSION

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

data/bin/torque

@@ -20,9 +20,12 @@ options = {}
 
 option_parser = OptionParser.new do |opts|
 
-  help_message = "This script will fail unless it is run in a directory that was configured for Torque by running " \
-  "'torque config' (see 'torque config --help' for more). To change the directory torque runs in, change your " \
-  "current working directory, or use the --root option"
+  help_message = "The main executable for the Torque gem. Generates release notes automatically for your Pivotal " \
+    "Tracker project.\n"
+  help_message += "\n"
+  help_message += "This script must be run in a directory that has been configured for Torque by running 'torque " \
+    "config' in that directory (see 'torque config --help' for more). You can use the --root option to make Torque " \
+    "run from a directory different from your working directory."
 
   opts.banner  = "\nUsage:"
   opts.banner += "\n    torque [options]"
@@ -52,6 +55,11 @@ option_parser = OptionParser.new do |opts|
     options[:help] = arg
   end
 
+  opts.on("-i", "--iterations NUMBER", "Compiles notes for NUMBER of previous iterations") do
+    |arg|
+    options[:iterations] = arg
+  end
+
   opts.on("--label LABELS", "Filters stories by a (comma-separated) list of labels") do
     |arg|
     options[:label] = arg
@@ -118,6 +126,16 @@ begin
     puts "Unknown arguments: #{ARGV.join(", ")}"
     puts option_parser.help
     exit
+  
+  elsif (options.has_key?(:accept_to) || options.has_key?(:accept_from)) && options.has_key?(:iterations)
+    err_str = "Conflicting options: "
+    err_str += "-t/--to, " if options.has_key? :accept_to
+    err_str += "-f/--from, " if options.has_key? :accept_from
+    err_str += "-i/iterations. "
+    err_str += "Cannot use a custom date range with 'iterations' option"
+    puts err_str
+#    puts option_parser.help
+    exit 1
   end
 
 rescue OptionParser::InvalidOption, OptionParser::MissingArgument
@@ -131,7 +149,7 @@ end
 if !Torque::Pivotal.connection?
   puts "ABORTING"
   puts "Cannot connect to www.pivotaltracker.com. A connection is required to use Torque"
-  exit 1
+  exit 2
 end
 
 # Runs Torque, handling errors
@@ -142,28 +160,28 @@ rescue Torque::MissingTokenError, Torque::InvalidTokenError => e
   puts "ABORTING"
   puts e.message
   puts "Run 'torque config --token' to set your Pivotal Tracker API token"
-  (e.is_a? Torque::MissingTokenError) ? (exit 2) : (exit 3)
+  (e.is_a? Torque::MissingTokenError) ? (exit 3) : (exit 4)
 rescue Torque::MissingProjectError, Torque::InvalidProjectError => e
   puts "ABORTING"
   puts e.message
   puts "Run 'torque project' to set your Pivotal Tracker project"
-  (e.is_a? Torque::MissingProjectError) ? (exit 4) : (exit 5)
+  (e.is_a? Torque::MissingProjectError) ? (exit 5) : (exit 6)
 rescue Torque::PivotalAPIError => e
   puts "ABORTING"
   puts e.message
-  exit 6
+  exit 7
 rescue Torque::MissingTorqueInfoFileError => e
   puts "ABORTING"
   puts e.message
   puts "Run 'torque config' in this directory, or change your working directory"
-  exit 7
+  exit 8
 rescue Torque::MissingOutputDirectoryError => e
   puts "ABORTING"
   puts e.message
   puts "Run 'torque config -o [directory]' to create/change your output directory"
-  exit 8
+  exit 9
 rescue ArgumentError => e
   puts "ABORTING"
   puts e.message
-  exit 9
+  exit 10
 end

data/lib/torque.rb

@@ -29,22 +29,20 @@ class Torque
   ##
   # @param project_html An html string containing all the project's stories
   # @param project_name The name of the current project
+  # @param iterations True if the stories are organized into iterations, else false
   #
   # Returns a string comprising the release notes document
-  def generate_notes(project_html, project_name)
+  def generate_notes(project_html, project_name, iterations=false)
 
     notes_string = ""
 
-    # Parses stories from html, filters them by date and returns them in an array
-    stories = PivotalHTMLParser.new.process_project_date_filter(project_html, @settings.accept_from, @settings.accept_to)
-
     # Adds the header
     notes_string += Date.today.strftime(@date_format)+"\n"
     notes_string += "Release Notes\n"
     notes_string += "Project #{@settings.project} - '#{project_name}'\n"
 
-    if @settings.filters_on
-      notes_string += "Filter - '#{@settings.filter_string}'\n"
+    if @settings.filters_on && !@settings.iterations
+      notes_string += "Filter '#{@settings.filter_string}'\n"
     end
 
     if @settings.custom_date_range
@@ -53,33 +51,44 @@ class Torque
       notes_string += "("+@settings.accept_from.strftime(@date_format)+" - "+@settings.accept_to.strftime(@date_format)+")\n"
     end
 
-    notes_string += "\nThese notes were generated with Torque, a Pivotal Tracker command line utility"
     notes_string += "\n"
+    notes_string += "These notes were generated with Torque, a Pivotal Tracker command line utility\n"
     notes_string += "\n"
 
-    # Adds each story
-    stories.sort! { |s1, s2| -(s1.date_accepted <=> s2.date_accepted) }
-    stories.length.times do |i|
-      story = stories[i]
+    if iterations
+      # Adds each iteration
       
-      notes_string += "#{story.story_id}\n"
-      notes_string += "#{story.name}\n"
-      notes_string += "Accepted on "+story.date_accepted.strftime(@date_format)+"\n"
-      notes_string += "https://www.pivotaltracker.com/story/show/#{story.story_id}\n"
+      iteration_list = PivotalHTMLParser.new.process_project_iterations(project_html)
+
+      iteration_list = Iteration.sort_list(iteration_list)
+      iteration_list.each do |iteration|
+        notes_string += "-- Iteration #{iteration.number} --\n"
+        notes_string += "\n"
 
-      print_if_verbose "[Torque] (#{story.date_accepted.strftime(@date_format)}) #{story.name}"
+        print_if_verbose "[Torque]"
+        print_if_verbose "[Torque] -- Iteration #{iteration.number} --"
 
-      descArray = story.description.split("\n")
-      descArray.length.times do |i|
-        notes_string += "\t"+descArray[i]+"\n"
+        iteration.sort_stories
+        iteration.stories.each do |story|
+          notes_string += generate_story_string(story)
+          print_if_verbose "[Torque] (#{story.date_accepted.strftime(@date_format)}) #{story.name}"
+        end
       end
+
+    else
+      # Adds each story
       
-      notes_string += "\n"
+      stories = PivotalHTMLParser.new.process_project_date_filter(project_html, @settings.accept_from, @settings.accept_to)
 
-    end
+      stories = Story.sort_list(stories)
+      stories.each do |story|
+        notes_string += generate_story_string(story)
+        print_if_verbose "[Torque] (#{story.date_accepted.strftime(@date_format)}) #{story.name}"
+      end
 
-    print_if_verbose "[Torque]"
-    print_if_verbose "[Torque] Added #{stories.length} stories"
+      print_if_verbose "[Torque]"
+      print_if_verbose "[Torque] Added #{stories.length} stories"
+    end
 
     notes_string
   end
@@ -144,17 +153,34 @@ class Torque
 
     print_if_not_silent "Filter: '#{@settings.filter_string}'" if @settings.filters_on
 
-    print_if_not_silent "Generating release notes: " \
-      + (@settings.custom_date_range ? "Custom " : "") \
-      + @settings.accept_from.strftime(@date_format) + " - " \
-      + @settings.accept_to.strftime(@date_format) \
-      + "..."
+    if @settings.iterations
+      print_if_not_silent "Generating release notes: Last #{@settings.iterations} iterations..."
+
+    else
+      print_if_not_silent "Generating release notes: " \
+        + (@settings.custom_date_range ? "Custom " : "") \
+        + @settings.accept_from.strftime(@date_format) + " - " \
+        + @settings.accept_to.strftime(@date_format) \
+        + "..."
+    end
 
     pivotal = Pivotal.new(@settings.token)
-    @settings.filters_on \
-    ? project_html = pivotal.get_project_stories(@settings.project, @settings.filter_string) \
-    : project_html = pivotal.get_project_stories(@settings.project)
-    notes_string = generate_notes(project_html, project_name)
+
+    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
+    end
+    
+    iterations_on = (!@settings.iterations.nil?)
+    notes_string = generate_notes(project_html, project_name, iterations_on)
 
     # Writes the notes to file
 
@@ -188,6 +214,27 @@ class Torque
 
   private
 
+  # story: A Story object
+  # 
+  # Generates a string of release notes for the story
+  # If verbose, prints a statement saying the story was added to stdout
+  def generate_story_string(story)
+    notes_string = ""
+
+    notes_string += "#{story.story_id}\n"
+    notes_string += "#{story.name}\n"
+    notes_string += "Accepted on "+story.date_accepted.strftime(@date_format)+"\n"
+    notes_string += "https://www.pivotaltracker.com/story/show/#{story.story_id}\n"
+
+    descArray = story.description.split("\n")
+    descArray.length.times do |i|
+      notes_string += "\t"+descArray[i]+"\n"
+    end
+    
+    notes_string += "\n"
+    notes_string
+  end
+
   # Prints a message if silent is not on
   def print_if_not_silent(msg)
     puts msg unless @settings.silent

data/lib/torque/iteration.rb

@@ -0,0 +1,48 @@
+class Torque
+  
+  ##
+  # Stores the data for one finished iteration of a PT project
+  class Iteration
+
+    ##
+    # The iteration's number
+    attr_reader :number
+
+    ##
+    # The iteration's list of stories
+    attr_reader :stories
+
+    ##
+    # @param number The iteration's number
+    # @param stories A list of stories in the iteration 
+    def initialize(number, stories=[])
+
+      @number = number
+      @stories = stories
+    end
+
+    ##
+    # @param story A story
+    #
+    # Adds story to the list of stories
+    def add_story(story)
+      @stories << story
+    end
+
+    ##
+    # Sorts the list of stories from most to least recent
+    def sort_stories
+      @stories = Story.sort_list(stories)
+    end
+
+    ##
+    # @param iterations A list of iterations
+    #
+    # Returns a list of iterations sorted from most to least recent
+    def self.sort_list(iterations)
+      sorted = iterations.sort {|i1, i2| Integer(i2.number) - Integer(i1.number) }
+      sorted
+    end
+
+  end
+end

data/lib/torque/pivotal.rb

@@ -34,6 +34,35 @@ class Torque
       end
     end
 
+    ##
+    # Sends a request through the Pivotal Tracker API
+    #
+    # Returns a string of html data from Pivotal Tracker with data on each of a user's projects
+    def get_project_data
+
+      host="pivotaltracker.com"
+      port=80
+      url="http://www.pivotaltracker.com/services/v3/projects"
+      headers={'X-TrackerToken'=>@token}
+
+      url = URI.escape(url)
+
+      response=Net::HTTP.new(host, port).get(url, headers)
+
+      # Handles network errors
+      if response.code == "401"
+        raise InvalidTokenError.new "The Pivotal Tracker API token supplied is not valid"
+
+      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"
+        )
+      end
+
+      response.body
+    end
+
     ##
     # @param project The ID of the Pivotal Tracker project from which to get data
     # @param filter_string A string filter for the stories
@@ -73,14 +102,18 @@ class Torque
     end
 
     ##
-    # Sends a request through the Pivotal Tracker API
+    # @param project The ID of the Pivotal Tracker project from which to get data
+    # @param number The number of project iterations to fetch
     #
-    # Returns a string of html data from Pivotal Tracker with data on each of a user's projects
-    def get_project_data
+    # Sends a request throgh the Pivotal Tracker API
+    #
+    # Returns a string of html data from Pivotal Tracker with data on previous finished project iterations
+    def get_project_iterations(project, number=1)
 
+      # Polls story data from pivotal tracker
       host="pivotaltracker.com"
       port=80
-      url="http://www.pivotaltracker.com/services/v3/projects"
+      url="http://www.pivotaltracker.com/services/v3/projects/#{project}/iterations/done?offset=-#{number}"
       headers={'X-TrackerToken'=>@token}
 
       url = URI.escape(url)
@@ -89,18 +122,21 @@ class Torque
 
       # Handles network errors
       if response.code == "401"
-        raise InvalidTokenError.new "The Pivotal Tracker API token supplied is not valid"
+        raise InvalidTokenError.new "The Pivotal Tracker API token supplied is not valid for project #{project}"
 
-      elsif response.code != "200"
+      elsif response.code == "500"
+        raise InvalidProjectError.new "The Pivotal Tracker project ID supplied, #{project}, is invalid"
+
+      elsif !(["2","3"].member? response.code[0])
         raise PivotalAPIError.new(
           "The Pivotal Tracker API responded with an unexpected error code: #{response.code}. Check your " \
-            "API token, and/or internet connection"
+          + "project ID, API token, and/or internet connection"
         )
+        
       end
 
       response.body
     end
 
-
   end
 end

data/lib/torque/pivotal_html_parser.rb

@@ -3,8 +3,10 @@
 
 require 'date'
 require 'nokogiri'
+require_relative 'iteration'
 require_relative 'story'
 
+
 class Torque
   class PivotalHTMLParser
 
@@ -29,29 +31,41 @@ class Torque
 
     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)
     def process_project(project_html_string)
 
+      project_element = Nokogiri::HTML(project_html_string)
+      process_project_element(project_element)
+    end
+
+
+    ##
+    # @param project_html_string An html string containing iteration data for a Pivotal Tracker project
+    # 
+    # Returns a list of Iteration objects parsed from project_html_string (least recent to most recent iteration)
+    def process_project_iterations(project_html_string)
+
       project_html = Nokogiri::HTML(project_html_string)
-      story_html_array = project_html.search('story')
-      story_list = []
+      iteration_html_array = project_html.search('iteration')
+      iteration_list = []
 
-      story_html_array.each do
-        |story_element|
-        story_list << process_story(story_element)
+      iteration_html_array.each do
+        |iteration_element|
+        iteration_list << process_iteration_element(iteration_element)
       end
 
-      story_list
+      iteration_list
     end
 
-
     private
-    # story: A Nokogiri::XML::Element
+
+    # story_element: A Nokogiri::XML::Element representing a story (root element - "story")
     #
-    # Returns a Story object based off the information in the story
-    def process_story(story_element)
+    # Returns a Story object based off the information in the element
+    def process_story_element(story_element)
 
       story_hash = {}
 
@@ -63,5 +77,41 @@ class Torque
       Story.create(story_hash)
     end
 
+    # project_element: A Nokogiri::XML::Element representing a project (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)
+
+      story_html_array = project_element.search('story')
+      story_list = []
+
+      story_html_array.each do
+        |story_element|
+        story_list << process_story_element(story_element)
+      end
+
+      story_list
+    end
+
+    # 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)
+      
+      iter_number = nil
+      stories = []
+
+      iteration_element.children.each do
+        |child|
+        if child.name == "id"
+          iter_number = child.children[0].text
+        elsif child.name == "stories"
+          stories = process_project_element(child)
+        end
+      end
+
+      Iteration.new(iter_number, stories)
+    end
+
   end
 end

data/lib/torque/record_pathname_settings.rb

@@ -9,12 +9,13 @@ class Torque
     ##
     # @param output_dir The path to the release notes output directory
     # @param project The project id
-    # @param custom True if this is a run with custom settings, else false
+    # @param custom True if this is a run with custom date settings, else false
     # @param fs An instance of the FileSystem class
-    def initialize(output_dir, project, custom, fs)
+    def initialize(output_dir, project, custom, iterations, fs)
       @output_dir = output_dir
       @project = project
       @custom = custom
+      @iterations = iterations
       @fs = fs
     end
 
@@ -32,18 +33,13 @@ class Torque
     def generate_record_path
       if @custom
         path_for_custom_date_range
+      elsif @iterations
+        path_for_iterations
       else
-        path_for_default_date_range
+        path_for_default
       end
     end
 
-    # The path to the record of the release notes file if default dates were used
-    def path_for_default_date_range
-      title = "#{@project}-#{current_date_string}"
-      @path="#{@output_dir}/previous/#{title}.txt"
-      @path
-    end
-
     # The path to the record of the release notes file if a custom date range was used
     def path_for_custom_date_range
       title = "#{@project}-#{current_date_string}"
@@ -71,6 +67,20 @@ class Torque
       @path
     end
 
+    def path_for_iterations
+      title = "#{@project}-#{current_date_string}"
+      title += "-iter-#{@iterations}"
+      @path = "#{@output_dir}/previous/#{title}.txt"
+      @path
+    end
+
+    # The path to the record of the release notes file if default dates were used
+    def path_for_default
+      title = "#{@project}-#{current_date_string}"
+      @path = "#{@output_dir}/previous/#{title}.txt"
+      @path
+    end
+
     # A string representing the current date: YYYY-MM-DD
     def current_date_string
       Date.today.strftime("%Y-%m-%d")

data/lib/torque/settings.rb

@@ -61,6 +61,10 @@ class Torque
     # True if filters are being used for the stories, else false
     attr_reader :filters_on
 
+    ##
+    # The number of iterations of the project to generate notes for, or nil if not using iterations
+    attr_reader :iterations
+
     ##
     # The path to the .last-run file in the records directory
     attr_reader :last_run_path
@@ -111,7 +115,7 @@ class Torque
       @root_dir = @options[:root_dir] || "."
       @root_dir = File.expand_path(@root_dir)
 
-      # Handles boolean options
+      # Handles basic options
 
       @email = @options[:email] || false
       @silent = @options[:silent] || false
@@ -188,6 +192,19 @@ class Torque
       @accept_from, @accept_to = date_settings.get_dates
       @custom_date_range = date_settings.custom_date_range?
 
+      # Determines the number of iterations to generate for, throwing an error if it is invalid
+
+      @iterations = @options[:iterations]
+
+      if @iterations
+        begin
+          @iterations = Integer(@iterations)
+          raise ArgumentError.new if @iterations <= 0
+        rescue ArgumentError
+          raise ArgumentError.new "Invalid number of iterations: #{@iterations}"
+        end
+      end
+
       # Sets the path to the main "release-notes.txt" file
       
       @current_notes_path = "#{output_dir}/release-notes.txt"
@@ -198,7 +215,7 @@ class Torque
 
       # Determines the path name to use for the record of the output file
       
-      record_pathname_settings = RecordPathnameSettings.new(@output_dir, @project, @custom, @fs)
+      record_pathname_settings = RecordPathnameSettings.new(@output_dir, @project, @custom, @iterations, @fs)
       @record_path = record_pathname_settings.get_path
 
     end

data/lib/torque/story.rb

@@ -63,6 +63,8 @@ class Torque
     end
     private :handle_nil
 
+    # TODO Add an 'owner' field
+
     ##
     # Parses the story's fields from its html hash
     def parse
@@ -100,6 +102,13 @@ class Torque
       self
     end
 
+    ##
+    # Sorts a list of stories so that the most recent come first
+    def self.sort_list(stories)
+      sorted = stories.sort { |s1, s2| -(s1.date_accepted <=> s2.date_accepted) }
+      sorted
+    end
+
     def to_s
       return "Story("+@name+", "+"#{@story_id}"+")"
     end

metadata

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