bridgetown-foundation 2.0.0.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 00a2692340742728b14ce61beb79b3181409376be73f56c21a60db4e3d28c3ee
+  data.tar.gz: fc2ae32d07c3f218d98ed6409abab7431e6927078005c6dc4dbd158d054ce4c5
+SHA512:
+  metadata.gz: 82722f2c1d63bbc05f2d8de93290999316162c0de9f55d91c24fbe831ee67a7b0335c1e3c91846038518b7d944e413c6b1be795fcead56e53815b068c2c2de72
+  data.tar.gz: de9adb2dc49ed52b36fe7f61e7f10f29e30b8b12fced50cd8e2cc678b563f11001c79d038fead8a786898963c8be45352b85207a14aa65be21423abeecc756f6

data/.rubocop.yml

@@ -0,0 +1,7 @@
+---
+inherit_from: ../.rubocop.yml
+
+AllCops:
+  Exclude:
+    - "*.gemspec"
+    - "script/console"

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+task spec: :test
+require "rake/testtask"
+Rake::TestTask.new(:test) do |test|
+  test.libs << "lib" << "test"
+  test.pattern = "test/**/test_*.rb"
+  test.verbose = true
+end

data/benchmark/refinements.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "benchmark"
+
+class TestInclusion
+  module StringAdder
+    def included_add(num)
+      to_i + num
+    end
+  end
+
+  String.include StringAdder
+
+  def self.perform
+    raise "crash!" unless "10".included_add(20) == 30
+  end
+end
+
+module StringAdderRefinement
+  refine String do
+    def refined_add(num)
+      to_i + num
+    end
+  end
+end
+
+class TestRefinement
+  using StringAdderRefinement
+
+  def self.perform
+    raise "crash!" unless "10".refined_add(20) == 30
+  end
+end
+
+raise "Unconfirmed!" unless "".respond_to?(:included_add)
+raise "Unconfirmed!" if "".respond_to?(:refined_add)
+
+n = 1_000_000
+Benchmark.bmbm(12) do |x|
+  x.report("inclusion:") do
+    n.times do
+      TestInclusion.perform
+    end
+  end
+  x.report("refinements:") do
+    n.times do
+      TestRefinement.perform
+    end
+  end
+end

data/bridgetown-foundation.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "lib/bridgetown/foundation/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "bridgetown-foundation"
+  spec.version       = Bridgetown::Foundation::VERSION
+  spec.author        = "Bridgetown Team"
+  spec.email         = "maintainers@bridgetownrb.com"
+  spec.summary       = "Ruby language extensions and other utilities useful for the Bridgetown ecosystem"
+  spec.homepage      = "https://github.com/bridgetownrb/bridgetown/tree/main/bridgetown-foundation"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r!^(test|script)/!) }
+  spec.require_paths = ["lib"]
+
+  spec.metadata      = {
+    "source_code_uri"       => "https://github.com/bridgetownrb/bridgetown",
+    "bug_tracker_uri"       => "https://github.com/bridgetownrb/bridgetown/issues",
+    "changelog_uri"         => "https://github.com/bridgetownrb/bridgetown/releases",
+    "homepage_uri"          => spec.homepage,
+    "rubygems_mfa_required" => "true",
+  }
+
+  spec.add_dependency("hash_with_dot_access", "~> 2.0")
+  spec.add_dependency("inclusive", "~> 1.0")
+  spec.add_dependency("zeitwerk", "~> 2.5")
+end

data/lib/bridgetown/foundation/core_ext/class.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Bridgetown::Foundation
+  module CoreExt
+    module Class
+      module Descendants
+        def descendants
+          direct_children = subclasses.select do |klass|
+            next true if klass.name.nil? # anonymous class
+
+            # We do this to weed out old classes pre-Zeitwerk reload
+            klass == Kernel.const_get(klass.name)
+          rescue NameError
+            nil
+          end
+
+          (direct_children + direct_children.map(&:descendants)).flatten
+        end
+      end
+
+      ::Class.include Descendants
+    end
+  end
+end

