torque 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4bbf96a5e564ef44f742123c47a9509abe4c18ea
-  data.tar.gz: e20c283836eee7bf65a5b3bac666a40e389ecd96
+  metadata.gz: 4b758a1a40b981493fc10c574974eddb9d65aa6c
+  data.tar.gz: 9e937f2bbeb8e3af7b6b1939d61014c8b5f96d29
 SHA512:
-  metadata.gz: df9a49f19e231ba96215dbfc1082e790502c82c0d7e3fd06410f1ca8f96e0f568c6c76e64a79fe9cbe96081715a5dbb332303033f394cfe3177756eda6cb1236
-  data.tar.gz: 490ca79fbe959b5f6232bf9a9825c791213ac1f51c60a72bcb69f779fd1d4644f50d054b16c97eec314e20765f71b3a951cf0c5f6d25bedb57145fae3fe3945e
+  metadata.gz: 74e771fe69f47007a1badc7cd1b33e24dc1f077ef1025a433549abe4e8f42ab6b1876196d1f8fcfd0380138fbbb06b6f30b29a40730f6ba57e8ab3d4731860db
+  data.tar.gz: 16205617e5a71c342f41611cb74b103ff966111970098c59f7121ba29d6ce1448fa11503f6b82be0f3260e201f99660bd40ba8c9fafc2525a69860084d2ccbc2

data/README.md

@@ -91,17 +91,22 @@ To filter your results by story label, owner or type:
     # torque --owner "list + of , owners"
     # torque --type "list, of + story types"
 
-When using filters, "," is used to signify OR, "+" is used to signify AND, and "+" has a higher precedence than ",". For example, "ios + android, ios + web" becomes
+When using filters:
+* "," => OR
+* "+" => AND
+* "+" is evaluated before ","
+
+For example, "ios + android, ios + web" becomes
 
     ("ios" AND "android") OR ("ios" AND "web")
 
-Additionally, the "owner" filter will try to match against first/middle/last names as well as full names. For instance, '--owner Lee' will match stories owned by "Lee Grant", "Jake Lee", or "Kate Lee Swanson".
+The "owner" filter will try to match against first/middle/last names as well as full names. For instance, '--owner Lee' will match stories owned by (eg) "Lee Grant", "Jake Lee", or "John Lee Jones".
 
 To email the release notes from a personal email to Torque's mailing list:
 
     # torque --email
 
-Running with the 'verbose' option will print a running list of stories as they are added. Running with the 'silent' option will silence all output.
+Running with '-v/--verbose' will print a running list of stories as they are added. Running with '-s/--silent' will silence all output.
 
 To display all available Pivotal Tracker projects or change your current project:
 
@@ -111,6 +116,77 @@ To set up automatic emailing of the notes and add/remove from the mailing list:
 
     # torque email
 
+To view/change the format of the notes that Torque generates:
+
+    # torque format
+
+Formatting
+----------
+
+By default, stories are formatted like this:
+
+    12345678
+    Story Name
+    Accepted on 2012/12/21
+    https://www.pivotaltracker.com/story/show/12345678
+        Short description of story goes here
+        - This is a side note
+        - This is another side note
+
+To change the way that stories are formatted, use 'torque format -s/--set'. Alternately, use 'torque format -e/--example' to see some sample output from a new format.
+
+The format is set by way of a "formatting string", a mix of plain text and parameters (eg "%a") that act as placeholders for elements of a 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)
+
+Exit Codes
+----------
+
+The following is a list of exit codes that are thrown on various errors for each of the Torque scripts.
+
+(general)
+3   Invalid arguments
+4   Cannot connect to Pivotal Tracker API
+
+torque
+5   Missing torque info file
+6   Missing output directory
+7   Missing token
+8   Invalid token
+9   Missing project
+10  Invalid project
+11  Misc. Pivotal Tracker API request error
+12  Misc argument error
+
+torque config
+5   Pre-existing output directory
+6   Pre-existing torque info file
+7   Invalid output directory
+
+torque email
+5   Missing torque info file
+
+torque format
+5   Missing torque info file
+
+torque project
+5   Missing torque info file
+6   Project not found
+
 License
 -------
 

data/VERSION

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

data/bin/config

@@ -11,6 +11,7 @@ require 'highline/import'
 require 'net/http'
 require 'optparse'
 require 'pathname'
+require "#{lib_dir}/torque/format_string"
 require "#{lib_dir}/torque/pivotal"
 require "#{lib_dir}/torque/torque_info_parser"
 require "#{lib_dir}/torque/project/project"
@@ -62,7 +63,7 @@ begin
 rescue OptionParser::InvalidOption, OptionParser::MissingArgument
   puts $!.to_s
   puts option_parser
-  exit
+  exit 3
 end
 
 # Handles special cases and exceptions
