mobility 0.8.13 → 1.0.0

data/lib/mobility.rb

@@ -6,100 +6,94 @@ require 'mobility/version'
 =begin
 
 Mobility is a gem for storing and retrieving localized data through attributes
-on a class. The {Mobility} module includes all necessary methods and modules to
-support defining backend accessors on a class.
+on a class.
 
-To enable Mobility on a class, simply include or extend the {Mobility} module,
-and define any attribute accessors using {Translates#mobility_accessor} (aliased to the
-value of {Mobility.accessor_method}, which defaults to +translates+).
+There are two ways to translate attributes on a class, both of which are
+variations on the same basic mechanism. The first and most common way is to
+extend the `Mobility` module, which adds a class method +translates+.
+Translated attributes can then be defined like this:
 
-  class MyClass
+  class Post
     extend Mobility
     translates :title, backend: :key_value
   end
 
-When defining this module, Mobility attempts to +require+ various gems (for
-example, +active_record+ and +sequel+) to evaluate which are loaded. Loaded
-gems are tracked with dynamic subclasses of the {Loaded} module and referenced
-in backends to define gem-dependent behavior.
+Behind the scenes, +translates+ simply creates an instance of
++Mobility.translations_class+, passes it whatever arguments are passed to
++translates+, and includes the instance (which is a module) into the class.
 
-=end
-module Mobility
-  require "mobility/attributes"
-  require "mobility/backend"
-  require "mobility/backends"
-  require "mobility/backend_resetter"
-  require "mobility/configuration"
-  require "mobility/fallbacks"
-  require "mobility/loaded"
-  require "mobility/plugins"
-  require "mobility/translates"
+So the above example is equivalent to:
 
-  # General error for version compatibility conflicts
-  class VersionNotSupportedError < ArgumentError; end
-  CALL_COMPILABLE_REGEXP = /\A[a-zA-Z_]\w*[!?]?\z/
-  private_constant :CALL_COMPILABLE_REGEXP
+  class Post
+    Mobility.translations_class.new(:title, backend: :key_value)
+  end
+
+`Mobility.translations_class` is a subclass of `Mobility::Translations` created
+when `Mobility.configure` is called to configure Mobility. In fact, when you
+call `Mobility.configure`, it is the subclass of `Mobility::Translations` which
+is passed to the block as `config`. Plugins and plugin configuration is all
+applied to the same `Mobility.translations_class`.
+
+There is another way to use Mobility, which is to create your own subclass or
+subclasses of +Mobility::Translations+ and include them explicitly, without
+using +translates+.
 
-  begin
-    require "rails"
-    Loaded::Rails = true
-  rescue LoadError => e
-    raise unless e.message =~ /rails/
-    Loaded::Rails = false
+For example:
+
+  class Translations < Mobility::Translations
+    plugins do
+      backend :key_value
+      # ...
+    end
   end
 
-  begin
-    require "active_record"
-    raise VersionNotSupportedError, "Mobility is only compatible with ActiveRecord 4.2 and greater" if ::ActiveRecord::VERSION::STRING < "4.2"
-    Loaded::ActiveRecord = true
-  rescue LoadError => e
-    raise unless e.message =~ /active_record/
-    Loaded::ActiveRecord = false
+  class Post
+    include Translations.new(:title)
   end
 
-  if Loaded::ActiveRecord
-    require "mobility/active_model"
-    require "mobility/active_record"
-    if Loaded::Rails
-      require "rails/generators/mobility/generators"
+This usage might be handy if, for example, you want to have more complex
+configuration, where some models use some plugins while others do not. Since
+`Mobility::Translations` is a class like any other, you can subclass it and
+define plugins specifically on the subclass which are not present on its
+parent:
+
+  class TranslationsWithFallbacks < Translations
+    plugins do
+      fallbacks
     end
   end
 
