torque 0.3.1 → 0.4.0

data/bin/project

@@ -51,7 +51,7 @@ begin
 rescue OptionParser::InvalidOption, OptionParser::MissingArgument
   puts $!.to_s
   puts option_parser
-  exit
+  exit 3
 end
 
 # Handles special cases and exceptions
@@ -67,7 +67,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 4
 end
 
 # Locates project identifiers
@@ -81,35 +81,25 @@ if options[:name]
   project_identifiers << options[:name]
 end
 
+project_manager = Torque::ProjectManager.new
+begin
+  project_manager.load_project_list    
+rescue Torque::MissingTorqueInfoFileError => e
+  puts "ABORTING"
+  puts e.message
+  puts "Run 'torque config' in this directory, or change your working directory"
+  exit 5
+end
+
 if project_identifiers.size == 0
-  
-  project_manager = Torque::ProjectManager.new
-  begin
-    project_manager.load_project_list    
-  rescue Torque::MissingTorqueInfoFileError => e
-    puts "ABORTING"
-    puts e.message
-    puts "Run 'torque config' in this directory, or change your working directory"
-    exit 2
-  end
 
   puts project_manager.format_project_list
 
 elsif project_identifiers.size == 1
 
-  # Throw error if cannot find a matching project
-  if !Pathname.new("./.torqueinfo.yaml").exist?
-    puts "Directory is not configured for torque (.torqueinfo.yaml file is missing). Run 'torque config' in this " \
-      + "directory, or change your working directory"
-    exit
-  end
-
   # Switch to a new project
   identifier = project_identifiers[0]
 
-  project_manager = Torque::ProjectManager.new
-  project_manager.load_project_list
-
   if is_name
     project = project_manager.project_list.select { |project| project.name == identifier }[0]
   else
@@ -124,7 +114,7 @@ elsif project_identifiers.size == 1
     end
     puts
     puts project_manager.format_project_list
-    exit
+    exit 6
   end
 
   Torque::TorqueInfoParser.new.set("project", project.id)
@@ -133,4 +123,5 @@ elsif project_identifiers.size == 1
 else
   # Too many project identifiers. Throw error
   puts "Only 1 project allowed, found #{project_identifiers.size}: #{project_identifiers.to_s}"
+  exit 3
 end

data/bin/torque

@@ -35,11 +35,14 @@ option_parser = OptionParser.new do |opts|
   opts.banner += "\nSpecial commands:"
   opts.banner += "\n    config    Configures a directory for use with Torque"
   opts.banner += "\n    email     Sets up user email, adds to/removes from Torque's mailing list"
+  opts.banner += "\n    format    Controls the format of the generated documents"
   opts.banner += "\n    project   Displays & switches between available Pivotal Tracker projects"
   opts.banner += "\n"
   opts.banner += "\nOptions:"
   opts.banner += "\n"
 
+  # TODO --dry and --less options
+
   opts.on("--email", "Email the compiled notes to the email list in .torqueinfo") do
     |arg|
     options[:email] = arg
@@ -107,6 +110,9 @@ if(ARGV[0]=="config")
 elsif(ARGV[0]=="email")
   exec("#{exec_dir}/email #{arg_string}")
 
+elsif(ARGV[0]=="format")
+  exec("#{exec_dir}/format #{arg_string}")
+
 elsif(ARGV[0]=="project")
   exec("#{exec_dir}/project #{arg_string}")
   
@@ -125,23 +131,22 @@ begin
   elsif !ARGV.empty?
     puts "Unknown arguments: #{ARGV.join(", ")}"
     puts option_parser.help
-    exit
+    exit 3
   
   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 += "-i/--iterations. "
     err_str += "Cannot use a custom date range with 'iterations' option"
     puts err_str
-#    puts option_parser.help
-    exit 1
+    exit 3
   end
 
 rescue OptionParser::InvalidOption, OptionParser::MissingArgument
   puts $!.to_s
   puts option_parser.help
-  exit
+  exit 3
 end
 
 # Checks for a connection to Pivotal Tracker
@@ -149,39 +154,40 @@ end
 if !Torque::Pivotal.connection?
   puts "ABORTING"
   puts "Cannot connect to www.pivotaltracker.com. A connection is required to use Torque"
-  exit 2
+  exit 4
 end
 
 # Runs Torque, handling errors
 
 begin
   Torque.new(options).execute
+rescue Torque::MissingTorqueInfoFileError => e
+  puts "ABORTING"
+  puts e.message
+  puts "Run 'torque config' in this directory, or change your working directory"
+  exit 5
+rescue Torque::MissingOutputDirectoryError => e
+  puts "ABORTING"
+  puts e.message
+  puts "Run 'torque config -o [directory]' to create/change your output directory"
+  exit 6
 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 3) : (exit 4)
