tins 1.61.0 → 1.62.0

data/lib/tins/duration.rb

@@ -1,74 +1,289 @@
 # frozen_string_literal: false
 
+require 'tins/enum_joined'
+
 module Tins
   # A class to represent durations with support for formatting and parsing time
   # intervals.
   class Duration
     include Comparable
 
-    # Returns the number of seconds represented by the given duration string
-    # according to the provided template format.
+    # Raised when a duration string cannot be parsed by any of the
+    # provided templates.
     #
-    # @param [String] string The duration string to parse.
-    # @param [String] template for the duration format, see {#format}.
-    #   Default: '%S%d+%h:%m:%s.%f'
+    # @see .parse
+    class ParserError < ArgumentError
+    end
+
+    # Resolves a {HUMAN_CONNECTORS} preset to its connector hash.
     #
-    # @return [Integer, Float] The number of (fractional) seconds of the duration.
+    # Shared by {#to_human} and {.parse_human} so that both
+    # accept the same +connector:+ keyword argument without
+    # duplicating the nil / Symbol / Hash dispatch.
     #
-    # @raise [ArgumentError] If the string doesn't match the expected template format
+    # @see HUMAN_CONNECTORS
+    # @see STYLE_DEFAULT_CONNECTOR
+    module ConnectorResolver
+      # Resolves a connector specification to a +Hash+ with keys
+      # +:words+, +:two_words+, and +:last_word+.
+      #
+      # @param connector [Symbol, Hash, nil] A preset name from
+      #   {HUMAN_CONNECTORS}, a custom hash, or +nil+ (derive from
+      #   +style+ via {STYLE_DEFAULT_CONNECTOR}).
+      # @param style [Symbol, Hash] The label style passed alongside,
+      #   used only when +connector+ is +nil+.
+      #
+      # @return [Hash] The resolved connector hash.
+      #
+      # @raise [ArgumentError] If +connector+ is neither +nil+, a
+      #   +Symbol+, nor a +Hash+.
+      #
+      # @see HUMAN_CONNECTORS
+      # @see STYLE_DEFAULT_CONNECTOR
+      def resolve_connector(connector, style)
+        case connector
+        when nil
+          key = style.is_a?(Symbol) ? style : :abbrev
+          HUMAN_CONNECTORS.fetch(STYLE_DEFAULT_CONNECTOR.fetch(key))
+        when Symbol then HUMAN_CONNECTORS.fetch(connector)
+        when Hash   then connector
+        else raise ArgumentError,
+          "connector must be a Symbol or Hash, got #{connector.class}"
+        end
+      end
+    end
+    private_constant :ConnectorResolver
+    include ConnectorResolver
+
+    # Built-in label styles for {#to_human}. Keys are the unit symbols
+    # (+:days+, +:hours+, +:minutes+, +:seconds+); values are the literal
+    # strings appended directly after each unit's numeric value.
     #
-    # @example Basic parsing
-    #   Tins::Duration.parse('6+05:04:03', template: '%S%d+%h:%m:%s') # => 536643
-    #   Tins::Duration.parse('6+05:04:03.21', template: '%S%d+%h:%m:%s.%f') # => 536643.21
+    # +:words+ uses spelled-out units (the default); +:abbrev+ uses
+    # single-letter suffixes. A caller may instead pass their own +Hash+ with the
+    # same keys to {#to_human} to override either built-in, e.g. for another
+    # language.
     #
-    # @example Parsing negative durations
-    #   Tins::Duration.parse('-6+05:04:03', template: '%S%d+%h:%m:%s') # => -536643
+    # @see #to_human
+    HUMAN_STYLES = {
+      abbrev: { days: 'd', hours: 'h', minutes: 'm', seconds: 's' }.freeze,
+      words:  {
+                days: ' days',   hours: ' hours',
+                minutes: ' minutes', seconds: ' seconds'
+              }.freeze
+    }.freeze
+
+    # Named connector presets for {#to_human} and {.parse_human}.
     #