-  begin
-    require "sequel"
-    raise VersionNotSupportedError, "Mobility is only compatible with Sequel 4.0 and greater" if ::Sequel::MAJOR < 4
-    require "sequel/plugins/mobility"
-    unless defined?(ActiveSupport::Inflector)
-      # TODO: avoid automatically including the inflector extension
-      require "sequel/extensions/inflector"
-    end
-    require "sequel/plugins/dirty"
-    require "mobility/sequel"
-    Loaded::Sequel = true
-  rescue LoadError => e
-    raise unless e.message =~ /sequel/
-    Loaded::Sequel = false
+  class Comment
+    include TranslationsWithFallbacks.new(:author)
   end
 
-  class << self
-    def extended(model_class)
-      return if model_class.respond_to? :mobility_accessor
+In this case, +Comment+ uses +TranslationsWithFallbacks+ and thus has the
+fallbacks plugin, whereas +Post+ uses +Translations+ which does not have that
+plugin enabled.
 
-      model_class.extend Translates
-      model_class.extend ClassMethods
-      #TODO: Remove in v1.0
-      model_class.include InstanceMethods
+=end
+module Mobility
+  # A generic exception used by Mobility.
+  class Error < StandardError
+  end
 
-      if translates = Mobility.config.accessor_method
-        model_class.singleton_class.send(:alias_method, translates, :mobility_accessor)
-      end
+  require "mobility/backend"
+  require "mobility/backends"
+  require "mobility/plugin"
+  require "mobility/plugins"
+  require "mobility/translations"
 
-      if Loaded::ActiveRecord && model_class < ::ActiveRecord::Base
-        model_class.include(ActiveRecord)
-      end
+  # General error for version compatibility conflicts
+  class VersionNotSupportedError < ArgumentError; end
+  CALL_COMPILABLE_REGEXP = /\A[a-zA-Z_]\w*[!?]?\z/
+  private_constant :CALL_COMPILABLE_REGEXP
 
-      if Loaded::Sequel && model_class < ::Sequel::Model
-        model_class.include(Sequel)
+  require "rails/generators/mobility/generators" if defined?(Rails)
+
+  class << self
+    def extended(model_class)
+      def model_class.translates(*args, **options)
+        include Mobility.translations_class.new(*args, **options)
       end
     end
 
@@ -110,6 +104,38 @@ module Mobility
       model_class.extend self
     end
 
+    # Alias to default backend defined on *translations_class+.
+    # @return [Symbol,Class]
+    def default_backend
+      translations_class.defaults[:backend]
+    end
+
+    # Configure Mobility
+    # @yield [Mobility::Translations]
+    def configure(&block)
+      translates_with(Class.new(Translations)) unless @translations_class
+      if block.arity == 0
+        translations_class.instance_exec(&block)
+      else
+        yield translations_class
+      end
+    end
+
+    def translates_with(pluggable)
+      raise ArgumentError, "translations class must be a subclass of Module." unless Module === pluggable
+      @translations_class = pluggable
+    end
+
+    def translations_class
+      @translations_class ||
+        raise(Error, "Mobility has not been configured. "\
+              "Configure with Mobility.configure, or assign a translations class with Mobility.translates_with(<class>)")
+    end
+
+    def reset_translations_class
+      @translations_class = nil
+    end
+
     # @!group Locale Accessors
     # @return [Symbol] Mobility locale
     def locale
@@ -144,55 +170,6 @@ module Mobility
       RequestStore.store
     end
 
-    # @!group Configuration Methods
-    # @return [Mobility::Configuration] Mobility configuration
-    def config
-      @configuration ||= Configuration.new
-    end
-
-    # (see Mobility::Configuration#accessor_method)
-    # @!method accessor_method
-    #
-    # (see Mobility::Configuration#query_method)
-    # @!method query_method
-
-    # (see Mobility::Configuration#new_fallbacks)
-    # @!method new_fallbacks
-
-    # (see Mobility::Configuration#default_backend)
-    # @!method default_backend
-
-    # (see Mobility::Configuration#default_options)
-    # @!method default_options
-    #
-    # (see Mobility::Configuration#plugins)
-    # @!method plugins
-    #
-    # (see Mobility::Configuration#default_accessor_locales)
-    # @!method default_accessor_locales
-    %w[accessor_method query_method default_backend default_options plugins default_accessor_locales].each do |method_name|
-      define_method method_name do
-        config.public_send(method_name)
-      end
-    end
-
-    # TODO: Remove in v1.0
-    def default_fallbacks(*args)
-      config.public_send(:default_fallbacks, *args)
-    end
-
-    # TODO: Make private in v1.0
-    def new_fallbacks(*args)
-      config.public_send(:new_fallbacks, *args)
-    end
-
-    # Configure Mobility
-    # @yield [Mobility::Configuration] Mobility configuration
-    def configure
-      yield config
-    end
-    # @!endgroup
-
     # Return normalized locale
     # @param [String,Symbol] locale
     # @return [String] Normalized locale