+  (e.is_a? Torque::MissingTokenError) ? (exit 7) : (exit 8)
 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 5) : (exit 6)
+  (e.is_a? Torque::MissingProjectError) ? (exit 9) : (exit 10)
 rescue Torque::PivotalAPIError => e
   puts "ABORTING"
   puts e.message
-  exit 7
-rescue Torque::MissingTorqueInfoFileError => e
-  puts "ABORTING"
-  puts e.message
-  puts "Run 'torque config' in this directory, or change your working directory"
-  exit 8
-rescue Torque::MissingOutputDirectoryError => e
-  puts "ABORTING"
-  puts e.message
-  puts "Run 'torque config -o [directory]' to create/change your output directory"
-  exit 9
+  exit 11
+
 rescue ArgumentError => e
   puts "ABORTING"
   puts e.message
-  exit 10
-end
+  exit 12
+end

data/lib/torque.rb

@@ -17,8 +17,6 @@ class Torque
   # @param options A hash of the settings to use for
   # @param settings An instance of Torque::Settings (default: Torque::Settings.new)
   # @param settings An instance of Torque::FileSystem (default: Torque::FileSystem.new)
-  #
-  # Creates a new instance of Torque
   def initialize(options, settings=nil, fs=nil)
     @fs = fs || FileSystem.new
     @settings = settings || Settings.new(options, @fs)
@@ -29,10 +27,10 @@ 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
+  # @param iterations_on 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, iterations=false)
+  # @return A string comprising the release notes document
+  def generate_notes(project_html, project_name, iterations_on=false)
 
     notes_string = ""
 
@@ -41,12 +39,13 @@ class Torque
     notes_string += "Release Notes\n"
     notes_string += "Project #{@settings.project} - '#{project_name}'\n"
 
-    if @settings.iterations
+    if iterations_on
       # Past iterations header
       notes_string += "Last "
-      notes_string += @settings.iterations == 1 \
-                      ? notes_string += "iteration"
-                      : notes_string += "#{@settings.iterations} iterations"
+      notes_string += (@settings.iterations == 1 \
+                      ? "iteration"
+                      : "#{@settings.iterations} iterations"
+                      )
       notes_string += "\n"
 
     elsif @settings.custom_date_range
@@ -71,7 +70,7 @@ class Torque
     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
+    if iterations_on
       # Adds each iteration
       
       iteration_list = html_parser.process_project_iterations(project_html)
@@ -86,7 +85,10 @@ class Torque
 
         iteration.sort_stories
         iteration.stories.each do |story|
-          notes_string += generate_story_string(story)
+          notes_string += @settings.format_string.apply(story)
+          notes_string += "\n"
+          notes_string += "\n"
+
           print_if_verbose "[Torque] (#{story.date_accepted.strftime(@date_format)}) #{story.name}"
         end
       end
@@ -104,7 +106,10 @@ class Torque
 
       stories = Story.sort_list(stories)
       stories.each do |story|
-        notes_string += generate_story_string(story)
+        notes_string += @settings.format_string.apply(story)
+        notes_string += "\n"
+        notes_string += "\n"
+
         print_if_verbose "[Torque] (#{story.date_accepted.strftime(@date_format)}) #{story.name}"
       end
 
@@ -158,6 +163,8 @@ class Torque
   end
 
   ##
+  # @return The generated notes
+  #
   # The method run by Torque on the command line. Generates the notes, writes them to file, optionally emails them
   def execute
 
@@ -219,7 +226,7 @@ class Torque
 
     print_if_not_silent "Notes generated!"
 
-    # Emails the release notes to all specified addresses
+    # Emails the release notes to the mailing list 
     
     email_notes(notes_string, project_name) if(@settings.email)
 
@@ -228,27 +235,6 @@ 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/date_settings.rb

@@ -23,14 +23,14 @@ class Torque
     ##
     # Generates the accept_from and accept_to dates if they don't already exist
     #
-    # Returns [accept_from, accept_to]
+    # @return [accept_from, accept_to]
     def get_dates
       generate_dates if !@accept_from || !@accept_to
       return @accept_from, @accept_to
     end
 
     ##
-    # Returns true if the date range was set manually via command line, else false
+    # @return True if the date range was set manually via command line, else false
     def custom_date_range?
       generate_dates if !@custom_date_range
       return @custom_date_range

data/lib/torque/field_filter.rb

@@ -14,15 +14,11 @@ class Torque
 
     ##
     # @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
