mobility 0.8.10 → 1.0.0.beta2

data/lib/mobility/backends/null.rb

@@ -20,5 +20,7 @@ Backend which does absolutely nothing. Mostly for testing purposes.
       def self.configure(_); end
       # @!endgroup
     end
+
+    register_backend(:null, Null)
   end
 end

data/lib/mobility/backends/sequel.rb

@@ -1,9 +1,12 @@
+# frozen_string_literal: true
+require "mobility/backend"
+
 module Mobility
   module Backends
     module Sequel
       def self.included(backend_class)
-        backend_class.include(Backend)
-        backend_class.extend(ClassMethods)
+        backend_class.include Backend
+        backend_class.extend ClassMethods
       end
 
       module ClassMethods

data/lib/mobility/backends/sequel/column.rb

@@ -50,5 +50,7 @@ Implements the {Mobility::Backends::Column} backend for Sequel models.
         end.compact
       end
     end
+
+    register_backend(:sequel_column, Sequel::Column)
   end
 end

data/lib/mobility/backends/sequel/container.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
-require "mobility/backends/sequel/json"
+require "mobility/backends/sequel"
 require "mobility/backends/sequel/jsonb"
+require "mobility/backends/container"
 
 module Mobility
   module Backends
@@ -11,10 +12,7 @@ Implements the {Mobility::Backends::Container} backend for Sequel models.
 =end
     class Sequel::Container
       include Sequel
-
-      # @!method column_name
-      #   @return [Symbol] (:translations) Name of translations column
-      option_reader :column_name
+      include Container
 
       # @!group Backend Accessors
       #
@@ -44,7 +42,7 @@ Implements the {Mobility::Backends::Container} backend for Sequel models.
       def self.configure(options)
         options[:column_name] ||= :translations
         options[:column_name] = options[:column_name].to_sym
-        column_name, db_schema = options[:column_name], options[:model_class].db_schema
+        column_name, db_schema = options[:column_name], model_class.db_schema
         options[:column_type] = db_schema[column_name] && (db_schema[column_name][:db_type]).to_sym
         unless %i[json jsonb].include?(options[:column_type])
           raise InvalidColumnType, "#{options[:column_name]} must be a column of type json or jsonb"
@@ -114,5 +112,7 @@ Implements the {Mobility::Backends::Container} backend for Sequel models.
         end
       end
     end
+
+    register_backend(:sequel_container, Sequel::Container)
   end
 end

data/lib/mobility/backends/sequel/hstore.rb

@@ -20,7 +20,7 @@ Implements the {Mobility::Backends::Hstore} backend for Sequel models.
         # @!group Backend Accessors
         # @!macro backend_writer
         def write(locale, value, options = {})
-          super(locale, value && value.to_s, options)
+          super(locale, value && value.to_s, **options)
         end
         # @!endgroup
 
@@ -35,5 +35,7 @@ Implements the {Mobility::Backends::Hstore} backend for Sequel models.
         class HStoreOp < ::Sequel::Postgres::HStoreOp; end
       end
     end
+
+    register_backend(:sequel_hstore, Sequel::Hstore)
   end
 end

data/lib/mobility/backends/sequel/json.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'mobility/backends/sequel/pg_hash'
 
 Sequel.extension :pg_json, :pg_json_ops
@@ -42,5 +43,7 @@ Implements the {Mobility::Backends::Json} backend for Sequel models.
         class JSONOp < ::Sequel::Postgres::JSONOp; end
       end
     end
+
+    register_backend(:sequel_json, Sequel::Json)
   end
 end

data/lib/mobility/backends/sequel/jsonb.rb

@@ -55,7 +55,7 @@ Implements the {Mobility::Backends::Jsonb} backend for Sequel models.
 
           def =~(other)
             case other
-            when Integer, Hash
+            when Integer, ::Hash
               to_dash_arrow =~ other.to_json
             when NilClass
               ~to_question
@@ -66,5 +66,7 @@ Implements the {Mobility::Backends::Jsonb} backend for Sequel models.
         end
       end
     end
+
+    register_backend(:sequel_jsonb, Sequel::Jsonb)
   end
 end

data/lib/mobility/backends/sequel/key_value.rb

