mobility 0.1.20 → 0.2.0

data/lib/mobility/{backend → backends}/table.rb

@@ -1,5 +1,7 @@
+require "mobility/plugins/cache"
+
 module Mobility
-  module Backend
+  module Backends
 =begin
 
 Stores attribute translation as rows on a model-specific translation table
@@ -30,14 +32,14 @@ another, and Mobility will handle mapping reads/writes to each. The subclass
 used in this case will be generated from the +association_name+ by
 singularizing it and converting it to camelcase.
 
-For more details, see examples in {Mobility::Backend::ActiveRecord::Table}.
+For more details, see examples in {Mobility::Backends::ActiveRecord::Table}.
 
 ==Backend Options
 
 ===+association_name+
 
-Name of association on model. Defaults to +:mobility_model_translations+. If
-specified, ensure name does not overlap with other methods on model or with the
+Name of association on model. Defaults to +:translations+. If specified,
+ensure name does not overlap with other methods on model or with the
 association name used by other backends on model (otherwise one will overwrite
 the other).
 
@@ -58,39 +60,77 @@ Subclass to use when dynamically generating translation class for model, by
 default +:Translation+. Should be a symbol. Generally this does not need to be
 set.
 
-@see Mobility::Backend::ActiveRecord::Table
-@see Mobility::Backend::Sequel::Table
+@see Mobility::Backends::ActiveRecord::Table
+@see Mobility::Backends::Sequel::Table
 =end
     module Table
-      include OrmDelegator
+      extend Backend::OrmDelegator
+
+      # @!macro backend_constructor
+      # @option options [Symbol] association_name Name of association
+      def initialize(model, attribute, options = {})
+        super
+        @association_name = options[:association_name]
+      end
+
+      # @!group Backend Accessors
+      # @!macro backend_reader
+      def read(locale, options = {})
+        translation_for(locale, options).send(attribute)
+      end
+
+      # @!macro backend_writer
+      def write(locale, value, options = {})
+        translation_for(locale, options).tap { |t| t.send("#{attribute}=", value) }.send(attribute)
+      end
+      # @!endgroup
+
+      # @!macro backend_iterator
+      def each_locale
+        translations.each { |t| yield t.locale.to_sym }
+      end
+
+      private
+
+      def translations
+        model.send(association_name)
+      end
+
+      def self.included(backend)
+        backend.extend ClassMethods
+      end
+
+      module ClassMethods
+        # Apply custom processing for plugin
+        # @param (see Backend::Setup#apply_plugin)
+        # @return (see Backend::Setup#apply_plugin)
+        def apply_plugin(name)
+          if name == :cache
+            include self::Cache
+            true
+          else
+            super
+          end
+        end
+      end
 
       # Simple hash cache to memoize translations as a hash so they can be
       # fetched quickly.
-      class TranslationsCache < Hash
-
-        # @yield [locale] Yields locale to block in case attribute is not yet
-        #   cached, expects a new translation for that locale.
-        # @raise [ArgumentError] if block is not given
-        def initialize
-          raise ArgumentError, "missing block" unless block_given?
-          super() { |hash, locale| hash[locale] = yield(locale) }
-        end
+      module Cache
+        include Plugins::Cache::TranslationCacher.new(:translation_for)
 
-        # Return wrapper class which reads and writes to only one attribute of this cache.
-        # @param [String] attribute
-        # @return [Class] Hash-like wrapper object to be used as attribute cache
-        def for(attribute)
-          cache = self
+        private
 
-          Class.new do
-            define_singleton_method :[] do |locale|
-              cache[locale].send(attribute)
-            end
+        def cache
+          model_cache || model.instance_variable_set(:"@__mobility_#{association_name}_cache", {})
+        end
 
-            define_singleton_method :[]= do |locale, value|
-              cache[locale].send("#{attribute}=", value)
-            end
-          end
+        def model_cache
+          model.instance_variable_get(:"@__mobility_#{association_name}_cache")
+        end
+
+        def clear_cache
+          model_cache && model_cache.clear
         end
       end
     end

data/lib/mobility/configuration.rb

@@ -5,6 +5,8 @@ Stores shared Mobility configuration referenced by all backends.
 
 =end
   class Configuration
+    RESERVED_OPTION_KEYS = %i[backend model_class].freeze
+
     # Alias for mobility_accessor (defaults to +translates+)
     # @return [Symbol]
     attr_accessor :accessor_method
@@ -13,6 +15,26 @@ Stores shared Mobility configuration referenced by all backends.
     # @return [Symbol]
     attr_accessor :query_method
 