data/lib/bridgetown/foundation/core_ext/string.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Bridgetown::Foundation
+  module CoreExt
+    module String
+      module Colorize
+        class << self
+          extend Inclusive::Class
+
+          # @return [Bridgetown::Foundation::Packages::Ansi]
+          public_packages def ansi = [Bridgetown::Foundation::Packages::Ansi]
+
+          def included(klass)
+            ansi.tap do |a|
+              a.colors.each_key do |color|
+                klass.define_method(color) { |*args| a.public_send(color, self, *args) }
+              end
+            end
+          end
+        end
+
+        # Reset output colors back to a regular string output
+        def reset_ansi
+          Colorize.ansi.reset(self)
+        end
+      end
+
+      module StartsWithAndEndsWith
+        def self.included(klass)
+          klass.alias_method :starts_with?, :start_with?
+          klass.alias_method :ends_with?, :end_with?
+        end
+      end
+
+      ::String.include Colorize, StartsWithAndEndsWith
+    end
+  end
+end

data/lib/bridgetown/foundation/packages/ansi.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Bridgetown::Foundation
+  module Packages
+    module Ansi
+      extend self
+
+      ESCAPE = format("%c", 27)
+      MATCH = %r!#{ESCAPE}\[(?:\d+)(?:;\d+)*(j|k|m|s|u|A|B|G)|\e\(B\e\[m!ix
+      COLORS = {
+        bold: 1,
+        black: 30,
+        red: 31,
+        green: 32,
+        yellow: 33,
+        blue: 34,
+        magenta: 35,
+        cyan: 36,
+        white: 37,
+      }.freeze
+
+      def colors = COLORS
+
+      # Strip ANSI from the current string.  It also strips cursor stuff,
+      # well some of it, and it also strips some other stuff that a lot of
+      # the other ANSI strippers don't.
+      def strip(str)
+        str.gsub MATCH, ""
+      end
+
+      # Does the string include ANSI color codes?
+      def has?(str)
+        !!(str =~ MATCH)
+      end
+
+      # Reset the color back to the default color so that you do not leak any
+      # colors when you move onto the next line. This is probably normally
+      # used as part of a wrapper so that we don't leak colors.
+      def reset(str = "")
+        @ansi_reset ||= format("%c[0m", 27)
+        "#{@ansi_reset}#{str}"
+      end
+
+      # SEE: `self::COLORS` for a list of methods.  They are mostly
+      # standard base colors supported by pretty much any xterm-color, we do
+      # not need more than the base colors so we do not include them.
+      COLORS.each do |color, num|
+        define_method color do |str|
+          "#{format("%c", 27)}[#{num}m#{str}#{reset}"
+        end
+      end
+    end
+  end
+end

data/lib/bridgetown/foundation/packages/pid_tracker.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Bridgetown::Foundation
+  module Packages
+    module PidTracker
+      def create_pid_dir
+        FileUtils.mkdir_p pids_dir
+      end
+
+      def add_pid(pid, file:)
+        File.write pidfile_for(file), "#{pid}\n", mode: "a+"
+      end
+
+      def read_pidfile(file)
+        File.readlines pidfile_for(file), chomp: true
+      end
+
+      def remove_pidfile(file)
+        File.delete pidfile_for(file)
+      end
+
+      private
+
+      def root_dir
+        Dir.pwd
+      end
+
+      def pids_dir
+        File.join(root_dir, "tmp", "pids")
+      end
+
+      def pidfile_for(file)
+        File.join(pids_dir, "#{file}.pid")
+      end
+    end
+  end
+end

