mobility 0.8.11 → 1.0.0.rc1

data/lib/mobility/plugins/attribute_methods.rb

@@ -12,30 +12,39 @@ attributes only.
 
 =end
     module AttributeMethods
-      class << self
-        # Applies attribute_methods plugin for a given option value.
-        # @param [Attributes] attributes
-        # @param [Boolean] option Value of option
-        # @raise [ArgumentError] if model class does not support dirty tracking
-        def apply(attributes, option)
-          if option
-            include_attribute_methods_module(attributes.model_class, *attributes.names)
-          end
+      extend Plugin
+
+      default true
+      requires :attributes
+
+      initialize_hook do |*names|
+        include InstanceMethods
+
+        define_method :translated_attributes do
+          super().merge(names.inject({}) do |attributes, name|
+            attributes.merge(name.to_s => send(name))
+          end)
+        end
+      end
+
+      # Applies attribute_methods plugin for a given option value.
+      included_hook do
+        if options[:attribute_methods]
+          define_method :untranslated_attributes, ::ActiveRecord::Base.instance_method(:attributes)
         end
+      end
 
-        private
-
-        def include_attribute_methods_module(model_class, *attribute_names)
-          module_builder =
-            if Loaded::ActiveRecord && model_class.ancestors.include?(::ActiveRecord::AttributeMethods)
-              require "mobility/plugins/active_record/attribute_methods"
-              Plugins::ActiveRecord::AttributeMethods
-            else
-              raise ArgumentError, "#{model_class} does not support AttributeMethods plugin."
-            end
-          model_class.include module_builder.new(*attribute_names)
+      module InstanceMethods
+        def translated_attributes
+          {}
+        end
+
+        def attributes
+          super.merge(translated_attributes)
         end
       end
     end
+
+    register_plugin(:attribute_methods, AttributeMethods)
   end
 end

data/lib/mobility/plugins/attributes.rb

@@ -0,0 +1,72 @@
+# frozen-string-literal: true
+module Mobility
+  module Plugins
+=begin
+
+Takes arguments, converts them to strings, and stores in an array +@names+,
+made available with an +attr_reader+. Also provides some convenience methods
+for aggregating attributes.
+
+=end
+    module Attributes
+      extend Plugin
+
+      # Attribute names for which accessors will be defined
+      # @return [Array<String>] Array of names
+      attr_reader :names
+
+      initialize_hook do |*names|
+        @names = names.map(&:to_s).freeze
+      end
+
+      # Yield each attribute name to block
+      # @yieldparam [String] Attribute
+      def each &block
+        names.each(&block)
+      end
+
+      # Show useful information about this module.
+      # @return [String]
+      def inspect
+        "#<Translations @names=#{names.join(", ")}>"
+      end
+
+      included_hook do |klass|
+        names = @names
+
+        klass.class_eval do
+          extend ClassMethods
+          names.each { |name| mobility_attributes << name.to_s }
+          mobility_attributes.uniq!
+        rescue FrozenError
+          raise FrozenAttributesError, "Attempting to translate these attributes on #{klass}, which has already been subclassed: #{names.join(', ')}."
+        end
+      end
+
+      module ClassMethods
+        # Return true if attribute name is translated on this model.
+        # @param [String, Symbol] Attribute name
+        # @return [Boolean]
+        def mobility_attribute?(name)
+          mobility_attributes.include?(name.to_s)
+        end
+
+        # Return translated attribute names on this model.
+        # @return [Array<String>] Attribute names
+        def mobility_attributes
+          @mobility_attributes ||= []
+        end
+
+        def inherited(klass)
+          super
+          attrs = mobility_attributes.freeze # ensure attributes are not modified after being inherited
+          klass.class_eval { @mobility_attributes = attrs.dup }
+        end
+      end
+
+      class FrozenAttributesError < Error; end
+    end
+
+    register_plugin(:attributes, Attributes)
+  end
+end

data/lib/mobility/plugins/backend.rb

