keycase 1.2.0 → 1.3.0

data/lib/keycase/snake_case.rb

@@ -1,14 +1,33 @@
 # frozen_string_literal: true
 
-require "set"
-
-require_relative "support/transformer"
+require_relative "support/structure_keys"
 require_relative "support/tokenizer"
 
 module Keycase
   module SnakeCase
+    def self.convert_string(str, upcase: false)
+      words = Keycase::Support::Tokenizer.words(str)
+      converter = upcase ? :upcase : :downcase
+      words.map(&converter).join("_")
+    end
+
+    def self.convert(value, upcase: false)
+      case value
+      when String then convert_string(value, upcase: upcase)
+      when Symbol then convert_string(value.to_s, upcase: upcase).to_sym
+      else value
+      end
+    end
+
+    def self.convert_keys(structure, options = {})
+      upcase = options.fetch(:upcase, false)
+      Keycase::Support::StructureKeys.transform(structure, options) do |key|
+        convert(key, upcase: upcase)
+      end
+    end
+
     refine Object do
-      def to_snake_case
+      def to_snake_case(_options = {})
         self
       end
 
@@ -18,43 +37,43 @@ module Keycase
     end
 
     refine String do
-      def to_snake_case
-        Keycase::Support::Tokenizer.words(self).map do |word|
-          word.downcase
-        end.join("_")
+      def to_snake_case(upcase: false)
+        Keycase::SnakeCase.convert_string(self, upcase: upcase)
       end
     end
 
     refine Symbol do
-      def to_snake_case
-        to_s.to_snake_case.to_sym
+      def to_snake_case(upcase: false)
+        Keycase::SnakeCase.convert(self, upcase: upcase)
       end
     end
 
     refine Array do
       def with_snake_case_keys(options = {})
-        Keycase::Support::Transformer.transform_array(
-          self,
-          ::Set.new,
-          0,
-          options[:max_depth]
-        ) do |key|
-          key.to_snake_case
-        end
+        Keycase::SnakeCase.convert_keys(self, options)
       end
     end
 
     refine Hash do
       def with_snake_case_keys(options = {})
-        Keycase::Support::Transformer.transform_hash(
-          self,
-          ::Set.new,
-          0,
-          options[:max_depth]
-        ) do |key|
-          key.to_snake_case
-        end
+        Keycase::SnakeCase.convert_keys(self, options)
       end
     end
+
+    refine Struct do
+      def with_snake_case_keys(options = {})
+        Keycase::SnakeCase.convert_keys(self, options)
+      end
+    end
+  end
+
+  class << self
+    def snake_case(value, upcase: false)
+      SnakeCase.convert(value, upcase: upcase)
+    end
+
+    def with_snake_case_keys(value, options = {})
+      SnakeCase.convert_keys(value, options)
+    end
   end
 end

data/lib/keycase/support/acronyms.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Keycase
+  module Support
+    module Acronyms
+      module_function
+
+      def index(list)
+        return {} if list.nil?
+
+        Array(list).each_with_object({}) do |item, memo|
+          s = item.to_s
+          next if s.empty?
+
+          memo[s.downcase] = s
+        end
+      end
+
+      def segment(word, acronyms_by_downcase)
+        acronyms_by_downcase[word.downcase] || word.capitalize
+      end
+
+      def leading_acronym?(first_word, acronyms_by_downcase)
+        return false unless first_word
+
+        acronyms_by_downcase.key?(first_word.downcase)
+      end
+    end
+  end
+end