@@ -228,17 +205,7 @@ module Mobility
     # @param [String,Symbol] locale
     # @raise [InvalidLocale] if locale is present but not available
     def enforce_available_locales!(locale)
-      # TODO: Remove conditional in v1.0
-      if I18n.enforce_available_locales
-        raise Mobility::InvalidLocale.new(locale) unless (I18n.locale_available?(locale) || locale.nil?)
-      else
-        warn <<-EOL
-WARNING: You called Mobility.enforce_available_locales! in a situation where
-I18n.enforce_available_locales is false. In the past, Mobility would do nothing
-in this case, but as of the next major release Mobility will ignore the I18n
-setting and enforce available locales whenever this method is called.
-EOL
-      end
+      raise Mobility::InvalidLocale.new(locale) unless (locale.nil? || available_locales.include?(locale.to_sym))
     end
 
     # Returns available locales. Defaults to I18n.available_locales, but will
@@ -250,8 +217,8 @@ EOL
     #   simply default to +I18n.available_locales+, we may define many more
     #   methods (in LocaleAccessors) than is really necessary.
     def available_locales
-      if Loaded::Rails && Rails.application
-        Rails.application.config.i18n.available_locales || I18n.available_locales
+      if defined?(Rails) && Rails.application
+        Rails.application.config.i18n.available_locales&.map(&:to_sym) || I18n.available_locales
       else
         I18n.available_locales
       end
@@ -270,41 +237,6 @@ EOL
     end
   end
 
-  # TODO: Remove entire module in v1.0
-  module InstanceMethods
-    # Fetch backend for an attribute
-    # @deprecated Use mobility_backends[:<attribute>] instead.
-    # @param [String] attribute Attribute
-    def mobility_backend_for(attribute)
-      warn %{
-WARNING: mobility_backend_for is deprecated and will be removed in the next
-version of Mobility. Use <post>.<attribute>_backend instead.}
-      mobility_backends[attribute.to_sym]
-    end
-
-    def mobility
-      warn %{
-WARNING: <post>.mobility is deprecated and will be removed in the next
-version of Mobility. To get backends, use <post>.<attribute>_backend instead.}
-      @mobility ||= Adapter.new(self)
-    end
-
-    class Adapter < Struct.new(:model)
-      def backend_for(attribute)
-        model.mobility_backends[attribute.to_sym]
-      end
-    end
-    private_constant :Adapter
-  end
-
-  module ClassMethods
-    # Return translated attribute names on this model.
-    # @return [Array<String>] Attribute names
-    def mobility_attributes
-      []
-    end
-  end
-
   class InvalidLocale < I18n::InvalidLocale; end
   class NotImplementedError < StandardError; end
 end

data/lib/mobility/backend.rb

@@ -1,6 +1,4 @@
 # frozen-string-literal: true
-require "mobility/backend/orm_delegator"
-
 module Mobility
 =begin
 