@@ -36,7 +36,7 @@ Implements the {Mobility::Backends::KeyValue} backend for Sequel models.
             options[:association_name] ||= :"#{options[:type]}_translations"
             options[:class_name]       ||= Mobility::Sequel.const_get("#{type.capitalize}Translation")
           end
-          options[:table_alias_affix] = "#{options[:model_class]}_%s_#{options[:association_name]}"
+          options[:table_alias_affix] = "#{model_class}_%s_#{options[:association_name]}"
         rescue NameError
           raise ArgumentError, "You must define a Mobility::Sequel::#{type.capitalize}Translation class."
         end
@@ -93,7 +93,7 @@ Implements the {Mobility::Backends::KeyValue} backend for Sequel models.
               join_type = nils.empty? ? :inner : :left_outer
               # TODO: simplify to hash.transform_values { join_type } when
               #   support for Ruby 2.3 is deprecated
-              Hash[hash.keys.map { |key| [key, join_type] }]
+              ::Hash[hash.keys.map { |key| [key, join_type] }]
             else
               {}
             end
@@ -101,13 +101,13 @@ Implements the {Mobility::Backends::KeyValue} backend for Sequel models.
             hash = visit(boolean.args, locale)
             # TODO: simplify to hash.transform_values { :inner } when
             #   support for Ruby 2.3 is deprecated
-            Hash[hash.keys.map { |key| [key, :inner] }]
+            ::Hash[hash.keys.map { |key| [key, :inner] }]
           elsif boolean.op == :OR
             hash = boolean.args.map { |op| visit(op, locale) }.
-              compact.inject(&:merge)
+              compact.inject(:merge)
             # TODO: simplify to hash.transform_values { :left_outer } when
             #   support for Ruby 2.3 is deprecated
-            Hash[hash.keys.map { |key| [key, :left_outer] }]
+            ::Hash[hash.keys.map { |key| [key, :left_outer] }]
           else
             visit(boolean.args, locale)
           end
@@ -153,7 +153,7 @@ Implements the {Mobility::Backends::KeyValue} backend for Sequel models.
           end
           define_method :after_save do
             super()
-            attributes.each { |attribute| public_send(Backend.method_name(attribute)).save_translations }
+            attributes.each { |attribute| mobility_backends[attribute].save_translations }
           end
         end
         include callback_methods
@@ -202,5 +202,7 @@ Implements the {Mobility::Backends::KeyValue} backend for Sequel models.
         end
       end
     end
+
+    register_backend(:sequel_key_value, Sequel::KeyValue)
   end
 end

data/lib/mobility/backends/sequel/serialized.rb

@@ -36,6 +36,10 @@ Sequel serialization plugin.
       include Sequel
       include HashValued
 
+      def self.valid_keys
+        super + [:format]
+      end
+
       # @!group Backend Configuration
       # @param (see Backends::Serialized.configure)
       # @option (see Backends::Serialized.configure)
@@ -110,5 +114,7 @@ Sequel serialization plugin.
         super.to_sym
       end
     end
+
+    register_backend(:sequel_serialized, Sequel::Serialized)
   end
 end

data/lib/mobility/backends/sequel/table.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 require "mobility/util"
 require "mobility/backends/sequel"
-require "mobility/backends/key_value"
+require "mobility/backends/table"
+require "mobility/sequel/column_changes"
 require "mobility/sequel/model_translation"
 require "mobility/sequel/sql"
 
@@ -34,7 +35,7 @@ Implements the {Mobility::Backends::Table} backend for Sequel models.
         # @raise [CacheRequired] if cache option is false
         def configure(options)
           raise CacheRequired, "Cache required for Sequel::Table backend" if options[:cache] == false
-          table_name = Util.singularize(options[:model_class].table_name)
+          table_name = Util.singularize(model_class.table_name)
           options[:table_name]  ||= :"#{table_name}_translations"
           options[:foreign_key] ||= Util.foreign_key(Util.camelize(table_name.downcase))
           if association_name = options[:association_name]
@@ -175,5 +176,7 @@ Implements the {Mobility::Backends::Table} backend for Sequel models.
 
       class CacheRequired < ::StandardError; end
     end