data/lib/bridgetown/foundation/packages/safe_translations.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Bridgetown::Foundation
+  module Packages
+    # NOTE: this is tested by `test/test_ruby_helpers.rb` in bridgetown-core
+    #
+    # This is loosely based on the HtmlSafeTranslation module from ActiveSupport, but you can
+    # actually use it for any kind of safety use case in a translation setting because its
+    # decoupled from any specific escaping or safety mechanisms.
+    module SafeTranslations
+      extend Inclusive::Public
+
+      def translate(key, escaper, safety_method = :html_safe, **options)
+        safe_options = escape_translation_options(options, escaper)
+
+        i18n_error = false
+
+        exception_handler = ->(*args) do
+          i18n_error = true
+          I18n.exception_handler.(*args)
+        end
+
+        I18n.translate(key, **safe_options, exception_handler:).then do |translation|
+          i18n_error ? translation : safe_translation(translation, safety_method)
+        end
+      end
+
+      public_function :translate
+
+      def escape_translation_options(options, escaper)
+        @reserved_i18n_keys ||= I18n::RESERVED_KEYS.to_set
+
+        options.to_h do |name, value|
+          unless @reserved_i18n_keys.include?(name) || (name == :count && value.is_a?(Numeric))
+            next [name, escaper.(value)]
+          end
+
+          [name, value]
+        end
+      end
+
+      def safe_translation(translation, safety_method)
+        @safe_value ||= -> { _1.respond_to?(safety_method) ? _1.send(safety_method) : _1 }
+
+        return translation.map { @safe_value.(_1) } if translation.respond_to?(:map)
+
+        @safe_value.(translation)
+      end
+    end
+  end
+end

data/lib/bridgetown/foundation/questionable_string.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Bridgetown::Foundation
+  class QuestionableString < ::String
+    def method_missing(method_name, *args)
+      value = method_name.to_s
+      if value.end_with?("?")
+        value.chop!
+        return self == value
+      end
+
+      super
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      method_name.end_with?("?") || super
+    end
+  end
+end

data/lib/bridgetown/foundation/refine_ext/deep_duplicatable.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Bridgetown::Foundation
+  module RefineExt
+    # This is a very simplistic algorithm…it essentially just works on the Array/Hash values level,
+    # which for our purposes is fine.
+    module DeepDuplicatable
+      refine ::Hash do
+        def deep_dup
+          hash = dup
+          each do |key, value|
+            hash.delete(key)
+            if key.is_a?(::String) || key.is_a?(::Symbol)
+              hash[key] = value.dup
+            else
+              hash[key.dup] = if value.is_a?(Array) || value.is_a?(Hash)
+                                value.deep_dup
+                              else
+                                value.dup
+                              end
+            end
+          end
+          hash
+        end
+      end
+
+      refine ::Array do
+        def deep_dep
+          map do |item|
+            next item.dup unless item.is_a?(Array) || item.is_a?(Hash)
+
+            item.deep_dup
+          end
+        end
+      end
+    end
+  end
+end
+
+module Bridgetown
+  module Refinements
+    include Foundation::RefineExt::DeepDuplicatable
+  end
+end

data/lib/bridgetown/foundation/refine_ext/module.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Bridgetown::Foundation
+  module RefineExt
+    module Module
+      using RefineExt::Object
+
+      refine ::Module do
+        def nested_within?(other)
+          return false if self == other
+
+          other.nested_parents.within?(nested_parents) #[1..])
+        end
+
+        def nested_parents
+          return [] unless name
+
+          nesting_segments = name.split("::")[...-1]
+          nesting_segments.map.each_with_index do |_nesting_name, index|
+            Kernel.const_get(nesting_segments[..-(index + 1)].join("::"))
+          end
+        end
+
+        def nested_parent
+          nested_parents.first
+        end
+
+        def nested_name
+          name&.split("::")&.last
+        end
+      end
+    end
+  end
+end
+
+module Bridgetown
+  module Refinements
+    include Foundation::RefineExt::Module
+  end
+end

