torque 0.0.1

data/bin/project

@@ -0,0 +1,136 @@
+#!/usr/bin/env ruby
+
+# Manages user projects for Torque. Displays the list of Pivotal Tracker projects that can be accessed by a given
+# token, or automatically changes the project when given a project name or ID
+
+lib_dir = File.expand_path("../lib", File.dirname(__FILE__))
+working_dir = '.'
+
+require 'optparse'
+require 'pathname'
+require_relative "#{lib_dir}/torque/pivotal"
+require_relative "#{lib_dir}/torque/torque_info_parser"
+require_relative "#{lib_dir}/torque/error/missing_torque_info_file_error"
+require_relative "#{lib_dir}/torque/project/project"
+require_relative "#{lib_dir}/torque/project/project_manager"
+
+
+# Handles arguments
+
+options = {}
+option_parser = OptionParser.new do |opts|
+
+  help_message = "Changes the current Pivotal Tracker project to the one specified, or lists the projects available " \
+    "with the current API token when run with no arguments"
+
+  opts.banner  = "\nUsage:"
+  opts.banner += "\n    torque project [ID]"
+  opts.banner += "\n    torque project [-n/--name NAME]"
+  opts.banner += "\n"
+  opts.banner += "\n#{help_message}"
+  opts.banner += "\n"
+  opts.banner += "\n"
+
+  opts.on("-h", "--help", "Displays this help screen") do
+    |arg|
+    options[:help] = arg
+  end
+
+  opts.on("-n", "--name NAME", "Switches the Torque project to the project named NAME") do
+    |arg|
+    options[:name] = arg
+  end
+
+end
+
+# Handles invalid parsing errors
+
+begin
+  option_parser.parse!
+
+rescue OptionParser::InvalidOption, OptionParser::MissingArgument
+  puts $!.to_s
+  puts option_parser
+  exit
+end
+
+# Handles special cases and exceptions
+
+if (ARGV.member? "help") || options[:help]
+  puts "(Ran with 'help' option; other options ignored)"
+  puts option_parser
+  exit
+end
+
+# Checks for a connection to Pivotal Tracker
+
+if !Torque::Pivotal.connection?
+  puts "ABORTING"
+  puts "Cannot connect to www.pivotaltracker.com. A connection is required to use Torque"
+  exit 1
+end
+
+# Locates project identifiers
+
+project_identifiers = ARGV
+
+is_name = false
+
+if options[:name]
+  is_name = true
+  project_identifiers << options[:name]
+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
+    project = project_manager.project_list.select { |project| project.id == identifier }[0]
+  end
+
+  if project.nil?
+    if is_name
+      puts "No project named #{identifier}"
+    else
+      puts "No project with id #{identifier}"
+    end
+    puts
+    puts project_manager.format_project_list
+    exit
+  end
+
+  Torque::TorqueInfoParser.new.set("project", project.id)
+  puts "Switched to project #{project.id} - '#{project.name}'"
+
+else
+  # Too many project identifiers. Throw error
+  puts "Only 1 project allowed, found #{project_identifiers.size}: #{project_identifiers.to_s}"
+end

data/bin/torque

