philosophal 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1df7f3c754eeef6776d0e3a18bcfdb81124e413187beb2f580dd550cbdcd046e
-  data.tar.gz: 03ed60c26e12f8225145e6f00a138da84e3d1aa11ffd1ab1be878df0032e6896
+  metadata.gz: d588fe0288b3b4d953de700a9218a607b4e7fc23d3946a8e34b4a1f90a7f1265
+  data.tar.gz: cf23c471421f8661992e575bfef9edb21e2a659962c0f54ec1618f0047b23b87
 SHA512:
-  metadata.gz: ab3fd3bf30dbaba5d2936979b832b2f9a715b7dbab19eba5d08c7feb4e84aa5affd41247b294ffc7ff9a4c054dcaba932ba2cb98d9c8699b5825d1dbad4c0a9b
-  data.tar.gz: 2b372e50b9bcf123531cdc0df806061893e86a3ddc70eddc2cc47731a017cff18dea606aea8c3477c2d8f2adf1faaa051c3728ad8645b166a0c5c120e583f951
+  metadata.gz: ae95691e4be606dbca97f8c3a1e3ccf96b34a310b95a5f07567cc8e2c80f37491ae92e03ecc4d60cfc851c0147d8b63ea0b9bb4cc16f64b1c32e06b1fdb33ed4
+  data.tar.gz: 3db4c56bea72d05e0e7a2d75a65842d567e6f2c33f8a37ffcdf2a82374c404c6cc37ce3dec376e94f004b55d3dd6182de8a15518f962d7f70f7aa26effceeb39

data/CHANGELOG.md

@@ -1,4 +1,28 @@
-## [Unreleased]
+## [2.0.0] - 2026-11-03
+
+- Add: new `track_changes:` option for `cprop`, which defines `prop_was` (the value at the last `changes_applied`) and `prop_changed?` (the value differs from it)
+- Add: `changes_applied` records the current values of the tracked properties as the reference
+- Add: `changed_properties` returns a hash of the tracked properties changed since the last `changes_applied`, with their new value
+- Add: RBS type signatures (`sig/`), shipped with the gem
+- Fix: **ArrayOf** and **HashOf** no longer accept `nil` or `false` entries of the wrong type without converting them
+- Fix: converting to **ArrayOf** or **HashOf** no longer modifies the given array or hash
+- Perf: the reader of a property without default is now a plain `attr_reader`
+- Perf: writers, and readers falling back to their default, no longer look up their property in the schema
+- Breaking: redeclaring in a subclass, with a default and `override: false`, a property no longer applies the subclass default or type (the parent methods are kept)
+- Perf: fewer lookups and allocations when converting, loading JSON, `to_json_hash`, `changes_applied` and `changed_properties`
+- Fix: `Properties::Schema` now defines `each`, so its Enumerable methods (`map`, `select`, `find`...) work and yield the properties
+
+## [1.3.0] - 2026-10-19
+
+- Breaking: minimum required Ruby version is now **3.3** (was 3.1)
+- Breaking: assigning `nil` no longer converts it (e.g. to `0` or `""`); the property is reset and its reader returns the default value
+- Fix: converting a Numeric to **DateTime** no longer requires ActiveSupport (`Time.zone`)
+- Fix: properties declared in a subclass no longer leak into the parent class
+- Fix: a property set to `false` is no longer replaced by its default value, and predicate methods (`prop?`) take the default into account
+- Fix: **ArrayOf** and **HashOf** instances are now really shared for the same subtypes, and **HashOf** accepts anonymous classes
+- Fix: descriptions are no longer evaluated as Ruby code (parentheses or `#{...}` in a description broke or ran code)
+- Fix: `json.load` no longer modifies the given hash or array, and accepts frozen hashes
+- Fix: `override: true` now also replaces a method defined in the class itself before `cprop`
 
 ## [1.0.0] - 2025-03-24
 

data/README.md