+    # Default set of options. These will be merged with any backend options
+    # when defining translated attributes (with +translates+). Default options
+    # may not include the keys 'backend' or 'model_class'.
+    # @return [Hash]
+    attr_reader :default_options
+    def default_options=(options)
+      if (keys = options.keys & RESERVED_OPTION_KEYS).present?
+        raise ReservedOptionKey,
+          "Default options may not contain the following reserved keys: #{keys.join(', ')}"
+      else
+        @default_options = options
+      end
+    end
+
+    # Plugins to apply. Order of plugins is important, as this becomes the
+    # order in which plugins modules are included into the backend class or
+    # attributes instance.
+    # @return [Array<Symbol>]
+    attr_accessor :plugins
+
     # Default fallbacks instance
     # @return [I18n::Locale::Fallbacks]
     def default_fallbacks(fallbacks = {})
@@ -41,6 +63,24 @@ Stores shared Mobility configuration referenced by all backends.
       @query_method = :i18n
       @default_fallbacks = lambda { |fallbacks| I18n::Locale::Fallbacks.new(fallbacks) }
       @default_accessor_locales = lambda { I18n.available_locales }
+      @default_options = {
+        cache: true,
+        dirty: false,
+        fallbacks: nil,
+        presence: true,
+        default: nil
+      }
+      @plugins = %i[
+        cache
+        dirty
+        fallbacks
+        presence
+        default
+        fallthrough_accessors
+        locale_accessors
+      ]
     end
+
+    class ReservedOptionKey < Exception; end
   end
 end

data/lib/mobility/plugins.rb

@@ -0,0 +1,35 @@
+module Mobility
+=begin
+
+Plugins allow modular customization of backends independent of the backend
+itself. They are enabled through the {Configuration.plugins} configuration
+setting, which takes an array of symbols corresponding to plugin names. The
+order of these names is important since it determines the order in which
+plugins will be applied.
+
+So if our {Configuration.plugins} is an array +[:foo]+, and we call
+`translates` on our model, +Post+, like this:
+
+  class Post
+    translates :title, foo: true
+  end
+
+Then the +Foo+ plugin will be applied with the option value +true+. Applying a
+module calls a class method, +apply+ (in this case +Foo.apply+), which takes
+two arguments:
+
+- an instance of the {Attributes} class, +attributes+, from which the backend
+  can configure the backend class (+attributes.backend_class+) and the model
+  (+attributes.model_class+), and the +attributes+ module itself (which
+  will be included into the backend).
+- the value of the +option+ passed into the model with +translates+ (in this
+  case, +true+).
+
+Typically, the plugin will include a module into either
++attributes.backend_class+ or +attributes+ itself, configured according to the
+option value. For examples, see classes under the {Mobility::Plugins} namespace.
+
+=end
+  module Plugins
+  end
+end

data/lib/mobility/plugins/active_model.rb

@@ -0,0 +1,6 @@
+module Mobility
+  module Plugins
+    module ActiveModel
+    end
+  end
+end

data/lib/mobility/plugins/active_model/dirty.rb

@@ -0,0 +1,81 @@
+# frozen-string-literal: true
+
+module Mobility
+  module Plugins
+=begin
+
+Dirty tracking for models which include the +ActiveModel::Dirty+ module.
+
+Assuming we have an attribute +title+, this module will add support for the
+following methods:
+- +title_changed?+
+- +title_change+
+- +title_was+
+- +title_will_change!+
+- +title_previously_changed?+
+- +title_previous_change+
+- +restore_title!+
+
+In addition, the private method +restore_attribute!+ will also restore the
+value of the translated attribute if passed to it.
+
+@see http://api.rubyonrails.org/classes/ActiveModel/Dirty.html Rails documentation for Active Model Dirty module
+
+=end
+    module ActiveModel
+      module Dirty
+        # @!group Backend Accessors
+        # @!macro backend_writer
+        # @param [Hash] options
+        def write(locale, value, options = {})
+          locale_accessor = Mobility.normalize_locale_accessor(attribute, locale)
+          if model.changed_attributes.has_key?(locale_accessor) && model.changed_attributes[locale_accessor] == value
+            model.attributes_changed_by_setter.except!(locale_accessor)
+          elsif read(locale, options.merge(fallback: false)) != value
+            model.send(:attribute_will_change!, locale_accessor)
+          end
+          super
+        end
+        # @!endgroup
+
+        # Builds module which adds suffix/prefix methods for translated
+        # attributes so they act like normal dirty-tracked attributes.
+        class MethodsBuilder < Module
+          def initialize(*attribute_names)
+            attribute_names.each do |name|
+              method_suffixes.each do |suffix|
+                define_method "#{name}#{suffix}".freeze do
+                  __send__("attribute#{suffix}".freeze, Mobility.normalize_locale_accessor(name))
+                end
+              end
+
+              define_method "restore_#{name}!".freeze do
+                locale_accessor = Mobility.normalize_locale_accessor(name)
+                if attribute_changed?(locale_accessor)
+                  __send__("#{name}=".freeze, changed_attributes[locale_accessor])
+                end
+              end
+            end
+
+            define_method :restore_attribute! do |attr|
+              attribute_names.include?(attr.to_s) ? send("restore_#{attr}!".freeze) : super(attr)
+            end
+            private :restore_attribute!
+          end
+
+          private
+
+          # Get method suffixes. Creating an object just to get the list of
+          # suffixes is not very efficient, but the most reliable way given that
+          # they change from Rails version to version.
+          def method_suffixes
+            @method_suffixes ||=
+              Class.new do
+                include ::ActiveModel::Dirty
+              end.attribute_method_matchers.map(&:suffix).select { |m| m =~ /\A_/ }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mobility/plugins/active_record.rb

