humane 0.6.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f1d568f746432126417fdd6541c249d81475c663e4e9ae9a772fcbc1dc59e3f
-  data.tar.gz: f85e12c6dbd402a4a1d452ba4629e6921418ff8609d6222333b17c1b51ae6a05
+  metadata.gz: 4d763c1ac13b418641448e26596e05164e13473257fa89c9dfbe4c752c31a780
+  data.tar.gz: 17672a19ade63d69bc0531d798e432b69daafe242fd9b61f594867a8bef3ee6e
 SHA512:
-  metadata.gz: fa9e176a20d540c3c325c6f1015c2353b2fbced72397d9bcb645eea021129341781543399ac0a94d1cde5b885e64738e7d723d14c2bfb8548c3b7f7d392664cd
-  data.tar.gz: e59a7270df069333babc2d10f6234bbb507853b9b2c1583e437e41f1451a1f0dd6bc82cba1f88ec83989bb31a2957132f8d8c38a4bd96a056fb1a1b293ebd39f
+  metadata.gz: a1acce1f07be40fa5aad7073b099801465adc0af544acdeb27fcacc1562249144d809c5c83130447deec443714c768c377c94334a511d232acbe43a71558012a
+  data.tar.gz: 617655da198133fd9d931e69ff43ae3e8cd670e56d674a42b787fb63d0f3b7aec5aabb530e22129fa5b67e2fbcc68ed7ec7d1702cea206cb7411951c9b6efb85

data/README.md

@@ -5,47 +5,20 @@
 [![Release](https://img.shields.io/github/v/release/woodie/humane-ruby.svg)](https://github.com/woodie/humane-ruby/releases/latest)
 [![License](https://img.shields.io/github/license/woodie/humane-ruby.svg)](LICENSE)
 
-Getting human-readable file sizes with 1000-based math
-(as the Mac Finder displays) and relative times worded the way Swift's
-`RelativeDateTimeFormatter` does turned out to be a real challenge to get
-both right and simple. The `humane` library exists so a Ruby application can share
-consistent size and time formatting with a Swift application, instead of
-reaching for a library whose output doesn't match Swift's or that's
-complicated to drop in.
+Human-readable file sizes (1000-based math, capitalized labels, the way Mac
+Finder displays them) and relative times (`"3 minutes ago"`, `"in 3 hours"`)
+for Ruby and Go HTML templates -- as simple to drop in as ActionView's own
+helpers, with output that's consistent with
+[`humane`](https://github.com/woodie/humane) (Go) and
+[`humane-swift`](https://github.com/woodie/humane-swift).
 
 ```ruby
 require "humane"
 
-Humane::SizeFormatter.new.string(from_byte_count: 225_935) # "226 KB"
-
-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
-import Foundation
-
-ByteCountFormatter.string(fromByteCount: Int64(225935), countStyle: .file) // "226 KB"
-
-let formatter = RelativeDateTimeFormatter(); formatter.unitsStyle = .full
-formatter.localizedString(for: time, relativeTo: now) // "3 minutes ago"
+Humane::SizeFormatter.human_size(225_935) # "226 KB"
+Humane::TimeFormatter.time_ago(Time.now - 180, Time.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
 
 ```
@@ -58,33 +31,42 @@ or in a `Gemfile`:
 gem "humane"
 ```
 
-## Beyond Foundation's defaults
+## `time_ago` options
+
+`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:
 
-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:
+```ruby
+Humane::TimeFormatter.time_ago(at, relative_to) # approximate: true, include_seconds: false
+```
 
-- `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 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).
+- **`approximate`** (default `true`): 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 exactly (down to its
+  44:30/89:30 rounding cutoffs), through the "1 day" bucket.
+- **`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
+  value without formatting -- for a scan, download, or other record that
+  doesn't have a timestamp yet.
 
 ```ruby
-Humane::TimeFormatter.new(approximate: true).string(at: t - 15 * 3600, relative_to: t)
-# => "about 15 hours ago"
+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"
 ```
 
 ## Scope
 
-Finder's `.file` byte-count style, and a numeric (non-calendar-aware)
-relative time style -- that's the whole surface area today.
-`allowed_units`/alternate `count_style`s and a `:named` style
-(`"yesterday"`, calendar-boundary-aware) aren't implemented -- contributions
-welcome.
+Finder's byte-count style, and a numeric (non-calendar-aware) relative time
+style through the "1 day" bucket -- that's the whole surface area today.
+Alternate size units/styles and a `:named` style (`"yesterday"`,
+calendar-boundary-aware) aren't implemented -- contributions welcome.
+
+## Development
+
+```
+bundle exec standardrb
+bundle exec rspec -fd spec
+```

data/lib/humane/size_formatter.rb

@@ -1,24 +1,36 @@
 # frozen_string_literal: true
 
 module Humane
-  # Formats byte counts the way Finder does: 1000-based math, capitalized unit labels.
+  # 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[B KB MB GB TB PB EB].freeze
+    UNITS = %w[KB MB GB TB PB EB].freeze
 
-    # 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
+    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
 
-      return "#{from_byte_count} B" if from_byte_count < 1000
+        exponent = [(Math.log(byte_count) / Math.log(1000)).to_i, UNITS.size].min
+        value = byte_count / (1000.0**exponent)
 
-      exponent = [(Math.log(from_byte_count) / Math.log(1000)).to_i, UNITS.size - 1].min
-      rounded = (from_byte_count / (1000.0**exponent) * 10).round / 10.0
+        "#{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
 
-      if rounded < 10
-        format("%.1f %s", rounded, UNITS[exponent])
-      else
-        format("%.0f %s", rounded, UNITS[exponent])
+        formatted = format("%.#{decimals}f", value)
+        formatted.include?(".") ? formatted.sub(/0+\z/, "").sub(/\.\z/, "") : formatted
       end
     end
   end

data/lib/humane/time_formatter.rb

@@ -1,59 +1,58 @@
 # frozen_string_literal: true
 
 module Humane
-  # Formats one time relative to another the way Finder-adjacent tools do.
+  # 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
-    # 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 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 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 < 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
+    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
 
-      # 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]
+        if include_seconds && seconds < 60
+          return wrap(pluralize(seconds.to_i, "second"), future: future)
         end
 
-      text = "about #{text}" if @approximate && approximable
-      wrap(text, 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
+      private
 
-    def wrap(text, future:)
-      future ? "in #{text}" : "#{text} ago"
-    end
+      def wrap(text, future:)
+        future ? "in #{text}" : "#{text} ago"
+      end
 
-    def pluralize(count, unit)
-      count == 1 ? "1 #{unit}" : "#{count} #{unit}s"
+      def pluralize(count, unit)
+        (count == 1) ? "1 #{unit}" : "#{count} #{unit}s"
+      end
     end
   end
 end

data/lib/humane/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: humane
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.9.0
 platform: ruby
 authors:
 - John Woodell
@@ -9,8 +9,8 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Finder-accurate file sizes and relative dates for Ruby, modeled on Swift's
-  ByteCountFormatter and RelativeDateTimeFormatter.
+description: Finder-style file sizes and ActionView-flavored relative dates for Ruby,
+  consistent with the humane (Go) and humane-swift siblings.
 email:
 - woodie@netpress.com
 executables: []
@@ -45,5 +45,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Swift's file sizes and relative dates for Ruby
+summary: Finder-style file sizes and relative dates, as simple as ActionView
 test_files: []