data/lib/bridgetown/foundation/refine_ext/object.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Bridgetown::Foundation
+  module RefineExt
+    module Object
+      refine ::Object do
+        # This method lets you check if the receiver is "within" the other object. In most cases,
+        # this check is accomplished via the `include?` method…aka, `10.within? [5, 10]` would
+        # return `true` as `[5, 10].include? 10` is true. And String/String comparison are
+        # case-insensivitve.
+        #
+        # However, for certain comparison types: Module/Class, Hash, and Set, the lesser-than (`<`)
+        # operator is used instead. This is so you can check `BigDecimal.within? Numeric`,
+        # `{easy_as: 123}.within?({indeed: "it's true", easy_as: 123})`, and if a Set is a
+        # `proper_subset?` of another Set.
+        #
+        # For Array/Array comparisons, a difference is checked, so `[1,2].within? [3,2,1]` is true,
+        # but `[1,2].within? [2,3]` is false.
+        #
+        # Also for Range, the `cover?` method is used instead of `include?`.
+        #
+        # @param other [Object] for determining if receiver lies within this value
+        # @return [Boolean]
+        def within?(other) # rubocop:disable Metrics
+          # rubocop:disable Style/IfUnlessModifier
+          if is_a?(Module) && other.is_a?(Module)
+            return self < other
+          end
+
+          if (is_a?(Hash) && other.is_a?(Hash)) || (is_a?(Set) && other.is_a?(Set))
+            return self < other
+          end
+
+          if is_a?(Array) && other.is_a?(Array)
+            return false if empty?
+
+            return difference(other).empty?
+          end
+
+          if other.is_a?(Range)
+            return other.cover?(self) == true
+          end
+
+          if is_a?(::String) && other.is_a?(::String)
+            return other.downcase.include?(downcase)
+          end
+
+          other&.include?(self) == true
+          # rubocop:enable Style/IfUnlessModifier
+        rescue NoMethodError
+          false
+        end
+
+        # NOTE: if you _really_ need to preserve Active Support's `in?` functionality, you can just
+        #   require "active_support/core_ext/object/inclusion"
+        def in?(...) = Bridgetown::Foundation.deprecation_warning(
+          self, :in?, :within?, 2024, 12
+        ).then { within?(...) }
+      end
+    end
+  end
+end
+
+module Bridgetown
+  module Refinements
+    include Foundation::RefineExt::Object
+  end
+end

data/lib/bridgetown/foundation/refine_ext/string.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Bridgetown::Foundation
+  module RefineExt
+    module String
+      refine ::String do
+        def indent!(indent_by, *args)
+          if args.length.positive?
+            Kernel.warn "multiple arguments aren't supported by `indent!' in Bridgetown", uplevel: 1
+          end
+
+          gsub! %r!^(?\!$)!, " " * indent_by
+        end
+
+        def indent(indent_by, *args)
+          if args.length.positive?
+            Kernel.warn "multiple arguments aren't supported by `indent' in Bridgetown", uplevel: 1
+          end
+
+          dup.indent!(indent_by)
+        end
+
+        def questionable = Bridgetown::Foundation::QuestionableString.new(self)
+
+        def inquiry = Bridgetown::Foundation.deprecation_warning(
+          self, :inquiry, :questionable, 2024, 12
+        ).then { questionable }
+      end
+    end
+  end
+end
+
+module Bridgetown
+  module Refinements
+    include Foundation::RefineExt::String
+  end
+end

data/lib/bridgetown/foundation/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Foundation
+    # TODO: should we define versions here now and pull it within Core?
+    VERSION = "2.0.0.beta1"
+  end
+end

