pixar-ruby-extensions 1.11.1

data/lib/pixar_ruby_extensions/integer/utils.rb

@@ -0,0 +1,187 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+module PixarRubyExtensions
+
+  module IntegerExtensions
+
+    module Utils
+
+      # Array for processing pix_humanize_secs.
+      # How many weeks in a year??
+      # first, given the Gregorian calendar, how many days in 1000 years?
+      #   365000 days if all are common years
+      #  +250    cuz every 4th year is a leap year
+      #  - 7     cuz centuries are only leap years if divisble by 400
+      #            so there are only 3, not 10
+      #  = 365243
+      #
+      #  and there are 7 days per week, so in 1000 years, a week averages to
+      #  365243 / 7
+      #  = 5217.7571428571426 weeks per 1000 years
+      #  = 52.177571428571426 weeks per year
+
+      HUMANIZE_SECS_ARRAY = [
+        [60, :seconds, :second],
+        [60, :minutes, :minute],
+        [24, :hours, :hour],
+        [7, :days, :day],
+        [52.1776, :weeks, :week],
+        [100, :years, :year],
+        [10, :centuries, :century],
+        [Float::INFINITY, :millenia, :millenium]
+      ].freeze
+
+      # Very handy!
+      # Converts an integer number of seconds into a English string, like so:
+      #
+      #    123456789.humanize_secs
+      #    # => "3 years 47 weeks 0 days 21 hours 33 minutes 9 seconds"
+      #
+      # Idea credits to:
+      # Mladen Jablanović at
+      # http://stackoverflow.com/questions/4136248/how-to-generate-a-human-readable-time-range-using-ruby-on-rails
+      #
+      # And:
+      # Jonathan Simmons at
+      # https://gist.github.com/jonathansimmons/24fa43ac6ee53819fb93
+      #
+      # @param omit_zeros [Boolean] If true, units with a value of zero, like '0 weeks' or
+      #   '0 hours' will be omitted, so the output of calling this on the 123456789 example above
+      #   would be "3 years 47 weeks 21 hours 33 minutes 9 seconds". Default is false
+      #
+      # @param down_to [Symbol]  One of :seconds, :minutes, :hours, :days, :weeks, :years,
+      #   :centuries, :millenia
+      #   Only include time units down-to and including this one. Default is :seconds
+      #   NOTE: output is truncated not rounded. In the example here, you lose all info
+      #   about the 21 hrs, 33 min, and 9 secs, and just see '0 days'
+      #   @example:
+      #      123456789.pix_humanize_secs
+      #      # => "3 years 47 weeks 0 days 21 hours 33 minutes 9 seconds"
+      #
+      #      123456789.pix_humanize_secs down_to: :days
+      #      # => "3 years 47 weeks 0 days"
+      #
+      # @param up_to [Symbol]  One of :seconds, :minutes, :hours, :days, :weeks, :years,
+      #   :centuries, :millenia
+      #   Only include time units up-to and including this one. Default is :years.
+      #   @example:
+      #      44567789123.pix_humanize_secs
+      #      # => "1412 years 13 weeks 0 days 21 hours 25 minutes 23 seconds"
+      #
+      #      44567789123.pix_humanize_secs up_to: :millenia
+      #      # => "1 millenium 4 centuries 12 years 13 weeks 0 days 21 hours 25 minutes 23 seconds"
+      #
+      # @return [String] The integer number of seconds, expressed in descending English time units
+      #
+      def pix_humanize_secs(omit_zeros: false, down_to: :seconds, up_to: :years, fraction: nil)
+        # initialize values for our loop
+        remaining_next_unit = self
+        down_to_this_unit = false
+        up_to_this_unit = false
+
+        output_array = HUMANIZE_SECS_ARRAY.map do |count, current_unit, singular|
+          unit_names = [current_unit, singular]
+          # puts "START: starting next unit: #{current_unit}, remaining_next_unit: #{remaining_next_unit}"
+
+          # stop when or integer hits zero
+          next unless remaining_next_unit.positive?
+
+          # stop if we've hit our up_to unit
+          next if up_to_this_unit
+
+          if unit_names.include?(up_to)
+            up_to_this_unit = true
+            current_unit_count = remaining_next_unit
+          else
+            remaining_next_unit, current_unit_count = remaining_next_unit.divmod(count)
+          end
+
+          # puts "MID: current_unit: #{current_unit}, current_unit_count: #{current_unit_count}, remaining_next_unit: #{remaining_next_unit}"
+
+          # skip if we are below our down_to unit
+          down_to_this_unit ||= unit_names.include?(down_to)
+          next unless down_to_this_unit
+
+          display_current_unit_count = current_unit_count.to_i
+          # if we are processing 'seconds' and there is a fraction, append it to the seconds
+          display_current_unit_count += "0.#{fraction}".to_f if current_unit == :seconds && fraction
+
+          next if omit_zeros && display_current_unit_count.zero?
+
+          display_name = display_current_unit_count == 1 ? singular : current_unit
+
+          "#{display_current_unit_count} #{display_name}"
+        end # map
+
+        output_array.compact.reverse.join ' '
+      end
+
+      A_BYTE = 1
+      B_BYTES = 1.0
+      KB_BYTES = B_BYTES * 1024
+      MB_BYTES = KB_BYTES * 1024
+      GB_BYTES = MB_BYTES * 1024
+      TB_BYTES = GB_BYTES * 1024
+      PB_BYTES = TB_BYTES * 1024
+
+      HUMANIZED_BYTE_UNITS = {
+        A_BYTE => 'byte',
+        B_BYTES => 'bytes',
+        KB_BYTES => 'KiB',
+        MB_BYTES => 'MiB',
+        GB_BYTES => 'GiB',
+        TB_BYTES => 'TiB',
+        PB_BYTES => 'PiB'
+      }.freeze
+
+      # A number of bytes converted into a string showing
+      # KibiBytes, Mebibytes, etc up to Pebibytes, with 2
+      # decimal places of precision.
+      #
+      # Returns a string with the unit in the form 'MiB'
+      # unless < 1KiB, in which case 'byte(s)'
+      # For 76253886 bytes this will return "72.72 MiB"
+      #
+      # @return [String] The human-readable file size.
+      #######
+      def pix_humanize_bytes
+        bytes = self
+        if bytes < KB_BYTES
+          hsize = bytes
+          unit =  bytes == A_BYTE ? HUMANIZED_BYTE_UNITS[A_BYTE] : HUMANIZED_BYTE_UNITS[B_BYTES]
+
+        elsif bytes < MB_BYTES
+          hsize = (bytes / KB_BYTES).round(2)
+          unit = HUMANIZED_BYTE_UNITS[KB_BYTES]
+
+        elsif bytes < GB_BYTES
+          hsize = (bytes / MB_BYTES).round(2)
+          unit = HUMANIZED_BYTE_UNITS[MB_BYTES]
+
+        elsif bytes < TB_BYTES
+          hsize = (bytes / GB_BYTES).round(2)
+          unit = HUMANIZED_BYTE_UNITS[GB_BYTES]
+
+        elsif bytes < PB_BYTES
+          hsize = (bytes / TB_BYTES).round(2)
+          unit = HUMANIZED_BYTE_UNITS[TB_BYTES]
+
+        else
+          hsize = (bytes / PB_BYTES).round(2)
+          unit =  HUMANIZED_BYTE_UNITS[PB_BYTES]
+
+        end
+
+        "#{hsize} #{unit}"
+      end
+
+    end # module
+
+  end # module
+
+end # module