@@ -28,3 +28,42 @@ maxime.age = '40'
 puts maxime.inspect
 #<Person:0x00007da7088eed88 @first_name="maxime", @last_name="DÉSÉCOT", @age=40>
 ````
+
+### Tracking changes
+
+With `track_changes: true`, a property also gets `<name>_was` and `<name>_changed?`.
+Call `changes_applied` once the object is in a known state (built, loaded, saved...):
+`<name>_was` returns the value at that moment, and `<name>_changed?` tells whether the value differs from it.
+
+```ruby
+class Article
+  extend Philosophal::Properties
+
+  cprop :title, String, track_changes: true
+end
+
+article = Article.new
+article.title = 'Draft'
+article.title_changed? # => true (no reference yet)
+article.changes_applied
+article.title_changed? # => false
+article.title = 'Review'
+article.title = 'Final'
+article.title_was      # => "Draft"
+article.title_changed? # => true
+article.title = 'Draft'
+article.title_changed? # => false
+```
+
+`changed_properties` returns the tracked properties that changed, with their new value:
+
+```ruby
+article.title = 'Final'
+article.changed_properties # => { title: "Final" }
+article.changes_applied
+article.changed_properties # => {}
+```
+
+Before the first `changes_applied`, the reference is "never assigned": every assigned property is changed.
+`<name>_was` returns the stored value, without falling back to the default.
+`json.load` does not call `changes_applied`: call it on the loaded objects if they must start unchanged.

data/lib/philosophal/convertor.rb

@@ -87,7 +87,7 @@ module Philosophal
         return obj.to_datetime if obj.respond_to?(:to_datetime)
         return DateTime.new(*obj) if obj.is_a?(Array)
         return DateTime.parse(obj) if obj.is_a?(String)
-        return Time.zone.at(obj).to_datetime if obj.is_a?(Numeric)
+        return Time.at(obj).to_datetime if obj.is_a?(Numeric)
 
         raise Philosophal::TypeError
       end
@@ -102,9 +102,9 @@ module Philosophal
           return false if obj.zero?
 
         elsif obj.is_a?(String)
-          obj_downcase = obj.downcase
-          return true if obj_downcase == 'true'
-          return false if obj_downcase == 'false'
+          # casecmp compares ASCII only, which is enough for 'true' and 'false', and allocates no string.
+          return true if obj.casecmp('true') == 0 # rubocop:disable Style/NumericPredicate
+          return false if obj.casecmp('false') == 0 # rubocop:disable Style/NumericPredicate
 
         end
         raise Philosophal::TypeError
@@ -120,11 +120,8 @@ module Philosophal
         subtype_convert_method = convert_method_for(subtype)
         raise Philosophal::TypeError unless subtype_convert_method
 
-        convert_to_array(obj).tap do |new_obj|
-          new_obj.map! do |item|
-            send(subtype_convert_method, item)
-          end
-        end
+        # map, not map!: Array#to_a returns the given array itself, which must not be modified.
+        convert_to_array(obj).map { |item| send(subtype_convert_method, item) }
       end
 
       def convert_to_hash_of(obj, subtype)
@@ -134,9 +131,9 @@ module Philosophal
         value_convert_method = convert_method_for(subtype[:value_type])
         raise Philosophal::TypeError unless value_convert_method
 
-        convert_to_hash(obj).tap do |new_obj|
-          new_obj.transform_keys! { |key| send(key_convert_method, key) }
-          new_obj.transform_values! { |value| send(value_convert_method, value) }
+        # A new hash is built: Hash#to_h returns the given hash itself, which must not be modified.
+        convert_to_hash(obj).to_h do |key, value|
+          [send(key_convert_method, key), send(value_convert_method, value)]
         end
       end
     end

data/lib/philosophal/loaders/json_loader.rb

@@ -27,7 +27,7 @@ module Philosophal
       def load_from_array(array)
         raise LoadError, 'invalid json parameter' if array.find { |hash| !hash.is_a?(Hash) }
 
-        array.map! do |hash|
+        array.map do |hash|
           load_from_hash(hash)
         end
       end
