firm 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ebb1f6594b3ecc4e56863a0f04ce3eb44fc5bfad0218a183298b44e56e9cf8e
-  data.tar.gz: 4e2349b45ae0479c968406fcd2eafb7ac4e76c8317cbbeeea20ecb784e998115
+  metadata.gz: 9bde55f78b14c4b8c8cac20c709c2826391616cf5d30972bcdeff2613d9389f5
+  data.tar.gz: f4e7a9b3269ea524699693968c88d75372f6bf51dbe54c7e61b3bee349da3b71
 SHA512:
-  metadata.gz: 247ca7e7c9eb24fc5ca31c8cfb3f06ec9e4c3779627f3e35722d2c51a630c255cc4d182d434d35da7207f112b0905635a5717fd767f3c904a251b7ab84873cbd
-  data.tar.gz: 2953c510c88ed9078f777a0c8e23399f48339ef5f6c85fcf264fe025de795ecc187407d7d7bddf77b89dbb182eb158123e62aad909c91fbfffc04f613cf8280f
+  metadata.gz: 3768d2dda3e137c33b54ecfe27eda8f052c9eb8e21809e9e8f82eb434f9ce381fdf5cd430d9d118aacb75a6047c4db2bd175d2e9937be3fccc6b587f8cc0b683
+  data.tar.gz: 329dff1413b582f472b099181769c16afc91aeaa9fe6b827b1cb753be68df14d6dbda11e5d60f3da77e97feb22833b7b78db0a231b09a605c5f78d79845f16e0

data/lib/firm/serializable.rb

@@ -11,17 +11,35 @@ module FIRM
 
     class Exception < RuntimeError; end
 
+    # This class encapsulates a serializable property definition.
     class Property
-      def initialize(klass, prop, proc=nil, force: false, handler: nil, &block)
+      def initialize(klass, prop, proc=nil, force: false, handler: nil, optional: false, &block)
         ::Kernel.raise ArgumentError, "Invalid property id [#{prop}]" unless ::String === prop || ::Symbol === prop
         ::Kernel.raise ArgumentError, "Duplicate property id [#{prop}]" if klass.has_serializer_property?(prop)
         @klass = klass
         @id = prop.to_sym
         @forced = force
+        @optional = optional.nil? || optional
+        @default = if @optional
+                     case optional
+                     when Proc
+                       ::Kernel.raise ArgumentError,
+                                      'Invalid optional value proc' unless optional.arity.abs == 2
+                       optional
+                     when UnboundMethod
+                       ::Kernel.raise ArgumentError,
+                                      'Invalid optional value method' unless optional.arity.abs == 1
+                       ->(obj, id) { optional.bind(obj).call(id) }
+                     else
+                       optional == true ? nil : optional
+                     end
+                   else
+                     nil
+                   end
         if block || handler
           if handler
             ::Kernel.raise ArgumentError,
-                           "Invalid property handler #{handler} for #{prop}" unless ::Proc === handler || ::Symbol === handler
+                           "Invalid property handler #{handler} for #{prop}" unless ::Proc === handler || ::Symbol === handler || ::String === handler
             if handler.is_a?(::Proc)
               ::Kernel.raise ArgumentError, "Invalid property block #{proc} for #{prop}" unless block.arity == -3
               @getter = ->(obj) { handler.call(@id, obj) }
@@ -53,10 +71,15 @@ module FIRM
 
       attr_reader :id
 
+      # Serializes the defined property for the given object and inserts the serialized data
+      # into the given data object unless included in the given excludes list.
+      # @param [Object] obj
+      # @param [Object] data hash-like object
+      # @param [Array<Symbol>] excludes
       def serialize(obj, data, excludes)
         unless excludes.include?(@id)
           val = getter.call(obj)
-          unless Serializable === val && val.serialize_disabled? && !@forced
+          unless optional?(obj, val) || (Serializable === val && val.serialize_disabled? && !@forced)
             data[@id] = case val
                         when ::Array
                           val.select { |elem| !(Serializable === elem && elem.serialize_disabled?) }
@@ -69,15 +92,27 @@ module FIRM
         end
       end
 