data/lib/pixar_ruby_extensions/integer.rb

@@ -0,0 +1,14 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+require 'pixar_ruby_extensions/integer/utils'
+
+class Integer
+
+  include PixarRubyExtensions::IntegerExtensions::Utils
+
+end

data/lib/pixar_ruby_extensions/ipaddr/predicates.rb

@@ -0,0 +1,50 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+module PixarRubyExtensions
+
+  module IPAddrExtensions
+
+    module Predicates
+
+      # Handy when you don't know if a value is a String or an IPAddr
+      #
+      # Does not start with pix_ so that you can call it on
+      # either a String or an IPAddr
+      #
+      # Because it doesn't start with pix_ we are only
+      # adding this if it doesn't already exist as an
+      # instance method
+      unless IPAddr.instance_methods.include? :start_with?
+
+        def start_with?(str)
+          to_s.start_with? str
+        end
+
+      end
+
+      # Handy when you don't know if a value is a String or an IPAddr
+      #
+      # Does not start with pix_ so that you can call it on
+      # either a String or an IPAddr
+      #
+      # Because it doesn't start with pix_ we are only
+      # adding this if it doesn't already exist as an
+      # instance method
+      unless IPAddr.instance_methods.include? :end_with?
+
+        def end_with?(str)
+          to_s.end_with? str
+        end
+
+      end
+
+    end # module
+
+  end # module
+
+end # module

data/lib/pixar_ruby_extensions/ipaddr/utils.rb