-    # @example Custom template parsing
-    #   Tins::Duration.parse('05:04:03.21', template: '%h:%m:%s.%f') # => 18243.21
+    # Each entry maps to a +Hash+ with three keys:
+    # +:words+ (3+ items), +:two_words+ (exactly 2), and
+    # +:last_word+ (before the final item, 3+ only).
     #
-    # The parser supports the following directives in templates:
-    # - `%S` - Sign indicator (optional negative sign)
-    # - `%d` - Days component (integer)
-    # - `%h` - Hours component (integer)
-    # - `%m` - Minutes component (integer)
-    # - `%s` - Seconds component (integer)
-    # - `%f` - Fractional seconds component (decimal)
-    # - `%%` - Literal percent character
+    # +:none+ produces compact output (`"1m30s"`); +:spaces+
+    # separates with single spaces (`"1 minutes 30 seconds"`);
+    # +:prose+ uses grammatical connectors
+    # (`"1 minutes, and 30 seconds"`).
     #
-    # The parser is greedy and consumes as much of the input string as possible
-    # for each directive.
-    # If a directive expects a specific format but doesn't find it, an
-    # ArgumentError is raised.
-    def self.parse(string, template: '%S%d+%h:%m:%s.%f')
-      s, t  = string.to_s.dup, template.dup
-      d, sd = 0, 1
-      loop do
-        t.sub!(/\A(%[Sdhmsf%]|.)/) { |directive|
-          case directive
-          when '%S' then s.sub!(/\A-?/)   { sd *= -1 if _1 == ?-; '' }
-          when '%d' then s.sub!(/\A\d+/)  { d += 86_400 * _1.to_i; '' }
-          when '%h' then s.sub!(/\A\d+/)  { d += 3_600 * _1.to_i; '' }
-          when '%m' then s.sub!(/\A\d+/)  { d += 60 * _1.to_i; '' }
-          when '%s' then s.sub!(/\A\d+/)  { d += _1.to_i; '' }
-          when '%f' then s.sub!(/\A\d+/)  { d += Float(?. + _1); '' }
-          when '%%' then
-            if s[0] == ?%
-              s[0] = ''
-            else
-              raise "expected %s, got #{s.inspect}"
-            end
-          else
-            if directive == s[0]
-              s[0] = ''
+    # {#to_human} and {.parse_human} accept a +connector:+
+    # keyword argument that is either a +Symbol+ naming one of
+    # these presets or a +Hash+ with the three keys for
+    # full control. When +connector:+ is +nil+ (the default),
+    # the preset is derived from +style:+ via
+    # {STYLE_DEFAULT_CONNECTOR}.
+    #
+    # @see HUMAN_STYLES
+    # @see STYLE_DEFAULT_CONNECTOR
+    # @see #to_human
+    # @see .parse_human
+    HUMAN_CONNECTORS = {
+      none:   { words: '',  two_words: '',  last_word: ''  }.freeze,
+      spaces: { words: ' ', two_words: ' ', last_word: ' ' }.freeze,
+      prose:  {
+                words: ', ', two_words: ' and ', last_word: ', and '
+              }.freeze
+    }.freeze
+
+    # Maps each built-in {HUMAN_STYLES} key to its default
+    # {HUMAN_CONNECTORS} preset. Used when +connector:+ is
+    # not explicitly provided.
+    #
+    # @see HUMAN_CONNECTORS
+    # @see HUMAN_STYLES
+    STYLE_DEFAULT_CONNECTOR = { abbrev: :none, words: :prose }.freeze
+
+    class << self
+      include ConnectorResolver
+
+      # Parses a duration string against one or more templates,
+      # returning the total number of seconds.
+      #
+      # Templates are tried in order; the first one that matches wins.
+      # If no template matches, a {ParserError} is raised.
+      #
+      # @param [String] string The duration string to parse.
+      # @param [String, Array<String>, nil] template A single template
+      #   string, an array of template strings tried in order, or +nil+
+      #   (the built-in default `'%S%d+%h:%m:%s.%f'`).
+      #
+      # @return [Integer, Float] The number of (fractional) seconds.
+      #
+      # @raise [ParserError] If no template matches the string.
+      #
+      # @see #from_string
+      # @see #format
+      #
+      # @example Default template
+      #   Tins::Duration.parse('6+05:04:03')       # => 536643
+      #   Tins::Duration.parse('6+05:04:03.21')    # => 536643.21
+      #
+      # @example Parsing negative durations
+      #   Tins::Duration.parse('-6+05:04:03')      # => -536643
+      #
+      # @example Custom template
+      #   Tins::Duration.parse('05:04:03.21', template: '%h:%m:%s.%f')
+      #   # => 18243.21
+      #
+      # @example Multiple templates (first match wins)
+      #   Tins::Duration.parse('1m 30s',
+      #     template: [ '%m minutes %s seconds', '%S%d+%h:%m:%s.%f' ]
+      #   )
+      def parse(string, template: nil)
+        templates = Array(template).dup
+        templates.empty? and templates << '%S%d+%h:%m:%s.%f'
+        templates.each do |template|
+          result = parse_template(string, template:) and return result
+        rescue ParserError
+        end
+        raise ParserError, "#{string.inspect} did not match any of the " \
+          "templates in #{template.inspect}"
+      end
+
+      # Parses a duration string against a single template.
+      #
+      # Supported directives:
+      # - `%S` - Sign indicator (optional negative sign)
+      # - `%d` - Days component (integer)
+      # - `%h` - Hours component (integer)
+      # - `%m` - Minutes component (integer)
+      # - `%s` - Seconds component (integer)
+      # - `%f` - Fractional seconds component (decimal)
+      # - `%%` - Literal percent character
+      #
+      # The parser is greedy and consumes as much of the input string as
+      # possible for each directive. If a directive expects a specific
+      # format but doesn't find it, a {ParserError} is raised.
+      def parse_template(string, template:)
+        s, t  = string.to_s.dup, template.dup
+        d, sd = 0, 1
+        loop do
+          t.sub!(/\A(%[Sdhmsf%]|.)/) { |directive|
+            case directive
+            when '%S' then s.sub!(/\A-?/)   { sd *= -1 if _1 == ?-; '' }
+            when '%d' then s.sub!(/\A\d+/)  { d += 86_400 * _1.to_i; '' }
+            when '%h' then s.sub!(/\A\d+/)  { d += 3_600 * _1.to_i; '' }
+            when '%m' then s.sub!(/\A\d+/)  { d += 60 * _1.to_i; '' }
+            when '%s' then s.sub!(/\A\d+/)  { d += _1.to_i; '' }
+            when '%f' then s.sub!(/\A\d+/)  { d += Float(?. + _1); '' }
+            when '%%' then
+              if s[0] == ?%
+                s[0] = ''
+              else
+                raise ParserError, "expected %s, got #{s.inspect}"
+              end
             else
-              raise ArgumentError, "expected #{t.inspect}, got #{s.inspect}"
+              if directive == s[0]
+                s[0] = ''
+              else
+                raise ParserError, "expected #{t.inspect}, got #{s.inspect}"
+              end
             end
+            ''
+          } or break
+        end
+        sd * d
+      end
+      private :parse_template
+
+      # Creates a new {Duration} instance by parsing the given string
+      # with {#parse}.
+      #
+      # @param [String] string The duration string to parse.
+      # @param [String, nil] template for the duration format, see
+      #   {#format}. Default: +nil+ (falls back to the built-in format).
+      #
+      # @return [Duration] A new {Duration} instance.
+      #
+      # @raise [Duration::ParserError] If the string doesn't match the
+      #   expected template format.
+      #
+      # @see .parse
+      #
+      # @example Basic usage
+      #   Tins::Duration.from_string('6+05:04:03.21')
+      #   # => #<Tins::Duration: 6+05:04:03.210>
+      #
+      # @example Custom template
+      #   Tins::Duration.from_string('05:04:03', template: '%h:%m:%s')
+      #   # => #<Tins::Duration: 0+05:04:03.000>
+      def from_string(string, template: nil)
+        new(parse(string, template:))
+      end
+
+      # Parses a human-readable duration string (the inverse of {#to_human})
+      # and returns a new {Duration} instance.
+      #
+      # All 15 possible +to_human+ output shapes (every subset of 1–4 units,
+      # in canonical order) are generated as templates for the given +style+,
+      # joined with the supplied connectors, and tried in order against
+      # {#parse}. The first template that matches wins.
+      #
+      # @param [String] string The human-readable duration string.
+      # @param style [Symbol, Hash] Built-in label style (+:abbrev+ or
+      #   +:words+, see {HUMAN_STYLES}) or a custom +Hash+. Default: +:words+.
+      # @param connector [Symbol, Hash, nil] Connector preset
+      #   ({HUMAN_CONNECTORS}) or a custom +Hash+ with keys
+      #   +:words+, +:two_words+, +:last_word+.
+      #   Default: +nil+ (derived from +style:+).
+      #
+      # @return [Duration] A new {Duration} instance.
+      #
+      # @raise [ArgumentError] If +style+ is neither a +Symbol+ nor a +Hash+.
+      # @raise [ParserError] If no generated template matches the string.
+      #
+      # @see #to_human
+      # @see .parse
+      #
+      # @example Spelled-out units (default)
+      #   Tins::Duration.parse_human('1 minutes and 30 seconds')
+      #   # => #<Tins::Duration: 00:01:30>
+      #
+      # @example Abbreviated
+      #   Tins::Duration.parse_human('1m30s', style: :abbrev)
+      #   # => #<Tins::Duration: 00:01:30>
+      #
+      # @example Round-trip with #to_human
+      #   d = Tins::Duration.new(3725)
+      #   Tins::Duration.parse_human(d.to_human).to_f  # => 3725.0
+      def parse_human(string, style: :words, connector: nil)
+        labels =
+          case style
+          when Hash   then HUMAN_STYLES[:abbrev].merge(style)
+          when Symbol then HUMAN_STYLES.fetch(style)
+          else raise ArgumentError,
+            "style must be a Symbol or Hash, got #{style.class}"
           end
-          ''
-        } or break
+        conn = resolve_connector(connector, style)
+        units     = [ [ :days, '%d' ], [ :hours, '%h' ],
+                      [ :minutes, '%m' ], [ :seconds, '%s' ] ]
+        templates = (1..4).reverse_each.flat_map do |n|
+          units.combination(n).map do |combo|
+            parts = combo.map { |k, d| "#{d}#{labels[k]}" }
+                       .extend(EnumJoined)
+            parts.joined(**conn)
+          end
+        end
+        new(parse(string, template: templates))
       end
