philosophal 1.2.0 → 2.0.0

data/lib/philosophal/property.rb

@@ -2,7 +2,8 @@
 
 module Philosophal
   class Property
-    def initialize(name:, type:, default:, transform:, immutable:, description:, json:)
+    def initialize(name:, type:, default:, transform:, immutable:, description:, json:, override:,
+                   track_changes: false)
       @name = name
       @type = type
       @default = default
@@ -10,9 +11,11 @@ module Philosophal
       @immutable = immutable
       @description = description
       @json = json
+      @override = override
+      @track_changes = track_changes
     end
 
-    attr_reader :name, :type, :default, :transform, :immutable, :description, :json
+    attr_reader :name, :type, :default, :transform, :immutable, :description, :json, :override, :track_changes
 
     def json_name
       return @json if @json.is_a?(Symbol)
@@ -35,61 +38,167 @@ module Philosophal
       @transform != nil
     end
 
+    def override?
+      @override
+    end
+
+    def track_changes?
+      @track_changes
+    end
+
     def check_conversion(value)
       Philosophal.convert(self, value)
     end
 
-    def generate_writer_method(buffer = +'')
-      buffer <<
-        ' def ' << @name.name << "=(value)\n  " \
-                                 '@' << @name.name << ' = self.class.philosophal_properties[:' <<
-        @name.name <<
-        "].check_conversion(value)\n" \
-        "rescue Philosophal::TypeError => error\n" \
-        "error.set_backtrace(caller(1))\n  raise\n" \
-        "end\n"
-    end
-
-    def generate_immutable_writer_method(buffer = +'')
-      buffer <<
-        ' def ' << @name.name << "=(value)\n  " \
-                                 'raise FrozenError, "can\'t modify frozen variable @' <<
-        @name.name << '" if defined?(@' << @name.name << ")\n" \
-                                                         '@' << @name.name << ' = self.class.philosophal_properties[:' <<
-        @name.name <<
-        "].check_conversion(value).freeze\n" \
-        "rescue Philosophal::TypeError => error\n" \
-        "error.set_backtrace(caller(1))\n  raise\n" \
-        "end\n"
-    end
-
-    def generate_reader_method(buffer = +'')
-      buffer <<
-        ' def ' <<
-        @name.name <<
-        "\n  " \
-        '@' << @name.name << ' || self.class.philosophal_properties[:' <<
-        @name.name <<
-        "].default_value\n" \
-        "end\n"
-    end
-
-    def generate_boolean_method(buffer = +'')
-      buffer <<
-        ' def ' <<
-        @name.name <<
-        "?\n  " \
-        '!!@' << @name.name <<
-        "\nend\n"
-    end
-
-    def generate_description_method(buffer = +'')
-      buffer <<
-        ' def ' <<
-        @name.name <<
-        "_description\n  " \
-        '%(' << @description << ')' \
-                                "\nend\n"
+    # The Convertor method (and subtype) for the type, looked up once since the type never changes.
+    def convert_method
+      return @convert_method if defined?(@convert_method)
+
+      @convert_method = Philosophal::Convertor.convert_method_for(@type)
+    end
+
+    def method_generators
+      generators = {
+        writer_method_name => immutable ? :generate_immutable_writer_method : :generate_writer_method,
+        reader_method_name => default? ? :generate_reader_method : :generate_plain_reader_method
+      }
+      generators[boolean_method_name] = :generate_boolean_method if type == Philosophal::Types::BooleanType::Instance
+      generators[description_method_name] = :generate_description_method if description
+      generators.merge(change_tracking_generators)
+    end
+
+    def change_tracking_generators
+      return {} unless track_changes?
+
+      { was_method_name => :generate_was_method, changed_method_name => :generate_changed_method }
+    end
+
+    # Private constant of the generated methods module holding this property, so the writers
+    # reach it without looking it up in the schema.
+    def constant_name
+      return @constant_name if defined? @constant_name
+
+      @constant_name = :"PHILOSOPHAL_PROPERTY_#{@name.name}"
+    end
+
+    def writer_method_name
+      return @writer_method_name if defined? @writer_method_name
+
+      @writer_method_name = :"#{@name.name}="
+    end
+
+    def generate_writer_method(buffer)
+      buffer << <<~RUBY
+        def #{writer_method_name.name}(value)
+          @#{@name.name} = #{constant_name}.check_conversion(value)
+        rescue Philosophal::TypeError => error
+          error.set_backtrace(caller(1))
+          raise
+        end
+      RUBY
+    end
+
+    def generate_immutable_writer_method(buffer)
+      buffer << <<~RUBY
+        def #{writer_method_name.name}(value)
+          raise FrozenError, "can't modify frozen variable @#{@name.name}" if defined?(@#{@name.name})
+          @#{@name.name} = #{constant_name}.check_conversion(value).freeze
+        rescue Philosophal::TypeError => error
+          error.set_backtrace(caller(1))
+          raise
+        end
+      RUBY
+    end
+
+    def reader_method_name
+      @name
+    end
+
+    def variable_name
+      return @variable_name if defined? @variable_name
+
+      @variable_name = :"@#{@name.name}"
+    end
+
+    # Without a default the reader only returns the variable: attr_reader is the fastest form.
+    # The default is not looked up, so a subclass redeclaring the property with a default and
+    # override: false keeps this reader and does not get its default (not supported).
+    def generate_plain_reader_method(buffer)
+      buffer << "attr_reader :#{reader_method_name.name}\n"
+    end
+
+    def generate_reader_method(buffer)
+      buffer << <<~RUBY
+        def #{reader_method_name.name}
+          @#{@name.name}.nil? ? #{constant_name}.default_value : @#{@name.name}
+        end
+      RUBY
+    end
+
+    def boolean_method_name
+      return @boolean_method_name if defined? @boolean_method_name
+
+      @boolean_method_name = :"#{@name.name}?"
+    end
+
+    def generate_boolean_method(buffer)
+      buffer << <<~RUBY
+        def #{boolean_method_name.name}
+          !!#{reader_method_name.name}
+        end
+      RUBY
+    end
+
+    def description_method_name
+      return @description_method_name if defined? @description_method_name
+
+      @description_method_name = :"#{@name.name}_description"
+    end
+
+    def was_method_name
+      return @was_method_name if defined? @was_method_name
+
+      @was_method_name = :"#{@name.name}_was"
+    end
+
+    def was_variable_name
+      return @was_variable_name if defined? @was_variable_name
+
+      @was_variable_name = :"@__philosophal_#{@name.name}_was__"
+    end
+
+    # Returns the stored value at the last changes_applied (nil before), without falling back to the default.
+    def generate_was_method(buffer)
+      buffer << <<~RUBY
+        def #{was_method_name.name}
+          #{was_variable_name}
+        end
+      RUBY
+    end
+
+    def changed_method_name
+      return @changed_method_name if defined? @changed_method_name
+
+      @changed_method_name = :"#{@name.name}_changed?"
+    end
+
+    # True when the stored value differs from the one recorded at the last changes_applied.
+    def generate_changed_method(buffer)
+      buffer << <<~RUBY
+        def #{changed_method_name.name}
+          @#{@name.name} != #{was_variable_name}
+        end
+      RUBY
+    end
+
+    # The description is read from the property constant rather than written into the generated code,
+    # so it is never evaluated as Ruby.
+    def generate_description_method(buffer)
+      buffer << <<~RUBY
+        def #{description_method_name.name}
+          #{constant_name}.description
+        end
+      RUBY
     end
   end
 end

data/lib/philosophal/transform.rb

@@ -3,12 +3,14 @@
 module Philosophal
   class Transform
     def self.make(method, value)
-      case method
-      when Proc
-        method.call(value)
-      else
-        value.send(method)
-      end
+      return method.call(value) if method.is_a?(Proc)
+
+      result = value.send(method)
+      self_method?(method) ? value : result
+    end
+
+    def self.self_method?(method)
+      method.end_with?('!')
     end
   end
 end

data/lib/philosophal/types/array_of_type.rb

@@ -4,7 +4,7 @@ module Philosophal
   module Types
     class ArrayOfType
       def self.instance(subtype)
-        memorization.fetch(subtype, new(subtype).freeze)
+        memorization[subtype] ||= new(subtype).freeze
       end
 
       def self.memorization
@@ -13,15 +13,16 @@ module Philosophal
         @memorization = {}
       end
 
+      private_class_method :new
+
       attr_reader :subtype
 
       def initialize(subtype)
         @subtype = subtype
-        self.class.memorization[subtype] = self
       end
 
       def ===(array)
-        array.is_a?(Array) && !array.find { |entry| !entry.is_a?(@subtype) }
+        array.is_a?(Array) && array.all?(@subtype)
       end
     end
   end

data/lib/philosophal/types/boolean_type.rb

@@ -8,7 +8,7 @@ module Philosophal
       TRUE_FALSE_SET = Set[true, false]
 
       def ===(value)
-        TRUE_FALSE_SET.include?(value)
+        true.equal?(value) || false.equal?(value)
       end
 
       freeze

data/lib/philosophal/types/hash_of_type.rb

@@ -4,8 +4,7 @@ module Philosophal
   module Types
     class HashOfType
       def self.instance(key_type, value_type)
-        subtype = { key_type:, value_type: }
-        memorization.fetch(Marshal.dump(subtype), new(subtype).freeze)
+        memorization[[key_type, value_type]] ||= new({ key_type:, value_type: }).freeze
       end
 
       def self.memorization
@@ -14,17 +13,20 @@ module Philosophal
         @memorization = {}
       end
 
+      private_class_method :new
+
       attr_reader :subtype
 
       def initialize(subtype)
         @subtype = subtype.freeze
-        self.class.memorization[Marshal.dump(subtype)] = self
       end
 
       def ===(hash)
-        hash.is_a?(Hash) &&
-          !hash.keys.find { |key| !key.is_a?(@subtype[:key_type]) } &&
-          !hash.values.find { |value| !value.is_a?(@subtype[:value_type]) }
+        return false unless hash.is_a?(Hash)
+
+        key_type = @subtype[:key_type]
+        value_type = @subtype[:value_type]
+        hash.all? { |key, value| key.is_a?(key_type) && value.is_a?(value_type) }
       end
     end
   end

data/lib/philosophal.rb

@@ -2,7 +2,6 @@
 
 require 'date'
 require 'pathname'
-require 'set'
 require 'time'
 require 'json'
 
@@ -20,25 +19,24 @@ module Philosophal
   autoload :ArgumentError, 'philosophal/errors/argument_error'
 
   def self.convert(property, value)
-    if property.type === value
-      if property.transform?
-        Transform.make(property.transform, value)
-      else
-        value
-      end
-    else
-      convert_method, subtype = Convertor.convert_method_for(property.type)
-      raise Philosophal::TypeError unless convert_method
+    # nil means "no value": it is neither converted nor transformed, so the reader falls back to the default.
+    return if value.nil?
+
+    converted = property.type === value ? value : convert_to_type(property, value) # rubocop:disable Style/CaseEquality
+    return converted unless property.transform?
 
-      converted = if subtype
-                    Convertor.send(convert_method, value, subtype)
-                  else
-                    Convertor.send(convert_method, value)
-                  end
+    Transform.make(property.transform, converted)
+  end
 
-      return converted unless property.transform?
+  def self.convert_to_type(property, value)
+    convert_method, subtype = property.convert_method
+    raise Philosophal::TypeError unless convert_method
 
-      Transform.make(property.transform, converted)
+    if subtype
+      Convertor.send(convert_method, value, subtype)
+    else
+      Convertor.send(convert_method, value)
     end
   end
+  private_class_method :convert_to_type
 end

data/sig/manifest.yaml

@@ -0,0 +1,5 @@
+dependencies:
+  - name: date
+  - name: json
+  - name: pathname
+  - name: time

data/sig/philosophal/convertor.rbs

@@ -0,0 +1,35 @@
+module Philosophal
+  class Convertor
+    METHOD_TYPE_MAP: Hash[untyped, Symbol]
+
+    def self.convert_method_for: (type_spec type) -> (Symbol | [Symbol?, untyped] | nil)
+
+    def self.convert_to_symbol: (untyped obj) -> Symbol
+
+    def self.convert_to_string: (untyped obj) -> String
+
+    def self.convert_to_integer: (untyped obj) -> Integer
+
+    def self.convert_to_float: (untyped obj) -> Float
+
+    def self.convert_to_array: (untyped obj) -> Array[untyped]
+
+    def self.convert_to_hash: (untyped obj) -> Hash[untyped, untyped]
+
+    def self.convert_to_time: (untyped obj) -> Time
+
+    def self.convert_to_date: (untyped obj) -> Date
+
+    def self.convert_to_date_time: (untyped obj) -> DateTime
+
+    def self.convert_to_any: [T] (T obj) -> T
+
+    def self.convert_to_boolean: (untyped obj) -> bool
+
+    def self.convert_to_pathname: (untyped obj) -> Pathname
+
+    def self.convert_to_array_of: (untyped obj, Module subtype) -> Array[untyped]
+
+    def self.convert_to_hash_of: (untyped obj, Types::HashOfType::subtype subtype) -> Hash[untyped, untyped]
+  end
+end

data/sig/philosophal/errors/argument_error.rbs

@@ -0,0 +1,4 @@
+module Philosophal
+  class ArgumentError < ::ArgumentError
+  end
+end

data/sig/philosophal/errors/type_error.rbs

@@ -0,0 +1,4 @@
+module Philosophal
+  class TypeError < ::TypeError
+  end
+end

data/sig/philosophal/loaders/errors.rbs

@@ -0,0 +1,6 @@
+module Philosophal
+  module Loaders
+    class LoadError < StandardError
+    end
+  end
+end

data/sig/philosophal/loaders/json_loader.rbs

@@ -0,0 +1,29 @@
+module Philosophal
+  module Loaders
+    class JsonLoader
+      @klass: untyped
+
+      def initialize: (Properties klass) -> void
+
+      # A Hash or a JSON object string returns one instance, an Array or a JSON array string returns a list,
+      # any other String is read as a path to a JSON file.
+      def load: (Hash[Symbol, untyped] json) -> untyped
+              | (Array[Hash[Symbol, untyped]] json) -> Array[untyped]
+              | (String json) -> untyped
+
+      private
+
+      def load_from_array: (Array[Hash[Symbol, untyped]] array) -> Array[untyped]
+
+      def load_from_hash: (Hash[Symbol, untyped] hash) -> untyped
+
+      def setter_from_key: (Symbol key) -> Symbol
+
+      def load_from_json: (String str) -> untyped
+
+      def load_from_json_collection: (String json) -> Array[untyped]
+
+      def load_from_path: (String path) -> untyped
+    end
+  end
+end

data/sig/philosophal/loaders.rbs

@@ -0,0 +1,4 @@
+module Philosophal
+  module Loaders
+  end
+end

data/sig/philosophal/properties/instance_methods.rbs

@@ -0,0 +1,26 @@
+module Philosophal
+  module Properties
+    # Included in the instances of the classes that declare properties.
+    module InstanceMethods
+      def cprop?: (String | Symbol property_name, untyped klass) -> bool
+
+      def philosophal_inspect: (?boolish light) -> String
+
+      alias cprop_inspect philosophal_inspect
+
+      def philosophal_inspect_map: () -> Hash[Symbol, untyped]
+
+      alias cprop_inspect_map philosophal_inspect_map
+
+      def philosophal_values: () -> Array[Property]
+
+      def changed_properties: () -> Hash[Symbol, untyped]
+
+      def changes_applied: () -> self
+
+      def to_json_hash: () -> Hash[Symbol, untyped]
+
+      def to_json: (*untyped _args) -> String
+    end
+  end
+end

data/sig/philosophal/properties/schema.rbs

@@ -0,0 +1,47 @@
+module Philosophal
+  module Properties
+    class Schema
+      include Enumerable[Property]
+
+      @properties_index: Hash[Symbol, Property]
+      @mutex: Thread::Mutex
+      @immutables: Hash[Symbol, Property]
+      @mutables: Hash[Symbol, Property]
+      @json_names_h: Hash[Symbol, Symbol]
+      @json_setters: Hash[Symbol, Symbol]
+      @json_properties: Array[Property]
+      @tracked: Array[Property]
+
+      def initialize: (?properties_index: Hash[Symbol, Property]) -> void
+
+      def initialize_copy: (Schema source) -> void
+
+      attr_reader properties_index: Hash[Symbol, Property]
+
+      def []: (Symbol? key) -> Property?
+
+      def keys: () -> Array[Symbol]
+
+      def each: () { (Property) -> void } -> self
+              | () -> Enumerator[Property, self]
+
+      def <<: (Property value) -> self
+
+      def immutables: () -> Hash[Symbol, Property]
+
+      def mutables: () -> Hash[Symbol, Property]
+
+      def json_names_h: () -> Hash[Symbol, Symbol]
+
+      def json_setters: () -> Hash[Symbol, Symbol]
+
+      def json_properties: () -> Array[Property]
+
+      def tracked: () -> Array[Property]
+
+      private
+
+      def clear_caches: () -> void
+    end
+  end
+end

data/sig/philosophal/properties.rbs

@@ -0,0 +1,59 @@
+module Philosophal
+  # Extended by the classes that declare properties.
+  module Properties : Module
+    include Philosophal::Types
+
+    @philosophal_properties: Schema
+    @philosophal_descriptions: Hash[Symbol, String]
+    @json: Loaders::JsonLoader
+    @__philosophal_extension__: Module
+
+    def cprop: (
+                 Symbol name,
+                 type_spec `type`,
+                 ?default: untyped,
+                 ?transform: transform?,
+                 ?immutable: bool,
+                 ?description: String?,
+                 ?json: bool | String | Symbol,
+                 ?override: bool,
+                 ?track_changes: bool
+               ) -> untyped
+
+    def philosophal_properties: () -> Schema
+
+    def philosophal_descriptions: () -> Hash[Symbol, String]
+
+    alias cprop_descriptions philosophal_descriptions
+
+    def json: () -> Loaders::JsonLoader
+
+    private
+
+    def __philosophal_property_class__: () -> singleton(Property)
+
+    def __define_philosophal_methods__: (Property new_property) -> untyped
+
+    def __set_philosophal_property_constant__: (Property property) -> void
+
+    def __philosophal_extension__: () -> Module
+
+    def __generate_philosophal_methods__: (Property new_property) -> String
+
+    def __remove_philosophal_own_method__: (Symbol method_name) -> void
+
+    def __check_philosophal_options__: (
+                                         Symbol name,
+                                         transform: untyped,
+                                         immutable: untyped,
+                                         override: untyped,
+                                         description: untyped,
+                                         json: untyped,
+                                         track_changes: untyped
+                                       ) -> void
+
+    def __check_philosophal_transform_option__: (Symbol name, untyped transform) -> void
+
+    def __check_philosophal_boolean_option__: (Symbol option_name, untyped value) -> void
+  end
+end