tins 1.43.0 → 1.44.0

data/lib/tins/duration.rb

@@ -1,4 +1,8 @@
+# frozen_string_literal: false
+
 module Tins
+  # A class to represent durations with support for formatting and parsing time
+  # intervals.
   class Duration
     include Comparable
 
@@ -7,14 +11,37 @@ module Tins
     #
     # @param [String] string The duration string to parse.
     # @param [String] template for the duration format, see {#format}.
+    #   Default: '%S%d+%h:%m:%s.%f'
     #
     # @return [Integer, Float] The number of (fractional) seconds of the duration.
     #
-    # @example
+    # @raise [ArgumentError] If the string doesn't match the expected template format
+    #
+    # @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
+    #
+    # @example Parsing negative durations
+    #   Tins::Duration.parse('-6+05:04:03', template: '%S%d+%h:%m:%s') # => -536643
+    #
+    # @example Custom template parsing
+    #   Tins::Duration.parse('05:04:03.21', template: '%h:%m:%s.%f') # => 18243.21
+    #
+    # 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
+    #
+    # 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
+      s, t  = string.to_s.dup, template.dup
       d, sd = 0, 1
       loop do
         t.sub!(/\A(%[Sdhmsf%]|.)/) { |directive|
@@ -44,9 +71,13 @@ module Tins
       sd * d
     end
 
+    # Initializes a new Duration object with the specified number of seconds.
+    #
+    # @param seconds [ Integer, Float ] the total number of seconds to
+    # represent
     def initialize(seconds)
-      @negative = seconds < 0
-      seconds = seconds.abs
+      @negative         = seconds < 0
+      seconds           = seconds.abs
       @original_seconds = seconds
       @days, @hours, @minutes, @seconds, @fractional_seconds =
         [ 86_400, 3600, 60, 1, 0 ].inject([ [], seconds ]) {|(r, s), d|
@@ -60,40 +91,103 @@ module Tins
         }
     end
 
+    # Converts the original seconds value to a floating-point number.
+    #
+    # @return [Float] the original seconds value as a floating-point number
     def to_f
       @original_seconds.to_f
     end
 
+    # The <=> method compares this object with another object after converting
+    # both to floats.
+    #
+    # @param other [Object] the object to compare with
+    #
+    # @return [Integer] -1 if this object is less than other, 0 if they are
+    # equal, 1 if this object is greater than other
     def <=>(other)
       to_f <=> other.to_f
     end
 
+    # Returns true if the duration is negative.
+    #
+    # @return [TrueClass, FalseClass] true if the duration represents a
+    # negative time interval, false otherwise
     def negative?
       @negative
     end
 
+    # Returns true if the duration includes days, false otherwise.
+    #
+    # @return [TrueClass, FalseClass] true if the duration has any days, false
+    # otherwise
     def days?
       @days > 0
     end
 
+    # Returns true if the duration has any hours component
+    #
+    # @return [TrueClass, FalseClass] true if hours are present, false
+    # otherwise
     def hours?
       @hours > 0
     end
 
+    # Returns true if the duration has minutes, false otherwise.
+    #
+    # @return [TrueClass, FalseClass] true if minutes are greater than 0, false otherwise
     def minutes?
       @minutes > 0
     end
 
+    # Returns true if the duration has a positive seconds component.
+    #
+    # @return [TrueClass, FalseClass] true if seconds are greater than zero,
+    # false otherwise
     def seconds?
       @seconds > 0
     end
 
+    # Returns true if the duration includes fractional seconds.
+    #
+    # @return [TrueClass, FalseClass] true if fractional seconds are present,
+    # false otherwise
     def fractional_seconds?
       @fractional_seconds > 0
     end
 
+    # Formats the duration according to the given template and precision.
+    #
+    # The template string supports the following directives:
+    # - `%S` - Sign indicator (negative sign if duration is negative)
+    # - `%d` - Days component
+    # - `%h` - Hours component (zero-padded to 2 digits)
+    # - `%m` - Minutes component (zero-padded to 2 digits)
+    # - `%s` - Seconds component (zero-padded to 2 digits)
+    # - `%f` - Fractional seconds component (without the leading decimal point)
+    # - `%D` - Smart format (automatically includes days, fractional seconds, and sign)
+    # - `%%` - Literal percent character
+    #
+    # When using `%f`, the fractional part will be formatted according to the precision parameter.
+    #
+    # @param template [String] the format template to use for formatting
+    #   Default: '%S%d+%h:%m:%s.%f'
+    # @param precision [Integer] the precision to use for fractional seconds
+    #   When nil, uses default formatting with 6 decimal places
+    #
+    # @return [String] the formatted duration string
+    #
+    # @example Basic formatting
+    #   duration = Tins::Duration.new(93784.123)
+    #   duration.format('%d+%h:%m:%s.%f') # => "1+02:03:04.123000"
+    #
+    # @example Smart format
+    #   duration.format('%D') # => "1+02:03:04.123"
+    #
+    # @example Custom precision
+    #   duration.format('%s.%f', precision: 2) # => "04.12"
     def format(template = '%S%d+%h:%m:%s.%f', precision: nil)
-      result = template.gsub(/%[DdhmSs]/) { |directive|
+      result = template.gsub(/%[DdhmSs%]/) { |directive|
         case directive
         when '%S' then ?- if negative?
         when '%d' then @days
@@ -101,6 +195,7 @@ module Tins
         when '%m' then '%02u' % @minutes
         when '%s' then '%02u' % @seconds
         when '%D' then format_smart
+        when '%%' then '%'
         end
       }
       if result.include?('%f')
@@ -114,12 +209,32 @@ module Tins
       result
     end
 
+    # The to_s method returns a string representation of the duration by
+        # formatting it using the smart format method
+    #
+    # @return [String] the formatted duration string
     def to_s
       format_smart
     end
 
     private
 
+    # The format_smart method provides intelligent formatting based on the
+    # duration's components. It automatically determines which components are
+    # present and formats them accordingly, making it ideal for human-readable
+    # output where you want to avoid showing zero values.
+    #
+    # The smart format follows these rules:
+    # - If days are present, includes the day component (e.g., "1+02:03:04") -
+    # If fractional seconds are present, includes them with 3 decimal places
+    # (e.g., ".123")
+    # - If the duration is negative, includes the sign prefix
+    #
+    # This method is used internally by #to_s and can also be called directly
+    # for smart formatting using the %D directive.
+    #
+    # @return [String] a formatted duration string using intelligent component
+    # inclusion
     def format_smart
       template  = '%h:%m:%s'
       precision = nil

data/lib/tins/expose.rb

@@ -1,14 +1,63 @@
 module Tins
+  # A module that provides a way to expose private and protected methods for
+  # testing or debugging purposes.
+  #
+  # This module is particularly useful in test suites where you need to verify
+  # internal implementation details without making methods public, or for
+  # debugging complex object states during development.
+  #
+  # @example Basic method exposure
+  #   obj = MyClass.new
+  #   exposed_obj = obj.expose
+  #   exposed_obj.private_method  # Accessible now
+  #
+  # @example Direct method call
+  #   obj = MyClass.new
+  #   result = obj.expose(:private_method)
+  #   # Equivalent to: obj.private_method
+  #
+  # @example Block execution
+  #   obj = MyClass.new
+  #   obj.expose { self.private_method }
+  #
+  # @example Testing private methods
+  #   describe MyClass do
+  #     it "should handle edge cases" do
+  #       obj = MyClass.new
+  #       result = obj.expose(:private_calculation, arg1, arg2)
+  #       expect(result).to eq(expected_value)
+  #     end
+  #   end
+  #
+  # @note This module should only be used in test or debugging contexts.
+  #       Using it in production code can compromise encapsulation.
+  # @note Modifying the exposed object's state may affect the original object
+  #          since it operates on a duplicated instance.
   module Expose
     # Expose any (private/protected) method or internal state of this object
     # returning the result for specing purposes.
     #
-    # @param method_name [ Symbol | String ] name of the method
-    #                                        (shortcut for reader methods).
-    # @param block [ Proc ] any private/protected methods of the object can be
-    #                       called in this block.
+    # This method provides three distinct usage patterns:
     #
-    # @return [ Object ] result of the method or block call
+    # 1. **Method Call**: When given a method name, directly calls that method
+    #    and returns its result.
+    #
+    # 2. **Block Execution**: When given a block, evaluates the block in the
+    #    context of the object, allowing access to private/protected methods.
+    #
+    # 3. **Full Exposure**: When called without arguments, returns a duplicate
+    #    of the object with all private and protected methods exposed as public.
+    #
+    # @param method_name [Symbol, String, nil] name of the method to call,
+    #                                          or nil for full exposure
+    # @param args [Array] arguments to pass to the method when calling it
+    # @param block [Proc] block to execute in the context of the object
+    #
+    # @return [Object] result of the method call, block execution, or a new
+    #                  object with exposed methods (when called without args)
+    #
+    # @raise [NoMethodError] if method_name is given but doesn't exist
+    # @raise [ArgumentError] if both method_name and block are provided
     def expose(method_name = nil, *args, &block)
       if block
         instance_eval(&block)

data/lib/tins/extract_last_argument_options.rb

@@ -1,5 +1,14 @@
 module Tins
+  # Extracts the last argument from an array if it responds to to_hash
+  #
+  # This module provides a method to separate arguments into regular arguments
+  # and options (a hash) by checking if the last element responds to to_hash
   module ExtractLastArgumentOptions
+    # Extracts the last argument if it responds to to_hash and returns an array
+    # with the remaining elements and the extracted options hash.
+    #
+    # @return [Array<Object, Hash>] an array containing the sliced array and
+    # the extracted options hash
     def extract_last_argument_options
       last_argument = last
       if last_argument.respond_to?(:to_hash) and

data/lib/tins/file_binary.rb

@@ -1,37 +1,76 @@
 module Tins
+  # A module for detecting and analyzing binary files based on content patterns
+  #
+  # This module provides functionality to determine whether a file contains
+  # binary data by examining its content against various thresholds for
+  # null bytes and high-order bits. It's useful for identifying files that
+  # are not plain text, such as images, executables, or other binary formats.
+  #
+  # The detection is performed by scanning a specified portion of the file
+  # and calculating the percentage of bytes that match binary criteria.
   module FileBinary
+    # Constants used for binary detection logic
     module Constants
+      # Seek constant for absolute positioning
       SEEK_SET = ::File::SEEK_SET
 
-      ZERO_RE   = "\x00"
-      BINARY_RE = "\x01-\x1f\x7f-\xff"
+      # Regular expression matching null bytes (zero bytes)
+      ZERO_RE   = +"\x00"
 
+      # Regular expression matching binary bytes (high-order bits set)
+      BINARY_RE = +"\x01-\x1f\x7f-\xff"
+
+      # Ensure proper encoding for Ruby 1.9+
       if defined?(::Encoding)
         ZERO_RE.force_encoding(Encoding::ASCII_8BIT)
         BINARY_RE.force_encoding(Encoding::ASCII_8BIT)
       end
     end
 
+    # Default configuration options for binary detection
     class << self
-      # Default options can be queried/set via this hash.
+      # Accessor for default options hash
       attr_accessor :default_options
     end
+
+    # Configuration hash with sensible defaults for binary file detection
     self.default_options = {
+      # Starting offset for scanning file content
       offset:            0,
-      buffer_size:       2 ** 13,
+
+      # Buffer size in bytes for reading file content
+      buffer_size:       2 ** 13,  # 8KB
+
+      # Percentage threshold for binary bytes (high-order bits set)
       percentage_binary: 30.0,
+
+      # Percentage threshold for null bytes (zeros)
       percentage_zeros:  0.0,
     }
 
-    # Returns true if this file is considered to be binary, false if it is not
-    # considered to be binary, and nil if it was empty.
+    # Determines if a file is considered binary based on content analysis
+    #
+    # A file is classified as binary if either:
+    # 1. The percentage of null bytes exceeds the configured threshold
+    # 2. The percentage of binary bytes (bytes with high-order bit set) exceeds
+    #    the configured threshold
+    #
+    # @param options [Hash] Configuration options for binary detection
+    # @option options [Integer] :offset (0) Starting position in file to begin analysis
+    # @option options [Integer] :buffer_size (8192) Number of bytes to read for analysis
+    # @option options [Float] :percentage_binary (30.0) Binary byte threshold percentage
+    # @option options [Float] :percentage_zeros (0.0) Null byte threshold percentage
+    #
+    # @return [Boolean, nil] true if binary, false if not binary, nil if file is empty
+    #
+    # @example Basic usage
+    #   FileBinary.binary?('large_binary_file.dat')  # => true
     #
-    # A file is considered to be binary if the percentage of zeros exceeds
-    # <tt>options[:percentage_zeros]</tt> or the percentage of binary bytes
-    # (8-th bit is 1) exceeds <tt>options[:percentage_binary]</tt> in the
-    # buffer of size <tt>options[:buffer_size]</tt> that is checked (beginning
-    # from offset <tt>options[:offset]</tt>). If an option isn't given the one
-    # from FileBinary.default_options is used instead.
+    # @example Custom thresholds
+    #   FileBinary.binary?('file.txt', percentage_binary: 10.0)  # => false
+    #
+    # @example With offset and buffer size
+    #   FileBinary.binary?('file.log', offset: 1024, buffer_size: 4096)  # => true
     def binary?(options = {})
       options = FileBinary.default_options.merge(options)
       old_pos = tell
@@ -47,9 +86,21 @@ module Tins
       old_pos and seek old_pos, Constants::SEEK_SET
     end
 
-    # Returns true if FileBinary#binary? returns false, false if
-    # FileBinary#binary? returns true, and nil otherwise. For an explanation of
-    # +options+, see FileBinary#binary?.
+    # Returns the logical opposite of binary? - true if file is not binary (ASCII/text)
+    #
+    # @param options [Hash] Configuration options for ASCII detection
+    # @option options [Integer] :offset (0) Starting position in file to begin analysis
+    # @option options [Integer] :buffer_size (8192) Number of bytes to read for analysis
+    # @option options [Float] :percentage_binary (30.0) Binary byte threshold percentage
+    # @option options [Float] :percentage_zeros (0.0) Null byte threshold percentage
+    #
+    # @return [Boolean, nil] true if ASCII/text, false if binary, nil if file is empty
+    #
+    # @example Basic usage
+    #   FileBinary.ascii?('script.rb')  # => true
+    #
+    # @example With custom options
+    #   FileBinary.ascii?('data.bin', percentage_zeros: 5.0)  # => false
     def ascii?(options = {})
       case binary?(options)
       when true   then false
@@ -57,6 +108,9 @@ module Tins
       end
     end
 
+    # Module inclusion hook that extends the including class with ClassMethods
+    #
+    # @param modul [Module] The module that is including FileBinary
     def self.included(modul)
       modul.instance_eval do
         extend ClassMethods
@@ -64,20 +118,49 @@ module Tins
       super
     end
 
+    # Class methods that provide file-level binary detection capabilities
+    #
+    # These methods allow binary detection without manually opening files
     module ClassMethods
-      # Returns true if the file with name +name+ is considered to be binary
-      # using the FileBinary#binary? method.
+      # Determines if a file is considered binary by name
+      #
+      # @param name [String] Path to the file to analyze
+      # @param options [Hash] Configuration options for binary detection
+      # @option options [Integer] :offset (0) Starting position in file to begin analysis
+      # @option options [Integer] :buffer_size (8192) Number of bytes to read for analysis
+      # @option options [Float] :percentage_binary (30.0) Binary byte threshold percentage
+      # @option options [Float] :percentage_zeros (0.0) Null byte threshold percentage
+      #
+      # @return [Boolean, nil] true if binary, false if not binary, nil if file is empty
+      #
+      # @example Basic usage
+      #   FileBinary.binary?('config.json')  # => false
+      #
+      # @example With custom options
+      #   FileBinary.binary?('data.dat', percentage_binary: 25.0)  # => true
       def binary?(name, options = {})
         open(name, 'rb') { |f| f.binary?(options) }
       end
 
-      # Returns true if the file with name +name+ is considered to be ascii
-      # using the FileBinary#ascii? method.
+      # Determines if a file is considered ASCII/text by name
+      #
+      # @param name [String] Path to the file to analyze
+      # @param options [Hash] Configuration options for ASCII detection
+      # @option options [Integer] :offset (0) Starting position in file to begin analysis
+      # @option options [Integer] :buffer_size (8192) Number of bytes to read for analysis
+      # @option options [Float] :percentage_binary (30.0) Binary byte threshold percentage
+      # @option options [Float] :percentage_zeros (0.0) Null byte threshold percentage
+      #
+      # @return [Boolean, nil] true if ASCII/text, false if binary, nil if file is empty
+      #
+      # @example Basic usage
+      #   FileBinary.ascii?('readme.md')  # => true
+      #
+      # @example With custom options
+      #   FileBinary.ascii?('binary_file.dat', percentage_zeros: 10.0)  # => false
       def ascii?(name, options = {})
         open(name, 'rb') { |f| f.ascii?(options) }
       end
     end
   end
 end
-
-require 'tins/alias'