-      sd * d
     end
 
     # Initializes a new Duration object with the specified number of seconds.
@@ -91,9 +306,15 @@ module Tins
         }
     end
 
-    # Converts the original seconds value to a floating-point number.
+    # Returns the duration's magnitude in seconds as a floating-point
+    # number.
+    #
+    # A duration represents the time span between two points; the span
+    # itself is always non-negative. The sign is a direction qualifier,
+    # tracked separately — see {#negative?}.
     #
-    # @return [Float] the original seconds value as a floating-point number
+    # @return [Float] The magnitude of the duration in seconds.
+    #   Always non-negative.
     def to_f
       @original_seconds.to_f
     end
@@ -156,6 +377,74 @@ module Tins
       @fractional_seconds > 0
     end
 
+    # Returns a human-readable string representation of the duration.
+    # By default, uses spelled-out units (e.g. `1 minutes and 30 seconds`);
+    # pass +style: :abbrev+ for compact single-letter suffixes
+    # (e.g. `1m30s`), or pass your own +Hash+ keyed by the unit symbols
+    # (+:days+, +:hours+, +:minutes+, +:seconds+) for arbitrary wording.
+    #
+    # Fractional seconds are truncated (not rounded).
+    #
+    # @param max [Integer] Maximum number of time units to include,
+    #   starting from the largest. Default: +nil+ (all units).
+    # @param connector [Symbol, Hash, nil] Connector preset
+    #   ({HUMAN_CONNECTORS}) or a custom +Hash+ with keys
+    #   +:words+, +:two_words+, +:last_word+.
+    #   Default: +nil+ (derived from +style:+).
+    # @param style [Symbol, Hash] Built-in label style (+:abbrev+ or
+    #   +:words+, see {HUMAN_STYLES}) or a custom +Hash+ mapping the unit
+    #   symbols to label strings. A +Hash+ is merged onto the
+    #   +:abbrev+ defaults, so omitting a key keeps the single-letter label.
+    #   Default: +:words+.
+    #
+    # @raise [ArgumentError] If +style+ is neither a +Symbol+ nor a +Hash+.
+    #
+    # @return [String] Human-readable duration string.
+    #
+    # @see Tins::EnumJoined#joined
+    #
+    # @example Basic usage (default +:words+ style)
+    #   Tins::Duration.new(90).to_human
+    #   # => "1 minutes and 30 seconds"
+    #   Tins::Duration.new(3725).to_human
+    #   # => "1 hours, 2 minutes, and 5 seconds"
+    #   Tins::Duration.new(86_400).to_human  # => "1 days"
+    #   Tins::Duration.new(0).to_human       # => "0 seconds"
+    #
+    # @example Abbreviated units
+    #   Tins::Duration.new(90).to_human(style: :abbrev)
+    #   # => "1m30s"
+    #
+    # @example Custom labels (e.g. another language)
+    #   Tins::Duration.new(90).to_human(
+    #     style: { minutes: ' Min.', seconds: ' Sek.' }
+    #   )
+    #   # => "1 Min.30 Sek."
+    #
+    # @example Negative durations
+    #   Tins::Duration.new(-90).to_human
+    #   # => "-1 minutes and 30 seconds"
+    def to_human(max: nil, style: :words, connector: nil)
+      labels =
+        case style
+        when Hash   then HUMAN_STYLES[:abbrev].merge(style)
+        when Symbol then HUMAN_STYLES.fetch(style)
+        else raise ArgumentError,
+          "style must be a Symbol or Hash, got #{style.class}"
+        end
+      conn = resolve_connector(connector, style)
+      parts = [
+        [ @days, :days ], [ @hours, :hours ],
+        [ @minutes, :minutes ], [ @seconds, :seconds ]
+      ].select { |v, _| v > 0 }
+      parts << [ 0, :seconds ] if parts.empty?
+      parts  = parts.first(max) if max
+      items  = parts.map { |v, k| "#{v}#{labels[k]}" }
+               .extend(EnumJoined)
+      result = items.joined(**conn)
+      @negative ? "-#{result}" : result
+    end
+
     # Formats the duration according to the given template and precision.
     #
     # The template string supports the following directives:

data/lib/tins/enum_joined.rb

@@ -0,0 +1,68 @@
+module Tins
+  # Adds +joined+ to any +Enumerable+, providing human-friendly
+  # sentence-style joining with configurable connectors, similar
+  # to Rails' +Array#to_sentence+.
+  #
+  # @example Polite usage (include into your own class):
+  #   require 'tins/enum_joined'
+  #
+  #   class MyList
+  #     include Enumerable
+  #     include Tins::EnumJoined
+  #
+  #     def each
+  #       %w[foo bar baz].each { |x| yield x }
+  #     end
+  #   end
+  #
+  #   MyList.new.joined  # => "foo, bar, and baz"
+  #
+  # @example Rude usage (mixin into ::Enumerable globally):
+  #   require 'tins/xt/enum_joined'
+  #
+  #   [1, 2, 3].joined       # => "1, 2, and 3"
+  #   Set['a', 'b', 'c'].joined  # => "a, b, and c"
+  module EnumJoined
+    # Join all elements into a human-readable sentence.
+    #
+    # Uses three connectors, mirroring Rails' +Array#to_sentence+:
+    #
+    # | elements | connectors used               |
+    # |----------|-------------------------------|
+    # | 0        | (none) — returns `""`         |
+    # | 1        | (none) — returns the element  |
+    # | 2        | +two_words+                   |
+    # | 3+       | +words+ + +last_word+         |
+    #
+    # @param [String] words
+    #   Separator between all items except the last two.
+    #   Default: `', '`.
+    # @param [String] two_words
+    #   Separator between the only two items.
+    #   Default: `' and '`.
+    # @param [String] last_word
+    #   Separator before the last item (3+ items only).
+    #   Default: `', and '` (Oxford comma).
+    #
+    # @return [String] the joined sentence
+    #
+    # @example Default connectors
+    #   [1, 2].joined        # => "1 and 2"
+    #   [1, 2, 3].joined     # => "1, 2, and 3"
+    #
+    # @example Custom connectors
+    #   [1, 2, 3].joined(words: ' / ', last_word: ' / ')
+    #   # => "1 / 2 / 3"
+    def joined(words: ', ', two_words: ' and ', last_word: ', and ')
+      items = map(&:to_s)
+      case items.size
+      when 0 then ''
+      when 1 then items.first
+      when 2 then items.first + two_words + items.last
+      else
+        head, tail = items[0..-2], items.last
+        head.join(words) + last_word + tail
+      end
+    end
+  end
+end