+      # Returns the (unserialized) property value for the given object.
+      # @param [Object] obj
+      def get(obj)
+        getter.call(obj)
+      end
+
+      # Restores the defined property for the given object using the deserialized data
+      # extracted from the given data object.
+      # @param [Object] obj
+      # @param [Object] data hash-like object
+      # @return [void]
       def deserialize(obj, data)
         if data.has_key?(@id)
           setter.call(obj, data[@id])
         end
       end
 
-      def get(obj)
-        getter.call(obj)
+      def optional?(obj, val)
+        @optional && val == (Proc === @default ? @default.call(obj, @id) : @default)
       end
+      private :optional?
 
       def get_method(id)
         begin
@@ -312,15 +347,22 @@ module FIRM
     module SerializeClassMethods
 
       # Adds (a) serializable property(-ies) for instances of his class (and derived classes)
-      # @overload property(*props, force: false)
+      # @overload property(*props, force: false, optional: false)
       #   Specifies one or more serialized properties.
       #   The serialization framework will determine the availability of setter and getter methods
       #   automatically by looking for methods <code>"#{prop_id}=(v)"</code>, <code>"#set_{prop_id}(v)"</code> or <code>"#{prop_id}(v)"</code>
       #   for setters and <code>"#{prop_id}()"</code> or <code>"#get_{prop_id}"</code> for getters.
       #   @param [Symbol,String] props one or more ids of serializable properties
       #   @param [Boolean] force overrides any #disable_serialize for the properties specified
+      #   @param [Object] optional indicates optionality;
+      #                   if `false` the property will not be optional;
+      #                   `true` means optional if the serialized value == `nil`;
+      #                   any value other than 'false' or 'true' means optional if the serialize value equals that value;
+      #                   alternatively a Proc, Lambda (gets the object and the property id passed) or
+      #                   UnboundMethod (gets the property id passed) can be specified  which
+      #                   is called at serialization time to determine the default (optional) value
       #   @return [void]
-      # @overload property(hash, force: false)
+      # @overload property(hash, force: false, optional: false)
       #   Specifies one or more serialized properties with associated setter/getter method ids/procs/lambda-s.
       #   @example
       #     property(
@@ -340,8 +382,15 @@ module FIRM
       #         to be able to support setting explicit nil values.
       #   @param [Hash] hash a hash of pairs of property ids and getter/setter procs
       #   @param [Boolean] force overrides any #disable_serialize for the properties specified
+      #   @param [Object] optional indicates optionality;
+      #                   if `false` the property will not be optional;
+      #                   `true` means optional if the serialized value == `nil`;
+      #                   any value other than 'false' or 'true' means optional if the serialize value equals that value;
+      #                   alternatively a Proc, Lambda (gets the object and the property id passed) or
+      #                   UnboundMethod (gets the property id passed) can be specified  which
+      #                   is called at serialization time to determine the default (optional) value
       #   @return [void]
-      # @overload property(*props, force: false, handler: nil, &block)
+      # @overload property(*props, force: false, handler: nil, optional: false, &block)
       #   Specifies one or more serialized properties with a getter/setter handler proc/method/block.
       #   The getter/setter proc or block should accept either 2 (property id and object for getter) or 3 arguments
       #   (property id, object and value for setter) and is assumed to handle getter/setter requests
@@ -364,29 +413,38 @@ module FIRM
       #         to be able to support setting explicit nil values.
       #   @param [Symbol,String] props one or more ids of serializable properties
       #   @param [Boolean] force overrides any #disable_serialize for the properties specified
+      #   @param [Symbol,String,Proc] handler serialization handler method name or Proc
+      #   @param [Object] optional indicates optionality;
+      #                   if `false` the property will not be optional;
+      #                   `true` means optional if the serialized value == `nil`;
+      #                   any value other than 'false' or 'true' means optional if the serialize value equals that value;
+      #                   alternatively a Proc, Lambda (gets the object and the property id passed) or
+      #                   UnboundMethod (gets the property id passed) can be specified  which
+      #                   is called at serialization time to determine the default (optional) value
       #   @yieldparam [Symbol,String] id property id
       #   @yieldparam [Object] obj object instance
       #   @yieldparam [Object] val optional property value to set in case of setter request
       #   @return [void]
       def property(*props, **kwargs, &block)
         forced = !!kwargs.delete(:force)
