Module: Familia::Distinguisher

Included in:
Familia
Defined in:
lib/familia/distinguisher.rb

Instance Method Summary collapse

Instance Method Details

#distinguisher(value_to_distinguish, strict_values: true) ⇒ String?

This method determines the appropriate transformation to apply based on the class of the input argument.

The method uses a case statement to handle different classes:

  • For Symbol, String, Integer, and Float classes, it traces the operation and converts the value to a string.
  • For Familia::Horreum class, it traces the operation and returns the identifier of the value.
  • For TrueClass, FalseClass, and NilClass, it traces the operation and converts the value to a string ("true", "false", or "").
  • For any other class, it traces the operation and returns nil.

Alternative names for value_to_distinguish could be input_value, value, or object.

Parameters:

  • value_to_distinguish (Object) —

    The value to be processed. Keep in mind that all data is stored as a string so whatever the type of the value, it will be converted to a string.

  • strict_values (Boolean) (defaults to: true) —

    Whether to enforce strict value handling. Defaults to true.

Returns:

  • (String, nil) —

    The processed value as a string or nil for unsupported classes.



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/familia/distinguisher.rb', line 28

def distinguisher(value_to_distinguish, strict_values: true)
  case value_to_distinguish
  when ::Symbol, ::String, ::Integer, ::Float
    Familia.trace :TOREDIS_DISTINGUISHER, nil, 'string' if Familia.debug?

    # Symbols and numerics are naturally serializable to strings
    # so it's a relatively low risk operation.
    value_to_distinguish.to_s

  when ::TrueClass, ::FalseClass, ::NilClass
    Familia.trace :TOREDIS_DISTINGUISHER, nil, 'true/false/nil' if Familia.debug?

    # TrueClass, FalseClass, and NilClass are considered high risk because their
    # original types cannot be reliably determined from their serialized string
    # representations. This can lead to unexpected behavior during deserialization.
    # For instance, a TrueClass value serialized as "true" might be deserialized as
    # a String, causing application errors. Even more problematic, a NilClass value
    # serialized as an empty string makes it impossible to distinguish between a
    # nil value and an empty string upon deserialization. Such scenarios can result
    # in subtle, hard-to-diagnose bugs. To mitigate these risks, we raise an
    # exception when encountering these types unless the strict_values option is
    # explicitly set to false.
    #
    raise Familia::NotDistinguishableError, value_to_distinguish if strict_values

    value_to_distinguish.to_s #=> "true", "false", ""

  when Familia::Base, Class
    Familia.trace :TOREDIS_DISTINGUISHER, nil, 'base' if Familia.debug?

    # When called with a class we simply transform it to its name. For
    # instances of Familia class, we store the identifier.
    if value_to_distinguish.is_a?(Class)
      value_to_distinguish.name
    else
      value_to_distinguish.identifier
    end

  else
    Familia.trace :TOREDIS_DISTINGUISHER, nil, "else1 #{strict_values}" if Familia.debug?

    if value_to_distinguish.class.ancestors.member?(Familia::Base)
      Familia.trace :TOREDIS_DISTINGUISHER, nil, 'isabase' if Familia.debug?

      value_to_distinguish.identifier

    else
      Familia.trace :TOREDIS_DISTINGUISHER, nil, "else2 #{strict_values}" if Familia.debug?
      raise Familia::NotDistinguishableError, value_to_distinguish if strict_values

      nil
    end
  end
end