@@ -0,0 +1,77 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+module PixarRubyExtensions
+
+  module IPAddrExtensions
+
+    module Utils
+
+      # Convert starting and ending IPv4 IP addresses (either Strings or IPAddrs)
+      # into a single masked IPv4 IPAddr
+      #
+      # @param starting[Strings, IPAddr] the starting IP address
+      #
+      # @param ending[Strings, IPAddr] the ending IP address
+      #
+      # @return [IPAddr] the IP address range represented as a masked IPv4 address
+      #
+      # @example
+      #   IPAddr.j_masked_v4addr '10.0.0.0', '10.0.0.255' # => #<IPAddr: IPv4:10.0.0.0/255.255.255.0>
+      #
+      def pix_masked_v4addr(starting, ending)
+        IPAddr.new "#{starting}/#{j_cidr_from_ends(starting, ending)}"
+      end # self.j_masked_v4addr(starting,ending)
+
+      # Given starting and ending IPv4 IP addresses (either Strings or IPAddrs)
+      # return the CIDR notation routing prefix mask
+      #
+      # @param starting[Strings, IPAddr] the starting IP address
+      #
+      # @param ending[Strings, IPAddr] the ending IP address
+      #
+      # @return [FixNum] the CIDR notation routing prefix mask
+      #
+      # @example
+      #   IPAddr.j_cidr_from_ends '10.0.0.0', '10.0.0.255' # => 24
+      #
+      def pix_cidr_from_ends(starting, ending)
+        starting = IPAddr.new(starting) unless starting.is_a? IPAddr
+        ending = IPAddr.new(ending) unless ending.is_a? IPAddr
+
+        # how many possible addresses in the range?
+        num_addrs = ending.to_i - starting.to_i + 1
+
+        # convert the number of possible addresses to
+        # binary then subtract the number of bits from
+        # the full length of an IPv4 addr
+        # (32 bits) and that gives the CIDR prefix
+        32 - num_addrs.to_s(2).length + 1
+      end # self.get_cidr(starting,ending)
+
+      # Convert a starting address (either String or IPAddr) and a
+      # CIDR notation routing prefix mask into the IPv4 address
+      # of at the end of the range of addresses.
+      #
+      # @param starting[Strings, IPAddr] the starting IP address
+      #
+      # @param cidr[FixNum] the CIDR mask
+      #
+      # @return [IPAddr] the ending IP address of the range.
+      #
+      # @example
+      #   IPAddr.j_ending_address '10.0.0.0', 24 # => #<IPAddr: IPv4:10.0.0.255>
+      #
+      def pix_ending_address(starting, cidr)
+        IPAddr.new("#{starting}/#{cidr}").to_range.max
+      end # ending_address
+
+    end # module
+
+  end # module
+
+end # module

data/lib/pixar_ruby_extensions/ipaddr.rb

@@ -0,0 +1,20 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'pixar_ruby_extensions/ipaddr/utils'
+require 'pixar_ruby_extensions/ipaddr/predicates'
+
+############################################
+# A few augmentations to IPAddr handling.
+#
+class IPAddr
+
+  extend PixarRubyExtensions::IPAddrExtensions::Utils
+  include PixarRubyExtensions::IPAddrExtensions::Predicates
+
+end # Class IPAddr

data/lib/pixar_ruby_extensions/json/jsonl.rb

@@ -0,0 +1,50 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+module PixarRubyExtensions
+
+  module JSONExtensions
+
+    # Add support for jsonlines (.jsonl) files
+    # See https://jsonlines.org/
+    #
+    # See also Array#pix_to_jsonl
+    #
+    module JSONL
+
+      # Read a jsonlines file and return an array of objects, with the addition of
+      # ignoring comment lines, as with JSONExtensions::Utils#pix_parse
+      #
+      # @param source [String] the string of JSON to be parsed
+      #
+      # @param comment_string [String] the string that marks the start
+      #   of a comment line, possibly with leading whitespace. Default is '#'
+      #
+      # @return [Object] The parsed JSON
+      ####################
+      def pix_parse_jsonl(source, comment_string: '#', **opts)
+        src = pix_strip_comments(source, comment_string: comment_string)
+        src.split("\n").map { |line| JSON.parse(line, **opts) }
+      end
+
+      # Generate a jsonlines string from an array of objects.
+      #
+      # @param objects [Array<Object>] the objects to be turned into jsonlines
+      #
+      # @return [String] The jsonlines string
+      ####################
+      def pix_generate_jsonl(objects, **opts)
+        raise TypeError, "Expected an Array, got a #{objects.class}" unless objects.is_a? Array
+
+        objects.map { |obj| JSON.generate(obj, **opts) }.join("\n")
+      end
+
+    end # module
+
+  end # class
+
+end # module

data/lib/pixar_ruby_extensions/json/utils.rb