@@ -74,7 +75,7 @@ if ((ARGV.member? "help") || options[:help])
 elsif !ARGV.empty?
   puts "Unknown arguments: #{ARGV.join(", ")}"
   puts option_parser.help
-  exit
+  exit 3
 end
 
 # Checks for a connection to Pivotal Tracker
@@ -82,7 +83,7 @@ end
 if !Torque::Pivotal.connection?
   puts "ABORTING"
   puts "Cannot connect to www.pivotaltracker.com. A connection is required to configure Torque"
-  exit 1
+  exit 4
 end
 
 # Configures the directory
@@ -102,7 +103,7 @@ if !options[:token]
     puts "The default output directory, #{default_output_dir}, already exists."
     puts "(Use -o to manually choose an existing output directory or create a new one)"
     puts "(Use -f to overwrite an existing directory)"
-    exit
+    exit 5
   end
   
 
@@ -113,7 +114,7 @@ if !options[:token]
     puts "A .torqueinfo.yaml file already exists in this directory."
     puts "(Use -o to ignore this file and change only the output directory)"
     puts "(Use -f to overwrite this file)"
-    exit
+    exit 6
   end
   
 
@@ -132,7 +133,13 @@ if !options[:token]
     puts "- Creating directory #{output_dir}"
   end
 
-  FileUtils.mkdir_p("#{output_dir}/previous")
+  begin
+    FileUtils.mkdir_p("#{output_dir}/previous")
+  rescue Errno::EACCES => e
+    puts "ABORTING"
+    puts "Cannot use output directory \"#{output_dir}\""
+    exit 7
+  end
 
   if options[:force] && torque_info_path.exist?
     puts "- Overwriting file .torqueinfo.yaml"
@@ -157,7 +164,7 @@ end
 
 # Determines whether to set up a new API token and project ID
 
-should_setup_info = true
+should_setup_torque_info = true
 if retained_torque_info_file
   valid = /^\s*(y|Y|n|N)\s*$/
   setup_info_prompt = ask("Existing Torque info file found. Would you like to set up a new API token? [y/n]") {
@@ -165,11 +172,11 @@ if retained_torque_info_file
     q.validate = valid
   }
   setup_info_prompt.strip!
-  should_setup_info = (setup_info_prompt =~ /y|Y/)
+  should_setup_torque_info = (setup_info_prompt =~ /y|Y/)
 end
 
 
-if should_setup_info
+if should_setup_torque_info
 
   # Adds the API token to the torque info file
 
@@ -247,12 +254,16 @@ if should_setup_info
   end
 end
 
-# Finishes
 
+# Sets the default format string
+
+Torque::TorqueInfoParser.new.set("format", Torque::FormatString.default)
+
+# Finishes
 
 puts 
 puts "Configuration complete!"
-if !options[:token] && !(options[:output_dir] && !should_setup_info)
+unless options[:token] || (options[:output_dir] && !should_setup_torque_info)
   puts "WARNING: Do not check .torqueinfo.yaml into your version control system! (Contains sensitive information)"
-end
-puts
+  puts
+end

data/bin/email

@@ -10,8 +10,8 @@ working_dir = "."
 require 'highline/import'
 require 'mail'
 require 'optparse'
-require "#{lib_dir}/torque/torque_info_parser"
 require "#{lib_dir}/torque/pivotal"
+require "#{lib_dir}/torque/torque_info_parser"
 
 # Parses the options
 options = {}
@@ -60,7 +60,7 @@ begin
 rescue OptionParser::InvalidOption, OptionParser::MissingArgument
   puts $!.to_s
   puts option_parser
-  exit
+  exit 3
 end
 
 # Handles special cases and exceptions
@@ -72,15 +72,7 @@ if ((ARGV.member? "help") || options[:help])
 elsif !ARGV.empty?
   puts "Unknown arguments: #{ARGV.join(", ")}"
   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
+  exit 3
 end
 
 # Parses the torque info file
@@ -92,7 +84,7 @@ rescue Torque::MissingTorqueInfoFileError => e
   puts "ABORTING"
   puts e.message
   puts "Run 'torque config' in this directory, or change your working directory"
-  exit 2
+  exit 5
 end
 
 # Util method to display the current email settings
@@ -137,12 +129,6 @@ if options[:setup]
   
 end
 
-# Validates all emails to be added
-
-options[:add].each do |email|
-
-end
-
 # Adds and removes emails from the email list
 
 unless (options[:add].empty? && options[:rm].empty?)
@@ -169,9 +155,13 @@ unless (options[:add].empty? && options[:rm].empty?)
 
 end
 
-# Finishes
+# Displays the current email settings
+
+options_empty = options.size == 2 && options[:add].empty? && options[:rm].empty?
 
 torque_info.parse
+puts "(When torque is run with the '--email' option, these addresses will receive a copy of the notes)" \
+  if options_empty
 puts
 disp_email(torque_info)
