right_support 2.7.0 → 2.8.0

data/lib/right_support/stats/helpers.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2009-2012 RightScale Inc
+# Copyright (c) 2009-2013 RightScale Inc
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -44,22 +44,18 @@ module RightSupport
     # Convert 0 value to nil
     # This is in support of displaying "none" rather than 0
     #
-    # === Parameters
-    # value(Integer|Float):: Value to be converted
+    # @param value [Integer, Float] Value to be converted
     #
-    # === Returns
-    # (Integer|Float|nil):: nil if value is 0, otherwise the original value
+    # @return [Integer, Float, NilClass] nil if value is 0, otherwise the original value
     def self.nil_if_zero(value)
       value == 0 ? nil : value
     end
 
     # Convert values hash into percentages
     #
-    # === Parameters
-    # values(Hash):: Values to be converted whose sum is the total for calculating percentages
+    # @param values [Hash] Values to be converted whose sum is the total for calculating percentages
     #
-    # === Return
-    # (Hash):: Converted values with keys "total" and "percent" with latter being a hash with values as percentages
+    # @return [Hash] Converted values with keys "total" and "percent" with latter being a hash with values as percentages
     def self.percentage(values)
       total = 0
       values.each_value { |v| total += v }
@@ -70,11 +66,9 @@ module RightSupport
 
     # Convert elapsed time in seconds to displayable format
     #
-    # === Parameters
-    # time(Integer|Float):: Elapsed time
+    # @param time [Integer, Float] Elapsed time
     #
-    # === Return
-    # (String):: Display string
+    # @return [String] Display string
     def self.elapsed(time)
       time = time.to_i
       if time <= MINUTE
@@ -100,11 +94,9 @@ module RightSupport
     # string of that precision after applying rounding
     # When precision is wide ranging, limit precision of the larger numbers
     #
-    # === Parameters
-    # value(Float|Array|Hash):: Value(s) to be converted
+    # @param value [Float, Array, Hash] Value(s) to be converted
     #
