torque 0.3.1 → 0.4.0

data/lib/torque/iteration.rb

@@ -38,7 +38,7 @@ class Torque
     ##
     # @param iterations A list of iterations
     #
-    # Returns a list of iterations sorted from most to least recent
+    # @return 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

data/lib/torque/mailer.rb

@@ -28,11 +28,6 @@ class Torque
       end
     end
 
-    # ##
-    # # Returns true if the email and password combination is valid, else false
-    # def verify
-    # end
-
     # @param notes_string The release notes file in string form
     # @param subject_line The subject line to use in the email
     # @param address_list A comma-separated list of email addresses to which to send the notes

data/lib/torque/pivotal.rb

@@ -13,7 +13,7 @@ class Torque
     end
 
     ##
-    # Returns true if a connection to www.pivotaltracker.com exists, else false
+    # @return True if a connection to www.pivotaltracker.com exists, else false
     def self.connection?
       begin
         TCPSocket.new "www.pivotaltracker.com", 80
@@ -24,7 +24,7 @@ class Torque
     end
 
     ##
-    # Returns true if the token supplied is a valid token, else false
+    # @return True if the token supplied is a valid token, else false
     def check_token
       begin
         get_project_data
@@ -35,9 +35,9 @@ class Torque
     end
 
     ##
-    # Sends a request through the Pivotal Tracker API
+    # @return A string of html data from Pivotal Tracker with data on each of a user's projects
     #
-    # Returns a string of html data from Pivotal Tracker with data on each of a user's projects
+    # Sends a request through the Pivotal Tracker API
     def get_project_data
 
       host="pivotaltracker.com"
@@ -66,9 +66,9 @@ class Torque
     ##
     # @param project The ID of the Pivotal Tracker project from which to get data
     #
-    # Sends a request through the Pivotal Tracker API
+    # @return A string of html data from Pivotal Tracker with data on the stories for the given project
     #
-    # Returns a string of html data from Pivotal Tracker with data on the stories for the given project
+    # Sends a request through the Pivotal Tracker API
     def get_project_stories(project)
 
       # Polls story data from pivotal tracker
@@ -103,9 +103,9 @@ class Torque
     # @param project The ID of the Pivotal Tracker project from which to get data
     # @param number The number of project iterations to fetch
     #
-    # Sends a request throgh the Pivotal Tracker API
+    # @return A string of html data from Pivotal Tracker with data on finished iterations of a project
     #
-    # Returns a string of html data from Pivotal Tracker with data on finished iterations of a project
+    # Sends a request throgh the Pivotal Tracker API
     def get_project_iterations(project, number=1)
 
       # Polls story data from pivotal tracker

data/lib/torque/pivotal_html_parser.rb

@@ -38,7 +38,7 @@ class Torque
     ##
     # @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)
+    # @return 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)
@@ -51,7 +51,7 @@ class Torque
     ##
     # @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)
+    # @return 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)

data/lib/torque/project/project.rb

@@ -16,6 +16,10 @@ class Torque
     # The project name
     attr_reader :name
 
+    ##
+    # @param id The project's ID
+    # @param name The project's name
+    # @param current True if this is the current project, else false
     def initialize(id, name, current=false)
       @current = current
       @id = id

data/lib/torque/project/project_manager.rb

@@ -27,17 +27,16 @@ class Torque
 
     ##
     # @param token A Pivotal Tracker API token (default: Loads token from .torqueinfo.yaml)
+    # @return the project list
     #
     # Requests and processes the project list from the Pivotal Tracker API
-    #
-    # Returns the project list
     def load_project_list(token=nil)
       get_project_list(token)
       @project_list
     end
 
     ##
-    # Returns the project list if 'load_project_list' has been called, else returns nil
+    # @return The project list if 'load_project_list' has been called, else returns nil
     #
     # Does not do any processing
     def project_list
@@ -45,7 +44,7 @@ class Torque
     end
 
     ##
-    # Returns the current project if 'load_project_list' has been called and one exists, else returns nil
+    # @return The current project if 'load_project_list' has been called and one exists, else returns nil
     def current_project
       @project_list.nil? \
       ? nil
@@ -53,7 +52,7 @@ class Torque
     end
 
     ##
-    # Formats the project list as a printable string
+    # @return The project list formatted as a printable string
     #
     # Prepends an asterisk to the current project
     def format_project_list

data/lib/torque/record_pathname_settings.rb

@@ -20,7 +20,7 @@ class Torque
     end
 
     ##
-    # Returns the path to the record file, generating one if it does not exist
+    # @return The path to the record file, generating one if it does not exist
     def get_path
       generate_record_path if !@path
       @path

data/lib/torque/settings.rb