data/lib/keycase/support/struct_instantiation.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Keycase
+  module Support
+    module StructInstantiation
+      KEYWORD_INIT_IVAR = :@keycase_keyword_init
+
+      module_function
+
+      def struct_keyword_init_available?
+        return @struct_keyword_init_available if defined?(@struct_keyword_init_available)
+
+        available = false
+        begin
+          Struct.new(:x, keyword_init: true)
+          available = true
+        rescue TypeError
+          available = false
+        end
+        @struct_keyword_init_available = available
+      end
+
+      def mark_keyword_init!(klass)
+        klass.instance_variable_set(KEYWORD_INIT_IVAR, true)
+      end
+
+      def struct_keyword_init?(klass)
+        return false unless struct_keyword_init_available?
+
+        return true if klass.instance_variable_defined?(KEYWORD_INIT_IVAR)
+
+        klass.respond_to?(:keyword_init?) && klass.keyword_init?
+      end
+
+      def build_struct_class(*members, keyword_init:)
+        if keyword_init && struct_keyword_init_available?
+          Struct.new(*members, keyword_init: true).tap do |klass|
+            mark_keyword_init!(klass)
+          end
+        else
+          Struct.new(*members)
+        end
+      end
+
+      def each_member_pair(structure)
+        # Struct member accessors can hide the methods used by conversion.
+        ::Struct.instance_method(:each_pair).bind(structure).to_enum(:call)
+      end
+
+      def rebuild(original, pairs)
+        klass = Object.instance_method(:class).bind(original).call
+        original_members = each_member_pair(original).map(&:first)
+        new_members = pairs.keys
+
+        # Older Rubies cannot identify keyword_init on Struct classes created by callers.
+        return copy_struct(original, pairs, klass) if new_members == original_members
+
+        target_klass = build_struct_class(*new_members, keyword_init: struct_keyword_init?(klass))
+        instantiate(target_klass, pairs, new_members)
+      end
+
+      def instantiate(klass, pairs, member_order)
+        instance = klass.allocate
+        # A converted member named initialize can hide Struct's initializer.
+        initializer = ::Struct.instance_method(:initialize).bind(instance)
+        if struct_keyword_init?(klass)
+          initializer.call(**pairs)
+        else
+          values = member_order.map do |member|
+            pairs[member]
+          end
+          initializer.call(*values)
+        end
+        instance
+      end
+
+      def copy_struct(original, pairs, klass)
+        copy = duplicate_struct(original, klass)
+        writer = ::Struct.instance_method(:[]=).bind(copy)
+        pairs.each do |member, value|
+          writer.call(member, value)
+        end
+        copy
+      end
+
+      def duplicate_struct(original, klass)
+        return Object.instance_method(:dup).bind(original).call unless copy_hooks_shadowed?(klass)
+
+        # dup dispatches copy hooks, which member accessors can hide.
+        copy = Class.instance_method(:allocate).bind(klass).call
+        ::Struct.instance_method(:initialize_copy).bind(copy).call(original)
+        copy_instance_variables(original, copy)
+        copy
+      end
+
+      def copy_hooks_shadowed?(klass)
+        (%i[initialize_dup initialize_copy] & klass.members).any? do |hook|
+          klass.instance_method(hook).arity.zero?
+        end
+      end
+
+      def copy_instance_variables(original, copy)
+        reader = Object.instance_method(:instance_variable_get).bind(original)
+        writer = Object.instance_method(:instance_variable_set).bind(copy)
+        Object.instance_method(:instance_variables).bind(original).call.each do |name|
+          writer.call(name, reader.call(name))
+        end
+      end
+      private_class_method :copy_struct, :duplicate_struct, :copy_hooks_shadowed?, :copy_instance_variables
+    end
+  end
+end

data/lib/keycase/support/structure_keys.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "set"
+
+require_relative "transformer"
+
+module Keycase
+  module Support
+    module StructureKeys
+      module_function
+
+      def transform(structure, options = {}, &key_converter)
+        opts = Transformer.enrich_options(options)
+        state = Transformer::State.new(::Set.new, 0, opts, :none)
+
+        Transformer.transform_value(structure, state, &key_converter)
+      end
+    end
+  end
+end

data/lib/keycase/support/tokenizer.rb

@@ -7,13 +7,9 @@ module Keycase
 
       def words(value)
         value