+        optional = kwargs.has_key?(:optional) ? kwargs.delete(:optional) : false
         if block || kwargs[:handler]
           props.each do |prop|
-            serializer_properties << Property.new(self, prop, force: forced, handler: kwargs[:handler], &block)
+            serializer_properties << Property.new(self, prop, force: forced, handler: kwargs[:handler], optional: optional, &block)
           end
         else
           props.flatten.each do |prop|
             if ::Hash === prop
               prop.each_pair do |pn, pp|
-                serializer_properties << Property.new(self, pn, pp, force: forced)
+                serializer_properties << Property.new(self, pn, pp, force: forced, optional: optional)
               end
             else
-              serializer_properties << Property.new(self, prop, force: forced)
+              serializer_properties << Property.new(self, prop, force: forced, optional: optional)
             end
           end
           unless kwargs.empty?
             kwargs.each_pair do |pn, pp|
-              serializer_properties << Property.new(self, pn, pp, force: forced)
+              serializer_properties << Property.new(self, pn, pp, force: forced, optional: optional)
             end
           end
         end

data/lib/firm/version.rb

@@ -4,6 +4,6 @@
 module FIRM
 
   # FIRM version
-  VERSION = "1.0.0"
+  VERSION = "1.1.1"
 
 end

data/tests/serializer_tests.rb

@@ -691,6 +691,69 @@ module SerializerTestMixin
 
   end
 
+  class SomeClass
+
+    include FIRM::Serializable
+
+    property :always
+    property :not_when_nil, optional: true  # alternatively you can use `optional: nil`
+    property :not_when_some_value, optional: -1
+    property :not_when_some_derived_value, optional: ->(_obj, _id) { :derived_value }
+
+    def initialize(always, not_when_nil = nil, not_when_some_value = -1, not_when_some_derived_value = :derived_value)
+      @always = always
+      @not_when_nil = not_when_nil
+      @not_when_some_value = not_when_some_value
+      @not_when_some_derived_value = not_when_some_derived_value
+    end
+
+    attr_accessor :always, :not_when_nil, :not_when_some_value, :not_when_some_derived_value
+
+    class << self
+
+      def deserialize_initializer
+        @init ||= ->(obj, _data) { obj }
+      end
+
+      def deserialize_initializer=(init)
+        @init = init
+      end
+
+    end
+
+
+    def init_from_serialized(_data)
+      initialize(nil) # first call the initialize method
+      self.class.deserialize_initializer.call(self, _data)
+      self
+    end
+    protected :init_from_serialized
+
+  end
+
+  def test_optional
+    SomeClass.deserialize_initializer = ->(obj, _data) {
+      obj.always = 'NOT'
+      obj.not_when_nil = :not_nil
+      obj.not_when_some_value = 10
+      obj.not_when_some_derived_value = nil
+    }
+
+    obj_serial = SomeClass.new('Always').serialize
+    obj_new = assert_nothing_raised { SomeClass.deserialize(obj_serial) }
+    assert_equal('Always', obj_new.always)          # always (de-)serialized, so overwrites custom init on deserialize
+    assert_equal(:not_nil, obj_new.not_when_nil)    # not serialized since nil, so leaves custom init
+    assert_equal(10, obj_new.not_when_some_value)   # not serialized since default value, so leaves custom init
+    assert_nil(obj_new.not_when_some_derived_value) # not serialized since default value, so leaves custom init
+
+    obj_serial = SomeClass.new('Always', :ok, 99, :specific_value).serialize
+    obj_new = assert_nothing_raised { SomeClass.deserialize(obj_serial) }
+    assert_equal('Always', obj_new.always)          # always (de-)serialized, so overwrites custom init on deserialize
+    assert_equal(:ok, obj_new.not_when_nil)         # serialized since not default, so overwrites custom init
+    assert_equal(99, obj_new.not_when_some_value)   # serialized since not default, so overwrites custom init
+    assert_equal(:specific_value, obj_new.not_when_some_derived_value) # serialized since not default, so overwrites custom init
+  end
+
   class House
 
     include FIRM::Serializable

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: firm
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Martin Corino
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-10-08 00:00:00.000000000 Z
+date: 2024-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -103,7 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
+rubygems_version: 3.5.22
 signing_key: 
 specification_version: 4
 summary: Format independent Ruby object marshalling