@@ -0,0 +1,150 @@
+#!/usr/bin/env ruby
+
+lib_dir = File.expand_path("../lib", File.dirname(__FILE__))
+exec_dir = File.expand_path(File.dirname(__FILE__))
+
+require 'net/http'
+require 'optparse'
+require "#{lib_dir}/torque"
+require "#{lib_dir}/torque/pivotal"
+require "#{lib_dir}/torque/error/invalid_project_error"
+require "#{lib_dir}/torque/error/invalid_token_error"
+require "#{lib_dir}/torque/error/missing_project_error"
+require "#{lib_dir}/torque/error/missing_token_error"
+require "#{lib_dir}/torque/error/pivotal_api_error"
+
+
+# Parses the options
+
+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"
+
+  opts.banner  = "\nUsage:"
+  opts.banner += "\n    torque [options]"
+  opts.banner += "\n"
+  opts.banner += "\n#{help_message}"
+  opts.banner += "\n"
+  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    project   Displays & switches between available Pivotal Tracker projects"
+  opts.banner += "\n"
+  opts.banner += "\nOptions:"
+  opts.banner += "\n"
+
+  opts.on("--email", "Email the compiled notes to the email list in .torqueinfo") do
+    |arg|
+    options[:email] = arg
+  end
+
+  opts.on("-f,", "--from FROM_DATE", "Set the date (inclusive) from which to accept Pivotal stories") do
+    |arg|
+    options[:accept_from] = arg
+  end
+
+  opts.on("-h", "--help", "Displays this help screen") do
+    |arg|
+    options[:help] = arg
+  end
+
+  opts.on("--root ROOT_DIR", "Set the root directory for the script (should contain a .torqueinfo.yaml file)") do
+    |arg|
+    options[:root_dir] = arg
+  end
+
+  opts.on("-s", "--silent", "Run silently (no output) (overrides -v)") do
+    |arg|
+    options[:silent] = arg
+  end
+
+  opts.on("-t,", "--to TO_DATE", "Set the date (inclusive) until which to accept Pivotal stories") do
+    |arg|
+    options[:accept_to] = arg
+  end
+
+  opts.on("-v", "--verbose", "Run verbosely") do
+    |arg|
+    options[:verbose] = arg
+  end
+end
+
+
+# Handles special commands
+
+arg_string = (ARGV.length <= 1 ? "" : ARGV[1..ARGV.length].join(" "))
+
+if(ARGV[0]=="config")
+  exec("#{exec_dir}/config #{arg_string}")
+
+elsif(ARGV[0]=="email")
+  exec("#{exec_dir}/email #{arg_string}")
+
+elsif(ARGV[0]=="project")
+  exec("#{exec_dir}/project #{arg_string}")
+  
+end
+
+# Handles special cases and exceptions
+
+begin
+  option_parser.parse!
+
+  if (ARGV.member? "help") || options[:help]
+    puts "(Ran with 'help' option; other options ignored)"
+    puts option_parser.help
+    exit
+  
+  elsif !ARGV.empty?
+    puts "Unknown arguments: #{ARGV.join(", ")}"
+    puts option_parser.help
+    exit
+  end
+
+rescue OptionParser::InvalidOption, OptionParser::MissingArgument
+  puts $!.to_s
+  puts option_parser.help
+  exit
+end
+
+# Checks for a connection to Pivotal Tracker
+
+if !Torque::Pivotal.connection?
+  puts "ABORTING"
+  puts "Cannot connect to www.pivotaltracker.com. A connection is required to use Torque"
+  exit 1
+end
+
+# Runs Torque, handling errors
+
+begin
+  Torque.new(options).execute
+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)
+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)
+rescue Torque::PivotalAPIError => e
+  puts "ABORTING"
+  puts e.message
+  exit 6
+rescue Torque::MissingTorqueInfoFileError => e
+  puts "ABORTING"
+  puts e.message
+  puts "Run 'torque config' in this directory, or change your working directory"
+  exit 7
+rescue Torque::MissingOutputDirectoryError => e
+  puts "ABORTING"
+  puts e.message
+  puts "Run 'torque config -o [directory]' to create/change your output directory"
+  exit 8
+end

data/lib/torque.rb

