pixar-ruby-extensions 1.11.1

data/lib/pixar_ruby_extensions/pathname/utils.rb

@@ -0,0 +1,139 @@
+# 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 Utils
+
+      require 'fileutils'
+
+      # Copy a path to a destination
+      # @see FileUtils.cp
+      def pix_cp(dest, **options)
+        FileUtils.cp @path, dest.to_s, **options
+      end # cp
+
+      # Recursively copy this path to a destination
+      # @see FileUtils.cp_r
+      def pix_cp_r(dest, **options)
+        FileUtils.cp_r @path, dest.to_s, **options
+      end # cp
+
+      # Write some string content to a file.
+      #
+      # Simpler than always using an open('w') block
+      #
+      # *CAUTION* this overwrites files!
+      #
+      def pix_save(content)
+        self.open('w') { |f| f.write content.to_s }
+      end
+
+      # Append some string content to a file.
+      #
+      # Simpler than always using an open('a') block
+      #
+      def pix_append(content)
+        self.open('a') { |f| f.write content.to_s }
+      end
+
+      # Not sure why this isn't in Pathname to begin with
+      #
+      # @see FileUtils.touch
+      def pix_touch
+        FileUtils.touch @path
+      end
+
+      # Pathname should use FileUtils.chown, not File.chown, its friendlier
+      def pix_chown(usr, grp)
+        FileUtils.chown usr, grp, @path
+      end
+
+      # Pathnames often need to be escaped for the shell
+      def pix_shellescape
+        require 'shellwords'
+        to_s.shellescape
+      end
+
+      # This allows us to write out to a file which many other
+      # threads or processes are reading, and not worry about
+      # them reading a partial file.
+      # It does so by writing into a temp file in the same directory,
+      # then renaming the file into the path `self`
+      #
+      # NOTE: There is much discussion online about the atomicity of
+      # unix 'rename' but in general as long as you're dealing with
+      # a single file, not a directory, and you are not moving it across
+      # filesystems, then yes, it will be atomic.
+      #
+      # WARNING: This will overwrite the current file.
+      #
+      # @param data [String] the data to write into the file.
+      #
+      # @return [void]
+      #
+      def pix_atomic_write(data)
+        raise "#{self} is a directory" if directory?
+
+        require 'tempfile'
+        tmpf = Pathname.new Tempfile.create(
+          ['.atomic_write', '.tmp'],
+          parent.to_s
+        )
+
+        if file?
+          ostat = stat
+          mode = ostat.mode
+          uid = ostat.uid
+          gid = ostat.gid
+        else
+          mode = 0o644
+          uid = nil
+          gid = nil
+        end
+
+        tmpf.chmod mode
+        tmpf.pix_chown(uid, gid) if uid && gid
+
+        tmpf.open('w+') { |f| f.write data }
+        tmpf.rename self
+      ensure
+        tmpf.delete if tmpf && tmpf.file?
+      end # end atomic_write
+
+      # DEPRECATED: use the pix_ version of this method
+      alias atomic_write pix_atomic_write
+
+      # @see PixarRubyExtensions::IntegerExtensions::Utils#pix_humanize_bytes
+      #
+      # @return [String] The human-readable file size.
+      #
+      def pix_humanize_size
+        # make sure we require this, in case the user only required
+        # 'pixar_ruby_extensions/pathname'
+        require 'pixar_ruby_extensions/integer'
+        size.pix_humanize_bytes
+      end
+
+      # The same as #pix_humanize_size except returns nil if
+      # the file size is zero, or the file doesn't exist.
+      #
+      # @return [String, nil] The human-readable file size, or nil
+      def pix_humanize_size?(show_unit: false)
+        return unless exist?
+        return if size.zero?
+
+        humanize_size
+      end
+
+    end # module
+
+  end # module
+
+end # module

data/lib/pixar_ruby_extensions/pathname.rb

@@ -0,0 +1,18 @@
+# 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 'pathname'
+require 'pixar_ruby_extensions/pathname/utils'
+require 'pixar_ruby_extensions/pathname/predicates'
+
+# include the modules loaded above
+class Pathname
+
+  include PixarRubyExtensions::PathnameExtensions::Predicates
+  include PixarRubyExtensions::PathnameExtensions::Utils
+
+end

data/lib/pixar_ruby_extensions/string/conversions.rb