@@ -9,10 +7,9 @@ Defines a minimum set of shared components included in any backend. These are:
 - a reader returning the +model+ on which the backend is defined ({#model})
 - a reader returning the +attribute+ for which the backend is defined
   ({#attribute})
-- a constructor setting these two elements (+model+, +attribute+), and
-  extracting fallbacks from the options hash ({#initialize})
+- a constructor setting these two elements (+model+, +attribute+)
 - a +setup+ method adding any configuration code to the model class
-  ({Setup#setup})
+  ({ClassMethods#setup})
 
 On top of this, a backend will normally:
 
@@ -50,7 +47,7 @@ On top of this, a backend will normally:
     end
   end
 
-@see Mobility::Attributes
+@see Mobility::Translations
 
 =end
 
@@ -66,9 +63,9 @@ On top of this, a backend will normally:
     # @!macro [new] backend_constructor
     #   @param model Model on which backend is defined
     #   @param [String] attribute Backend attribute
-    def initialize(model, attribute)
-      @model = model
-      @attribute = attribute
+    def initialize(*args)
+      @model = args[0]
+      @attribute = args[1]
     end
 
     # @!macro [new] backend_reader
@@ -103,7 +100,7 @@ On top of this, a backend will normally:
     # @param [Symbol] locale Locale to read
     # @return [TrueClass,FalseClass] Whether translation is present for locale
     def present?(locale, options = {})
-      Util.present?(read(locale, options))
+      Util.present?(read(locale, **options))
     end
 
     # @!method model_class
@@ -118,21 +115,18 @@ On top of this, a backend will normally:
     # Extend included class with +setup+ method and other class methods
     def self.included(base)
       base.extend ClassMethods
-      def base.options
-        @options
-      end
-      base.option_reader :model_class
-    end
-
-    # @param [String] attribute
-    # @return [String] name of backend reader method
-    def self.method_name(attribute)
-      @backend_method_names ||= {}
-      @backend_method_names[attribute] ||= "#{attribute}_backend"
+      base.singleton_class.attr_reader :options, :model_class
     end
 
     # Defines setup hooks for backend to customize model class.
     module ClassMethods
+      # Returns valid option keys for this backend. This is overriden in
+      # backends to define which keys are valid for each backend class.
+      # @return [Array]
+      def valid_keys
+        []
+      end
+
       # Assign block to be called on model class.
       # @yield [attribute_names, options]
       # @note When called multiple times, setup blocks will be appended
@@ -152,6 +146,7 @@ On top of this, a backend will normally:
       def inherited(subclass)
         subclass.instance_variable_set(:@setup_block, @setup_block)
         subclass.instance_variable_set(:@options, @options)
+        subclass.instance_variable_set(:@model_class, @model_class)
       end
 
       # Call setup block on a class with attributes and options.
@@ -166,14 +161,14 @@ On top of this, a backend will normally:
       # Build a subclass of this backend class for a given set of options
       # @note This method also freezes the options hash to prevent it from
       #   being changed.
+      # @param [Class] model_class Class
       # @param [Hash] options
       # @return [Class] backend subclass
-      def with_options(options = {}, &block)
-        configure(options) if respond_to?(:configure)
-        options.freeze
+      def build_subclass(model_class, options)
         Class.new(self) do
-          @options = options
-          class_eval(&block) if block_given?
+          @model_class = model_class
+          configure(options) if respond_to?(:configure)
+          @options = options.freeze
         end
       end
 
@@ -191,27 +186,6 @@ On top of this, a backend will normally:
         EOM
       end
 
-      # {Attributes} uses this method to get a backend class specific to the
-      # model using the backend. Backend classes can override this method to
-      # return a class specific to the model class using the backend (e.g.
-      # either an ActiveRecord or Sequel backend class depending on whether the
-      # model is an ActiveRecord model or a Sequel model.)
-      # @see OrmDelegator
-      # @see Attributes
-      # @return [self] returns itself
-      def for(_)
-        self
-      end
-
-      # Called from plugins to apply custom processing for this backend.
-      # Name is the name of the plugin.
-      # @param [Symbol] name Name of plugin
-      # @return [Boolean] Whether the plugin was applied
-      # @note This is currently only called by Plugins::Cache.
-      def apply_plugin(_)
-        false
-      end
-
       # Show useful information about this backend class, if it has no name.
       # @return [String]
       def inspect
@@ -220,10 +194,12 @@ On top of this, a backend will normally:
     end
 
     Translation = Struct.new(:backend, :locale) do
-      %w[read write].each do |accessor|
-        define_method accessor do |*args|
-          backend.send(accessor, locale, *args)
-        end
+      def read(options = {})
+        backend.read(locale, options)
+      end
+
+      def write(value, options = {})
+        backend.write(locale, value, options)
       end
     end
   end