mobility 0.1.20 → 0.2.0

data/lib/mobility/plugins/default.rb

@@ -0,0 +1,73 @@
+module Mobility
+  module Plugins
+=begin
+
+Defines value or proc to fall through to if return value from getter would
+otherwise be nil.
+
+@example With default enabled (falls through to default value)
+  class Post
+    extend Mobility
+    translates :title, default: 'foo'
+  end
+
+  Mobility.locale = :en
+  post = Post.new(title: "English title")
+
+  Mobility.locale = :de
+  post.title
+  #=> 'foo'
+
+@example Overriding default with reader option
+  class Post
+    extend Mobility
+    translates :title, default: 'foo'
+  end
+
+  Mobility.locale = :en
+  post  = Post.new(title: "English title")
+
+  Mobility.locale = :de
+  post.title
+  #=> 'foo'
+
+  post.title(default: 'bar')
+  #=> 'bar'
+
+  post.title(default: nil)
+  #=> nil
+
+@example Using Proc as default
+  class Post
+    extend Mobility
+    translates :title, default: lambda { |model:, attribute:| attribute.to_s }
+  end
+
+  post = Post.new(title: nil)
+  post.title
+  #=> "title"
+
+  post.title(default: lambda { |model:| model.class.name.to_s })
+  #=> "Post"
+=end
+    class Default < Module
+      # Applies default plugin to attributes.
+      # @param [Attributes] attributes
+      # @param [Object] option
+      def self.apply(attributes, option)
+        attributes.backend_class.include(new(option))
+      end
+
+      def initialize(default_option)
+        define_method :read do |locale, options = {}|
+          default = options.has_key?(:default) ? options.delete(:default) : default_option
+          if (value = super(locale, options)).nil?
+            default.is_a?(Proc) ? default.call(model: model, attribute: attribute) : default
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mobility/plugins/dirty.rb

@@ -0,0 +1,61 @@
+require "mobility/backend_resetter"
+require "mobility/plugins/fallthrough_accessors"
+
+module Mobility
+  module Plugins
+=begin
+
+Dirty tracking for Mobility attributes. See class-specific implementations for
+details.
+
+@see Mobility::Plugins::ActiveModel::Dirty
+@see Mobility::Plugins::Sequel::Dirty
+
+@note Dirty tracking can have unexpected results when combined with fallbacks.
+  A change in the fallback locale value will not mark an attribute falling
+  through to that locale as changed, even though it may look like it has
+  changed. However, when the value for the current locale is changed from nil
+  or blank to a new value, the change will be recorded as a change from that
+  fallback value, rather than from the nil or blank value. The specs are the
+  most reliable source of information on the interaction between dirty tracking
+  and fallbacks.
+
+=end
+    module Dirty
+      class << self
+        # Applies dirty plugin to attributes 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
+            FallthroughAccessors.apply(attributes, true)
+            include_dirty_module(attributes.backend_class, attributes.model_class, *attributes.names)
+          end
+        end
+
+        private
+
+        def include_dirty_module(backend_class, model_class, *attribute_names)
+          dirty_module =
+            if Loaded::ActiveRecord && model_class.ancestors.include?(::ActiveModel::Dirty)
+              if (model_class < ::ActiveRecord::Base)
+                require "mobility/plugins/active_record/dirty"
+                Plugins::ActiveRecord::Dirty
+              else
+                require "mobility/plugins/active_model/dirty"
+                Plugins::ActiveModel::Dirty
+              end
+            elsif Loaded::Sequel && model_class < ::Sequel::Model
+              require "mobility/plugins/sequel/dirty"
+              Plugins::Sequel::Dirty
+            else
+              raise ArgumentError, "#{model_class} does not support Dirty module."
+            end
+          backend_class.include dirty_module
+          model_class.include dirty_module.const_get(:MethodsBuilder).new(*attribute_names)
+        end
+      end
+    end
+  end
+end

data/lib/mobility/{backend → plugins}/fallbacks.rb

@@ -1,5 +1,7 @@
+require "mobility/util"
+
 module Mobility
-  module Backend
+  module Plugins
 =begin
 
 Falls back to one or more alternative locales in case no value is defined for a
@@ -75,41 +77,44 @@ locale was +nil+.
   post.title(fallback: :fr)
   #=> "Mobilité"
 =end
-    module Fallbacks
-      # @!macro [new] backend_constructor
-      #   @param model Model on which backend is defined
-      #   @param [String] attribute Backend attribute
-      #   @option backend_options [Hash] fallbacks Fallbacks hash
-      def initialize(model, attributes, **backend_options)
-        super
-        @fallbacks =
-          if (fallbacks = backend_options[:fallbacks]).is_a?(Hash)
-            Mobility.default_fallbacks(fallbacks)
-          elsif fallbacks == true
-            Mobility.default_fallbacks
-          end
+    class Fallbacks < Module
+      # Applies fallbacks plugin to attributes.
+      # @param [Attributes] attributes
+      # @param [Boolean] option
+      def self.apply(attributes, option)
+        attributes.backend_class.include(new(option)) unless option == false
       end
 