@@ -0,0 +1,113 @@
+# 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 StringExtensions
+
+    module Conversions
+
+      TRUE_STR = 'true'
+      FALSE_STR = 'false'
+
+      # Convert the strings "true" and "false"
+      # (after stripping whitespace and downcasing)
+      # to true and false respectively
+      #
+      # Return nil if any other string.
+      #
+      # @return [Boolean,nil] the boolean value. Nil if n/a
+      #
+      def pix_to_bool
+        case strip.downcase
+        when TRUE_STR then true
+        when FALSE_STR then false
+        end # case
+      end # to bool
+
+      # Convert a string to a Time object using Time.parse
+      #
+      # @return [Time] the time represented by the string, or nil
+      #
+      def pix_to_time
+        # needed to get .parse
+        require 'time'
+
+        ::Time.parse self
+      rescue
+        nil
+      end
+
+      # Convert a String to a Pathname object
+      #
+      # @return [Pathname]
+      #
+      def pix_to_pathname
+        ::Pathname.new self
+      end
+      alias pix_to_path pix_to_pathname
+
+      # Word-wrap a string to a max width.
+      # By default, runs of newlines are preserved.
+      #
+      # Regexp found at http://www.java2s.com/Code/Ruby/String/WordwrappingLinesofText.htm
+      #
+      # @param width [Integer] Must be a positive Integer. Defaults to 2 columns less than
+      #   the current terminal width, or 78 if terminal width cannot be obtained.
+      #
+      # @param preserve_newlines [Boolean] Should runs of 2+ newlines be preserved?
+      #   Defaults to true. If false, runs of newlines become a single newline.
+      #
+      # @return [String] The string word-wrapped to lines no more than <width> chars long.
+      #
+      def pix_word_wrap(width = nil, preserve_newlines: true)
+        if width.nil?
+          begin
+            require 'io/console'
+            width = IO.console.winsize.last - 2
+          rescue
+            width = 78
+          end
+        else
+          width = width.to_i
+          raise ArgumentError, 'Width must be an iteger > 0' unless width.positive?
+        end
+
+        return lines.map { |l| l.gsub(/(.{1,#{width}})(\s+|\Z)/, "\\1\n") }.join if preserve_newlines
+
+        gsub(/(.{1,#{width}})(\s+|\Z)/, "\\1\n")
+      end
+
+      # Encode this string to be used when building a URL.
+      #
+      # DO NOT use this to encode an entire URL, or any part of a URL that has
+      # characters that shouldn't be encoded - as it will encode the slashes and other
+      # proper URL parts, e.g.
+      #
+      #    url = 'http://foobar.com/foo?bar=this has spaces'.pix_url_encode
+      #    # => "http%3A%2F%2Ffoobar.com%2Ffoo%3Fbar%3Dthis%20has%20spaces"
+      #
+      # Instead just convert any appropriate sub-part of the URL
+      #
+      #   endoded_value = 'this has spaces'.pix_url_encode
+      #   url = "http://foobar.com/foo?bar=#{endoded_value}"
+      #   # => "http://foobar.com/foo?bar=this%20has%20spaces"
+      #
+      # This uses ERB::Util.url_encode, which converts spaces to '%20'.
+      # Consult the interwebs for the differences between '%20' and '+', and
+      # ERB::Util.url_encode vs CGI.escape
+      #
+      def pix_url_encode
+        require 'erb'
+        ERB::Util.url_encode self
+      end
+
+    end # module
+
+  end # module
+
+end # module

data/lib/pixar_ruby_extensions/string/predicates.rb

@@ -0,0 +1,52 @@
+# 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 StringExtensions
+
+    module Predicates
+
+      INTEGER_RE = /\A-?[0-9]+\Z/.freeze
+      FLOAT_RE = /\A-?[0-9]+\.[0-9]+\Z/.freeze
+
+      # Does this string contain an integer?
+      # (i.e. it consists only of numeric digits,
+      #  maybe with a dash in front)
+      #
+      # @return [Boolean]
+      #
+      def pix_integer?
+        self =~ INTEGER_RE ? true : false
+      end
+
+      # Does this string contain a float?
+      # (i.e. it consists only of numeric digits,
+      #  maybe with a dash in front followed by one
+      #  dot, followed by at least one more digit)
+      #
+      # @return [Boolean]
+      #
+      def pix_float?
+        self =~ FLOAT_RE ? true : false
+      end
+
+      # is this some representation of a number?
+      #
+      # @return [Boolean]
+      #
+      def pix_numeric?
+        true if Float(self)
+      rescue
+        false
+      end
+
+    end # module
+
+  end # module
+
+end # module

data/lib/pixar_ruby_extensions/string.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 'pixar_ruby_extensions/string/conversions'
+require 'pixar_ruby_extensions/string/predicates'
+
+# include the modules loaded above
+class String
+
+  include PixarRubyExtensions::StringExtensions::Predicates
+  include PixarRubyExtensions::StringExtensions::Conversions
+
+end

data/lib/pixar_ruby_extensions/time/utils.rb

@@ -0,0 +1,46 @@
+# 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 TimeExtensions
+
+    module Utils
+
+      # @return [Integer] the milliseconds of the Time
+      def pix_msec
+        strftime('%L').to_i
+      end
+
+      # This is useful for anyone who interacts with the Jamf Pro APIs, which
+      # often deliver timestamps as the unix epoch in milliseconds.
+      # e.g. '2023-02-28 14:43:41.456 -0800' would be 1677624221456
+      #
+      # @return [Integer] The Time as a unix epoch with milliseconds appended
+      def pix_to_epoch_with_msecs
+        msec = strftime('%L').rjust(3, '0')
+        epoch = strftime('%s')
+        "#{epoch}#{msec}".to_i
+      end
+
+      # @return [String] the Time formatted for our logs and UI display.
+      #   '%F %T' is short for '%Y-%m-%d %H:%M:%S'
+      def pix_to_display
+        strftime '%F %T'
+      end
+
+      # @return [String] the Time formatted as iso8601 with the
+      #   milliseconds
+      def pix_to_iso8601_with_msecs
+        strftime("%FT%T.#{pix_msec}%z")
+      end
+
+    end
+
+  end
+
+end

data/lib/pixar_ruby_extensions/time.rb

@@ -0,0 +1,16 @@
+# 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 'time'
+require 'pixar_ruby_extensions/time/utils'
+
+# include the modules loaded above
+class Time
+
+  include PixarRubyExtensions::TimeExtensions::Utils
+
+end

data/lib/pixar_ruby_extensions/version.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
+
+# our version
+module PixarRubyExtensions
+
+  VERSION = '1.11.1'
+
+end

data/lib/pixar_ruby_extensions.rb

@@ -0,0 +1,44 @@
+# 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
+
+# These are extensions to Ruby modules and classes in Ruby's Core
+# and Standard Library. We've put them here because we've found
+# ourselves performing these tasks repeatedly in our code over the years
+# and we like to stay DRY.
+# They are also used in our open-source projects, and their use there
+# will be migrating to use this gem, rather than their built-in
+# versions - also in pursuit of DRYness.
+
+# To ease troubleshooting and prevent name collisions:
+
+# - With only a couple of exceptions, all monkey-patched methods are
+#   prefixed with "pix_"
+
+# - Methods are not directly monkey-patched into the Core or StdLib classes/modules.
+#   Instead they are defined in modules with obvious namespaces, and mixed-in to the
+#   Core or StdLib classes/modules. This provides _much_ easier debugging when there
+#   are exceptions, since the error and backtrace will indicate exactly where these
+#   methods are defined.
+module PixarRubyExtensions; end
+
+require 'pixar_ruby_extensions/version'
+
+# NOTE: You may require these individually if you don't need them all.
+
+require 'pixar_ruby_extensions/array'
+require 'pixar_ruby_extensions/filetest'
+require 'pixar_ruby_extensions/hash'
+require 'pixar_ruby_extensions/integer'
+require 'pixar_ruby_extensions/float'
+require 'pixar_ruby_extensions/ipaddr'
+require 'pixar_ruby_extensions/json'
+require 'pixar_ruby_extensions/object'
+require 'pixar_ruby_extensions/pathname'
+require 'pixar_ruby_extensions/string'
+require 'pixar_ruby_extensions/time'

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: pixar-ruby-extensions
+version: !ruby/object:Gem::Version
+  version: 1.11.1
+platform: ruby
+authors:
+- Chris Lasell
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-09-28 00:00:00.000000000 Z
+dependencies: []
+description: |
+  This gem contans extensions to the Ruby core and standard libraries which have been used in many
+  Pixar projects over the years.
+email: chrisl@pixar.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE.txt
+files:
+- LICENSE.txt
+- README.md
+- lib/pixar-ruby-extensions.rb
+- lib/pixar_ruby_extensions.rb
+- lib/pixar_ruby_extensions/array.rb
+- lib/pixar_ruby_extensions/array/predicates.rb
+- lib/pixar_ruby_extensions/array/utils.rb
+- lib/pixar_ruby_extensions/filetest.rb
+- lib/pixar_ruby_extensions/filetest/predicates.rb
+- lib/pixar_ruby_extensions/float.rb
+- lib/pixar_ruby_extensions/float/utils.rb
+- lib/pixar_ruby_extensions/hash.rb
+- lib/pixar_ruby_extensions/hash/utils.rb
+- lib/pixar_ruby_extensions/integer.rb
+- lib/pixar_ruby_extensions/integer/utils.rb
+- lib/pixar_ruby_extensions/ipaddr.rb
+- lib/pixar_ruby_extensions/ipaddr/predicates.rb
+- lib/pixar_ruby_extensions/ipaddr/utils.rb
+- lib/pixar_ruby_extensions/json.rb
+- lib/pixar_ruby_extensions/json/jsonl.rb
+- lib/pixar_ruby_extensions/json/utils.rb
+- lib/pixar_ruby_extensions/object.rb
+- lib/pixar_ruby_extensions/object/predicates.rb
+- lib/pixar_ruby_extensions/pathname.rb
+- lib/pixar_ruby_extensions/pathname/predicates.rb
+- lib/pixar_ruby_extensions/pathname/utils.rb
+- lib/pixar_ruby_extensions/string.rb
+- lib/pixar_ruby_extensions/string/conversions.rb
+- lib/pixar_ruby_extensions/string/predicates.rb
+- lib/pixar_ruby_extensions/time.rb
+- lib/pixar_ruby_extensions/time/utils.rb
+- lib/pixar_ruby_extensions/version.rb
+homepage: https://github.com/PixarAnimationStudios/pixar-ruby-extensions
+licenses:
+- LicenseRef-LICENSE.txt
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.11
+signing_key:
+specification_version: 4
+summary: Extensions to Ruby Core and Ctandard libraries used in Pixar's ruby projects
+test_files: []