@@ -0,0 +1,78 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+module PixarRubyExtensions
+
+  module JSONExtensions
+
+    module Utils
+
+      # The same as JSON.parse, except whole-line comments are
+      # stripped from source before its parsed.
+      #
+      # Comment lines start with zero or more whitespace followed
+      # by the comment string, which by default is '#' but you
+      # can pass in others, such as '--'
+      #
+      # NOTE: Even though the JSON standard does not include
+      # support for comments, apprarently the Ruby JSON.parse
+      # method does honor '//' comments. I only discovered that
+      # when testing this method.
+      # I'm leaving it here though because we already use #
+      # comments, and that's the kind that YAML uses
+      #
+      # This command doesn't support or recognize in-line comments
+      # only whole-line comments.
+      #
+      # See JSON.parse for the standard opts and return value
+      #
+      # @param source [String] the string of JSON to be parsed
+      #
+      # @param comment_string [String] the string that marks the start
+      #   of a comment line, possibly with leading whitespace.
+      #
+      # @return [Object] The parsed JSON
+      #
+      def pix_parse(source, comment_string: '#', **opts)
+        src = pix_strip_comments(source, comment_string: comment_string)
+        JSON.parse src, **opts
+      end
+
+      # See pix_parse and JSON.parse!
+      def pix_parse!(source, comment_string: '#', **opts)
+        src = pix_strip_comments(source, comment_string: comment_string)
+        JSON.parse! src, **opts
+      end
+
+      # See pix_parse and JSON.load_file
+      def pix_load_file(filespec, comment_string: '#', **opts)
+        pix_parse File.read(filespec), comment_string: comment_string, **opts
+      end
+
+      # See pix_parse and JSON.load_file!
+      def pix_load_file!(filespec, comment_string: '#', **opts)
+        pix_parse! File.read(filespec), comment_string: comment_string, **opts
+      end
+
+      # remove comment lines from a string
+      #
+      # @param source [String] the string from which to remove comment lines
+      #
+      # @param comment_string [String] the string that marks the
+      #   start of a commend line, possibly with leading whitespce
+      #
+      # @return [String] the string with comment lines removed.
+      #
+      def pix_strip_comments(source, comment_string: '#')
+        source.lines.reject { |l| l =~ /^\s*#{comment_string}/ }.join
+      end
+
+    end # module
+
+  end # class
+
+end # module

data/lib/pixar_ruby_extensions/json.rb

@@ -0,0 +1,17 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+require 'json'
+require 'pixar_ruby_extensions/json/utils'
+require 'pixar_ruby_extensions/json/jsonl'
+
+module JSON
+
+  extend PixarRubyExtensions::JSONExtensions::Utils
+  extend PixarRubyExtensions::JSONExtensions::JSONL
+
+end

data/lib/pixar_ruby_extensions/object/predicates.rb

@@ -0,0 +1,49 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+module PixarRubyExtensions
+
+  module ObjectExtensions
+
+    module Predicates
+
+      BOOLEANS = [true, false].freeze
+
+      # is an object an explict true or false?
+      #
+      # @return [Boolean]
+      #
+      def pix_boolean?
+        BOOLEANS.include? self
+      end
+      alias pix_bool? pix_boolean?
+
+      # Is an object nil, or empty?
+      #
+      # Handier, and broader, than constantly doing
+      # var.to_s.empty? and doesn't require coercion
+      #
+      # @return [Boolean]
+      #
+      def pix_empty?
+        if nil?
+          true
+        elsif respond_to?(:empty?)
+          empty?
+        else
+          false
+        end
+      end
+
+      # pix_empty? was originally pix_blank?
+      alias pix_blank? pix_empty?
+
+    end # module
+
+  end # module
+
+end # module

data/lib/pixar_ruby_extensions/object.rb

@@ -0,0 +1,15 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+require 'pixar_ruby_extensions/object/predicates'
+
+# include the modules loaded above
+class Object
+
+  include PixarRubyExtensions::ObjectExtensions::Predicates
+
+end

data/lib/pixar_ruby_extensions/pathname/predicates.rb

@@ -0,0 +1,38 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+module PixarRubyExtensions
+
+  module PathnameExtensions
+
+    module Predicates
+
+      # Is this a real file rather than a symlink?
+      # @see FileTest.pix_real_file?
+      def pix_real_file?
+        FileTest.pix_real_file? self
+      end
+
+      # Is this a real directory rather than a symlink?
+      # @see FileTest.pix_real_directory?
+      def pix_real_directory?
+        FileTest.pix_real_directory? self
+      end
+
+      # does a path include another?
+      # i.e. is 'other' a descendant of self ?
+      def pix_include?(other)
+        eps = expand_path.to_s
+        oeps = other.expand_path.to_s
+        oeps != eps && oeps.start_with?(eps)
+      end
+
+    end # module
+
+  end # module
+
+end # module