data/lib/tins/enum_squeeze.rb

@@ -1,4 +1,37 @@
 module Tins
+  # Adds +squeeze+ and +squeeze!+ to any +Enumerable+, providing
+  # the same "collapse consecutive duplicates" semantics as
+  # +String#squeeze+ but for generic collections.
+  #
+  # Two elements are considered duplicates when +item == previous+.
+  # You can optionally restrict squeezing to a subset of elements by
+  # passing case-equality matchers (+===+) or a predicate block.
+  #
+  # @example Polite usage (include into your own class):
+  #   require 'tins/enum_squeeze'
+  #
+  #   class Repeater
+  #     include Enumerable
+  #     include Tins::EnumSqueeze
+  #
+  #     def each
+  #       [1, 1, 2, 2, 3].each { |i| yield i }
+  #     end
+  #   end
+  #
+  #   Repeater.new.squeeze  # => [1, 2, 3]
+  #
+  # @example Rude usage (mixin into ::Enumerable globally):
+  #   require 'tins/xt/enum_squeeze'
+  #
+  #   # Now any custom Enumerable gains squeeze/squeeze!:
+  #   enum = (1..5).to_a # Array already has its own #squeeze,
+  #   # so this is more useful for custom Enumerables:
+  #   class Repeater
+  #     include Enumerable
+  #     def each = [1, 1, 2, 2, 3].each { |i| yield i }
+  #   end
+  #   Repeater.new.squeeze  # => [1, 2, 3]
   module EnumSqueeze
     A_THING_THAT_IS_NOT_A_THING = Object.new.freeze
 