@@ -2,6 +2,7 @@ require 'date'
 require_relative 'date_settings'
 require_relative 'field_filter'
 require_relative 'file_system'
+require_relative 'format_string'
 require_relative 'record_pathname_settings'
 require_relative 'torque_info_parser'
 require_relative 'error/missing_project_error'
@@ -62,6 +63,10 @@ class Torque
     # True if field filters are being used for stories, else false
     attr_reader :filters_on
 
+    ##
+    # The FormatString object to use to generate notes
+    attr_reader :format_string
+
     ##
     # The number of iterations of the project to generate notes for, or nil if not using iterations
     attr_reader :iterations
@@ -141,11 +146,23 @@ class Torque
       
       @email_address = torque_info.email_address
       @email_password = torque_info.email_password
-      @email_to = torque_info.email_to
-      @output_dir = torque_info.output_dir
+      email_to_raw = torque_info.email_to
+      format_string_raw = torque_info.format
+      output_dir_raw = torque_info.output_dir
       @project = torque_info.project
       @token = torque_info.token
 
+      if    email_to_raw.class == NilClass; @email_to = []
+      elsif email_to_raw.class == String;   @email_to = [email_to_raw]
+      elsif email_to_raw.class == Array;    @email_to = email_to_raw
+      else; raise "Unknown parsing error on .torqueinfo.yaml's 'email_to' field: #{@email_to}"
+      end
+
+      @format_string = Torque::FormatString.new(format_string_raw)
+
+      output_dir_raw = "release_notes" if output_dir_raw.blank?
+      @output_dir = "#{@root_dir}/#{output_dir_raw}"
+
       raise MissingTokenError.new(
         "API token for Pivotal Tracker has not been set"
         ) if @token.blank?
@@ -153,15 +170,6 @@ class Torque
         "Project ID for Pivotal Tracker has not been set"
         ) if @project.blank?
 
-      @output_dir = "release_notes" if @output_dir.blank?
-      @output_dir = "#{@root_dir}/#{@output_dir}"
-
-      if    @email_to.class == NilClass; @email_to = []
-      elsif @email_to.class == String;   @email_to = [@email_to]
-      elsif @email_to.class == Array;    @email_to = @email_to
-      else; raise "Unknown parsing error on .torqueinfo.yaml's 'email_to' field: #{@email_to}"
-      end
-
       # Sets up the output directory, throwing an error if it cannot be found
 
       if !@fs.path_exist? @output_dir

data/lib/torque/story.rb

@@ -6,48 +6,48 @@ class Torque
 
     ##
     # The current state of the story (finished, accepted, etc)
-    attr_reader :current_state
+    attr_accessor :current_state
 
     ##
     # The date that the story was accepted, or nil if it has not been accepted yet
-    attr_reader :date_accepted
+    attr_accessor :date_accepted
 
     ##
     # The story description
-    attr_reader :description
+    attr_accessor :description
 
     ##
     # The estimate for the story
-    attr_reader :estimate
+    attr_accessor :estimate
+
+    ##
+    # The story's ID
+    attr_accessor :id
 
     ##
     # The labels for the story
-    attr_reader :labels
+    attr_accessor :labels
 
     ##
     # The name of the story
-    attr_reader :name
+    attr_accessor :name
 
     ##
     # The owner of the story
-    attr_reader :owner
+    attr_accessor :owner
 
     ##
     # The ID of the story's project
-    attr_reader :project_id
-
-    ##
-    # The story's ID
-    attr_reader :story_id
+    attr_accessor :project_id
 
     ##
     # The story's type (feature, chore, etc)
-    attr_reader :type
+    attr_accessor :type
 
     ##
     # @param html_hash A hash (of html elements keyed by their tags) generated from Pivotal Tracker story html
     #
-    # Returns a new story whose fields were parsed from the html_hash provided
+    # @return A new story whose fields were parsed from the html_hash provided
     def self.create(html_hash)
       Story.new(html_hash).parse
     end
@@ -67,25 +67,34 @@ class Torque
     end
     private :handle_nil
 
-    # TODO Add an 'owner' field
+    ##
+    # @return The url pointing to the story
+    def url
+      "https://www.pivotaltracker.com/story/show/#{id}"
+    end
 
     ##
     # Parses the story's fields from its html hash
+    #
+    # @return The story (self)
     def parse
       html_hash = @html_hash
 
       # Default values
+      
       @current_state = ""
-      @date_accepted = nil # Will be a date
+      @date_accepted = nil # [Date]
       @description = ""
       @estimate = -1
-      @labels = "" # Will be an array
+      @id = -1
+      @labels = "" # [Array]
       @name = ""
       @owner = ""
       @project_id = -1
-      @story_id = -1
       @type = ""
 
