humane 0.9.0 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d763c1ac13b418641448e26596e05164e13473257fa89c9dfbe4c752c31a780
-  data.tar.gz: 17672a19ade63d69bc0531d798e432b69daafe242fd9b61f594867a8bef3ee6e
+  metadata.gz: b0e7b2d5c4485d84a102a56c7586e7a61e62312729b1978d8221a24cc7d23917
+  data.tar.gz: c51ce6b56f73e1d859c9cb65e4a096cee6030c37fe4664c30ab16da13193d9a3
 SHA512:
-  metadata.gz: a1acce1f07be40fa5aad7073b099801465adc0af544acdeb27fcacc1562249144d809c5c83130447deec443714c768c377c94334a511d232acbe43a71558012a
-  data.tar.gz: 617655da198133fd9d931e69ff43ae3e8cd670e56d674a42b787fb63d0f3b7aec5aabb530e22129fa5b67e2fbcc68ed7ec7d1702cea206cb7411951c9b6efb85
+  metadata.gz: d3477e12b897535a507f1cd95c3b2c57619e71bce6f3d320c89eafde5621a5fb382f18eb9fa10a570d9edc511d2b62fe0c6ba6e65338432730ef5a1baf64b2ed
+  data.tar.gz: 8be3d6ed6747f5adcc66edc8eca5dc2ce7ea3fd4252af19a1e376787333a6af6a1d039590b49c885ecbe3594eb351364be7aa0e734b805bf4ad795fe2c9f47cf

data/README.md

@@ -15,8 +15,13 @@ helpers, with output that's consistent with
 ```ruby
 require "humane"
 
-Humane::SizeFormatter.human_size(225_935) # "226 KB"
-Humane::TimeFormatter.time_ago(Time.now - 180, Time.now) # "3 minutes ago"
+Humane.human_size(225_935) # "226 KB"
+
+mtime = Time.now - 180
+Humane.time_ago(mtime) # "3 minutes ago" -- relative to the real clock
+
+now = Time.now
+Humane.distance_in_time(mtime, now) # "3 minutes ago" -- explicit relative_to, for tests
 ```
 
 ## Install
@@ -31,14 +36,24 @@ or in a `Gemfile`:
 gem "humane"
 ```
 
-## `time_ago` options
+## `distance_in_time` and `time_ago`
+
+Two entry points, same naming split as ActionView's own
+`distance_of_time_in_words`/`time_ago_in_words`:
+
+- **`distance_in_time(at, relative_to, **opts)`** -- the explicit,
+  fully-tested core. Takes both times, so it's what specs should call.
+- **`time_ago(at, **opts)`** -- a one-argument convenience for the common
+  "drop into a view" case. Supplies `Time.now` as `relative_to` internally;
+  everything else is identical to `distance_in_time`.
 
-`time_ago`'s recommended defaults already match ActionView's own
-`distance_of_time_in_words` defaults -- pass no keyword arguments at all and
-you get them for free:
+Both share the same keyword options and recommended defaults, already
+matching ActionView's own `distance_of_time_in_words` defaults -- pass none
+at all and you get them for free:
 
 ```ruby
-Humane::TimeFormatter.time_ago(at, relative_to) # approximate: true, include_seconds: false
+Humane.distance_in_time(at, relative_to) # approximate: true, include_seconds: false
+Humane.time_ago(at)                      # same defaults, relative_to is Time.now
 ```
 
 - **`approximate`** (default `true`): prefixes `"about"`/`"in about"` on the
@@ -48,13 +63,13 @@ Humane::TimeFormatter.time_ago(at, relative_to) # approximate: true, include_sec
 - **`include_seconds`** (default `false`): under 30 seconds, collapses to
   `"less than a minute ago"`/`"in less than a minute"` instead of an exact
   second count. Matches ActionView's `include_seconds` default.
-- **`when_nil`** (default `nil`): if `at` is `nil`, `time_ago` returns this
+- **`when_nil`** (default `nil`): if `at` is `nil`, both methods return this
   value without formatting -- for a scan, download, or other record that
   doesn't have a timestamp yet.
 
 ```ruby
