humane 0.2.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +44 -26
- data/lib/humane/time_formatter.rb +9 -5
- data/lib/humane/version.rb +1 -1
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 572a6a4a29165d48eec68db31af6cb222a88de6f989099d353811225898c4673
|
|
4
|
+
data.tar.gz: cfc60adb65c39694c156f7b173d053431d469ec26d1bf98a584c83b05bfc5887
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: baa6946270a2a9bcaa4636993324df9cae89da3ff2a753552bc21bcdc5569a9fe10075dc48e4e2e910a2f50d811ff324bf7e7ce59168c03025cc2f2157626d5e
|
|
7
|
+
data.tar.gz: 4dc6ee4899fe1ae32d33c36307a5a01bef49cf34fb368668b28bd584cae6bce38d9a00be13d9aef532020015d40f00375c1c9ad8299380882bdcc29935469f78
|
data/README.md
CHANGED
|
@@ -1,14 +1,37 @@
|
|
|
1
1
|
# humane-ruby
|
|
2
2
|
|
|
3
|
-
[](https://rubygems.org/gems/humane)
|
|
4
3
|
[](https://www.ruby-lang.org/)
|
|
5
4
|
[](https://github.com/woodie/humane-ruby/actions/workflows/ci.yml)
|
|
6
5
|
[](https://github.com/woodie/humane-ruby/releases/latest)
|
|
7
6
|
[](LICENSE)
|
|
8
7
|
|
|
9
|
-
|
|
8
|
+
Getting human-readable file sizes with 1000-based math
|
|
9
|
+
(as the Mac Finder displays) and relative times worded the way Swift's
|
|
10
|
+
`RelativeDateTimeFormatter` does turned out to be a real challenge to get
|
|
11
|
+
both right and simple. The `humane` library exists so a Ruby application can share
|
|
12
|
+
consistent size and time formatting with a Swift application, instead of
|
|
13
|
+
reaching for a library whose output doesn't match Swift's or that's
|
|
14
|
+
complicated to drop in.
|
|
10
15
|
|
|
11
|
-
|
|
16
|
+
```ruby
|
|
17
|
+
require "humane"
|
|
18
|
+
|
|
19
|
+
Humane::SizeFormatter.new.string(from_byte_count: 225_935) # "226 KB"
|
|
20
|
+
|
|
21
|
+
time_formatter = Humane::TimeFormatter.new
|
|
22
|
+
time_formatter.string(at: Time.now - 180, relative_to: Time.now) # "3 minutes ago"
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Corresponding functions in Swift will have consistent output.
|
|
26
|
+
|
|
27
|
+
```swift
|
|
28
|
+
import Foundation
|
|
29
|
+
|
|
30
|
+
ByteCountFormatter.string(fromByteCount: Int64(225935), countStyle: .file) // "226 KB"
|
|
31
|
+
|
|
32
|
+
let formatter = RelativeDateTimeFormatter(); formatter.unitsStyle = .full
|
|
33
|
+
formatter.localizedString(for: time, relativeTo: now) // "3 minutes ago"
|
|
34
|
+
```
|
|
12
35
|
|
|
13
36
|
## Install
|
|
14
37
|
|
|
@@ -22,33 +45,28 @@ or in a `Gemfile`:
|
|
|
22
45
|
gem "humane"
|
|
23
46
|
```
|
|
24
47
|
|
|
25
|
-
##
|
|
48
|
+
## Beyond Foundation's defaults
|
|
26
49
|
|
|
27
|
-
|
|
28
|
-
|
|
50
|
+
Two options on `Humane::TimeFormatter`, both off by default so it matches
|
|
51
|
+
`RelativeDateTimeFormatter` exactly out of the box:
|
|
29
52
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
53
|
+
- `include_seconds` (default `false`): below a minute, collapses to "less than a
|
|
54
|
+
minute ago"/"in less than a minute" instead of an exact second count. Named after
|
|
55
|
+
ActionView's `include_seconds`, which defaults the same way.
|
|
56
|
+
- `approximate` (default `false`): prefixes "about"/"in about" on buckets of an hour
|
|
57
|
+
or larger, the way ActionView's `distance_of_time_in_words` does past that same
|
|
58
|
+
boundary -- for a render that can't refresh itself and shouldn't overstate its own
|
|
59
|
+
precision.
|
|
36
60
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
#
|
|
61
|
+
```ruby
|
|
62
|
+
Humane::TimeFormatter.new(approximate: true).string(at: t - 15 * 3600, relative_to: t)
|
|
63
|
+
# => "about 15 hours ago"
|
|
40
64
|
```
|
|
41
65
|
|
|
42
|
-
`Humane::TimeFormatter.new` uses `at:`, not `for:` -- Ruby's `for` is a
|
|
43
|
-
reserved word, and while a `for:` keyword argument technically parses, reading
|
|
44
|
-
it back out inside the method needs `binding.local_variable_get(:for)`. Not
|
|
45
|
-
worth it just to match Swift's `localizedString(for:relativeTo:)` label
|
|
46
|
-
literally.
|
|
47
|
-
|
|
48
66
|
## Scope
|
|
49
67
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
`
|
|
53
|
-
|
|
54
|
-
|
|
68
|
+
Finder's `.file` byte-count style, and a numeric (non-calendar-aware)
|
|
69
|
+
relative time style -- that's the whole surface area today.
|
|
70
|
+
`allowed_units`/alternate `count_style`s and a `:named` style
|
|
71
|
+
(`"yesterday"`, calendar-boundary-aware) aren't implemented -- contributions
|
|
72
|
+
welcome.
|
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
module Humane
|
|
4
|
-
# Formats one time relative to another the way Finder-adjacent tools do
|
|
4
|
+
# Formats one time relative to another the way Finder-adjacent tools do.
|
|
5
5
|
class TimeFormatter
|
|
6
|
-
#
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
# 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.
|
|
7
|
+
# 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.
|
|
8
|
+
def initialize(include_seconds: false, approximate: false)
|
|
9
|
+
@include_seconds = include_seconds
|
|
10
|
+
@approximate = approximate
|
|
9
11
|
end
|
|
10
12
|
|
|
11
13
|
# Returns the time at `at` relative to `relative_to` as a human-readable string.
|
|
@@ -14,7 +16,7 @@ module Humane
|
|
|
14
16
|
future = seconds.negative?
|
|
15
17
|
seconds = seconds.abs
|
|
16
18
|
|
|
17
|
-
if
|
|
19
|
+
if !@include_seconds && seconds < 60
|
|
18
20
|
return future ? "in less than a minute" : "less than a minute ago"
|
|
19
21
|
end
|
|
20
22
|
|
|
@@ -29,6 +31,8 @@ module Humane
|
|
|
29
31
|
pluralize((seconds / 86_400.0).round, "day")
|
|
30
32
|
end
|
|
31
33
|
|
|
34
|
+
text = "about #{text}" if @approximate && seconds >= 3600
|
|
35
|
+
|
|
32
36
|
future ? "in #{text}" : "#{text} ago"
|
|
33
37
|
end
|
|
34
38
|
|
data/lib/humane/version.rb
CHANGED