humane 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 572a6a4a29165d48eec68db31af6cb222a88de6f989099d353811225898c4673
-  data.tar.gz: cfc60adb65c39694c156f7b173d053431d469ec26d1bf98a584c83b05bfc5887
+  metadata.gz: 9f1d568f746432126417fdd6541c249d81475c663e4e9ae9a772fcbc1dc59e3f
+  data.tar.gz: f85e12c6dbd402a4a1d452ba4629e6921418ff8609d6222333b17c1b51ae6a05
 SHA512:
-  metadata.gz: baa6946270a2a9bcaa4636993324df9cae89da3ff2a753552bc21bcdc5569a9fe10075dc48e4e2e910a2f50d811ff324bf7e7ce59168c03025cc2f2157626d5e
-  data.tar.gz: 4dc6ee4899fe1ae32d33c36307a5a01bef49cf34fb368668b28bd584cae6bce38d9a00be13d9aef532020015d40f00375c1c9ad8299380882bdcc29935469f78
+  metadata.gz: fa9e176a20d540c3c325c6f1015c2353b2fbced72397d9bcb645eea021129341781543399ac0a94d1cde5b885e64738e7d723d14c2bfb8548c3b7f7d392664cd
+  data.tar.gz: e59a7270df069333babc2d10f6234bbb507853b9b2c1583e437e41f1451a1f0dd6bc82cba1f88ec83989bb31a2957132f8d8c38a4bd96a056fb1a1b293ebd39f

data/README.md

@@ -22,6 +22,14 @@ time_formatter = Humane::TimeFormatter.new
 time_formatter.string(at: Time.now - 180, relative_to: Time.now) # "3 minutes ago"
 ```
 
+Both methods also accept positional arguments, matching `humane` (Go)'s
+positional-only calling convention:
+
+```ruby
+Humane::SizeFormatter.new.string(225_935) # "226 KB"
+time_formatter.string(Time.now - 180, Time.now) # "3 minutes ago"
+```
+
 Corresponding functions in Swift will have consistent output.
 
 ```swift
@@ -33,6 +41,11 @@ let formatter = RelativeDateTimeFormatter(); formatter.unitsStyle = .full
 formatter.localizedString(for: time, relativeTo: now) // "3 minutes ago"
 ```
 
+If you're writing Swift directly rather than calling Foundation by hand,
+[`humane-swift`](https://github.com/woodie/humane-swift) wraps these same two
+formatters with the identical API shape -- including the
+`includeSeconds`/`approximate` options below.
+
 ## Install
 
 ```
@@ -47,16 +60,21 @@ gem "humane"
 
 ## Beyond Foundation's defaults
 
-Two options on `Humane::TimeFormatter`, both off by default so it matches
-`RelativeDateTimeFormatter` exactly out of the box:
+Foundation is the baseline every default matches exactly, in all three
+languages -- these two options on `Humane::TimeFormatter` are how you layer
+ActionView's wording on top of it, not a replacement for it. Both off by
+default, so `Humane::TimeFormatter.new` and calling `RelativeDateTimeFormatter`
+directly always agree:
 
-- `include_seconds` (default `false`): below a minute, collapses to "less than a
+- `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. Named after
   ActionView's `include_seconds`, which defaults the same way.
-- `approximate` (default `false`): prefixes "about"/"in about" on buckets of an hour
-  or larger, the way ActionView's `distance_of_time_in_words` does past that same
-  boundary -- for a render that can't refresh itself and shouldn't overstate its own
-  precision.
+- `approximate` (default `false`): prefixes "about"/"in about" on the hour-scale
+  buckets (1 hour, and 2..24 hours), the way ActionView's `distance_of_time_in_words`
+  does for those same buckets -- for a render that can't refresh itself and shouldn't
+  overstate its own precision. Matches ActionView's own table exactly (down to its
+  44:30/89:30 rounding cutoffs), through the "1 day" bucket; week/month/year buckets
+  are out of scope. See [issue #1](https://github.com/woodie/humane-ruby/issues/1).
 
 ```ruby
 Humane::TimeFormatter.new(approximate: true).string(at: t - 15 * 3600, relative_to: t)

data/lib/humane/size_formatter.rb

@@ -5,8 +5,11 @@ module Humane
   class SizeFormatter
     UNITS = %w[B KB MB GB TB PB EB].freeze
 
-    # Returns from_byte_count as a Finder-style human-readable string.
-    def string(from_byte_count:)
+    # Returns from_byte_count as a Finder-style human-readable string; accepts positional or from_byte_count: keyword argument -- see docs/COMMENTS.md.
+    def string(positional_from_byte_count = nil, from_byte_count: nil)
+      from_byte_count ||= positional_from_byte_count
+      raise ArgumentError, "from_byte_count is required" unless from_byte_count
+
       return "#{from_byte_count} B" if from_byte_count < 1000
 
       exponent = [(Math.log(from_byte_count) / Math.log(1000)).to_i, UNITS.size - 1].min

data/lib/humane/time_formatter.rb

@@ -4,40 +4,54 @@ module Humane
   # Formats one time relative to another the way Finder-adjacent tools do.
   class TimeFormatter
     # include_seconds shows exact seconds under a minute instead of collapsing to "less than a minute ago/in less than a minute". Defaults to false, matching ActionView's include_seconds.
-    # approximate prefixes "about"/"in about" on buckets of an hour or more, matching ActionView's distance_of_time_in_words past that same boundary. Defaults to false.
+    # approximate prefixes "about"/"in about" on the hour-scale buckets (1 hour, and 2..24 hours), matching ActionView's distance_of_time_in_words wording for those buckets. Defaults to false. See docs/COMMENTS.md and humane-ruby issue #1 for the full bucket table this ports.
     def initialize(include_seconds: false, approximate: false)
       @include_seconds = include_seconds
       @approximate = approximate
     end
 
-    # Returns the time at `at` relative to `relative_to` as a human-readable string.
-    def string(at:, relative_to:)
+    # Returns at relative to relative_to; accepts positional or at:/relative_to: keyword arguments -- see docs/COMMENTS.md.
+    def string(positional_at = nil, positional_relative_to = nil, at: nil, relative_to: nil)
+      at ||= positional_at
+      relative_to ||= positional_relative_to
+      raise ArgumentError, "at is required" unless at
+      raise ArgumentError, "relative_to is required" unless relative_to
+
       seconds = relative_to - at
       future = seconds.negative?
       seconds = seconds.abs
 
-      if !@include_seconds && seconds < 60
+      if !@include_seconds && seconds < 30
         return future ? "in less than a minute" : "less than a minute ago"
       end
 
-      text =
-        if seconds < 60
-          pluralize(seconds.to_i, "second")
-        elsif seconds < 3600
-          pluralize((seconds / 60.0).round, "minute")
-        elsif seconds < 86_400
-          pluralize((seconds / 3600.0).round, "hour")
-        else
-          pluralize((seconds / 86_400.0).round, "day")
-        end
+      if @include_seconds && seconds < 60
+        return wrap(pluralize(seconds.to_i, "second"), future: future)
+      end
 
-      text = "about #{text}" if @approximate && seconds >= 3600
+      # 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
 
-      future ? "in #{text}" : "#{text} ago"
+      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

data/lib/humane/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: humane
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - John Woodell