@@ -0,0 +1,190 @@
+require 'date'
+require 'pathname'
+require_relative 'torque/pivotal'
+require_relative 'torque/pivotal_html_parser'
+require_relative 'torque/mailer'
+require_relative 'torque/settings'
+require_relative 'torque/torque_info_parser'
+require_relative 'torque/project/project'
+require_relative 'torque/project/project_manager'
+
+##
+# The central class for Torque. Takes in a hash of options, generates release notes from online data, writes them to
+# file and emails them
+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)
+
+    @date_format = "%Y/%m/%d"
+  end
+
+  ##
+  # @param project_html An html string containing all the project's stories
+  # @param project_name The name of the current project
+  #
+  # Returns a string comprising the release notes document
+  def generate_notes(project_html, project_name)
+
+    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.custom_date_range
+      notes_string += "(custom "+@settings.accept_from.strftime(@date_format)+" - "+@settings.accept_to.strftime(@date_format)+")\n"
+    else
+      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 += "\n"
+
+    # Adds each story
+    stories.sort! { |s1, s2| -(s1.date_accepted <=> s2.date_accepted) }
+    stories.length.times do |i|
+      story = stories[i]
+      
+      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"
+
+      print_if_verbose "[Torque] (#{story.date_accepted.strftime(@date_format)}) #{story.name}"
+
+      descArray = story.description.split("\n")
+      descArray.length.times do |i|
+        notes_string += "\t"+descArray[i]+"\n"
+      end
+      
+      notes_string += "\n"
+
+    end
+
+    print_if_verbose "[Torque]"
+    print_if_verbose "[Torque] Added #{stories.length} stories"
+
+    notes_string
+  end
+
+  ##
+  # @param notes_string A string representation of the generated release notes
+  # @param project_name The name of the current project
+  # @param mailer An instance of Torque::Mailer (default: Torque::Mailer.new(@settings.email_address, @settings.email_password) )
+  #
+  # Emails notes_string to the email list specified in the torque info file
+  def email_notes(notes_string, project_name, mailer=nil)
+    print_if_not_silent "Emailing notes..."
+
+    mailer ||= Mailer.new(@settings.email_address, @settings.email_password)
+
+    if @settings.email_address.blank?
+      print_if_not_silent "Emailing notes failed: No sender email address found. (Set this with 'torque email')"
+    elsif @settings.email_password.blank?
+      print_if_not_silent "Emailing notes failed: No sender email password found. (Set this with 'torque email')"
+    elsif(@settings.email_to.length == 0)
+      print_if_not_silent "No email addresses found. (Add them with 'torque email')"
+    else
+    
+      address_list = ""
+      @settings.email_to.each_with_index {
+        |address, i|
+
+        if i!=0
+          address_list << ", "
+        end
+        address_list << address
+      }
+
+      subject_line = \
+        "Release Notes: Project #{@settings.project} - '#{project_name}' (" \
+        + (@settings.custom_date_range ? "Custom " : "") \
+        + "#{@settings.accept_from.strftime('%Y/%m/%d')} - " \
+        + "#{@settings.accept_to.strftime('%Y/%m/%d')}" \
+        + ")"
+
+      mailer.send_notes(notes_string, subject_line, address_list)
+
+      print_if_not_silent "Emailed notes to #{address_list}"
+    end
+  end
+
+  ##
+  # The method run by Torque on the command line. Generates the notes, writes them to file, optionally emails them
+  def execute
+
+    # Determines the current project
+
+    torque_info = TorqueInfoParser.new(@settings.torque_info_path)
+    project_manager = ProjectManager.new(torque_info)
+    
+    project_manager.load_project_list
+    project_name = project_manager.current_project.name
+
+    # Generates the notes
+
+    print_if_not_silent "Current project: #{@settings.project} - '#{project_name}'"
+
+    print_if_not_silent "Generating release notes: " \
+      + (@settings.custom_date_range ? "Custom " : "") \
+      + @settings.accept_from.strftime(@date_format) + " - " \
+      + @settings.accept_to.strftime(@date_format) \
+      + "..."
+
+    project_html = Pivotal.new(@settings.token).get_project_stories(@settings.project)
+    notes_string = generate_notes(project_html, project_name)
+
+    # Writes the notes to file
+
+    root_dir_path = Pathname.new(@settings.root_dir)
+    rel_notes_path = Pathname.new(@settings.current_notes_path).relative_path_from(root_dir_path)
+    print_if_not_silent "- Writing notes > #{rel_notes_path}"
+
+    @fs.file_write("#{@settings.current_notes_path}", notes_string)
+
+    # Creates a record of the notes file
+
+    rel_record_path = Pathname.new(@settings.record_path).relative_path_from(root_dir_path)
+    print_if_not_silent "- Copying notes > #{rel_record_path}"
+
+    begin
+      @fs.file_write("#{@settings.record_path}", notes_string)
+    rescue => e
+      err_str = "WARNING: Unable to make a record of the release notes file. Could not locate records "
+      err_str += "directory \"#{File.expand_path(@settings.record_path)}\""
+      print_if_not_silent err_str
+    end
+
+    print_if_not_silent "Notes generated!"
+
+    # Emails the release notes to all specified addresses
+    
+    email_notes(notes_string, project_name) if(@settings.email)
+
+  end
+
+
+  private
+
+  # Prints a message if silent is not on
+  def print_if_not_silent(msg)
+    puts msg unless @settings.silent
+  end
+
+  # Prints a message if verbose is on and silent is not
+  def print_if_verbose(msg)
+    print_if_not_silent msg if @settings.verbose
+  end
+
+end