-    # === Return
-    # (String|Array|Hash):: Value(s) converted to decimal digit string
+    # @return [String, Array, Hash] Value(s) converted to decimal digit string
     def self.enough_precision(value)
       scale = [1.0, 10.0, 100.0, 1000.0, 10000.0, 100000.0, 1000000.0]
       enough = lambda { |v| v = v.abs
@@ -133,60 +125,55 @@ module RightSupport
     end
 
     # Wrap string by breaking it into lines at the specified separators
+    # Convert all whitespace sequences to single space before wrapping
     # Allow for presence of color encoding when measuring string length
     #
-    # === Parameters
-    # string(String):: String to be wrapped
-    # max_length(Integer|Array):: Maximum length of a line, or array containing
+    # @param string [String] String to be wrapped
+    # @param max_length [Integer, Array] Maximum length of a line, or array containing
     #   maximum length of first line followed by maximum for any subsequent line
     #   including indent
-    # indent(String):: Indentation for each line after first
-    # separators(Regexp):: Separators where string can wrap
+    # @param indent [String] Indentation for each line after first
+    # @param separators [Regexp] Separators where string can wrap
     #
-    # === Return
-    # (String|Array):: Multi-line string
+    # @return [String, Array] Multi-line string
     def self.wrap(string, max_length, indent, separators)
       # Strip color encoding from string
-      strip = lambda { |string| string.gsub(/\e\[[0-9]*m/, "") }
+      strip = lambda { |str| str.gsub(/\e\[[0-9]*m/, "") }
 
-      # Split string at specified separators and return an array of arrays
-      # containing string segments and associated separator
-      split = lambda do |string, separators|
-        head, sep, tail = string.partition(separators)
-        if tail == ""
-          [[head, sep]]
-        else
-          [[head, sep]].concat(split.call(tail, separators))
-        end
-      end
+      # Convert all whitespace (especially \n) to space
+      # to provide a clean slate for wrapping
+      string = string.gsub(/\s+/, " ")
 
-      all = []
-      line = ["", last_sep = ""]
+      # Split string apart using separators one step at a time
+      # while building lines of the requested length
+      lines = []
+      line = ["", last_separator = ""]
       limit = max_length.is_a?(Array) ? max_length[0] : max_length
       length = 0
       separators = /#{separators}/ if separators.is_a?(String)
-      split.call(string, separators).each do |str, sep|
-        if (length + strip.call(str).size + last_sep.size + sep.size) > limit
-          all.push(line) unless line[0] == ""
-          line = [indent, last_sep = ""]
+      while !string.empty? do
+        head, separator, tail = string.partition(separators)
+        if (length + strip.call(head).size + last_separator.size + separator.size) > limit
+          lines.push(line) unless line[0] == ""
+          line = [indent, last_separator = ""]
           length = indent.size
           limit = max_length.is_a?(Array) ? max_length[1] : max_length
         end
-        line[0] += (str = last_sep + str)
-        line[1] = last_sep = sep
-        length += strip.call(str).size
+        line[0] += (head = last_separator + head)
+        line[1] = last_separator = separator
+        length += strip.call(head).size
+        string = tail
       end
-      all.push(line)
-      all[0..-2].inject("") { |a, (str, sep)| a + str + sep + "\n" } + all[-1][0]
+      lines.push(line)
+      lines[0..-2].inject("") { |a, (str, separator)| a + str + separator + "\n" } + lines[-1][0]
     end
 
     # Format time value in local time
     #
-    # === Parameters
-    # time(Integer):: Time in seconds in Unix-epoch to be formatted
-    # with_year(Boolean):: Whether to include year, defaults to false
+    # @param time [Integer] Time in seconds in Unix-epoch to be formatted
+    # @param with_year [Boolean] Whether to include year, defaults to false
     #
-    # (String):: Formatted time string
+    # @return [String] Formatted time string
     def self.time_at(time, with_year = false)
       if with_year
         Time.at(time).strftime("%a %b %d %H:%M:%S %Y")
@@ -198,42 +185,39 @@ module RightSupport
     # Sort hash elements by key in ascending order into array of key/value pairs
     # Sort keys numerically if possible, otherwise as is
     #
-    # === Parameters
-    # hash(Hash):: Data to be sorted
+    # @param hash [Hash] Data to be sorted
     #
-    # === Return
-    # (Array):: Key/value pairs from hash in key sorted order
+    # @return [Array] Key/value pairs from hash in key sorted order
     def self.sort_key(hash)
       hash.to_a.map { |k, v| [k =~ /^\d+$/ ? k.to_i : k, v] }.sort
     end
 
     # Sort hash elements by value in ascending order into array of key/value pairs
     #
-    # === Parameters
-    # hash(Hash):: Data to be sorted
+    # @param hash [Hash] Data to be sorted
     #
-    # === Return
-    # (Array):: Key/value pairs from hash in value sorted order
+    # @return [Array] Key/value pairs from hash in value sorted order
     def self.sort_value(hash)
       hash.to_a.sort { |a, b| a[1] <=> b[1] }
     end
 
     # Converts server statistics to a displayable format
     #
-    # === Parameters
-    # stats(Hash):: Statistics with generic keys "name", "identity", "hostname", "revision", "service uptime",
+    # @param stats [Hash] Statistics with generic keys "name", "identity", "hostname", "revision", "service uptime",
     #   "machine uptime", "memory KB", "stat time", "last reset time", "version", and "brokers" with
     #   "revision", "machine uptime", "memory KB", "version", and "brokers" being optional;
     #   any other keys ending with "stats" have an associated hash value that is displayed in sorted
     #   key order, unless "stats" is preceded by a non-blank, in which case that character is prepended
     #   to the key to drive the sort order
-    # options(Hash):: Formatting options
-    #   :name_width(Integer):: Maximum characters in displayed stat name
-    #   :sub_name_width(Integer):: Maximum characters in displayed sub-stat name
-    #   :sub_stat_value_width(Integer):: Maximum characters in displayed sub-stat value line
     #
-    # === Return
-    # (String):: Display string
+    # @option options [Integer] :name_width Maximum characters in displayed stat name
+    # @option options [Integer] :sub_name_width Maximum characters in displayed sub-stat name
+    # @option options [Integer] :sub_stat_value_width Maximum characters in displayed sub-stat value line
+    # @option options [Array<Hash>] :highlight Sub-statistics to highlight along with specific attributes to highlight,
+    #   e.g., [{"exceptions" => "total"}, {"response time" => "> 1.0"}, {"health" => ["red", "yellow"]},
+    #   {"non-deliveries" => [{"last" => "< 36000"}]}]
+    #
+    # @return [String] Display string
     def self.stats_str(stats, options = {})
       name_width = options[:name_width] || MAX_STAT_NAME_WIDTH
 
@@ -266,12 +250,10 @@ module RightSupport
 
     # Converts service uptime stats to displayable format
     #
-    # === Parameters
-    # stats(Integer|Hash):: Service uptime in seconds if an Integer, otherwise a Hash containing
+    # @param stats [Integer, Hash] Service uptime in seconds if an Integer, otherwise a Hash containing
     #   "uptime", "total_uptime", "restarts", "graceful_exits", "crashes", and "last_crash_time" values
     #
-    # === Return
-    # (String):: Service uptime display
+    # @return [String] Service uptime display
     def self.service_up_str(stats)
       if stats.is_a?(Integer)
         elapsed(stats)
@@ -290,9 +272,8 @@ module RightSupport
 
     # Convert broker information to displayable format
     #
-    # === Parameter
-    # brokers(Hash):: Broker stats with keys
-    #   "brokers"(Array):: Stats for each broker in priority order as hash with keys
+    # @param brokers [Hash] Broker stats with keys
+    #   "brokers" [Array] Stats for each broker in priority order as hash with keys
     #     "alias"(String):: Broker alias
     #     "identity"(String):: Broker identity
     #     "status"(Symbol):: Status of connection
@@ -301,19 +282,21 @@ module RightSupport
     #     "failure last"(Hash|nil):: Last connect failure information with key "elapsed", or nil if none
     #     "failures"(Integer|nil):: Number of failed attempts to connect to broker, or nil if none
     #     "retries"(Integer|nil):: Number of attempts to connect after failure, or nil if none
-    #   "exceptions"(Hash|nil):: Exceptions raised per category, or nil if none
+    #   "exceptions" [Hash, NilClass] Exceptions raised per category, or nil if none
     #     "total"(Integer):: Total exceptions for this category
     #     "recent"(Array):: Most recent as a hash of "count", "type", "message", "when", and "where"
-    #   "heartbeat"(Integer|nil):: Number of seconds between AMQP heartbeats, or nil if heartbeat disabled
-    #   "returns"(Hash|nil):: Message return activity stats with keys "total", "percent", "last", and "rate"
+    #   "heartbeat" [Integer, NilClass] Number of seconds between AMQP heartbeats, or nil if heartbeat disabled
+    #   "returns" [Hash, NilClass] Message return activity stats with keys "total", "percent", "last", and "rate"
     #     with percentage breakdown per request type, or nil if none
-    # options(Hash):: Formatting options
-    #   :name_width(Integer):: Fixed width for left-justified name display
-    #   :sub_name_width(Integer):: Maximum characters in displayed sub-stat name
-    #   :sub_stat_value_width(Integer):: Maximum characters in displayed sub-stat value line
     #
-    # === Return
-    # str(String):: Broker display with one line per broker plus exceptions
+    # @option options [Integer] :name_width Fixed width for left-justified name display
+    # @option options [Integer] :sub_name_width Maximum characters in displayed sub-stat name
+    # @option options [Integer] :sub_stat_value_width Maximum characters in displayed sub-stat value line
+    # @option options [Array<Hash>] :highlight Sub-statistics to highlight along with specific attributes to highlight,
+    #   e.g., [{"exceptions" => "total"}, {"response time" => "> 1.0"}, {"health" => ["red", "yellow"]},
+    #   {"non-deliveries" => [{"last" => "< 36000"}]}]
+    #
+    # @return [String] Broker display with one line per broker plus exceptions
     def self.brokers_str(brokers, options = {})
       name_width = options[:name_width] || MAX_STAT_NAME_WIDTH
       sub_name_width = options[:sub_name_width] || MAX_SUB_STAT_NAME_WIDTH
@@ -373,16 +356,17 @@ module RightSupport
     # Display any nil value, empty hash, or hash with a "total" value of 0 as "none"
     # Display any floating point value or hash of values with at least two significant digits of precision
     #
-    # === Parameters
-    # name(String):: Display name for the stat
-    # value(Object):: Value of this stat
-    # options(Hash):: Formatting options
-    #   :name_width(Integer):: Fixed width for left-justified name display
-    #   :sub_name_width(Integer):: Maximum characters in displayed sub-stat name
-    #   :sub_stat_value_width(Integer):: Maximum characters in displayed sub-stat value line
+    # @param name [String] Display name for the stat
+    # @param value [Object] Value of this stat
+    #
+    # @option options [Integer] :name_width Fixed width for left-justified name display
+    # @option options [Integer] :sub_name_width Maximum characters in displayed sub-stat name
+    # @option options [Integer] :sub_stat_value_width Maximum characters in displayed sub-stat value line
+    # @option options [Array<Hash>] :highlight Sub-statistics to highlight along with specific attributes to highlight,
+    #   e.g., [{"exceptions" => "total"}, {"response time" => "> 1.0"}, {"health" => ["red", "yellow"]},
+    #   {"non-deliveries" => [{"last" => "< 36000"}]}]
     #
-    # === Return
-    # (String):: Single line display of stat
+    # @return [String] Single line display of stat
     def self.sub_stats_str(name, value, options = {})
       name_width = options[:name_width] || MAX_STAT_NAME_WIDTH
       sub_name_width = options[:sub_name_width] || MAX_SUB_STAT_NAME_WIDTH
@@ -393,7 +377,8 @@ module RightSupport
       sprintf("%-#{name_width}s#{SEPARATOR}", name) + value.to_a.sort.map do |attr|
         k, v = attr
         name = k =~ /percent$/ ? k[0..-9] : k
-        sprintf("%-#{sub_name_width}s#{SEPARATOR}", name) + if v.is_a?(Float) || v.is_a?(Integer)
+        sprintf("%-#{sub_name_width}s#{SEPARATOR}", name) +
+        if v.is_a?(Numeric)
           str = k =~ /age$/ ? elapsed(v) : enough_precision(v)
           str += "/sec" if k =~ /rate$/
           str += " sec" if k =~ /time$/
@@ -421,19 +406,17 @@ module RightSupport
 
     # Convert activity information to displayable format
     #
-    # === Parameters
-    # value(Hash|nil):: Information about activity, or nil if the total is 0
-    #   "total"(Integer):: Total activity count
-    #   "percent"(Hash):: Percentage for each type of activity if tracking type, otherwise omitted
-    #   "last"(Hash):: Information about last activity
+    # @param value [Hash, NilClass] Information about activity, or nil if the total is 0
+    #   "total" [Integer] Total activity count
+    #   "percent" [Hash] Percentage for each type of activity if tracking type, otherwise omitted
+    #   "last" [Hash] Information about last activity
     #     "elapsed"(Integer):: Seconds since last activity started
     #     "type"(String):: Type of activity if tracking type, otherwise omitted
     #     "active"(Boolean):: Whether activity still active if tracking whether active, otherwise omitted
-    #   "rate"(Float):: Recent average rate if measuring rate, otherwise omitted
-    #   "duration"(Float):: Average duration of activity if tracking duration, otherwise omitted
+    #   "rate" [Float] Recent average rate if measuring rate, otherwise omitted
+    #   "duration" [Float] Average duration of activity if tracking duration, otherwise omitted
     #
-    # === Return
-    # str(String):: Activity stats in displayable format without any line separators
+    # @return [String] Activity stats in displayable format without any line separators
     def self.activity_str(value)
       str = ""
       str += enough_precision(sort_value(value["percent"]).reverse).map { |k, v| "#{k}: #{v}%" }.join(", ") +
@@ -452,15 +435,13 @@ module RightSupport
  
     # Convert last activity information to displayable format
     #
-    # === Parameters
-    # last(Hash):: Information about last activity
-    #   "elapsed"(Integer):: Seconds since last activity started
-    #   "type"(String):: Type of activity if tracking type, otherwise omitted
-    #   "active"(Boolean):: Whether activity still active if tracking whether active, otherwise omitted
-    # single_item:: Whether this is to appear as a single item in a comma-separated list
+    # @param last [Hash] Information about last activity
+    #   "elapsed" [Integer] Seconds since last activity started
+    #   "type" [String] Type of activity if tracking type, otherwise omitted
+    #   "active" [Boolean] Whether activity still active if tracking whether active, otherwise omitted
+    # @param single_item [Boolean] Whether this is to appear as a single item in a comma-separated list
     #   in which case there should be no ':' in the formatted string
     #
-    # === Return
     # str(String):: Last activity in displayable format without any line separators
     def self.last_activity_str(last, single_item = false)
       str = "#{elapsed(last['elapsed'])} ago"
@@ -477,25 +458,29 @@ module RightSupport
 
     # Convert exception information to displayable format
     #
-    # === Parameters
-    # exceptions(Hash):: Exceptions raised per category
-    #   "total"(Integer):: Total exceptions for this category
-    #   "recent"(Array):: Most recent as a hash of "count", "type", "message", "when", and "where"
-    # indent(String):: Indentation for each line
-    # options(Hash):: Formatting options
-    #   :sub_stat_value_width(Integer):: Maximum characters in displayed sub-stat value line
+    # @param exceptions [Hash] Exceptions raised per category
+    #   "total" [Integer] Total exceptions for this category
+    #   "recent" [Array<Hash>] Most recent as a hash of "count", "type", "message", "when", and "where"
+    # @param indent [String] Indentation for each line
     #
-    # === Return
-    # (String):: Exceptions in displayable format with line separators
+    # @option options [Integer] :sub_stat_value_width Maximum characters in displayed sub-stat value line
+    #
+    # @return [String] Exceptions in displayable format with line separators
     def self.exceptions_str(exceptions, indent, options = {})
       sub_stat_value_width = options[:sub_stat_value_width] || MAX_SUB_STAT_VALUE_WIDTH
       indent2 = indent + (" " * 4)
+      max_length = [sub_stat_value_width, sub_stat_value_width + indent2.size]
+      separators = / |\/\/|\/|::|\.|-/
       exceptions.to_a.sort.map do |k, v|
         sprintf("%s total: %d, most recent:\n", k, v["total"]) + v["recent"].reverse.map do |e|
-          where = " IN #{e["where"]}" if e["where"]
-          indent + wrap("(#{e["count"]}) #{time_at(e["when"])} #{e["type"]}: #{e["message"]}#{where}",
-                        [sub_stat_value_width, sub_stat_value_width + indent2.size],
-                        indent2, / |\/\/|\/|::|\.|-/)
+          head = "(#{e["count"]}) #{time_at(e["when"])} #{e["type"]}: "
+          message = e["message"]
+          if (i = (/(:[0-9]+:in `[^']+')/ =~ message))
+            # Dropping anything after the first line of an embedded backtrace to reduce bulk
+            message = message[0..i-1] + $1 + "..."
+          end
+          tail = " IN #{e["where"]}" if e["where"]
+          indent + wrap("#{head}#{message}#{tail}", max_length, indent2, separators)
         end.join("\n")
       end.join("\n" + indent)
     end
@@ -505,11 +490,9 @@ module RightSupport
     # Display any floating point values with one decimal place precision
     # Display any empty values as "none"
     #
-    # === Parameters
-    # hash(Hash):: Hash to be displayed
+    # @param hash [Hash] Hash to be displayed
     #
-    # === Return
-    # (String):: Single line hash display
+    # @return [String] Single line hash display
     def self.hash_str(hash)
       str = ""
       sort_key(hash).map do |k, v|

data/right_support.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{right_support}
-  s.version = "2.7.0"
+  s.version = "2.8.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Tony Spataro", "Sergey Sergyenko", "Ryan Williamson", "Lee Kirchhoff", "Alexey Karpik", "Scott Messier"]
-  s.date = %q{2013-01-26}
+  s.date = %q{2013-08-28}
   s.description = %q{A toolkit of useful, reusable foundation code created by RightScale.}
   s.email = %q{support@rightscale.com}
   s.extra_rdoc_files = [
@@ -143,41 +143,37 @@ Gem::Specification.new do |s|
   s.summary = %q{Reusable foundation code.}
 
   if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_development_dependency(%q<rake>, ["~> 0.9"])
       s.add_development_dependency(%q<jeweler>, ["~> 1.8.3"])
+      s.add_development_dependency(%q<right_develop>, ["~> 1.0"])
       s.add_development_dependency(%q<ruby-debug>, [">= 0.10"])
       s.add_development_dependency(%q<ruby-debug19>, [">= 0.11.6"])
       s.add_development_dependency(%q<rdoc>, [">= 2.4.2"])
-      s.add_development_dependency(%q<rspec>, ["~> 2.0"])
-      s.add_development_dependency(%q<cucumber>, ["~> 1.0"])
-      s.add_development_dependency(%q<flexmock>, ["~> 0.8"])
+      s.add_development_dependency(%q<flexmock>, ["~> 1.0"])
       s.add_development_dependency(%q<syntax>, ["~> 1.0.0"])
       s.add_development_dependency(%q<nokogiri>, ["~> 1.5"])
     else
       s.add_dependency(%q<rake>, ["~> 0.9"])
       s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
+      s.add_dependency(%q<right_develop>, ["~> 1.0"])
       s.add_dependency(%q<ruby-debug>, [">= 0.10"])
       s.add_dependency(%q<ruby-debug19>, [">= 0.11.6"])
       s.add_dependency(%q<rdoc>, [">= 2.4.2"])
-      s.add_dependency(%q<rspec>, ["~> 2.0"])
-      s.add_dependency(%q<cucumber>, ["~> 1.0"])
-      s.add_dependency(%q<flexmock>, ["~> 0.8"])
+      s.add_dependency(%q<flexmock>, ["~> 1.0"])
       s.add_dependency(%q<syntax>, ["~> 1.0.0"])
       s.add_dependency(%q<nokogiri>, ["~> 1.5"])
     end
   else
     s.add_dependency(%q<rake>, ["~> 0.9"])
     s.add_dependency(%q<jeweler>, ["~> 1.8.3"])
+    s.add_dependency(%q<right_develop>, ["~> 1.0"])
     s.add_dependency(%q<ruby-debug>, [">= 0.10"])
     s.add_dependency(%q<ruby-debug19>, [">= 0.11.6"])
     s.add_dependency(%q<rdoc>, [">= 2.4.2"])
-    s.add_dependency(%q<rspec>, ["~> 2.0"])
-    s.add_dependency(%q<cucumber>, ["~> 1.0"])
-    s.add_dependency(%q<flexmock>, ["~> 0.8"])
+    s.add_dependency(%q<flexmock>, ["~> 1.0"])
     s.add_dependency(%q<syntax>, ["~> 1.0.0"])
     s.add_dependency(%q<nokogiri>, ["~> 1.5"])
   end