@@ -35,23 +35,18 @@ module Philosophal
       def load_from_hash(hash)
         obj = @klass.new
 
-        hash.each_key do |key|
+        hash.each do |key, value|
           setter = setter_from_key(key)
           next unless obj.respond_to?(setter)
 
-          obj.public_send(setter, hash.delete(key))
+          obj.public_send(setter, value)
         end
 
         obj
       end
 
       def setter_from_key(key)
-        real_key = @klass.philosophal_properties.json_names_h[key]
-        property = @klass.philosophal_properties[real_key]
-
-        return :"#{property.name}=" if property
-
-        :"#{key}="
+        @klass.philosophal_properties.json_setters[key] || :"#{key}="
       end
 
       def load_from_json(str)

data/lib/philosophal/properties/instance_methods.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Philosophal
+  module Properties
+    module InstanceMethods
+      def cprop?(property_name, klass)
+        property = self.class.philosophal_properties.properties_index[property_name.to_sym]
+        return false unless property
+
+        klass = klass.class unless klass.is_a?(Class)
+        property.type == klass
+      end
+
+      def philosophal_inspect(light = false)
+        keys_map = philosophal_inspect_map
+
+        if light
+          keys_map.reject! do |_, v|
+            v.nil? || (v.respond_to?(:empty?) && v.empty?)
+          end
+        end
+
+        keys_str = keys_map.map { |k, v| [k, v.inspect].join(': ') }.join(', ')
+        "#{self.class}:#{format('0x00%x', object_id << 1)} #{keys_str}"
+      end
+      alias cprop_inspect philosophal_inspect
+
+      def philosophal_inspect_map
+        self.class.philosophal_properties.to_h do |property|
+          [
+            property.name,
+            send(property.name)
+          ]
+        end
+      end
+      alias cprop_inspect_map philosophal_inspect_map
+
+      def philosophal_values
+        self.class.philosophal_properties.properties_index.values
+      end
+
+      # Properties declared with track_changes: true whose value changed since the last changes_applied,
+      # with their new value.
+      def changed_properties
+        self.class.philosophal_properties.tracked.each_with_object({}) do |property, changes|
+          next unless send(property.changed_method_name)
+
+          changes[property.name] = send(property.name)
+        end
+      end
+
+      # Records the current values as the reference of the tracked properties: none of them is changed anymore.
+      # The values are duplicated, so modifying one in place is still seen as a change.
+      def changes_applied
+        self.class.philosophal_properties.tracked.each do |property|
+          instance_variable_set(property.was_variable_name, instance_variable_get(property.variable_name).dup)
+        end
+
+        self
+      end
+
+      def to_json_hash
+        self.class.philosophal_properties.json_properties.to_h do |property|
+          [
+            property.json_name,
+            send(property.name)
+          ]
+        end
+      end
+
+      def to_json(*_args)
+        to_json_hash.to_json
+      end
+    end
+  end
+end

data/lib/philosophal/properties/schema.rb

@@ -10,6 +10,14 @@ module Philosophal
         @mutex = Mutex.new
       end
 
+      # Called by #dup: a subclass gets its own index, so its properties do not leak into the parent.
+      def initialize_copy(source)
+        super
+        @properties_index = source.properties_index.dup
+        @mutex = Mutex.new
+        clear_caches
+      end
+
       attr_reader :properties_index
 
       def [](key)
@@ -20,9 +28,18 @@ module Philosophal
         @properties_index.keys
       end
 
+      # Yields each property in declaration order; Enumerable builds on it.
+      def each(&)
+        return enum_for(:each) { @properties_index.size } unless block_given?
+
+        @properties_index.each_value(&)
+        self
+      end
+
       def <<(value)
         @mutex.synchronize do
           @properties_index[value.name] = value
+          clear_caches
         end
 
         self
@@ -47,6 +64,37 @@ module Philosophal
           [property.json_name, key]
         end
       end