-      # @!group Backend Accessors
-      # @!macro backend_reader
-      # @param [Boolean,Symbol,Array] fallback
-      #   +false+ to disable fallbacks on lookup, or a locale or array of
-      #   locales to set fallback(s) for this lookup.
-      def read(locale, **options)
-        if !options[:fallbacks].nil?
-          warn "You passed an option with key 'fallbacks', which will be
-            ignored. Did you mean 'fallback'?"
-        end
-        fallback = options.delete(:fallback)
-        return super if fallback == false || (fallback.nil? && fallbacks.nil?)
-        (fallback ? [locale, *fallback] : fallbacks[locale]).detect do |fallback_locale|
-          value = super(fallback_locale, **options)
-          break value if value.present?
-        end
+      def initialize(fallbacks_option)
+        define_read(convert_option_to_fallbacks(fallbacks_option))
       end
 
       private
-      attr_reader :fallbacks
+
+      def define_read(fallbacks)
+        define_method :read do |locale, **options|
+          fallback = options.delete(:fallback)
+
+          if fallback == false || (fallback.nil? && fallbacks.nil?)
+            super(locale, options)
+          else
+            (fallback ? [locale, *fallback] : fallbacks[locale]).detect do |fallback_locale|
+              value = super(fallback_locale, options)
+              break value if Util.present?(value)
+            end
+          end
+        end
+      end
+
+      def convert_option_to_fallbacks(option)
+        if option.is_a?(Hash)
+          Mobility.default_fallbacks(option)
+        elsif option == true
+          Mobility.default_fallbacks
+        else
+          option
+        end
+      end
     end
   end
 end

data/lib/mobility/plugins/fallthrough_accessors.rb