-          .gsub(/(?<=[A-Z])(?=[A-Z][a-z])/) do |_|
-            "_"
-          end
-          .gsub(/(?<=[0-9a-z])(?=[A-Z])/) do |_|
-            "_"
-          end
-          .scan(/[0-9A-Za-z]+/)
+          .gsub(/(?<=\p{Lu})(?=\p{Lu}\p{Ll})/, "_")
+          .gsub(/(?<=[\p{Ll}\p{Nd}])(?=\p{Lu})/, "_")
+          .scan(/[\p{L}\p{N}]+/)
       end
     end
   end

data/lib/keycase/support/transformer/collision.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Keycase
+  module Support
+    module Transformer
+      class << self
+        private
+
+        def keep_existing_key?(memo, new_key, original_key, on_collision)
+          return false unless memo.key?(new_key)
+
+          if on_collision == :raise
+            message = "Keycase detected a key collision: #{original_key.inspect} converted to " \
+                      "#{new_key.inspect}, which already exists in the transformed structure"
+            raise KeyCollisionError, message
+          end
+
+          on_collision == :keep_first
+        end
+
+        def resolve_on_collision!(options)
+          mode = options.fetch(:on_collision, :raise)
+          return mode if %i[raise overwrite keep_first].include?(mode)
+
+          raise ArgumentError, "Keycase on_collision must be :raise, :overwrite, or :keep_first (got #{mode.inspect})"
+        end
+      end
+    end
+  end
+end

data/lib/keycase/support/transformer/only_normalization.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Keycase
+  module Support
+    module Transformer
+      class << self
+        private
+
+        def convert_key?(key, options)
+          klasses = options[:__keycase_only_klasses]
+          return true if klasses.nil?
+
+          klasses.any? do |klass|
+            # Struct keys can hide is_a? with a member accessor.
+            klass === key # rubocop:disable Style/CaseEquality
+          end
+        end
+
+        def normalize_only_classes(only)
+          return nil if only.nil?
+
+          raise ArgumentError, "Keycase only must be an Array (got #{only.class})" unless only.is_a?(Array)
+
+          only.map do |spec|
+            normalize_only_spec(spec)
+          end
+        end
+
+        def normalize_only_spec(spec)
+          case spec
+          when Class
+            assert_only_allowed_class!(spec)
+            spec
+          when :string, "string" then String
+          when :symbol, "symbol" then Symbol
+          else
+            raise ArgumentError, "Keycase only: unsupported entry #{spec.inspect}"
+          end
+        end
+
+        def assert_only_allowed_class!(spec)
+          return if [String, Symbol].include?(spec)
+
+          raise ArgumentError,
+                "Keycase only allows String and Symbol as classes (got #{spec})"
+        end
+      end
+    end
+  end
+end

data/lib/keycase/support/transformer/structure_builders.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Keycase
+  module Support
+    module Transformer
+      class << self
+        private
+
+        def build_transformed_struct(struct, state, on_collision, &key_converter)
+          pairs = build_transformed_members(
+            StructInstantiation.each_member_pair(struct), child_state(state, :struct), on_collision, &key_converter
+          )
+          StructInstantiation.rebuild(struct, pairs)
+        end
+
+        def build_transformed_members(members, child, on_collision, &key_converter)
+          result = members.is_a?(Hash) && members.compare_by_identity? ? {}.compare_by_identity : {}
+          members.each_with_object(result) do |(key, value), memo|
+            new_key = convert_member_key(key, child, &key_converter)
+            next if keep_existing_key?(memo, new_key, key, on_collision)
+
+            memo[new_key] = transform_value(value, child, &key_converter)
+          end
+        end
+
+        def convert_member_key(key, state, &key_converter)
+          return key unless convert_key?(key, state.options)
+
+          new_key = key_converter.call(key)
+          # Only Struct members prohibit empty names; nested Hash keys may be empty.
+          return key if state.parent_kind == :struct && new_key.to_s.empty?
+
+          new_key
+        end
+      end
+    end
+  end
+end