-puts
+puts

data/bin/format

@@ -0,0 +1,170 @@
+#!/usr/bin/env ruby
+
+# Controls the format of the release notes that Torque generates.
+# Prompts for/sets the format string, and/or prints an example of the current format settings 
+
+lib_dir = File.expand_path("../lib", File.dirname(__FILE__))
+template_dir = File.expand_path("../template", File.dirname(__FILE__))
+working_dir = "."
+
+require 'highline/import'
+require 'optparse'
+require "#{lib_dir}/torque/format_string"
+require "#{lib_dir}/torque/story"
+require "#{lib_dir}/torque/torque_info_parser"
+require "#{lib_dir}/torque/error/missing_torque_info_file_error"
+
+# Parses the options
+options = {}
+option_parser = OptionParser.new do |opts|
+
+  help_message = "Sets the format string that Torque uses to generate release notes, or prints the current format " \
+                  "string settings if run with no arguments"
+  help_message += "\nThe format string consists of plain text as well as a series of parameters (eg. \"%a\") that " \
+                  "act as placeholders for elements of a story"
+  help_message += "\n"
+  help_message += "\nA format string of \"default\" will return the format string to its default value " \
+                  "(\"#{Torque::FormatString.default}\")"
+  help_message += "\n"
+  help_message += "\n"
+  help_message +=
+<<-END_STR
+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)
+END_STR
+
+  opts.banner  = "\nUsage:"
+  opts.banner += "\n    torque format [options]"
+  opts.banner += "\n"
+  opts.banner += "\n#{help_message}"
+  opts.banner += "\n"
+
+  opts.on("-e", "--example", "Optionally sets your format string after printing an example story") do
+    |arg|
+    options[:example] = arg
+  end
+
+  opts.on("-h", "--help", "Displays this help screen") do
+    |arg|
+    options[:help] = arg
+  end
+
+  opts.on("-s", "--set", "Sets your format string") do
+    |arg|
+    options[:set] = arg
+  end
+
+end
+
+# Parses options and handles exceptions
+
+begin
+  option_parser.parse!
+
+rescue OptionParser::InvalidOption, OptionParser::MissingArgument
+  puts $!.to_s
+  puts option_parser
+  exit 3
+end
+
+# Handles special cases and exceptions
+
+if ((ARGV.member? "help") || options[:help])
+  puts "(Ran with 'help' option; other options ignored)"
+  puts option_parser
+  exit
+elsif !ARGV.empty?
+  puts "Unknown arguments: #{ARGV.join(", ")}"
+  puts option_parser.help
+  exit 3
+elsif (options.has_key? :example) && (options.has_key? :set)
+  puts "Conflicting options: -e/--example and -s/--set. Choose either 'example' or 'set'."
+  exit 3
+end
+
+# An example story for display purposes
+
+sample_story = Torque::Story.new({})
+
+sample_story.current_state = "accepted"
+sample_story.date_accepted = Date.new(2012, 12, 21)
+sample_story.description = "Short description of story goes here\n- This is a side note\n- This is another side note"
+sample_story.estimate = 3
+sample_story.id = 12345678
+sample_story.labels = ["label-1", "label-2"]
+sample_story.name = "Story Name"
+sample_story.owner = "Owner Smith"
+sample_story.project_id = 123456
+sample_story.type = "feature"
+
+# Instantiates a TorqueInfoParser
+
+begin
+  torque_info = Torque::TorqueInfoParser.new.parse
+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 run with -e/--example or -s/--setup: Takes in a string, optionally verifies format settings, sets format string
+
+if options[:example] || options[:set]
+
+  default    = false # True if the default format string should be used
+  should_set = true  # True if the format string should be changed on file
+
+  format = (ask("Enter a format string below:") {|q| q.readline = true}).to_s
+  
+  if format == 'default'
+    default = true
+    format = Torque::FormatString.default
+  end
+
+  # If -e/--example, prints and validates the new settings 
+
+  if options[:example]
+    puts "---"
+    puts Torque::FormatString.new(format).apply(sample_story)
+    puts "---"
+
+    valid = /^\s*(y|Y|n|N)\s*$/
+    should_set_prompt = ask("Would you like to set this as your format? [y/n]") {
+      |q|
+      q.validate = valid
+    }
+    should_set_prompt.strip!
+    should_set = (should_set_prompt =~ /y|Y/)
+  end
+
+  if should_set
+    torque_info.set("format", format)
+    
+    to_print = "Set format string to "
+    to_print += (default ? "default" : "\"#{format}\"")
+    puts to_print
+  end
+
+# If run with no arguments, displays the current format settings
+
+else
+  puts 
+  puts "Current format string: \"#{torque_info.format}\""
+  puts "---"
+  puts Torque::FormatString.new(torque_info.format).apply(sample_story)
+  puts "---"
+end