mobility 0.1.20 → 0.2.0

data/lib/mobility/backend.rb

@@ -1,4 +1,5 @@
 # frozen-string-literal: true
+require "mobility/backend/orm_delegator"
 
 module Mobility
 =begin
@@ -8,9 +9,8 @@ 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 reader returning +options+ configuring the backend ({#options})
-- a constructor setting these three elements (+model+, +attribute+, +options+),
-  and extracting fallbacks from the options hash ({#initialize})
+- a constructor setting these two elements (+model+, +attribute+), and
+  extracting fallbacks from the options hash ({#initialize})
 - a +setup+ method adding any configuration code to the model class
   ({Setup#setup})
 
@@ -18,6 +18,8 @@ On top of this, a backend will normally:
 
 - implement a +read+ instance method to read from the backend
 - implement a +write+ instance method to write to the backend
+- implement an +each_locale+ instance method to iterate through available locales
+  (used to define other +Enumerable+ traversal and search methods)
 - implement a +configure+ class method to apply any normalization to the
   options hash
 - call the +setup+ method yielding attributes and options to configure the
@@ -27,11 +29,15 @@ On top of this, a backend will normally:
   class MyBackend
     include Mobility::Backend
 
-    def read(locale, **options)
+    def read(locale, options = {})
       # ...
     end
 
-    def write(locale, value, **options)
+    def write(locale, value, options = {})
+      # ...
+    end
+
+    def each_locale
       # ...
     end
 
@@ -49,21 +55,7 @@ On top of this, a backend will normally:
 =end
 
   module Backend
-    autoload :ActiveModel,  'mobility/backend/active_model'
-    autoload :ActiveRecord, 'mobility/backend/active_record'
-    autoload :Cache,        'mobility/backend/cache'
-    autoload :Column,       'mobility/backend/column'
-    autoload :Dirty,        'mobility/backend/dirty'
-    autoload :Fallbacks,    'mobility/backend/fallbacks'
-    autoload :Hstore,       'mobility/backend/hstore'
-    autoload :Jsonb,        'mobility/backend/jsonb'
-    autoload :KeyValue,     'mobility/backend/key_value'
-    autoload :Null,         'mobility/backend/null'
-    autoload :OrmDelegator, 'mobility/backend/orm_delegator'
-    autoload :Presence,     'mobility/backend/presence'
-    autoload :Sequel,       'mobility/backend/sequel'
-    autoload :Serialized,   'mobility/backend/serialized'
-    autoload :Table,        'mobility/backend/table'
+    include Enumerable
 
     # @return [String] Backend attribute
     attr_reader :attribute
@@ -80,29 +72,57 @@ On top of this, a backend will normally:
     end
 
     # @!macro [new] backend_reader
+    #   Gets the translated value for provided locale from configured backend.
     #   @param [Symbol] locale Locale to read
     #   @return [Object] Value of translation
     #
     # @!macro [new] backend_writer
+    #   Updates translation for provided locale without calling backend's methods to persist the changes.
     #   @param [Symbol] locale Locale to write
     #   @param [Object] value Value to write
     #   @return [Object] Updated value
 
+    # @!macro [new] backend_iterator
+    #   Yields locales available for this attribute.
+    #   @yieldparam [Symbol] Locale
+    def each_locale
+    end
+
+    # Yields translations to block
+    # @yieldparam [Mobility::Backend::Translation] Translation
+    def each
+      each_locale { |locale| yield Translation.new(self, locale) }
+    end
+
+    # List locales available for this backend.
+    # @return [Array<Symbol>] Array of available locales
+    def locales
+      map(&:locale)
+    end
+
+    # @param [Symbol] locale Locale to read
+    # @return [TrueClass,FalseClass] Whether translation is present for locale
+    def present?(locale, options = {})
+      Util.present?(read(locale, options))
+    end
+
     # Extend included class with +setup+ method
     def self.included(base)
       base.extend(Setup)
+      base.extend(ClassMethods)
     end
 
     # @param [String] attribute
     # @return [String] name of backend reader method
     def self.method_name(attribute)
-      "#{attribute}_backend".freeze
+      @backend_method_names ||= {}
+      @backend_method_names[attribute] ||= "#{attribute}_backend".freeze
     end
 
     # Defines setup hooks for backend to customize model class.
     module Setup
       # Assign block to be called on model class.
-      # @yield [attributes, options]
+      # @yield [attribute_names, options]
       # @note When called multiple times, setup blocks will be appended
       #   so that they are run together consecutively on class.
       def setup &block
@@ -123,13 +143,15 @@ On top of this, a backend will normally:
 
       # Call setup block on a class with attributes and options.
       # @param model_class Class to be setup-ed
-      # @param [Array<String>] attributes
+      # @param [Array<String>] attribute_names
       # @param [Hash] options
-      def setup_model(model_class, attributes, **options)
+      def setup_model(model_class, attribute_names, **options)
         return unless setup_block = @setup_block
-        model_class.class_exec(attributes, options, &setup_block)
+        model_class.class_exec(attribute_names, options, &setup_block)
       end
+    end
 
+    module ClassMethods
       # {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.
@@ -141,6 +163,23 @@ On top of this, a backend will normally:
       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
+    end
+
+    Translation = Struct.new(:backend, :locale) do
+      %w[read write].each do |accessor|
+        define_method accessor do |*args|
+          backend.send(accessor, locale, *args)
+        end
+      end
     end
   end
 end

data/lib/mobility/backend/orm_delegator.rb

@@ -8,25 +8,35 @@ Adds {#for} method to backend to return ORM-specific backend.
   class Post < ActiveRecord::Base
     # ...
   end
-  Mobility::Backend::KeyValue.for(Post)
-  #=> Mobility::Backend::ActiveRecord::KeyValue
+  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('::'.freeze)
         if Loaded::ActiveRecord && model_class < ::ActiveRecord::Base
-          const_get(name.split("::".freeze).insert(-2, "ActiveRecord".freeze).join("::".freeze))
+          require_backend("active_record", namespace.last.underscore)
+          const_get(namespace.insert(-2, "ActiveRecord".freeze).join("::".freeze))
         elsif Loaded::Sequel && model_class < ::Sequel::Model
-          const_get(name.split("::".freeze).insert(-2, "Sequel".freeze).join("::".freeze))
+          require_backend("sequel", namespace.last.underscore)
+          const_get(namespace.insert(-2, "Sequel".freeze).join("::".freeze))
         else
-          raise ArgumentError, "#{name.split('::'.freeze).last} backend can only be used by ActiveRecord or Sequel models".freeze
+          raise ArgumentError, "#{namespace.last} backend can only be used by ActiveRecord or Sequel models".freeze
         end
       end
 
-      def self.included(base)
-        base.extend(self)
+      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

data/lib/mobility/backend/stringify_locale.rb

@@ -0,0 +1,18 @@
+module Mobility
+  module Backend
+=begin
+
+Module which stringifies the locale passed in to read and write methods.
+
+=end
+    module StringifyLocale
+      def read(locale, options = {})
+        super(locale.to_s, options)
+      end
+
+      def write(locale, value, options = {})
+        super(locale.to_s, value, options)
+      end
+    end
+  end
+end

data/lib/mobility/backend_resetter.rb

@@ -13,15 +13,15 @@ Resets backend cache when reset events occur.
 
 =end
   class BackendResetter < Module
-    # @param [Array<String>] attributes Attributes whose backends should be reset
+    # @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(attributes, &block)
+    def initialize(attribute_names, &block)
       raise ArgumentError, "block required" unless block_given?
       @model_reset_method = Proc.new do
-        attributes.each do |attribute|
-          if @mobility_backends && @mobility_backends[attribute]
-            @mobility_backends[attribute].instance_eval(&block)
+        attribute_names.each do |name|
+          if @mobility_backends && @mobility_backends[name]
+            @mobility_backends[name].instance_eval(&block)
           end
         end
       end
@@ -31,10 +31,13 @@ Resets backend cache when reset events occur.
     # @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

data/lib/mobility/backends.rb

@@ -0,0 +1,4 @@
+module Mobility
+  module Backends
+  end
+end

data/lib/mobility/backends/active_record.rb

@@ -0,0 +1,20 @@
+module Mobility
+  module Backends
+    module ActiveRecord
+      def setup_query_methods(query_methods)
+        setup do |attributes, options|
+          extend(Module.new do
+            define_method ::Mobility.query_method do
+              super().extending(query_methods.new(attributes, options))
+            end
+          end)
+        end
+      end
+
+      def self.included(backend_class)
+        backend_class.include(Backend)
+        backend_class.extend(self)
+      end
+    end
+  end
+end

data/lib/mobility/{backend → backends}/active_record/column.rb

@@ -1,8 +1,11 @@
+require "mobility/backends/active_record"
+require "mobility/backends/column"
+
 module Mobility
-  module Backend
+  module Backends
 =begin
 
-Implements the {Mobility::Backend::Column} backend for ActiveRecord models.
+Implements the {Mobility::Backends::Column} backend for ActiveRecord models.
 
 You can use the +mobility:translations+ generator to create a migration adding
 translatable columns to the model table with:
@@ -13,9 +16,6 @@ The generated migration will add columns +title_<locale>+ for every locale in
 +I18n.available_locales+. (The generator can be run again to add new attributes
 or locales.)
 
-@note This backend disables the +locale_accessors+ option, which would
-  otherwise interfere with column methods.
-
 @example
   class Post < ActiveRecord::Base
     translates :title, backend: :column
@@ -32,27 +32,39 @@ or locales.)
       include ActiveRecord
       include Column
 
-      require 'mobility/backend/active_record/column/query_methods'
+      require 'mobility/backends/active_record/column/query_methods'
 
       # @!group Backend Accessors
       # @!macro backend_reader
-      def read(locale, **_)
+      def read(locale, _ = {})
         model.read_attribute(column(locale))
       end
 
-      # @!group Backend Accessors
       # @!macro backend_writer
-      def write(locale, value, **_)
+      def write(locale, value, _ = {})
         model.send(:write_attribute, column(locale), value)
       end
+      # @!endgroup
 
-      # @!group Backend Configuration
-      def self.configure(options)
-        options[:locale_accessors] = false
+      # @!macro backend_iterator
+      def each_locale
+        available_locales.each { |l| yield(l) if present?(l) }
       end
-      # @!endgroup
 
       setup_query_methods(QueryMethods)
+
+      private
+
+      def available_locales
+        @available_locales ||= get_column_locales
+      end
+
+      def get_column_locales
+        column_name_regex = /\A#{attribute}_([a-z]{2}(_[a-z]{2})?)\z/.freeze
+        model.class.columns.map do |c|
+          (match = c.name.match(column_name_regex)) && match[1].to_sym
+        end.compact
+      end
     end
   end
 end

data/lib/mobility/{backend → backends}/active_record/column/query_methods.rb

@@ -1,7 +1,9 @@
+require "mobility/backends/active_record/query_methods"
+
 module Mobility
-  module Backend
-    class ActiveRecord::Column::QueryMethods < Backend::ActiveRecord::QueryMethods
-      def initialize(attributes, **options)
+  module Backends
+    class ActiveRecord::Column::QueryMethods < ActiveRecord::QueryMethods
+      def initialize(attributes, _)
         super
         attributes_extractor = @attributes_extractor
         @opts_converter = opts_converter = lambda do |opts|

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

@@ -0,0 +1,29 @@
+require 'mobility/backends/active_record/pg_hash'
+
+module Mobility
+  module Backends
+=begin
+
+Implements the {Mobility::Backends::Hstore} backend for ActiveRecord models.
+
+@see Mobility::Backends::ActiveRecord::HashValued
+
+=end
+    class ActiveRecord::Hstore < ActiveRecord::PgHash
+      require 'mobility/backends/active_record/hstore/query_methods'
+
+      # @!group Backend Accessors
+      # @!macro backend_reader
+      # @!method read(locale, **options)
+
+      # @!group Backend Accessors
+      # @!macro backend_writer
+      def write(locale, value, options = {})
+        super(locale, value && value.to_s, options)
+      end
+      # @!endgroup
+
+      setup_query_methods(QueryMethods)
+    end
+  end
+end

data/lib/mobility/{backend → backends}/active_record/hstore/query_methods.rb

@@ -1,7 +1,7 @@
 module Mobility
-  module Backend
+  module Backends
     class ActiveRecord::Hstore::QueryMethods < ActiveRecord::QueryMethods
-      def initialize(attributes, **)
+      def initialize(attributes, _)
         super
         attributes_extractor = @attributes_extractor
 

data/lib/mobility/{backend → backends}/active_record/jsonb.rb

@@ -1,16 +1,16 @@
-require 'mobility/backend/active_record/hash_valued'
+require 'mobility/backends/active_record/pg_hash'
 
 module Mobility
-  module Backend
+  module Backends
 =begin
 
-Implements the {Mobility::Backend::Jsonb} backend for ActiveRecord models.
+Implements the {Mobility::Backends::Jsonb} backend for ActiveRecord models.
 
-@see Mobility::Backend::ActiveRecord::HashValued
+@see Mobility::Backends::ActiveRecord::HashValued
 
 =end
-    class ActiveRecord::Jsonb < ActiveRecord::HashValued
-      require 'mobility/backend/active_record/jsonb/query_methods'
+    class ActiveRecord::Jsonb < ActiveRecord::PgHash
+      require 'mobility/backends/active_record/jsonb/query_methods'
 
       # @!group Backend Accessors
       #

data/lib/mobility/{backend → backends}/active_record/jsonb/query_methods.rb

@@ -1,7 +1,9 @@
+require "mobility/backends/active_record/query_methods"
+
 module Mobility
-  module Backend
+  module Backends
     class ActiveRecord::Jsonb::QueryMethods < ActiveRecord::QueryMethods
-      def initialize(attributes, **)
+      def initialize(attributes, _)
         super
         attributes_extractor = @attributes_extractor