humane 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fb176a1cd9cc6c573a593535d45a97d2e64677c54c55726b647374a0213e8f06
+  data.tar.gz: 80474100589a2447566088e8fd5d0c4ea9eb232c7c2a1ebc7a054a7d802c539b
+SHA512:
+  metadata.gz: 4dd0a51d9b1571f64fdbab8e8708b9eaf5e018772fdf5d22bb0107eeaef8dcf778048046ab025f93e7d4c4dc7f6c51c344cb4efb2d9a35ad09a9adfec8d53acf
+  data.tar.gz: 7e190db93ce2f15afb477f207fc11519587da08bdcb684d46bd363c7756934579cac460b89364b42c5cbe1dea967d7052eba2d78e662a9114abbca010a60505f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Woodell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,53 @@
+# humane-ruby
+
+[![Ruby](https://img.shields.io/badge/Ruby-3.1-red.svg)](https://www.ruby-lang.org/)
+[![CI](https://github.com/woodie/humane-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/woodie/humane-ruby/actions/workflows/ci.yml)
+[![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)
+
+Swift's file sizes and relative dates for Ruby
+
+Finder-accurate file sizes and relative dates for Ruby, modeled on Swift's [`ByteCountFormatter`](https://developer.apple.com/documentation/foundation/bytecountformatter) and [`RelativeDateTimeFormatter`](https://developer.apple.com/documentation/foundation/relativedatetimeformatter) -- not literal ports (both are closed-source, and `TimeFormatter`'s wording is a deliberate departure), but the same idea: a small, configurable formatter object instead of a bare helper method.
+
+## Install
+
+```
+gem install humane
+```
+
+or in a `Gemfile`:
+
+```ruby
+gem "humane"
+```
+
+## Usage
+
+```ruby
+require "humane"
+
+size_formatter = Humane::SizeFormatter.new
+size_formatter.string(from_byte_count: 225_935) # "226 KB" -- 1000-based math,
+                                                  # capitalized units, matching
+                                                  # Finder, not Rails'
+                                                  # number_to_human_size (1024-
+                                                  # based despite the same label)
+
+time_formatter = Humane::TimeFormatter.new # collapse_minute: true
+time_formatter.string(at: scanned_at, relative_to: Time.now)
+# "3 minutes ago" / "3 minutes from now" / "less than a minute ago"
+```
+
+`Humane::TimeFormatter.new` uses `at:`, not `for:` -- Ruby's `for` is a
+reserved word, and while a `for:` keyword argument technically parses, reading
+it back out inside the method needs `binding.local_variable_get(:for)`. Not
+worth it just to match Swift's `localizedString(for:relativeTo:)` label
+literally.
+
+## Scope
+
+Only what lambada and scandalous actually need today: Finder's `.file`
+byte-count style, and a numeric (non-calendar-aware) relative time style.
+`ByteCountFormatter`'s `allowed_units`/alternate `count_style`s and
+`RelativeDateTimeFormatter`'s `:named` style (`"yesterday"`, calendar-
+boundary-aware) aren't implemented -- contributions welcome.

data/lib/humane/size_formatter.rb

@@ -0,0 +1,22 @@
+# 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.
+    def string(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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Humane
+  # Formats one time relative to another the way Finder-adjacent tools do, symmetric "X ago"/"X from now".
+  class TimeFormatter
+    # collapse_minute buckets anything under a minute as "less than a minute ago/from now". Defaults to true.
+    def initialize(collapse_minute: true)
+      @collapse_minute = collapse_minute
+    end
+
+    # Returns the time at `at` relative to `relative_to` as a human-readable string.
+    def string(at:, relative_to:)
+      seconds = relative_to - at
+      future = seconds.negative?
+      seconds = seconds.abs
+
+      if @collapse_minute && seconds < 60
+        return future ? "less than a minute from now" : "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
+
+      future ? "#{text} from now" : "#{text} ago"
+    end
+
+    private
+
+    def pluralize(count, unit)
+      count == 1 ? "1 #{unit}" : "#{count} #{unit}s"
+    end
+  end
+end

data/lib/humane/version.rb

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

data/lib/humane.rb

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

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: humane
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- John Woodell
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-07-08 00:00:00.000000000 Z
+dependencies: []
+description: Finder-accurate file sizes and relative dates for Ruby, modeled on Swift's
+  ByteCountFormatter and RelativeDateTimeFormatter.
+email:
+- woodie@netpress.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/humane.rb
+- lib/humane/size_formatter.rb
+- lib/humane/time_formatter.rb
+- lib/humane/version.rb
+homepage: https://github.com/woodie/humane-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/woodie/humane-ruby
+  source_code_uri: https://github.com/woodie/humane-ruby
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.5
+signing_key: 
+specification_version: 4
+summary: Swift's file sizes and relative dates for Ruby
+test_files: []