+
+      # Maps each JSON name to the writer of its property.
+      def json_setters
+        return @json_setters if defined?(@json_setters)
+
+        @json_setters = @properties_index.each_value.to_h do |property|
+          [property.json_name, property.writer_method_name]
+        end
+      end
+
+      # Properties declared with json: (exported by to_json_hash).
+      def json_properties
+        return @json_properties if defined?(@json_properties)
+
+        @json_properties = @properties_index.each_value.select(&:json)
+      end
+
+      # Properties declared with track_changes: true.
+      def tracked
+        return @tracked if defined?(@tracked)
+
+        @tracked = @properties_index.each_value.select(&:track_changes?)
+      end
+
+      private
+
+      def clear_caches
+        %i[@immutables @mutables @json_names_h @json_setters @json_properties @tracked].each do |cache|
+          remove_instance_variable(cache) if instance_variable_defined?(cache)
+        end
+      end
     end
   end
 end

data/lib/philosophal/properties.rb

@@ -3,36 +3,22 @@
 module Philosophal
   module Properties
     autoload :Schema, 'philosophal/properties/schema'
+    autoload :InstanceMethods, 'philosophal/properties/instance_methods'
     autoload :JSONLoader, 'philosophal/loaders/json_loader'
 
     include Philosophal::Types
 
-    def cprop(name, type, default: nil, transform: nil, immutable: false, description: nil, json: false)
-      default.freeze if default && !(default.is_a?(Proc) || default.frozen?)
+    def cprop(name, type, default: nil, transform: nil, immutable: false, description: nil, json: false, override: true,
+              track_changes: false)
+      __check_philosophal_options__(name, transform:, immutable:, override:, description:, json:, track_changes:)
 
-      if transform && !(transform.is_a?(Proc) || transform.is_a?(Symbol))
-        raise Philosophal::ArgumentError, "transform param must be a Symbol object or a Proc (#{name})."
-      end
-
-      unless Philosophal::Types::BooleanType::TRUE_FALSE_SET.include?(immutable)
-        raise Philosophal::ArgumentError, 'immutable param must be true or false.'
-      end
-
-      if description
-        raise Philosophal::ArgumentError, 'description param must be a string.' unless description.is_a?(String)
-
-        description.freeze unless description.frozen?
-      end
-
-      if json
-        unless json.is_a?(TrueClass) || json.is_a?(String) || json.is_a?(Symbol)
-          raise Philosophal::ArgumentError, 'json param must be true or a String or a Symbol.'
-        end
+      default.freeze unless default.is_a?(Proc)
+      description&.freeze
+      json = json.to_sym if json.is_a?(String)
 
-        json = json.to_sym if json.is_a?(String)
-      end
-
-      property = __philosophal_property_class__.new(name:, type:, default:, transform:, immutable:, description:, json:)
+      property = __philosophal_property_class__.new(
+        name:, type:, default:, transform:, immutable:, description:, json:, override:, track_changes:
+      )
 
       philosophal_properties << property
       __define_philosophal_methods__(property)
@@ -76,84 +62,76 @@ module Philosophal
     end
 
     def __define_philosophal_methods__(new_property)
+      __set_philosophal_property_constant__(new_property)
       code =	__generate_philosophal_methods__(new_property)
       __philosophal_extension__.module_eval(code)
     end
 
+    # The constant is replaced when the property is redeclared in the same class.
+    def __set_philosophal_property_constant__(property)
+      extension = __philosophal_extension__
+      constant_name = property.constant_name
+      extension.send(:remove_const, constant_name) if extension.const_defined?(constant_name, false)
+      extension.const_set(constant_name, property)
+      extension.private_constant(constant_name)
+    end
+
     def __philosophal_extension__