@@ -0,0 +1,161 @@
+# frozen-string-literal: true
+module Mobility
+  module Plugins
+=begin
+
+Plugin for setting up a backend for a set of model attributes. All backend
+plugins must depend on this.
+
+Defines:
+- instance method +mobility_backends+ which returns a hash whose keys are
+  attribute names and values a backend for each attribute.
+- class method +mobility_backend_class+ which takes an attribute name and
+  returns the backend class for that name.
+
+=end
+    module Backend
+      extend Plugin
+
+      requires :attributes, include: :before
+
+      # Backend class
+      # @return [Class] Backend class
+      attr_reader :backend_class
+
+      # Backend
+      # @return [Symbol,Class,Class] Name of backend, or backend class
+      attr_reader :backend
+
+      # Backend options
+      # @return [Hash] Options for backend
+      attr_reader :backend_options
+
+      def initialize(*args, **original_options)
+        super
+
+        # Validate that the default backend from config has valid keys
+        if (default = self.class.defaults[:backend])
+          name, backend_options = default
+          extra_keys = backend_options.keys - backend.valid_keys
+          raise InvalidOptionKey, "These are not valid #{name} backend keys: #{extra_keys.join(', ')}." unless extra_keys.empty?
+        end
+
+        include InstanceMethods
+      end
+
+      # Setup backend class, include modules into model class, include/extend
+      # shared modules and setup model with backend setup block (see
+      # {Mobility::Backend::Setup#setup_model}).
+      def included(klass)
+        super
+
+        klass.extend ClassMethods
+
+        if backend
+          @backend_class = backend.build_subclass(klass, backend_options)
+
+          backend_class.setup_model(klass, names)
+
+          names = @names
+          backend_class = @backend_class
+
+          klass.class_eval do
+            names.each { |name| mobility_backend_classes[name.to_sym] = backend_class }
+          end
+
+          backend_class
+        end
+      end
+
+      # Include backend name in inspect string.
+      # @return [String]
+      def inspect
+        "#<Translations (#{backend}) @names=#{names.join(", ")}>"
+      end
+
+      def load_backend(backend)
+        Backends.load_backend(backend)
+      rescue Backends::LoadError => e
+        raise e, "could not find a #{backend} backend. Did you forget to include an ORM plugin like active_record or sequel?"
+      end
+
+      private
+
+      # Override to extract backend options from options hash.
+      def initialize_options(original_options)
+        super
+
+        case options[:backend]
+        when String, Symbol, Class
+          @backend, @backend_options = options[:backend], options
+        when Array
+          @backend, @backend_options = options[:backend]
+          @backend_options = @backend_options.merge(original_options)
+        when NilClass
+          @backend = @backend_options = nil
+        else
+          raise ArgumentError, "backend must be either a backend name, a backend class, or a two-element array"
+        end
+
+        @backend = load_backend(backend)
+      end
+
+      # Override default validation to exclude backend options, which may be
+      # mixed in with plugin options.
+      def validate_options(options)
+        return super unless backend
+        super(options.slice(*(options.keys - backend.valid_keys)))
+      end
+
+      # Override default argument-handling in DSL to store kwargs passed along
+      # with plugin name.
+      def self.configure_default(defaults, key, backend = nil, backend_options = {})
+        defaults[key] = [backend, backend_options] if backend
+      end
+
+      module InstanceMethods
+        # Return a new backend for an attribute name.
+        # @return [Hash] Hash of attribute names and backend instances
+        # @api private
+        def mobility_backends
+          @mobility_backends ||= ::Hash.new do |hash, name|
+            next hash[name.to_sym] if String === name
+            hash[name] = self.class.mobility_backend_class(name).new(self, name.to_s)
+          end
+        end
+
+        def initialize_dup(other)
+          @mobility_backends = nil
+          super
+        end
+      end
+
+      module ClassMethods
+        # Return backend class for a given attribute name.
+        # @param [Symbol,String] Name of attribute
+        # @return [Class] Backend class
+        def mobility_backend_class(name)
+          mobility_backend_classes.fetch(name.to_sym)
+        rescue KeyError
+          raise KeyError, "No backend for: #{name}"
+        end
+
+        def inherited(klass)
+          parent_classes = mobility_backend_classes.freeze # ensure backend classes are not modified after being inherited
+          klass.class_eval { @mobility_backend_classes = parent_classes.dup }
+          super
+        end
+
+        protected
+
+        def mobility_backend_classes
+          @mobility_backend_classes ||= {}
+        end
+      end
+
+      class InvalidOptionKey < Error; end
+    end
+
+    register_plugin(:backend, Backend)
+  end
+end

data/lib/mobility/plugins/backend_reader.rb