+
+    register_backend(:sequel_table, Sequel::Table)
   end
 end

data/lib/mobility/backends/serialized.rb

@@ -23,8 +23,6 @@ Format for serialization. Either +:yaml+ (default) or +:json+.
 
 =end
     module Serialized
-      extend Backend::OrmDelegator
-
       class << self
 
         # @!group Backend Configuration
@@ -40,7 +38,7 @@ Format for serialization. Either +:yaml+ (default) or +:json+.
         def serializer_for(format)
           lambda do |obj|
             return if obj.nil?
-            if obj.is_a? Hash
+            if obj.is_a? ::Hash
               obj = obj.inject({}) do |translations, (locale, value)|
                 translations[locale] = value.to_s if Util.present?(value)
                 translations

data/lib/mobility/backends/table.rb

@@ -65,7 +65,6 @@ set.
 @see Mobility::Backends::Sequel::Table
 =end
     module Table
-      extend Backend::OrmDelegator
       # @!method association_name
       #   Returns the name of the translations association.
       #   @return [Symbol] Name of the association
@@ -84,13 +83,13 @@ set.
 
       # @!group Backend Accessors
       # @!macro backend_reader
-      def read(locale, options = {})
-        translation_for(locale, options).send(attribute)
+      def read(locale, **options)
+        translation_for(locale, **options).send(attribute)
       end
 
       # @!macro backend_writer
-      def write(locale, value, options = {})
-        translation_for(locale, options).send("#{attribute}=", value)
+      def write(locale, value, **options)
+        translation_for(locale, **options).send("#{attribute}=", value)
       end
       # @!endgroup
 
@@ -105,25 +104,22 @@ set.
         model.send(association_name)
       end
 
-      def self.included(backend)
-        backend.extend ClassMethods
-        backend.option_reader :association_name
-        backend.option_reader :subclass_name
-        backend.option_reader :foreign_key
-        backend.option_reader :table_name
+      def self.included(backend_class)
+        backend_class.extend ClassMethods
+        backend_class.option_reader :association_name
+        backend_class.option_reader :subclass_name
+        backend_class.option_reader :foreign_key
+        backend_class.option_reader :table_name
       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
+        def valid_keys
+          [:association_name, :subclass_name, :foreign_key, :table_name]
+        end
+
+        # Apply custom processing for cache plugin
+        def include_cache
+          include self::Cache
         end
 
         def table_alias(locale)
@@ -134,7 +130,18 @@ set.
       # Simple hash cache to memoize translations as a hash so they can be
       # fetched quickly.
       module Cache
