mobility 0.8.13 → 1.0.0.alpha

data/lib/mobility/attributes.rb

@@ -1,324 +0,0 @@
-# frozen_string_literal: true
-require "mobility/util"
-
-module Mobility
-=begin
-
-Defines accessor methods to include on model class. Inspired by Traco's
-+Traco::Attributes+ class.
-
-Normally this class will be created through class methods defined using
-{Mobility::Translates} accessor methods, and need not be created directly.
-However, the class is central to how Mobility hooks into models to add
-accessors and other methods, and should be useful as a reference when
-understanding and designing backends.
-
-==Including Attributes in a Class
-
-Since {Attributes} is a subclass of +Module+, including an instance of it is
-like including a module. Creating an instance like this:
-
-  Attributes.new("title", backend: :my_backend, locale_accessors: [:en, :ja], cache: true, fallbacks: true)
-
-will generate an anonymous module that behaves approximately like this:
-
-  Module.new do
-    def mobility_backends
-      # Returns a memoized hash with attribute name keys and backend instance
-      # values.  When a key is fetched from the hash, the hash calls
-      # +self.class.mobility_backend_class(name)+ (where +name+ is the
-      # attribute name) to get the backend class, then instantiate it (passing
-      # the model instance and attribute name to its initializer) and return it.
-      #
-      # The backend class returned from the class method
-      # +mobility_backend_class+ returns a subclass of
-      # +Mobility::Backends::MyBackend+ and includes into it:
-      #
-      # - Mobility::Plugins::Cache (from the +cache: true+ option)
-      # - instance of Mobility::Plugins::Fallbacks (from the +fallbacks: true+ option)
-      # - Mobility::Plugins::Presence (by default, disabled by +presence: false+)
-    end
-
-    def title(locale: Mobility.locale)
-      mobility_backends[:title].read(locale)
-    end
-
-    def title?(locale: Mobility.locale)
-      mobility_backends[:title].read(locale).present?
-    end
-
-    def title=(value, locale: Mobility.locale)
-      mobility_backends[:title].write(locale, value)
-    end
-
-    # Start Locale Accessors
-    #
-    def title_en
-      title(locale: :en)
-    end
-
-    def title_en?
-      title?(locale: :en)
-    end
-
-    def title_en=(value)
-      public_send(:title=, value, locale: :en)
-    end
-
-    def title_ja
-      title(locale: :ja)
-    end
-
-    def title_ja?
-      title?(locale: :ja)
-    end
-
-    def title_ja=(value)
-      public_send(:title=, value, locale: :ja)
-    end
-    # End Locale Accessors
-  end
-
-Including this module into a model class will thus add the backend method, the
-reader, writer and presence methods, and the locale accessor so the model
-class. (These methods are in fact added to the model in an +included+ hook.)
-
-Note that some simplifications have been made above for readability. (In
-reality, all getters and setters accept an options hash which is passed along
-to the backend instance.)
-
-==Setting up the Model Class
-
-Accessor methods alone are of limited use without a hook to actually modify the
-model class. This hook is provided by the {Backend::Setup#setup_model} method,
-which is added to every backend class when it includes the {Backend} module.
-
-Assuming the backend has defined a setup block by calling +setup+, this block
-will be called when {Attributes} is {#included} in the model class, passed
-attributes and options defined when the backend was defined on the model class.
-This allows a backend to do things like (for example) define associations on a
-model class required by the backend, as happens in the {Backends::KeyValue} and
-{Backends::Table} backends.
-
-Since setup blocks are evaluated on the model class, it is possible that
-backends can conflict (for example, overwriting previously defined methods).
-Care should be taken to avoid defining methods on the model class, or where
-necessary, ensure that names are defined in such a way as to avoid conflicts
-with other backends.
-
-=end
-  class Attributes < Module
-
-    # Method (accessor, reader or writer)
-    # @return [Symbol] method
-    attr_reader :method
-
-    # Attribute names for which accessors will be defined
-    # @return [Array<String>] Array of names
-    attr_reader :names
-
-    # Backend options
-    # @return [Hash] Backend options
-    attr_reader :options
-
-    # Backend class
-    # @return [Class] Backend class
-    attr_reader :backend_class
-
-    # Name of backend
-    # @return [Symbol,Class] Name of backend, or backend class
-    attr_reader :backend_name
-
-    # Model class
-    # @return [Class] Class of model
-    attr_reader :model_class
-
-    # @param [Symbol] method One of: [reader, writer, accessor]
-    # @param [Array<String>] attribute_names Names of attributes to define backend for
-    # @param [Hash] backend_options Backend options hash
-    # @option backend_options [Class] model_class Class of model
-    # @raise [ArgumentError] if method is not reader, writer or accessor
-    def initialize(*attribute_names, method: :accessor, backend: Mobility.default_backend, **backend_options)
-      raise ArgumentError, "method must be one of: reader, writer, accessor" unless %i[reader writer accessor].include?(method)
-      @method = method
-      @options = Mobility.default_options.to_h.merge(backend_options)
-      @names = attribute_names.map(&:to_s).freeze
-      raise BackendRequired, "Backend option required if Mobility.config.default_backend is not set." if backend.nil?
-      @backend_name = backend
-    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}).
-    # @param klass [Class] Class of model
-    def included(klass)
-      @model_class = @options[:model_class] = klass
-      @backend_class = get_backend_class(backend_name).for(model_class).with_options(options)
-
-      Mobility.plugins.each do |name|
-        plugin = get_plugin_class(name)
-        plugin.apply(self, options[name])
-      end
-
-      each do |name|
-        define_backend(name)
-        define_reader(name) if %i[accessor reader].include?(method)
-        define_writer(name) if %i[accessor writer].include?(method)
-      end
-
-      klass.include InstanceMethods
-      klass.extend ClassMethods
-
-      backend_class.setup_model(model_class, names)
-    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
-      "#<Attributes (#{backend_name}) @names=#{names.join(", ")}>"
-    end
-
-    private
-
-    def define_backend(attribute)
-      module_eval <<-EOM, __FILE__, __LINE__ + 1
-      def #{Backend.method_name(attribute)}
-        mobility_backends[:#{attribute}]
-      end
-      EOM
-    end
-
-    def define_reader(attribute)
-      class_eval <<-EOM, __FILE__, __LINE__ + 1
-        def #{attribute}(**options)
-          return super() if options.delete(:super)
-          #{set_locale_from_options_inline}
-          mobility_backends[:#{attribute}].read(locale, options)
-        end
-
-        def #{attribute}?(**options)
-          return super() if options.delete(:super)
-          #{set_locale_from_options_inline}
-          mobility_backends[:#{attribute}].present?(locale, options)
-        end
-      EOM
-    end
-
-    def define_writer(attribute)
-      class_eval <<-EOM, __FILE__, __LINE__ + 1
-        def #{attribute}=(value, **options)
-          return super(value) if options.delete(:super)
-          #{set_locale_from_options_inline}
-          mobility_backends[:#{attribute}].write(locale, value, options)
-        end
-      EOM
-    end
-
-    # This string is evaluated inline in order to optimize performance of
-    # getters and setters, avoiding extra steps where they are unneeded.
-    def set_locale_from_options_inline
-      <<-EOL
-if options[:locale]
-  #{"Mobility.enforce_available_locales!(options[:locale])" if I18n.enforce_available_locales}
-  locale = options[:locale].to_sym
-  options[:locale] &&= !!locale
-else
-  locale = Mobility.locale
-end
-EOL
-    end
-
-    def get_backend_class(backend)
-      return backend if Module === backend
-      require "mobility/backends/#{backend}"
-      get_class_from_key(Mobility::Backends, backend)
-    end
-
-    def get_plugin_class(plugin)
-      require "mobility/plugins/#{plugin}"
-      get_class_from_key(Mobility::Plugins, plugin)
-    end
-
-    def get_class_from_key(parent_class, key)
-      klass_name = key.to_s.gsub(/(^|_)(.)/){|x| x[-1..-1].upcase}
-      parent_class.const_get(klass_name)
-    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 all {Mobility::Attribute} module instances from among ancestors
-      # of this model.
-      # @return [Array<Mobility::Attributes>] Attribute modules
-      def mobility_modules
-        ancestors.grep(Attributes)
-      end
-
-      # Return translated attribute names on this model.
-      # @return [Array<String>] Attribute names
-      def mobility_attributes
-        mobility_modules.map(&:names).flatten.uniq
-      end
-
-      # 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
-
-      # @!method translated_attribute_names
-      # @return (see #mobility_attributes)
-      alias translated_attribute_names mobility_attributes
-
-      # Return backend class for a given attribute name.
-      # @param [Symbol,String] Name of attribute
-      # @return [Class] Backend class
-      def mobility_backend_class(name)
-        @backends ||= BackendsCache.new(self)
-        @backends[name.to_sym]
-      end
-
-      class BackendsCache < Hash
-        def initialize(klass)
-          # Preload backend mapping
-          klass.mobility_modules.each do |mod|
-            mod.names.each { |name| self[name.to_sym] = mod.backend_class }
-          end
-
-          super() do |hash, name|
-            if mod = klass.mobility_modules.find { |m| m.names.include? name.to_s }
-              hash[name] = mod.backend_class
-            else
-              raise KeyError, "No backend for: #{name}."
-            end
-          end
-        end
-      end
-      private_constant :BackendsCache
-    end
-  end
-
-  class BackendRequired < ArgumentError; end
-end

data/lib/mobility/backend/orm_delegator.rb

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-module Mobility
-  module Backend
-=begin
-
-Adds {#for} method to backend to return ORM-specific backend.
-
-@example KeyValue backend for AR model
-  class Post < ActiveRecord::Base
-    # ...
-  end
-  Mobility::Backends::KeyValue.for(Post)
-  #=> Mobility::Backends::ActiveRecord::KeyValue
-
-=end
-    module OrmDelegator
-      # @param [Class] model_class Class of model
-      # @return [Class] Class of backend to use for model
-      def for(model_class)
-        namespace = name.split('::')
-        if Loaded::ActiveRecord && model_class < ::ActiveRecord::Base
-          require_backend("active_record", namespace.last.underscore)
-          const_get(namespace.insert(-2, "ActiveRecord").join("::"))
-        elsif Loaded::Sequel && model_class < ::Sequel::Model
-          require_backend("sequel", namespace.last.underscore)
-          const_get(namespace.insert(-2, "Sequel").join("::"))
-        else
-          raise ArgumentError, "#{namespace.last} backend can only be used by ActiveRecord or Sequel models"
-        end
-      end
-
-      private
-
-      def require_backend(orm, backend)
-        begin
-          orm_backend = "mobility/backends/#{orm}/#{backend}"
-          require orm_backend
-        rescue LoadError => e
-          raise unless e.message =~ /#{orm_backend}/
-        end
-      end
-    end
-  end
-end

data/lib/mobility/backend_resetter.rb

@@ -1,50 +0,0 @@
-# frozen_string_literal: true
-
-module Mobility
-=begin
-
-Resets backend cache when reset events occur.
-
-@example Add trigger to call a method +my_backend_reset_method+ on backend instance when reset event(s) occurs on model
-  resetter = Mobility::BackendResetter.for(MyModel).new(attributes) { my_backend_reset_method }
-  MyModel.include(resetter)
-
-@see Mobility::ActiveRecord::BackendResetter
-@see Mobility::ActiveModel::BackendResetter
-@see Mobility::Sequel::BackendResetter
-
-=end
-  class BackendResetter < Module
-    # @param [Array<String>] attribute_names Names of attributes whose backends should be reset
-    # @yield Backend to reset as context for block
-    # @raise [ArgumentError] if no block is provided.
-    def initialize(attribute_names, &block)
-      raise ArgumentError, "block required" unless block_given?
-      names = attribute_names.map(&:to_sym)
-      @model_reset_method = Proc.new do
-        names.each do |name|
-          if @mobility_backends && @mobility_backends[name]
-            @mobility_backends[name].instance_eval(&block)
-          end
-        end
-      end
-    end
-
-    # Returns backend resetter class for model class
-    # @param [Class] model_class Class of model to which backend resetter will be applied
-    def self.for(model_class)
-      if Loaded::ActiveRecord && model_class < ::ActiveRecord::Base
-        require "mobility/active_record/backend_resetter"
-        ActiveRecord::BackendResetter
-      elsif Loaded::ActiveRecord && model_class.ancestors.include?(::ActiveModel::Dirty)
-        require "mobility/active_model/backend_resetter"
-        ActiveModel::BackendResetter
-      elsif Loaded::Sequel && model_class < ::Sequel::Model
-        require "mobility/sequel/backend_resetter"
-        Sequel::BackendResetter
-      else
-        self
-      end
-    end
-  end
-end

data/lib/mobility/configuration.rb

@@ -1,138 +0,0 @@
-# frozen_string_literal: true
-
-module Mobility
-=begin
-
-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
-
-    # Name of query scope/dataset method (defaults to +i18n+)
-    # @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
-
-    # @deprecated The default_options= setter has been deprecated. Set each
-    #   option on the default_options hash instead.
-    def default_options=(options)
-      warn %{
-WARNING: The default_options= setter has been deprecated.
-Set each option on the default_options hash instead, like this:
-
-  config.default_options[:fallbacks] = { ... }
-  config.default_options[:dirty] = true
-}
-      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
-
-    # Generate new fallbacks instance
-    # @note This method will call the proc defined in the variable set by the
-    # +fallbacks_generator=+ setter, passing the first argument to its `call`
-    # method. By default the generator returns an instance of
-    # +I18n::Locale::Fallbacks+.
-    # @param fallbacks [Hash] Fallbacks hash passed to generator
-    # @return [I18n::Locale::Fallbacks]
-    def new_fallbacks(fallbacks = {})
-      @fallbacks_generator.call(fallbacks)
-    end
-
-    # Assign proc which, passed a set of fallbacks, returns a default fallbacks
-    # instance. By default this is a proc which takes fallbacks and returns an
-    # instance of +I18n::Locale::Fallbacks+.
-    # @param [Proc] fallbacks generator
-    attr_writer :fallbacks_generator
-
-    # @deprecated Use {#new_fallbacks} instead.
-    def default_fallbacks(fallbacks = {})
-      warn %{
-WARNING: The default_fallbacks configuration getter has been renamed
-new_fallbacks to avoid confusion. The original method default_fallbacks will be
-removed in the next major version of Mobility.
-}
-      new_fallbacks(fallbacks)
-    end
-
-    # @deprecated Use {#fallbacks_generator=} instead.
-    def default_fallbacks=(fallbacks)
-      warn %{
-WARNING: The default_fallbacks= configuration setter has been renamed
-fallbacks_generator= to avoid confusion. The original method
-default_fallbacks= will be removed in the next major version of Mobility.
-}
-      self.fallbacks_generator = fallbacks
-    end
-
-    # Default backend to use (can be symbol or actual backend class)
-    # @return [Symbol,Class]
-    attr_accessor :default_backend
-
-    # Returns set of default accessor locles to use (defaults to
-    # +I18n.available_locales+)
-    # @return [Array<Symbol>]
-    def default_accessor_locales
-      if @default_accessor_locales.is_a?(Proc)
-        @default_accessor_locales.call
-      else
-        @default_accessor_locales
-      end
-    end
-    attr_writer :default_accessor_locales
-
-    def initialize
-      @accessor_method = :translates
-      @query_method = :i18n
-      @fallbacks_generator = lambda { |fallbacks| Mobility::Fallbacks.build(fallbacks) }
-      @default_accessor_locales = lambda { Mobility.available_locales }
-      @default_options = Options[{
-        cache:    true,
-        presence: true,
-        query:    true,
-        default:  Plugins::OPTION_UNSET
-      }]
-      @plugins = %i[
-        query
-        cache
-        dirty
-        fallbacks
-        presence
-        default
-        attribute_methods
-        fallthrough_accessors
-        locale_accessors
-      ]
-    end
-
-    class ReservedOptionKey < Exception; end
-
-    class Options < Hash
-      def []=(key, _)
-        if RESERVED_OPTION_KEYS.include?(key)
-          raise Configuration::ReservedOptionKey, "Default options may not contain the following reserved key: #{key}"
-        end
-        super
-      end
-    end
-  end
-end