dry-core 0.4.7

data/lib/dry/core/class_attributes.rb

@@ -0,0 +1,83 @@
+require 'dry/core/constants'
+require 'dry/core/errors'
+
+module Dry
+  module Core
+    # Internal support module for class-level settings
+    #
+    # @api public
+    module ClassAttributes
+      include Constants
+
+      # Specify what attributes a class will use
+      #
+      # @example
+      #  class ExtraClass
+      #    extend Dry::Core::ClassAttributes
+      #
+      #    defines :hello
+      #
+      #    hello 'world'
+      #  end
+      #
+      # @example with inheritance and type checking
+      #
+      #  class MyClass
+      #    extend Dry::Core::ClassAttributes
+      #
+      #    defines :one, :two, type: Integer
+      #
+      #    one 1
+      #    two 2
+      #  end
+      #
+      #  class OtherClass < MyClass
+      #    two 3
+      #  end
+      #
+      #  MyClass.one # => 1
+      #  MyClass.two # => 2
+      #
+      #  OtherClass.one # => 1
+      #  OtherClass.two # => 3
+      #
+      # @example with dry-types
+      #
+      #  class Foo
+      #    extend Dry::Core::ClassAttributes
+      #
+      #    defines :one, :two, type: Dry::Types['strict.int']
+      #  end
+      #
+      def defines(*args, type: Object)
+        mod = Module.new do
+          args.each do |name|
+            define_method(name) do |value = Undefined|
+              ivar = "@#{name}"
+
+              if value == Undefined
+                if instance_variable_defined?(ivar)
+                  instance_variable_get(ivar)
+                else
+                  nil
+                end
+              else
+                raise InvalidClassAttributeValue.new(name, value) unless type === value
+
+                instance_variable_set(ivar, value)
+              end
+            end
+          end
+
+          define_method(:inherited) do |klass|
+            args.each { |name| klass.send(name, send(name)) }
+
+            super(klass)
+          end
+        end
+
+        extend(mod)
+      end
+    end
+  end
+end

data/lib/dry/core/class_builder.rb

@@ -0,0 +1,105 @@
+module Dry
+  module Core
+    # Class for generating more classes
+    class ClassBuilder
+      ParentClassMismatch = Class.new(TypeError)
+
+      attr_reader :name
+      attr_reader :parent
+      attr_reader :namespace
+
+      def initialize(name:, parent: nil, namespace: nil)
+        @name = name
+        @namespace = namespace
+        @parent = parent || Object
+      end
+
+      # Generate a class based on options
+      #
+      # @example Create anonymous class
+      #   builder = Dry::Core::ClassBuilder.new(name: 'MyClass')
+      #
+      #   klass = builder.call
+      #   klass.name # => "MyClass"
+      #
+      # @example Create named class
+      #   builder = Dry::Core::ClassBuilder.new(name: 'User', namespace: Entities)
+      #
+      #   klass = builder.call
+      #   klass.name # => "Entities::User"
+      #   klass.superclass.name # => "Entities::User"
+      #   Entities::User # => "Entities::User"
+      #   klass.superclass == Entities::User # => true
+      #
+      # @return [Class]
+      def call
+        klass = if namespace
+                  create_named
+                else
+                  create_anonymous
+                end
+
+        yield(klass) if block_given?
+
+        klass
+      end
+
+      private
+
+      # @api private
+      def create_anonymous
+        klass = Class.new(parent)
+        name = self.name
+
+        klass.singleton_class.class_eval do
+          define_method(:name) { name }
+          alias_method :inspect, :name
+          alias_method :to_s, :name
+        end
+
+        klass
+      end
+
+      # @api private
+      def create_named
+        name = self.name
+        base = create_base(namespace, name, parent)
+        klass = Class.new(base)
+
+        namespace.module_eval do
+          remove_const(name)
+          const_set(name, klass)
+
+          const_get(name).name if RUBY_VERSION < '2.4'
+
+          remove_const(name)
+          const_set(name, base)
+        end
+
+        klass
+      end
+
+      # @api private
+      def create_base(namespace, name, parent)
+        begin
+          namespace.const_get(name)
+        rescue NameError
+        end
+
+        if namespace.const_defined?(name, false)
+          existing = namespace.const_get(name)
+
+          unless existing <= parent
+            raise ParentClassMismatch, "#{ existing.name } must be a subclass of #{ parent.name }"
+          end
+
+          existing
+        else
+          klass = Class.new(parent || Object)
+          namespace.const_set(name, klass)
+          klass
+        end
+      end
+    end
+  end
+end