data/lib/tins/null.rb

@@ -22,7 +22,7 @@ module Tins
   #
   #   # You can use the null object:
   #   user = find_user(id) || Tins::NULL
-  #   user.name  # => "" (instead of nil)
+  #   user.name.to_s  # => "" (instead of nil)
   #
   # @example With NullPlus for debugging
   #   user = find_user(id) || Tins::NullPlus.new(value: "Unknown", caller: caller)

data/lib/tins/version.rb

@@ -1,6 +1,11 @@
+# Version information for the Tins gem.
+#
+# This module is auto-generated by GemHadar and exposes the
+# current release version as a set of constants. Do not edit it
+# by hand; it is rewritten on every `rake version` invocation.
 module Tins
-  # Tins version
-  VERSION         = '1.61.0'
+  # The current version of the Tins gem as a String.
+  VERSION         = '1.62.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/tins/xt/enum_joined.rb

@@ -0,0 +1,7 @@
+require 'tins/enum_joined'
+
+module Tins
+  module ::Enumerable
+    include EnumJoined
+  end
+end

data/lib/tins/xt.rb

@@ -45,4 +45,5 @@ module Tins
   require 'tins/xt/deep_transform'
   require 'tins/xt/minimize'
   require 'tins/xt/enum_squeeze'
+  require 'tins/xt/enum_joined'
 end