-Humane::TimeFormatter.time_ago(t, now, approximate: false) # "15 hours ago", not "about 15 hours ago"
-Humane::TimeFormatter.time_ago(nil, now, when_nil: "an unknown time") # "an unknown time"
+Humane.distance_in_time(t, now, approximate: false) # "15 hours ago", not "about 15 hours ago"
+Humane.time_ago(nil, when_nil: "an unknown time") # "an unknown time"
 ```
 
 ## Scope

data/lib/humane/size.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Humane
+  UNITS = %w[KB MB GB TB PB EB].freeze
+
+  # Returns byte_count as a Finder-style human-readable string.
+  #
+  #   Humane.human_size(225_935) #=> "226 KB"
+  def self.human_size(byte_count)
+    return "Zero KB" if byte_count.zero?
+    return (byte_count == 1) ? "1 byte" : "#{byte_count} bytes" if byte_count < 1000
+
+    exponent = [(Math.log(byte_count) / Math.log(1000)).to_i, UNITS.size].min
+    value = byte_count / (1000.0**exponent)
+
+    "#{format_significant(value, 3)} #{UNITS[exponent - 1]}"
+  end
+
+  # Rounds value to sig_figs significant figures and trims trailing
+  # fractional zeros (and the decimal point itself, if nothing remains
+  # after it) -- see docs/COMMENTS.md.
+  def self.format_significant(value, sig_figs)
+    magnitude = Math.log10(value).floor + 1
+    decimals = [sig_figs - magnitude, 0].max
+
+    formatted = format("%.#{decimals}f", value)
+    formatted.include?(".") ? formatted.sub(/0+\z/, "").sub(/\.\z/, "") : formatted
+  end
+  private_class_method :format_significant
+end

data/lib/humane/time.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Humane
+  # Formats one time relative to another the way ActionView's
+  # distance_of_time_in_words does for wording, but direction-aware like
+  # RelativeDateTimeFormatter -- "X ago"/"in X", chosen automatically rather
+  # than requiring the caller to know which applies ahead of time. This is
+  # the explicit, fully-tested core -- see .time_ago below for the
+  # one-argument convenience. See docs/COMMENTS.md.
+  #
+  #   Humane.distance_in_time(Time.now - 180, Time.now) #=> "3 minutes ago"
+  def self.distance_in_time(at, relative_to, approximate: true, include_seconds: false, when_nil: nil)
+    return when_nil if at.nil?
+
+    seconds = relative_to - at
+    future = seconds.negative?
+    seconds = seconds.abs
+
+    if !include_seconds && seconds < 30
+      return future ? "in less than a minute" : "less than a minute ago"
+    end
+
+    if include_seconds && seconds < 60
+      return wrap(pluralize(seconds.to_i, "second"), future: future)
+    end
+
+    # Buckets come from distance_in_minutes, not raw seconds re-divided per unit -- see docs/COMMENTS.md.
+    distance_in_minutes = (seconds / 60.0).round
+
+    text, approximable =
+      case distance_in_minutes
+      when 1 then ["1 minute", false]
+      when 2..44 then [pluralize(distance_in_minutes, "minute"), false]
+      when 45..89 then ["1 hour", true]
+      when 90..1439 then [pluralize((distance_in_minutes / 60.0).round, "hour"), true]
+      when 1440..2519 then ["1 day", false]
+      else [pluralize((distance_in_minutes / 1440.0).round, "day"), false]
+      end
+
+    text = "about #{text}" if approximate && approximable
+    wrap(text, future: future)
+  end
+
+  # Returns at relative to the current time -- a convenience for the common
+  # "drop into a view" case, modeled on ActionView's time_ago_in_words
+  # wrapping distance_of_time_in_words with Time.now. Use .distance_in_time
+  # directly when the reference time needs to be explicit (tests, a fixed
+  # point other than now).
+  #
+  #   Humane.time_ago(Time.now - 180) #=> "3 minutes ago"
+  def self.time_ago(at, **opts)
+    distance_in_time(at, Time.now, **opts)
+  end
+
+  def self.wrap(text, future:)
+    future ? "in #{text}" : "#{text} ago"
+  end
+  private_class_method :wrap
+
+  def self.pluralize(count, unit)
+    (count == 1) ? "1 #{unit}" : "#{count} #{unit}s"
+  end
+  private_class_method :pluralize
+end

data/lib/humane/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Humane
-  VERSION = "0.9.0"
+  VERSION = "0.9.3"
 end

data/lib/humane.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "humane/version"
-require_relative "humane/size_formatter"
-require_relative "humane/time_formatter"
+require_relative "humane/size"
+require_relative "humane/time"
 
 module Humane
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: humane
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.3
 platform: ruby
 authors:
 - John Woodell
@@ -20,8 +20,8 @@ files:
 - LICENSE
 - README.md
 - lib/humane.rb
-- lib/humane/size_formatter.rb
-- lib/humane/time_formatter.rb
+- lib/humane/size.rb
+- lib/humane/time.rb
 - lib/humane/version.rb
 homepage: https://github.com/woodie/humane-ruby
 licenses:

data/lib/humane/size_formatter.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module Humane
-  # Formats byte counts the way Finder does: 1000-based math, capitalized
-  # unit labels, rounded to 3 significant figures. See docs/COMMENTS.md.
-  class SizeFormatter
-    UNITS = %w[KB MB GB TB PB EB].freeze
-
-    class << self
-      # Returns byte_count as a Finder-style human-readable string.
-      #
-      #   Humane::SizeFormatter.human_size(225_935) #=> "226 KB"
-      def human_size(byte_count)
-        return "Zero KB" if byte_count.zero?
-        return (byte_count == 1) ? "1 byte" : "#{byte_count} bytes" if byte_count < 1000
-
-        exponent = [(Math.log(byte_count) / Math.log(1000)).to_i, UNITS.size].min
-        value = byte_count / (1000.0**exponent)
-
-        "#{format_significant(value, 3)} #{UNITS[exponent - 1]}"
-      end
-
-      private
-
-      # Rounds value to sig_figs significant figures and trims trailing
-      # fractional zeros (and the decimal point itself, if nothing remains
-      # after it) -- see docs/COMMENTS.md.
-      def format_significant(value, sig_figs)
-        magnitude = Math.log10(value).floor + 1
-        decimals = [sig_figs - magnitude, 0].max
-
-        formatted = format("%.#{decimals}f", value)
-        formatted.include?(".") ? formatted.sub(/0+\z/, "").sub(/\.\z/, "") : formatted
-      end
-    end
-  end
-end

data/lib/humane/time_formatter.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module Humane
-  # Formats one time relative to another the way ActionView's
-  # distance_of_time_in_words does for wording, but direction-aware like
-  # RelativeDateTimeFormatter -- "X ago"/"in X", chosen automatically rather
-  # than requiring the caller to know which applies ahead of time. See
-  # docs/COMMENTS.md.
-  class TimeFormatter
-    class << self
-      # Returns at relative to relative_to as a human-readable string. If at
-      # is nil, returns when_nil without formatting -- see docs/COMMENTS.md.
-      #
-      #   Humane::TimeFormatter.time_ago(Time.now - 180, Time.now) #=> "3 minutes ago"
-      def time_ago(at, relative_to, approximate: true, include_seconds: false, when_nil: nil)
-        return when_nil if at.nil?
-
-        seconds = relative_to - at
-        future = seconds.negative?
-        seconds = seconds.abs
-
-        if !include_seconds && seconds < 30
-          return future ? "in less than a minute" : "less than a minute ago"
-        end
-
-        if include_seconds && seconds < 60
-          return wrap(pluralize(seconds.to_i, "second"), future: future)
-        end
-
-        # Buckets come from distance_in_minutes, not raw seconds re-divided per unit -- see docs/COMMENTS.md.
-        distance_in_minutes = (seconds / 60.0).round
-
-        text, approximable =
-          case distance_in_minutes
-          when 1 then ["1 minute", false]
-          when 2..44 then [pluralize(distance_in_minutes, "minute"), false]
-          when 45..89 then ["1 hour", true]
-          when 90..1439 then [pluralize((distance_in_minutes / 60.0).round, "hour"), true]
-          when 1440..2519 then ["1 day", false]
-          else [pluralize((distance_in_minutes / 1440.0).round, "day"), false]
-          end
-
-        text = "about #{text}" if approximate && approximable
-        wrap(text, future: future)
-      end
-
-      private
-
-      def wrap(text, future:)
-        future ? "in #{text}" : "#{text} ago"
-      end
-
-      def pluralize(count, unit)
-        (count == 1) ? "1 #{unit}" : "#{count} #{unit}s"
-      end
-    end
-  end
-end