data/lib/dry/core/constants.rb

@@ -0,0 +1,77 @@
+require 'set'
+
+module Dry
+  module Core
+    # A list of constants you can use to avoid memory allocations or identity checks.
+    #
+    # @example Just include this module to your class or module
+    #   class Foo
+    #     def call(value = EMPTY_ARRAY)
+    #        value.map(&:to_s)
+    #     end
+    #   end
+    #
+    # @api public
+    module Constants
+      # An empty array
+      EMPTY_ARRAY = [].freeze
+      # An empty hash
+      EMPTY_HASH = {}.freeze
+      # An empty list of options
+      EMPTY_OPTS = {}.freeze
+      # An empty set
+      EMPTY_SET = Set.new.freeze
+      # An empty string
+      EMPTY_STRING = ''.freeze
+
+      # A special value you can use as a default to know if no arguments
+      # were passed to you method
+      #
+      # @example
+      #   def method(value = Undefined)
+      #     if value == Undefined
+      #       puts 'no args'
+      #     else
+      #       puts value
+      #     end
+      #   end
+      Undefined = Object.new.tap do |undefined|
+        def undefined.to_s
+          'Undefined'
+        end
+
+        def undefined.inspect
+          'Undefined'
+        end
+
+        # Pick a value, if the first argument is not Undefined, return it back,
+        # otherwise return the second arg or yield the block.
+        #
+        # @example
+        #  def method(val = Undefined)
+        #    1 + Undefined.default(val, 2)
+        #  end
+        #
+        def undefined.default(x, y = self)
+          if x.equal?(self)
+            if y.equal?(self)
+              yield
+            else
+              y
+            end
+          else
+            x
+          end
+        end
+      end.freeze
+
+      def self.included(base)
+        super
+
+        constants.each do |const_name|
+          base.const_set(const_name, const_get(const_name))
+        end
+      end
+    end
+  end
+end

data/lib/dry/core/deprecations.rb