+    # @option field [Symbol] :label
+    # @option field [Symbol] :owner
+    # @option field [Symbol] :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".
+    # @param contents The contents of the field filter
     #
     # 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,
@@ -33,6 +29,9 @@ class Torque
     #
     # (ios AND android) OR (ios AND web)
     #
+    # 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".
+    #
     def initialize(field, contents="")
       @field = field
       @contents = contents
@@ -99,7 +98,7 @@ class Torque
     ##
     # Returns a string representation of the FieldFilter
     def to_s
-      "#{@field}: #{@contents}"
+      "#{@field} = #{@contents}"
     end
 
     

data/lib/torque/file_system.rb

@@ -9,15 +9,13 @@ class Torque
   # Supports:
   #
   # * File creation, reading, line-by-line iteration, and overwriting
-  #
   # * Directory creation
-  #
   # * Pathname checking
   #
   class FileSystem
 
     def initialize
-      # Do nothing. The file system's properties are automatically global
+      # Do nothing; the file system's properties are by definition global
     end
 
     ##
@@ -31,13 +29,13 @@ class Torque
     end
 
     ##
-    # Returns an iterator over each line of a file
+    # @return An iterator over each line of a file
     def file_each_line(filename)
       File.open(filename, "r").each_line
     end
 
     ##
-    # Returns the contents of a file
+    # @return The contents of a file
     def file_read(filename)
       File.read(filename)
     end
@@ -61,7 +59,9 @@ class Torque
     end
 
     ##
-    # Returns true if a pathname exists, else false
+    # @param pathname The pathname to test
+    #
+    # @return True if the pathname exists, else false
     def path_exist?(pathname)
       Pathname.new(pathname).exist?
     end

data/lib/torque/format_string.rb

@@ -0,0 +1,107 @@
+require 'date'
+
+class Torque
+    
+  ##
+  # Applies a format string to stories, generating custom string output for each story
+  #
+  # Parameters:
+  # * %a => Date accepted (MM/DD)
+  # * %A => Date accepted (YYYY/MM/DD)
+  # * %d => Description
+  # * %D => Description (tabbed once on each newline)
+  # * %e => Estimate
+  # * %i => ID
+  # * %l => Labels (separated by ", ")
+  # * %n => Newline character
+  # * %N => Name
+  # * %o => Owner of the story
+  # * %p => ID of the story's project
+  # * %u => URL pointing to the story
+  # * %t => Tab character
+  # * %T => Type (feature, bug, etc)
+  class FormatString
+
+    ##
+    # @param format_string The format string to use
+    def initialize(format_string)
+      @format_string = format_string
+    end
+
+    ##
+    # Returns the deafault format string to use
+    def self.default
+      "%i%n%N%nAccepted on %A%n%u%n%D"
+    end
+
+    ##
+    # @param story A Torque::Story object
+    #
+    # @return A string representing the story formatted according to the format string
+    def apply(story)
+
+      story_string = @format_string.clone
+
+      # %a
+      a = (story.date_accepted ? story.date_accepted.strftime("%m/%d") : "")
+      story_string.gsub!("%a", "#{a}")
+
+      # %A
+      aa = (story.date_accepted ? story.date_accepted.strftime("%Y/%m/%d") : "")
+      story_string.gsub!("%A", "#{aa}")
+
+      # %d
+      d = story.description
+      story_string.gsub!("%d", "#{d}")
+
+      # %D
+      dd = ""
+      story.description.each_line {|line| dd += "\t#{line}"} if story.description
+      story_string.gsub!("%D", "#{dd}")
+
+      # %e
+      e = story.estimate
+      story_string.gsub!("%e", "#{e}")
+
+      # %i
+      i = story.id
+      story_string.gsub!("%i", "#{i}")
+
+      # %l
+      l = (story.labels ? story.labels.join(", ") : "")
+      story_string.gsub!("%l", "#{l}")
+
+      # %n
+      n = "\n"
+      story_string.gsub!("%n", "#{n}")
+
+      # %N
+      nn = story.name
+      story_string.gsub!("%N", "#{nn}")
+
+      # %o
+      o = story.owner
+      story_string.gsub!("%o", "#{o}")
+
+      # %p
+      p = story.project_id
+      story_string.gsub!("%p", "#{p}")
+
+      # %t
+      t = "\t"
+      story_string.gsub!("%t", "#{t}")
+
+      # %T
+      tt = story.type
+      story_string.gsub!("%T", "#{tt}")
+
+      # %u
+      u = story.url
+      story_string.gsub!("%u", "#{u}")
+
+      story_string
+    end
+
+  end
+
+end