data/lib/keycase/support/transformer/visit.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Keycase
+  module Support
+    module Transformer
+      class << self
+        private
+
+        def check_depth!(depth, max_depth)
+          return if max_depth.nil?
+
+          raise StructureTooDeepError, "Keycase nesting exceeds max_depth (#{max_depth})" if depth > max_depth
+        end
+
+        def visit_structure(structure, visiting, kind)
+          oid = Object.instance_method(:object_id).bind(structure).call
+          raise CircularStructureError, circular_reference_message(kind) if visiting.include?(oid)
+
+          visiting.add(oid)
+          begin
+            yield
+          ensure
+            visiting.delete(oid)
+          end
+        end
+
+        def circular_reference_message(kind)
+          "Keycase detected a circular reference in a #{kind}"
+        end
+      end
+    end
+  end
+end

data/lib/keycase/support/transformer.rb

@@ -1,68 +1,82 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "struct_instantiation"
+require_relative "transformer/visit"
+require_relative "transformer/only_normalization"
+require_relative "transformer/collision"
+require_relative "transformer/structure_builders"
 
 module Keycase
   module Support
     module Transformer
+      State = Struct.new(:visiting, :depth, :options, :parent_kind)
+
       class << self
-        def transform_hash(hash, visiting, depth, max_depth, &key_converter)
-          check_depth!(depth, max_depth)
-
-          oid = hash.object_id
-          raise CircularStructureError, "Keycase detected a circular reference in a Hash" if visiting.include?(oid)
-
-          visiting.add(oid)
-          begin
-            hash.each_with_object({}) do |(key, value), memo|
-              new_key = key_converter.call(key)
-              if memo.key?(new_key)
-                message = "Keycase detected a key collision: #{key.inspect} converted to " \
-                          "#{new_key.inspect}, which already exists in the transformed hash"
-                raise KeyCollisionError, message
-              end
-
-              memo[new_key] = transform_value(
-                value,
-                visiting,
-                depth + 1,
-                max_depth,
-                &key_converter
-              )
-            end
-          ensure
-            visiting.delete(oid)
+        def enrich_options(options)
+          recursive = options.fetch(:recursive, true)
+          arrays = options.fetch(:arrays, true)
+          unless [true, false].include?(recursive)
+            raise ArgumentError, "Keycase recursive must be true or false (got #{recursive.inspect})"
+          end
+          unless [true, false].include?(arrays)
+            raise ArgumentError, "Keycase arrays must be true or false (got #{arrays.inspect})"
           end
+
+          options.merge(
+            recursive: recursive,
+            arrays: arrays,
+            __keycase_only_klasses: normalize_only_classes(options[:only])
+          )
         end
 
-        def transform_array(array, visiting, depth, max_depth, &key_converter)
-          check_depth!(depth, max_depth)
+        def transform_hash(hash, state, &key_converter)
+          return hash if state.options[:recursive] == false && state.parent_kind == :hash
 
-          oid = array.object_id
-          raise CircularStructureError, "Keycase detected a circular reference in an Array" if visiting.include?(oid)
+          on_collision = resolve_on_collision!(state.options)
+          check_depth!(state.depth, state.options[:max_depth])
 
-          visiting.add(oid)
-          begin
+          visit_structure(hash, state.visiting, "Hash") do
+            build_transformed_members(hash, child_state(state, :hash), on_collision, &key_converter)
+          end
+        end
+
+        def transform_array(array, state, &key_converter)
+          if state.options[:arrays] == false
+            return array.map do |element|
+              element
+            end
+          end
+
+          check_depth!(state.depth, state.options[:max_depth])
+
+          visit_structure(array, state.visiting, "Array") do
+            child = child_state(state, :array)
             array.map do |element|