+      # Processes each field
+
       @current_state = handle_nil(@current_state, html_hash["current_state"])
       @description = handle_nil(@description, html_hash["description"])
       @name = handle_nil(@name, html_hash["name"])
@@ -94,7 +103,7 @@ class Torque
 
       @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"]))
+      @id = Integer(handle_nil(@id, html_hash["id"]))
 
       @labels = handle_nil(@labels, html_hash["labels"])
       @labels = @labels.split(",")
@@ -104,12 +113,14 @@ class Torque
         @date_accepted = Date.strptime(date_acceptedString, "%Y/%m/%d")
       end
 
-      # Returns the generated story
+      # Returns the parsed story
+
       self
     end
 
     ##
-    # Sorts a list of stories so that the most recent come first
+    # @param stories A list of stories
+    # @return The list of stories sorted from most to least recently accepted
     def self.sort_list(stories)
       sorted = stories.sort { |s1, s2| -(s1.date_accepted <=> s2.date_accepted) }
       sorted

data/lib/torque/torque_info_parser.rb

@@ -21,6 +21,10 @@ class Torque
     # The email_to field (String or Array)
     attr_reader :email_to
 
+    ##
+    # The format string to use for the project
+    attr_reader :format
+
     ##
     # The project field (Fixnum)
     attr_reader :project
@@ -45,9 +49,10 @@ class Torque
     end
 
     ##
+    # @return The TorqueInfoParser (self)
+    #
     # Parses the file, storing the results as public instnance fields
     # Stores each field with no corresponding value in the file as 'nil'
-    # Returns self
     def parse
 
       if !@fs.path_exist?(@file_path)
@@ -59,12 +64,13 @@ class Torque
       begin
         torque_info_hash = YAML::load(@fs.file_read(@file_path)) || {}
       rescue Psych::SyntaxError
-        # If cannot parse, ignore contents
+        # TODO Implement custom error, raise/rescue paths to catch this problem
       end
 
       @email_address = torque_info_hash["email_address"]
       @email_password = torque_info_hash["email_password"]
       @email_to = torque_info_hash["email_to"]
+      @format = torque_info_hash["format"]
       @project = torque_info_hash["project"]
       @output_dir = torque_info_hash["output_dir"]
       @token = torque_info_hash["token"]
@@ -73,7 +79,8 @@ class Torque
     end
 
     ##
-    # Sets the specified field to the specified value in the file on disk
+    # @param field The field to set
+    # @param value The value to set the field to 
     def set(field, value)
       file_string = @fs.file_read(@file_path)
       new_file_string = set_string(field, value, file_string)
@@ -81,7 +88,8 @@ class Torque
     end
 
     ##
-    # Adds a list of values to a sequence belonging to field on disk
+    # @param field The field to add to
+    # @param values A list of values to add to the field
     def add(field, values)
       file_string = @fs.file_read(@file_path)
       new_file_string = add_string(field, values, file_string)
@@ -89,8 +97,10 @@ class Torque
     end
 
     ##
-    # Adds a list of values to a sequence belonging to field, eliminating duplicates, on disk
-    # Returns a list of all values that were added (were not duplicates)
+    # @param field The field to add to
+    # @param values A list of values to add to the field
+    #
+    # @return A list of all values that were added (ie that were not duplicates)
     def add_no_duplicates(field, values)
       file_string = @fs.file_read(@file_path)
       values_copy = values.clone
@@ -101,8 +111,10 @@ class Torque
     end
 
     ##
-    # Removes a field to a sequence of values on disk
-    # Returns a list of the values that were removed (could be found)
+    # @param field The field to remove from
+    # @param values A list of values to remove from the field
+    #
+    # @return A list of the values that were removed (ie that could be found)
     def rm(field, values)
       file_string = @fs.file_read(@file_path)
       values_copy = values.clone

data/lib/torque/version.rb

@@ -15,7 +15,7 @@ class Torque
     STRING = [MAJOR, MINOR, PATCH].compact.join('.')
     
     ##
-    # The string representing the current version of Torque (eg "1.9.2") 
+    # @return A string representing the current version of Torque (eg "1.9.2") 
     def self.string
       STRING
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: torque
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Nico Adams, Scrimmage
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-08 00:00:00.000000000 Z
+date: 2013-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -92,6 +92,7 @@ extra_rdoc_files:
 files:
 - bin/config
 - bin/email
+- bin/format
 - bin/project
 - bin/torque
 - lib/torque/date_settings.rb
@@ -104,6 +105,7 @@ files:
 - lib/torque/error/pivotal_api_error.rb
 - lib/torque/field_filter.rb
 - lib/torque/file_system.rb
+- lib/torque/format_string.rb
 - lib/torque/iteration.rb
 - lib/torque/mailer.rb
 - lib/torque/pivotal.rb