@@ -0,0 +1,224 @@
+require 'logger'
+
+module Dry
+  module Core
+    # An extension for issueing warnings on using deprecated methods.
+    #
+    # @example
+    #
+    #   class Foo
+    #     def self.old_class_api; end
+    #     def self.new_class_api; end
+    #
+    #     deprecate_class_method :old_class_api, :new_class_api
+    #
+    #     def old_api; end
+    #     def new_api; end
+    #
+    #     deprecate_method :old_api, :new_api, "old_api is no-no"
+    #   end
+    #
+    # @example You also can use this module for your custom messages
+    #
+    #   Dry::Core::Deprecations.announce("Foo", "use bar instead")
+    #   Dry::Core::Deprecations.warn("Baz is going to be removed soon")
+    #
+    # @api public
+    module Deprecations
+      STACK = -> { caller.find { |l| l !~ %r{(lib/dry/core)|(gems)} } }
+
+      class << self
+        # Prints a warning
+        #
+        # @param [String] msg Warning string
+        def warn(msg, tag: nil)
+          tagged = "[#{tag || 'deprecated'}] #{msg.gsub(/^\s+/, '')}"
+          logger.warn(tagged)
+        end
+
+        # Wraps arguments with a standard message format and prints a warning
+        #
+        # @param [Object] name what is deprecated
+        # @param [String] msg additional message usually containing upgrade instructions
+        def announce(name, msg, tag: nil)
+          warn(deprecation_message(name, msg), tag: tag)
+        end
+
+        # @api private
+        def deprecation_message(name, msg)
+          <<-MSG
+            #{ name } is deprecated and will be removed in the next major version
+            #{ msg }
+          MSG
+        end
+
+        # @api private
+        def deprecated_name_message(old, new = nil, msg = nil)
+          if new
+            deprecation_message(old, <<-MSG)
+              Please use #{new} instead.
+              #{msg}
+            MSG
+          else
+            deprecation_message(old, msg)
+          end
+        end
+
+        # Returns the logger used for printing warnings.
+        # You can provide your own with .set_logger!
+        #
+        # @param [IO] output output stream
+        #
+        # @return [Logger]
+        def logger(output = $stderr)
+          if defined?(@logger)
+            @logger
+          else
+            set_logger!(output)
+          end
+        end
+
+        # Sets a custom logger. This is a global setting.
+        #
+        # @overload set_logger!(output)
+        #   @param [IO] output Stream for messages
+        #
+        # @overload set_logger!
+        #   Stream messages to stdout
+        #
+        # @overload set_logger!(logger)
+        #   @param [#warn] logger
+        #
+        # @api public
+        def set_logger!(output = $stderr)
+          if output.respond_to?(:warn)
+            @logger = output
+          else
+            @logger = Logger.new(output).tap do |logger|
+              logger.formatter = proc { |_, _, _, msg| "#{ msg }\n" }
+            end
+          end
+        end
+
+        def [](tag)
+          Tagged.new(tag)
+        end
+      end
+
+      # @api private
+      class Tagged < Module
+        def initialize(tag)
+          @tag = tag
+        end
+
+        def extended(base)
+          base.extend Interface
+          base.deprecation_tag @tag
+        end
+      end
+
+      module Interface
+        # Sets/gets deprecation tag
+        #
+        # @option [String,Symbol] tag tag
+        def deprecation_tag(tag = nil)
+          if defined?(@deprecation_tag)
+            @deprecation_tag
+          else
+            @deprecation_tag = tag
+          end
+        end
+
+        # Issue a tagged warning message
+        #
+        # @param [String] msg warning message
+        def warn(msg)
+          Deprecations.warn(msg, tag: deprecation_tag)
+        end
+
+        # Mark instance method as deprecated
+        #
+        # @param [Symbol] old_name deprecated method
+        # @param [Symbol] new_name replacement (not required)
+        # @option [String] message optional deprecation message
+        def deprecate(old_name, new_name = nil, message: nil)
+          full_msg = Deprecations.deprecated_name_message(
+            "#{self.name}##{old_name}",
+            new_name ? "#{self.name}##{new_name}" : nil,
+            message
+          )
+          mod = self
+
+          if new_name
+            undef_method old_name if method_defined?(old_name)
+
+            define_method(old_name) do |*args, &block|
+              mod.warn("#{ full_msg }\n#{ STACK.() }")
+              __send__(new_name, *args, &block)
+            end
+          else
+            aliased_name = :"#{old_name}_without_deprecation"
+            alias_method aliased_name, old_name
+            private aliased_name
+            undef_method old_name
+
+            define_method(old_name) do |*args, &block|
+              mod.warn("#{ full_msg }\n#{ STACK.() }")
+              __send__(aliased_name, *args, &block)
+            end
+          end
+        end
+
+        # Mark class-level method as deprecated
+        #
+        # @param [Symbol] old_name deprecated method
+        # @param [Symbol] new_name replacement (not required)
+        # @option [String] message optional deprecation message
+        def deprecate_class_method(old_name, new_name = nil, message: nil)
+          full_msg = Deprecations.deprecated_name_message(
+            "#{self.name}.#{old_name}",
+            new_name ? "#{self.name}.#{new_name}" : nil,
+            message
+          )
+
+          meth = new_name ? method(new_name) : method(old_name)
+
+          singleton_class.instance_exec do
+            undef_method old_name if method_defined?(old_name)
+
+            define_method(old_name) do |*args, &block|
+              warn("#{ full_msg }\n#{ STACK.() }")
+              meth.call(*args, &block)
+            end
+          end
+        end
+
+        # Mark a constant as deprecated
+        # @param [Symbol] constant_name constant name to be deprecated
+        # @option [String] message optional deprecation message
+        def deprecate_constant(constant_name, message: nil)
+          value = const_get(constant_name)
+          remove_const(constant_name)
+
+          full_msg = Deprecations.deprecated_name_message(
+            "#{self.name}::#{constant_name}",
+            message
+          )
+
+          mod = Module.new do
+            define_method(:const_missing) do |missing|
+              if missing == constant_name
+                warn("#{ full_msg }\n#{ STACK.() }")
+                value
+              else
+                super(missing)
+              end
+            end
+          end
+
+          extend(mod)
+        end
+      end
+    end
+  end
+end