@@ -0,0 +1,66 @@
+# frozen-string-literal: true
+
+module Mobility
+  module Plugins
+=begin
+
+Defines +method_missing+ and +respond_to_missing?+ methods for a set of
+attributes such that a method call using a locale accessor, like:
+
+  article.title_pt_br
+
+will return the value of +article.title+ with the locale set to +pt-BR+ around
+the method call. The class is called "FallthroughAccessors" because when
+included in a model class, locale-specific methods will be available even if
+not explicitly defined with the +locale_accessors+ option.
+
+This is a less efficient (but more open-ended) implementation of locale
+accessors, for use in cases where the locales to be used are not known when the
+model class is generated.
+
+@example Using fallthrough locales on a plain old ruby class
+  class Post
+    def title
+      "title in #{Mobility.locale}"
+    end
+    include Mobility::FallthroughAccessors.new("title")
+  end
+
+  Mobility.locale = :en
+  post = Post.new
+  post.title
+  #=> "title in en"
+  post.title_fr
+  #=> "title in fr"
+
+=end
+    class FallthroughAccessors < Module
+      # Apply fallthrough accessors plugin to attributes.
+      # @param [Attributes] attributes
+      # @param [Boolean] option
+      def self.apply(attributes, option)
+        attributes.model_class.include new(*attributes.names) if option
+      end
+
+      # @param [String] One or more attributes
+      def initialize(*attributes)
+        method_name_regex = /\A(#{attributes.join('|'.freeze)})_([a-z]{2}(_[a-z]{2})?)(=?|\??)\z/.freeze
+
+        define_method :method_missing do |method_name, *arguments, &block|
+          if method_name =~ method_name_regex
+            attribute = $1.to_sym
+            locale, suffix = $2.split('_'.freeze)
+            locale = "#{locale}-#{suffix.upcase}".freeze if suffix
+            Mobility.with_locale(locale) { public_send("#{attribute}#{$4}".freeze, *arguments) }
+          else
+            super(method_name, *arguments, &block)
+          end
+        end
+
+        define_method :respond_to_missing? do |method_name, include_private = false|
+          (method_name =~ method_name_regex) || super(method_name, include_private)
+        end
+      end
+    end
+  end
+end

data/lib/mobility/plugins/locale_accessors.rb

@@ -0,0 +1,84 @@
+# frozen-string-literal: true
+
+module Mobility
+  module Plugins
+=begin
+
+Defines methods for a set of locales to access translated attributes in those
+locales directly with a method call, using a suffix including the locale:
+
+  article.title_pt_br
+
+If no locales are passed as an option to the initializer,
++I18n.available_locales+ will be used by default.
+
+@example
+  class Post
+    def title
+      "title in #{Mobility.locale}"
+    end
+    include Mobility::Plugins::LocaleAccessors.new("title", locales: [:en, :fr])
+  end
+
+  Mobility.locale = :en
+  post = Post.new
+  post.title
+  #=> "title in en"
+  post.title_fr
+  #=> "title in fr"
+
+=end
+    class LocaleAccessors < Module
+      # Apply locale accessors plugin to attributes.
+      # @param [Attributes] attributes
+      # @param [Boolean] option
+      def self.apply(attributes, option)
+        if accessor_locales = option
+          accessor_locales = Mobility.config.default_accessor_locales if accessor_locales == true
+          attributes.model_class.include new(*attributes.names, locales: accessor_locales)
+        end
+      end
+
+      # @param [String] One or more attribute names
+      # @param [Array<Symbol>] Locales
+      def initialize(*attribute_names, locales: I18n.available_locales)
+        attribute_names.each do |name|
+          locales.each do |locale|
+            define_reader(name, locale)
+            define_writer(name, locale)
+          end
+        end
+      end
+
+      private
+
+      def define_reader(name, locale)
+        warning_message = "locale passed as option to locale accessor will be ignored".freeze
+        normalized_locale = Mobility.normalize_locale(locale)
+
+        define_method "#{name}_#{normalized_locale}" do |**options|
+          return super() if options.delete(:super)
+          warn warning_message if options.delete(:locale)
+          Mobility.with_locale(locale) { send(name, options) }
+        end
+
+        define_method "#{name}_#{normalized_locale}?" do |**options|
+          return super() if options.delete(:super)
+          warn warning_message if options.delete(:locale)
+          Mobility.with_locale(locale) { send("#{name}?", options) }
+        end
+      end
+
+      def define_writer(name, locale)
+        warning_message = "locale passed as option to locale accessor will be ignored".freeze
+        normalized_locale = Mobility.normalize_locale(locale)
+
+        define_method "#{name}_#{normalized_locale}=" do |value, **options|
+          return super(value) if options.delete(:super)
+          warn warning_message if options.delete(:locale)
+          Mobility.with_locale(locale) { send("#{name}=", value, options) }
+        end
+      end
+    end
+  end
+end

data/lib/mobility/{backend → plugins}/presence.rb

@@ -1,29 +1,38 @@
+require "mobility/util"
+
 module Mobility
-  module Backend
+  module Plugins
 =begin
 
 Applies presence filter to values fetched from backend and to values set on
-backend. Included by default, but can be disabled with presence: false option.
+backend. Included by default, but can be disabled with +presence: false+ option.
 
 =end
     module Presence
+      # Applies presence plugin to attributes.
+      # @param [Attributes] attributes
+      # @param [Boolean] option
+      def self.apply(attributes, option)
+        attributes.backend_class.include(self) if option
+      end
+
       # @group Backend Accessors
       # @!macro backend_reader
-      # @param [Boolean] presence
+      # @option options [Boolean] presence
       #   *false* to disable presence filter.
       def read(locale, **options)
         return super if options.delete(:presence) == false
         value = super
-        value == false ? value : value.presence
+        value == false ? value : Util.presence(value)
       end
 
       # @group Backend Accessors
       # @!macro backend_writer
-      # @param [Boolean] presence
+      # @option options [Boolean] presence
       #   *false* to disable presence filter.
       def write(locale, value, **options)
         return super if options.delete(:presence) == false
-        super(locale, value == false ? value : value.presence, **options)
+        super(locale, value == false ? value : Util.presence(value), options)
       end
     end
   end

data/lib/mobility/plugins/sequel.rb

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

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

@@ -0,0 +1,59 @@
+# frozen-string-literal: true
+require "sequel/plugins/dirty"
+
+module Mobility
+  module Plugins
+=begin
+
+Dirty tracking for Sequel models which use the +Sequel::Plugins::Dirty+ plugin.
+Automatically includes dirty plugin in model class when enabled.
+
+@see http://sequel.jeremyevans.net/rdoc-plugins/index.html Sequel dirty plugin
+
+=end
+    module Sequel
+      module Dirty
+        # @!group Backend Accessors
+        # @!macro backend_writer
+        # @param [Hash] options
+        def write(locale, value, options = {})
+          locale_accessor = Mobility.normalize_locale_accessor(attribute, locale).to_sym
+          if model.column_changes.has_key?(locale_accessor) && model.initial_values[locale_accessor] == value
+            super
+            [model.changed_columns, model.initial_values].each { |h| h.delete(locale_accessor) }
+          elsif read(locale, options.merge(fallback: false)) != value
+            model.will_change_column(locale_accessor)
+            super
+          end
+        end
+        # @!endgroup
+
+        # Builds module which overrides dirty methods to handle translated as
+        # well as normal (untranslated) attributes.
+        class MethodsBuilder < Module
+          def initialize(*attribute_names)
+            # Although we load the plugin in the included callback method, we
+            # need to include this module here in advance to ensure that its
+            # instance methods are included *before* the ones defined here.
+            include ::Sequel::Plugins::Dirty::InstanceMethods
+
+            %w[initial_value column_change column_changed? reset_column].each do |method_name|
+              define_method method_name do |column|
+                if attribute_names.map(&:to_sym).include?(column)
+                  super(Mobility.normalize_locale_accessor(column).to_sym)
+                else
+                  super(column)
+                end
+              end
+            end
+          end
+
+          def included(model_class)
+            # this just adds Sequel::Plugins::Dirty to @plugins
+            model_class.plugin :dirty
+          end
+        end
+      end
+    end
+  end
+end