data/lib/bridgetown-foundation.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "bridgetown/foundation/version"
+require "hash_with_dot_access"
+require "inclusive"
+require "zeitwerk"
+require "delegate"
+
+module Bridgetown::Foundation
+  # This is loosly based on the `deprecate` method in `Gem::Deprecate`
+  #
+  # @param target [Object]
+  # @param name [Symbol] e.g. `:howdy`
+  # @param repl [Symbol] e.g. `:hello`
+  # @param year [Integer] e.g. `2025`
+  # @param month [Integer] e.g. `1` for January
+  def self.deprecation_warning(target, name, repl, year, month) # rubocop:disable Metrics/ParameterLists
+    klass = target.is_a?(Module)
+    target = klass ? "#{self}." : "#{self.class}#"
+    msg = [
+      "NOTE: #{target}#{name} is deprecated",
+      repl == :none ? " with no replacement" : "; use #{repl} instead",
+      format(". It will be removed on or after %4d-%02d.", year, month), # rubocop:disable Style/FormatStringToken
+      "\n#{target}#{name} called from #{Gem.location_of_caller.join(":")}",
+    ]
+    warn "#{msg.join}."
+  end
+end
+
+# You can add `using Bridgetown::Refinements` to any portion of your Ruby code to load in all
+# of the refinements available in Foundation. Or you can add a using statement for a particular
+# refinement which lives inside `Bridgetown::Foundation::RefineExt`.
+module Bridgetown::Refinements
+  include HashWithDotAccess::Refinements
+end
+
+Zeitwerk.with_loader do |l|
+  l.push_dir "#{__dir__}/bridgetown/foundation", namespace: Bridgetown::Foundation
+  l.ignore "#{__dir__}/bridgetown/foundation/version.rb"
+  l.setup
+  l.eager_load
+end
+
+module Bridgetown
+  # Any method call sent will be passed along to the wrapped object with refinements activated
+  class WrappedObjectWithRefinements < SimpleDelegator
+    using Bridgetown::Refinements
+
+    # rubocop:disable Style/MissingRespondToMissing
+    def method_missing(method, ...) = __getobj__.send(method, ...)
+    # rubocop:enable Style/MissingRespondToMissing
+  end
+
+  # Call this method to wrap any object(s) in order to use Foundation's refinements
+  #
+  # @param *obj [Object]
+  # @return [WrappedObjectWithRefinements]
+  def self.refine(*obj)
+    if obj.length == 1
+      WrappedObjectWithRefinements.new(obj[0])
+    else
+      obj.map { WrappedObjectWithRefinements.new _1 }
+    end
+  end
+
+  def self.add_refinement(mod, &)
+    Bridgetown::Refinements.include(mod)
+    Bridgetown::WrappedObjectWithRefinements.class_eval(&)
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: bridgetown-foundation
+version: !ruby/object:Gem::Version
+  version: 2.0.0.beta1
+platform: ruby
+authors:
+- Bridgetown Team
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-08-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hash_with_dot_access
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: inclusive
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+description:
+email: maintainers@bridgetownrb.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- Rakefile
+- benchmark/refinements.rb
+- bridgetown-foundation.gemspec
+- lib/bridgetown-foundation.rb
+- lib/bridgetown/foundation/core_ext/class.rb
+- lib/bridgetown/foundation/core_ext/string.rb
+- lib/bridgetown/foundation/packages/ansi.rb
+- lib/bridgetown/foundation/packages/pid_tracker.rb
+- lib/bridgetown/foundation/packages/safe_translations.rb
+- lib/bridgetown/foundation/questionable_string.rb
+- lib/bridgetown/foundation/refine_ext/deep_duplicatable.rb
+- lib/bridgetown/foundation/refine_ext/module.rb
+- lib/bridgetown/foundation/refine_ext/object.rb
+- lib/bridgetown/foundation/refine_ext/string.rb
+- lib/bridgetown/foundation/version.rb
+homepage: https://github.com/bridgetownrb/bridgetown/tree/main/bridgetown-foundation
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/bridgetownrb/bridgetown
+  bug_tracker_uri: https://github.com/bridgetownrb/bridgetown/issues
+  changelog_uri: https://github.com/bridgetownrb/bridgetown/releases
+  homepage_uri: https://github.com/bridgetownrb/bridgetown/tree/main/bridgetown-foundation
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Ruby language extensions and other utilities useful for the Bridgetown ecosystem
+test_files: []