humane 0.6.0 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f1d568f746432126417fdd6541c249d81475c663e4e9ae9a772fcbc1dc59e3f
-  data.tar.gz: f85e12c6dbd402a4a1d452ba4629e6921418ff8609d6222333b17c1b51ae6a05
+  metadata.gz: b0e7b2d5c4485d84a102a56c7586e7a61e62312729b1978d8221a24cc7d23917
+  data.tar.gz: c51ce6b56f73e1d859c9cb65e4a096cee6030c37fe4664c30ab16da13193d9a3
 SHA512:
-  metadata.gz: fa9e176a20d540c3c325c6f1015c2353b2fbced72397d9bcb645eea021129341781543399ac0a94d1cde5b885e64738e7d723d14c2bfb8548c3b7f7d392664cd
-  data.tar.gz: e59a7270df069333babc2d10f6234bbb507853b9b2c1583e437e41f1451a1f0dd6bc82cba1f88ec83989bb31a2957132f8d8c38a4bd96a056fb1a1b293ebd39f
+  metadata.gz: d3477e12b897535a507f1cd95c3b2c57619e71bce6f3d320c89eafde5621a5fb382f18eb9fa10a570d9edc511d2b62fe0c6ba6e65338432730ef5a1baf64b2ed
+  data.tar.gz: 8be3d6ed6747f5adcc66edc8eca5dc2ce7ea3fd4252af19a1e376787333a6af6a1d039590b49c885ecbe3594eb351364be7aa0e734b805bf4ad795fe2c9f47cf

data/README.md

@@ -5,47 +5,25 @@
 [![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"
+Humane.human_size(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:
+mtime = Time.now - 180
+Humane.time_ago(mtime) # "3 minutes ago" -- relative to the real clock
 
-```ruby
-Humane::SizeFormatter.new.string(225_935) # "226 KB"
-time_formatter.string(Time.now - 180, Time.now) # "3 minutes ago"
+now = Time.now
+Humane.distance_in_time(mtime, now) # "3 minutes ago" -- explicit relative_to, for tests
 ```
 
-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"
-```
-
-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 +36,52 @@ or in a `Gemfile`:
 gem "humane"
 ```
 
-## Beyond Foundation's defaults
+## `distance_in_time` and `time_ago`
 
-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:
+Two entry points, same naming split as ActionView's own
+`distance_of_time_in_words`/`time_ago_in_words`:
 
-- `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).
+- **`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`.
+
+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.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
+  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`, both methods return 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.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
 
-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.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.6.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.6.0
+  version: 0.9.3
 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: []
@@ -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:
@@ -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: []

data/lib/humane/size_formatter.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Humane
-  # Formats byte counts the way Finder does: 1000-based math, capitalized unit labels.
-  class SizeFormatter
-    UNITS = %w[B 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
-
-      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
-      rounded = (from_byte_count / (1000.0**exponent) * 10).round / 10.0
-
-      if rounded < 10
-        format("%.1f %s", rounded, UNITS[exponent])
-      else
-        format("%.0f %s", rounded, UNITS[exponent])
-      end
-    end
-  end
-end

data/lib/humane/time_formatter.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-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 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
-
-      # 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