-        include Plugins::Cache::TranslationCacher.new(:translation_for)
+        def translation_for(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
+
+        def clear_cache
+          model_cache && model_cache.clear
+        end
 
         private
 
@@ -145,10 +152,6 @@ set.
         def model_cache
           model.instance_variable_get(:"@__mobility_#{association_name}_cache")
         end
-
-        def clear_cache
-          model_cache && model_cache.clear
-        end
       end
     end
   end

data/lib/mobility/pluggable.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Mobility
+=begin
+
+Abstract Module subclass with methods to define plugins and defaults.
+Works with {Mobility::Plugin}. (Subclassed by {Mobility::Translations}.)
+
+=end
+  class Pluggable < Module
+    class << self
+      def plugin(name, *args)
+        Plugin.configure(self, defaults) { __send__ name, *args }
+      end
+
+      def plugins(&block)
+        Plugin.configure(self, defaults, &block)
+      end
+
+      def included_plugins
+        included_modules.grep(Plugin)
+      end
+
+      def defaults
+        @defaults ||= {}
+      end
+
+      def inherited(klass)
+        super
+        klass.defaults.merge!(defaults)
+      end
+    end
+
+    def initialize(*, **options)
+      initialize_options(options)
+      validate_options(@options)
+    end
+
+    attr_reader :options
+
+    private
+
+    def initialize_options(options)
+      @options = self.class.defaults.merge(options)
+    end
+
+    # This is overridden by backend plugin to exclude mixed-in backend options.
+    def validate_options(options)
+      plugin_keys = self.class.included_plugins.map { |p| Plugins.lookup_name(p) }
+      extra_keys = options.keys - plugin_keys
+      raise InvalidOptionKey, "No plugin configured for these keys: #{extra_keys.join(', ')}." unless extra_keys.empty?
+    end
+
+    class InvalidOptionKey < Error; end
+  end
+end

data/lib/mobility/plugin.rb

@@ -0,0 +1,260 @@
+# frozen-string-literal: true
+require "tsort"
+require "mobility/util"
+
+module Mobility
+=begin
+
+Defines convenience methods on plugin module to hook into initialize/included
+method calls on +Mobility::Pluggable+ instance.
+
+- #initialize_hook: called after {Mobility::Pluggable#initialize}, with
+  attribute names.
+- #included_hook: called after {Mobility::Pluggable#included}. (This can be
+  used to include any module(s) into the backend class, see
+  {Mobility::Plugins::Backend}.)
+
+Also includes a +configure+ class method to apply plugins to a pluggable
+({Mobility::Pluggable} instance), with a block.
+
+@example Defining a plugin
+  module MyPlugin
+    extend Mobility::Plugin
+
+    initialize_hook do |*names|
+      names.each do |name|
+        define_method "#{name}_foo" do
+          # method body
+        end
+      end
+    end
+
+    included_hook do |klass, backend_class|
+      backend_class.include MyBackendMethods
+      klass.include MyModelMethods
+    end
+  end
+
+@example Configure an attributes class with plugins
+  class Translations < Mobility::Translations
+  end
+
+  Mobility::Plugin.configure(Translations) do
+    cache
+    fallbacks
+  end
+
+  Translations.included_modules
+  #=> [Mobility::Plugins::Fallbacks, Mobility::Plugins::Cache, ...]
+=end
+  module Plugin
+    class << self
+      # Configure a pluggable {Mobility::Pluggable} with a block. Yields to a
+      # clean room where plugin names define plugins on the module. Plugin
+      # dependencies are resolved before applying them.
+      #
+      # @param [Class, Module] pluggable
+      # @param [Hash] defaults Plugin defaults hash to update
+      # @yield Block to define plugins
+      # @return [Hash] Updated plugin defaults
+      # @raise [Mobility::Plugin::CyclicDependency] if dependencies cannot be met
+      # @example
+      #   Mobility::Plugin.configure(Translations) do
+      #     cache
+      #     fallbacks [:en, :de]
+      #   end
+      def configure(pluggable, defaults = pluggable.defaults, &block)
+        DependencyResolver.new(pluggable, defaults).call(&block)
+      end
+    end
+
+    def initialize_hook(&block)
+      plugin = self
+
+      define_method :initialize do |*args, **options|
+        super(*args, **options)
+
+        class_exec(*args, &block) if plugin.dependencies_satisfied?(self.class)
+      end
+    end
+
+    def included_hook(&block)
+      plugin = self
+
+      define_method :included do |klass|
+        super(klass).tap do |backend_class|
+          if plugin.dependencies_satisfied?(self.class)
+            class_exec(klass, backend_class, &block)
+          end
+        end
+      end
+    end
+
+    def included(pluggable)
+      if defined?(@default) && !pluggable.defaults.has_key?(name = Plugins.lookup_name(self))
+        pluggable.defaults[name] = @default
+      end
+      super
+    end
+
+    def dependencies
+      @dependencies ||= {}
+    end
+
+    def default(value)
+      @default = value
+    end
+
+    # Method called when defining plugins to assign a default based on
+    # arguments and keyword arguments to the plugin method. By default, we
+    # simply assign the first argument, but plugins can opt to customize this
+    # if additional arguments or keyword arguments are required.
+    # (The backend plugin uses keyword arguments to set backend options.)
+    #
+    # @param [Hash] defaults
+    # @param [Symbol] key Plugin key on hash
+    # @param [Array] args Method arguments
+    def configure_default(defaults, key, *args)
+      defaults[key] = args[0] unless args.empty?
+    end
+
+    # Does this class include all plugins this plugin depends (directly) on?
+    # @param [Class] klass Pluggable class
+    def dependencies_satisfied?(klass)
+      required_plugins = dependencies.keys.map { |name| Plugins.load_plugin(name) }
+      (required_plugins - klass.included_modules).none?
+    end
+
+    # Specifies a dependency of this plugin.
+    #
+    # By default, the dependency is included (include: true). Passing +:before+
+    # or +:after+ will ensure the dependency is included before or after this
+    # plugin.
+    #
+    # Passing +false+ does not include the dependency, but checks that it has
+    # been included when running include and initialize hooks (so hooks will
+    # not run for this plugin if it has not been included). In other words:
+    # disable this plugin unless this dependency has been included elsewhere.
+    # (Note that this check is not applied recursively.)
+    #
+    # @param [Symbol] plugin Name of plugin dependency
+    # @option [TrueClass, FalseClass, Symbol] include
+    def requires(plugin, include: true)
+      unless [true, false, :before, :after].include?(include)
+        raise ArgumentError, "requires 'include' keyword argument must be one of: true, false, :before or :after"
+      end
+      dependencies[plugin] = include
+    end
+
+    DependencyResolver = Struct.new(:pluggable, :defaults) do
+      def call(&block)
+        plugins = DSL.call(defaults, &block)
+        tree = create_tree(plugins)
+
+        pluggable.include(*tree.tsort.reverse) unless tree.empty?
+      rescue TSort::Cyclic => e
+        raise_cyclic_dependency!(e.message)
+      end
+
+      private
+
+      def create_tree(plugins)
+        DependencyTree.new.tap do |tree|
+          visited = included_plugins
+          plugins.each { |plugin| traverse(tree, plugin, visited) }
+        end
+      end
+
+      def included_plugins
+        pluggable.included_modules.grep(Plugin)
+      end
+
+      # Recursively traverse dependencies and add their dependencies to tree
+      def traverse(tree, plugin, visited)
+        return if visited.include?(plugin)
+
+        tree.add(plugin)
+
+        plugin.dependencies.each do |dep_name, include_order|
+          next unless include_order
+          dep = Plugins.load_plugin(dep_name)
+          add_dependency(plugin, dep, tree, include_order)
+
+          traverse(tree, dep, visited << plugin)
+        end
+      end
+
+      def add_dependency(plugin, dep, tree, include_order)
+        case include_order
+        when :before
+          tree[plugin] += [dep]
+        when :after
+          check_after_dependency!(plugin, dep)
+          tree.add(dep)
+          tree[dep] += [plugin]
+        end
+      end
+
+      def check_after_dependency!(plugin, dep)
+        if included_plugins.include?(dep)
+          message = "'#{name(dep)}' plugin must come after '#{name(plugin)}' plugin"
+          raise DependencyConflict, append_pluggable_name(message)
+        end
+      end
+
+      def raise_cyclic_dependency!(error_message)
+        components = error_message.scan(/(?<=\[).*(?=\])/).first
+        names = components.split(', ').map! do |plugin|
+          name(Object.const_get(plugin)).to_s
+        end
+        message = "Dependencies cannot be resolved between: #{names.sort.join(', ')}"
+        raise CyclicDependency, append_pluggable_name(message)
+      end
+
+      def append_pluggable_name(message)
+        pluggable.name ? "#{message} in #{pluggable}" : message
+      end
+
+      def name(plugin)
+        Plugins.lookup_name(plugin)
+      end
+
+      class DependencyTree < Hash
+        include ::TSort
+        NO_DEPENDENCIES = Set.new.freeze
+
+        def add(key)
+          self[key] ||= NO_DEPENDENCIES
+        end
+
+        alias tsort_each_node each_key
+
+        def tsort_each_child(dep, &block)
+          self.fetch(dep, []).each(&block)
+        end
+      end
+
+      class DSL < BasicObject
+        def self.call(defaults, &block)
+          new(plugins = ::Set.new, defaults).instance_eval(&block)
+          plugins
+        end
+
+        def initialize(plugins, defaults)
+          @plugins = plugins
+          @defaults = defaults
+        end
+
+        def method_missing(m, *args)
+          plugin = Plugins.load_plugin(m)
+          @plugins << plugin
+          plugin.configure_default(@defaults, m, *args)
+        end
+      end
+    end
+    private_constant :DependencyResolver
+
+    class DependencyConflict < Mobility::Error; end
+    class CyclicDependency < DependencyConflict; end
+  end
+end