@@ -0,0 +1,34 @@
+# frozen-string-literal: true
+module Mobility
+  module Plugins
+=begin
+
+Defines convenience methods for accessing backends, of the form
+"<name>_backend". The format for this method can be customized by passing a
+different format string as the plugin option.
+
+=end
+    module BackendReader
+      extend Plugin
+
+      default true
+      requires :backend
+
+      initialize_hook do |*names|
+        if backend_reader = options[:backend_reader]
+          backend_reader = "%s_backend" if backend_reader == true
+
+          names.each do |name|
+            module_eval <<-EOM, __FILE__, __LINE__ + 1
+            def #{backend_reader % name}
+              mobility_backends[:#{name}]
+            end
+            EOM
+          end
+        end
+      end
+    end
+
+    register_plugin(:backend_reader, BackendReader)
+  end
+end

data/lib/mobility/plugins/cache.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-require "mobility/plugins/cache/translation_cacher"
 
 module Mobility
   module Plugins
@@ -8,8 +7,7 @@ module Mobility
 Caches values fetched from the backend so subsequent fetches can be performed
 more quickly. The cache stores cached values in a simple hash, which is not
 optimal for some storage strategies, so some backends (KeyValue, Table) use a
-custom module through the {Mobility::Backend::Setup#apply_plugin} hook. For
-details see the documentation for these backends.
+custom module by defining a method, +include_cache+, on the backend class.
 
 The cache is reset when one of a set of events happens (saving, reloading,
 etc.). See {BackendResetter} for details.
@@ -21,34 +19,78 @@ Values are added to the cache in two ways:
 
 =end
     module Cache
+      extend Plugin
+
+      default true
+      requires :backend, include: :before
+
       # Applies cache plugin to attributes.
-      # @param [Attributes] attributes
-      # @param [Boolean] option
-      def self.apply(attributes, option)
-        if option
-          backend_class = attributes.backend_class
-          backend_class.include(self) unless backend_class.apply_plugin(:cache)
-
-          model_class = attributes.model_class
-          model_class.include BackendResetter.for(model_class).new(attributes.names) { clear_cache }
+      included_hook do |_, backend_class|
+        if options[:cache]
+          if backend_class.respond_to?(:include_cache)
+            backend_class.include_cache
+          else
+            include_cache(backend_class)
+          end
         end
       end
 
-      # @group Backend Accessors
-      #
-      # @!macro backend_reader
-      # @!method read(locale, value, options = {})
-      #   @option options [Boolean] cache *false* to disable cache.
-      include TranslationCacher.new(:read)
-
-      # @!macro backend_writer
-      # @option options [Boolean] cache
-      #   *false* to disable cache.
-      def write(locale, value, **options)
-        return super if options.delete(:cache) == false
-        cache[locale] = super
+      private
+
+      def include_cache(backend_class)
+        backend_class.include BackendMethods
+      end
+
+      # Used in ORM cache plugins
+      def define_cache_hooks(klass, *reset_methods)
+        mod = self
+        private_methods = reset_methods & klass.private_instance_methods
+        reset_methods.each do |method_name|
+          define_method method_name do |*args|
+            super(*args).tap do
+              mod.names.each { |name| mobility_backends[name].clear_cache }
+            end
+          end
+        end
+        klass.class_eval { private(*private_methods) }
+      end
+
+      module BackendMethods
+        # @group Backend Accessors
+        #
+        # @!macro backend_reader
+        # @!method read(locale, value, options = {})
+        #   @option options [Boolean] cache *false* to disable cache.
+        def read(locale, **options)
+          return super(locale, **options) if options.delete(:cache) == false
+          if cache.has_key?(locale)
+            cache[locale]
+          else
+            cache[locale] = super(locale, **options)
+          end
+        end
+
+        # @!macro backend_writer
+        # @option options [Boolean] cache
+        #   *false* to disable cache.
+        def write(locale, value, **options)
+          return super if options.delete(:cache) == false
+          cache[locale] = super
+        end
+        # @!endgroup
+
+        def clear_cache
+          @cache = {}
+        end
+
+        private
+
+        def cache
+          @cache ||= {}
+        end
       end
-      # @!endgroup
     end
+
+    register_plugin(:cache, Cache)
   end
 end

data/lib/mobility/plugins/default.rb

@@ -6,8 +6,7 @@ module Mobility
 
 Defines value or proc to fall through to if return value from getter would
 otherwise be nil. This plugin is disabled by default but will be enabled if any
-value (other than +Mobility::Plugins::OPTION_UNSET+) is passed as the +default+
-option key.
+value is passed as the +default+ option key.
 
 If default is a +Proc+, it will be called with the context of the model, and
 passed arguments:
@@ -63,11 +62,13 @@ The proc can accept zero to three arguments (see examples below)
   #=> "Post"
 =end
     module Default
+      extend Plugin
+
+      requires :backend, include: :before
+
       # Applies default plugin to attributes.
-      # @param [Attributes] attributes
-      # @param [Object] option
-      def self.apply(attributes, option)
-        attributes.backend_class.include(self) unless option == Plugins::OPTION_UNSET
+      included_hook do |_klass, backend_class|
+        backend_class.include(BackendMethods)
       end
 
       # Generate a default value for given parameters.
@@ -82,19 +83,23 @@ The proc can accept zero to three arguments (see examples below)
         model.instance_exec(*args, &default_value)
       end
 
-      # @!group Backend Accessors
-      # @!macro backend_reader
-      # @option accessor_options [Boolean] default
-      #   *false* to disable presence filter.
-      def read(locale, accessor_options = {})
-        default = accessor_options.has_key?(:default) ? accessor_options.delete(:default) : options[:default]
-        if (value = super(locale, accessor_options)).nil?
-          Default[default, locale: locale, accessor_options: accessor_options, model: model, attribute: attribute]
-        else
-          value
+      module BackendMethods
+        # @!group Backend Accessors
+        # @!macro backend_reader
+        # @option accessor_options [Boolean] default
+        #   *false* to disable presence filter.
+        def read(locale, accessor_options = {})
+          default = accessor_options.has_key?(:default) ? accessor_options.delete(:default) : options[:default]
+          if (value = super(locale, **accessor_options)).nil?
+            Default[default, locale: locale, accessor_options: accessor_options, model: model, attribute: attribute]
+          else
+            value
+          end
         end
+        # @!endgroup
       end
-      # @!endgroup
     end
+
+    register_plugin(:default, Default)
   end
 end