-      if defined?(@__philosophal_extension__)
-        @__philosophal_extension__
-      else
-        @__philosophal_extension__ = Module.new do
-          def cprop?(property_name, klass)
-            property = self.class.philosophal_properties.properties_index[property_name.to_sym]
-            return false unless property
-
-            klass = klass.class unless klass.is_a?(Class)
-            property.type == klass
-          end
-
-          def philosophal_inspect(light = false)
-            keys_map = philosophal_inspect_map
-
-            if light
-              keys_map.reject! do |_, v|
-                v.nil? || (v.respond_to?(:empty?) && v.empty?)
-              end
-            end
-
-            keys_str = keys_map.map { |k, v| [k, v.inspect].join(': ') }.join(', ')
-            "#{self.class}:#{format('0x00%x', object_id << 1)} #{keys_str}"
-          end
-          alias cprop_inspect philosophal_inspect
-
-          def philosophal_inspect_map
-            philosophal_values.to_h do |property|
-              [
-                property.name,
-                send(property.name)
-              ]
-            end
-          end
-          alias cprop_inspect_map philosophal_inspect_map
-
-          def philosophal_values
-            self.class.philosophal_properties.properties_index.values
-          end
-
-          def to_json_hash
-            philosophal_values.select(&:json).to_h do |property|
-              [
-                property.json_name,
-                send(property.name)
-              ]
-            end
-          end
-
-          def to_json(*_args)
-            to_json_hash.to_json
-          end
-        end
+      @__philosophal_extension__ ||= Module.new { include Philosophal::Properties::InstanceMethods }
+    end
+
+    def __generate_philosophal_methods__(new_property)
+      buffer = +''
+
+      new_property.method_generators.each do |method_name, generator|
+        next unless new_property.override? || !method_defined?(method_name)
+
+        __remove_philosophal_own_method__(method_name) if new_property.override?
+        new_property.public_send(generator, buffer)
       end
+
+      # puts buffer
+      return buffer if buffer.empty?
+
+      +"# frozen_string_philosophal: true\n" << buffer
     end
 
-    def __generate_philosophal_methods__(new_property, buffer = +'')
-      buffer << "# frozen_string_philosophal: true\n"
-      if new_property.immutable
-        new_property.generate_immutable_writer_method(buffer)
-      else
-        new_property.generate_writer_method(buffer)
+    # Generated methods live in an included module, so a method defined in the class itself
+    # would hide them: it is removed to let the property override it. The method generated by a
+    # previous declaration of the property is removed too, so redefining it raises no warning.
+    def __remove_philosophal_own_method__(method_name)
+      [self, __philosophal_extension__].each do |owner|
+        next unless owner.method_defined?(method_name, false) || owner.private_method_defined?(method_name, false)
+
+        owner.remove_method(method_name)
       end
+    end
 
-      new_property.generate_reader_method(buffer)
+    def __check_philosophal_options__(name, transform:, immutable:, override:, description:, json:, track_changes:)
+      __check_philosophal_transform_option__(name, transform)
+      __check_philosophal_boolean_option__(:override, override)
+      __check_philosophal_boolean_option__(:immutable, immutable)
+      __check_philosophal_boolean_option__(:track_changes, track_changes)
 
-      new_property.generate_boolean_method(buffer) if new_property.type == Philosophal::Types::BooleanType::Instance
+      if description && !description.is_a?(String)
+        raise Philosophal::ArgumentError, 'description param must be a string.'
+      end
 
-      new_property.generate_description_method(buffer) if new_property.description
+      return if !json || json == true || json.is_a?(String) || json.is_a?(Symbol)
 
-      # puts buffer
+      raise Philosophal::ArgumentError, 'json param must be true or a String or a Symbol.'
+    end
+
+    def __check_philosophal_transform_option__(name, transform)
+      return if !transform || transform.is_a?(Proc) || transform.is_a?(Symbol)
+
+      raise Philosophal::ArgumentError, "transform param must be a Symbol object or a Proc (#{name})."
+    end
+
+    def __check_philosophal_boolean_option__(option_name, value)
+      return if Philosophal::Types::BooleanType::TRUE_FALSE_SET.include?(value)
 
-      buffer
+      raise Philosophal::ArgumentError, "#{option_name} param must be true or false."
     end
   end
 end