@@ -0,0 +1,6 @@
+module Mobility
+  module Plugins
+    module ActiveRecord
+    end
+  end
+end

data/lib/mobility/plugins/active_record/dirty.rb

@@ -0,0 +1,59 @@
+# frozen-string-literal: true
+require "mobility/plugins/active_model/dirty"
+
+module Mobility
+  module Plugins
+=begin
+
+Dirty tracking for AR models. See {Mobility::Plugins::ActiveModel::Dirty} for
+details on usage.
+
+=end
+    module ActiveRecord
+      module Dirty
+        include ActiveModel::Dirty
+
+        # Builds module which patches a few AR methods to handle changes to
+        # translated attributes just like normal attributes.
+        class MethodsBuilder < ActiveModel::Dirty::MethodsBuilder
+          def initialize(*attribute_names)
+            super
+            @attribute_names = attribute_names
+
+            changes_applied_method = ::ActiveRecord::VERSION::STRING < '5.1' ? :changes_applied : :changes_internally_applied
+            define_method changes_applied_method do
+              @previously_changed = changes
+              super()
+            end
+
+            define_method :clear_changes_information do
+              @previously_changed = ActiveSupport::HashWithIndifferentAccess.new
+              super()
+            end
+
+            define_method :previous_changes do
+              (@previously_changed ||= ActiveSupport::HashWithIndifferentAccess.new).merge(super())
+            end
+          end
+
+          # Overrides +ActiveRecord::AttributeMethods::ClassMethods#has_attribute+ to treat fallthrough attribute methods
+          # just like "real" attribute methods.
+          #
+          # @note Patching +has_attribute?+ is necessary as of AR 5.1 due to this commit[https://github.com/rails/rails/commit/4fed08fa787a316fa51f14baca9eae11913f5050].
+          #   (I have voiced my opposition to this change here[https://github.com/rails/rails/pull/27963#issuecomment-310092787]).
+          # @param [Attributes] attributes
+          def included(model_class)
+            names = @attribute_names
+            method_name_regex = /\A(#{names.join('|'.freeze)})_([a-z]{2}(_[a-z]{2})?)(=?|\??)\z/.freeze
+            has_attribute = Module.new do
+              define_method :has_attribute? do |attr_name|
+                super(attr_name) || !!method_name_regex.match(attr_name)
+              end
+            end
+            model_class.extend has_attribute
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mobility/plugins/cache.rb

@@ -0,0 +1,54 @@
+require "mobility/plugins/cache/translation_cacher"
+
+module Mobility
+  module Plugins
+=begin
+
+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.
+
+The cache is reset when one of a set of events happens (saving, reloading,
+etc.). See {BackendResetter} for details.
+
+Values are added to the cache in two ways:
+
+1. first read from backend
+2. any write to backend
+
+=end
+    module Cache
+      # 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 }
+        end
+      end
+
+      # @group Backend Accessors
+      #
+      # @!macro backend_reader
+      # @option options [Boolean] cache
+      #   *false* to disable cache.
+      # @!method read(locale, value, options = {})
+      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
+      end
+      # @!endgroup
+    end
+  end
+end

data/lib/mobility/plugins/cache/translation_cacher.rb

@@ -0,0 +1,40 @@
+module Mobility
+  module Plugins
+    module Cache
+=begin
+
+Creates a module to cache a given translation fetch method. The cacher defines
+private methods +cache+ and +clear_cache+ to access and clear, respectively, a
+translations hash.
+
+This cacher is used to cache translation values in {Mobility::Plugins::Cache},
+and also to cache translation *records* in {Mobility::Backends::Table} and
+{Mobility::Backends::KeyValue}.
+
+=end
+      class TranslationCacher < Module
+        # @param [Symbol] fetch_method Name of translation fetch method to cache
+        def initialize(fetch_method)
+          define_method fetch_method do |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
+
+          define_method :cache do
+            @cache ||= {}
+          end
+
+          define_method :clear_cache do
+            @cache = {}
+          end
+
+          private :cache, :clear_cache
+        end
+      end
+    end
+  end
+end