-              transform_value(
-                element,
-                visiting,
-                depth + 1,
-                max_depth,
-                &key_converter
-              )
+              transform_value(element, child, &key_converter)
             end
-          ensure
-            visiting.delete(oid)
           end
         end
 
-        def transform_value(value, visiting, depth, max_depth, &key_converter)
+        def transform_struct(struct, state, &key_converter)
+          return struct if state.options[:recursive] == false && state.parent_kind == :struct
+
+          on_collision = resolve_on_collision!(state.options)
+          check_depth!(state.depth, state.options[:max_depth])
+
+          visit_structure(struct, state.visiting, "Struct") do
+            build_transformed_struct(struct, state, on_collision, &key_converter)
+          end
+        end
+
+        def transform_value(value, state, &key_converter)
           case value
           when Hash
-            transform_hash(value, visiting, depth, max_depth, &key_converter)
+            transform_hash(value, state, &key_converter)
           when Array
-            transform_array(value, visiting, depth, max_depth, &key_converter)
+            transform_array(value, state, &key_converter)
+          when ::Struct
+            transform_struct(value, state, &key_converter)
           else
             value
           end
@@ -70,10 +84,8 @@ module Keycase
 
         private
 
-        def check_depth!(depth, max_depth)
-          return if max_depth.nil?
-
-          raise StructureTooDeepError, "Keycase nesting exceeds max_depth (#{max_depth})" if depth > max_depth
+        def child_state(state, parent_kind)
+          State.new(state.visiting, state.depth + 1, state.options, parent_kind)
         end
       end
     end

data/lib/keycase/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Keycase
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/keycase.rb

@@ -1,15 +1,20 @@
 # frozen_string_literal: true
 
+# Recursively converts string/symbol case and hash keys (camelCase, snake_case, etc.).
+#
+# +Keycase+ is reopened in +lib/keycase/<case>.rb+; module functions (+Keycase.camel_case+ and
+# friends) and refinement modules (+Keycase::CamelCase+, ...) live in those files, not here.
+#
+# Call module functions on +Keycase+ when +using Keycase::CamelCase+ (or another case module)
+# is impractical, such as in a Rails initializer, another gem, or shared code. Refinements remain
+# available for lexically scoped +to_*+ / +with_*_keys+ instance methods.
 require "keycase/version"
 require "keycase/support/errors"
 require "keycase/support/transformer"
 require "keycase/support/tokenizer"
 require "keycase/camel_case"
 require "keycase/kebab_case"
-require "keycase/pascal_case"
-require "keycase/screaming_snake_case"
 require "keycase/snake_case"
-require "keycase/train_case"
 
 module Keycase
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keycase
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - naoigcat
@@ -11,7 +11,7 @@ date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |2
       This gem converts the case of strings, symbols, and keys of hash recursively.
-      The convertible cases are camelCase, PascalCase, snake_case, etc.
+      The convertible cases are camelCase, snake_case, kebab-case.
 email:
 - 17925623+naoigcat@users.noreply.github.com
 executables: []
@@ -24,13 +24,17 @@ files:
 - lib/keycase.rb
 - lib/keycase/camel_case.rb
 - lib/keycase/kebab_case.rb
-- lib/keycase/pascal_case.rb
-- lib/keycase/screaming_snake_case.rb
 - lib/keycase/snake_case.rb
+- lib/keycase/support/acronyms.rb
 - lib/keycase/support/errors.rb
+- lib/keycase/support/struct_instantiation.rb
+- lib/keycase/support/structure_keys.rb
 - lib/keycase/support/tokenizer.rb
 - lib/keycase/support/transformer.rb
-- lib/keycase/train_case.rb
+- lib/keycase/support/transformer/collision.rb
+- lib/keycase/support/transformer/only_normalization.rb
+- lib/keycase/support/transformer/structure_builders.rb
+- lib/keycase/support/transformer/visit.rb
 - lib/keycase/version.rb
 homepage: https://github.com/naoigcat/ruby-keycase
 licenses: