mobility 0.0.1 → 0.1.0

data/lib/mobility/backend/table.rb

@@ -0,0 +1,93 @@
+module Mobility
+  module Backend
+=begin
+
+Stores attribute translation as rows on a model-specific translation table
+(similar to Globalize[https://github.com/globalize/globalize]). By default,
+the table name for a model +Post+ with table +posts+ will be
++post_translations+, and the translation class will be +Post::Translation+. The
+translation class is dynamically created when the backend is initialized on the
+model class, and subclasses {Mobility::ActiveRecord::ModelTranslation} (for AR
+models) or inherits {Mobility::Sequel::ModelTranslation} (for Sequel models).
+
+The backend expects the translations table (+post_translations+) to have:
+
+- a string column named +locale+ to store the locale of the translation
+- columns for each translated attribute that uses the table (in general, this
+  will be all attributes of the model)
+- an integer column with name +post_id+ (where +post+ is the name of the model class)
+
+Unlike Globalize, attributes need not all be on one table. Mobility supports
+any number of translation tables for a given model class (all of the structure
+described above), provided the +association_name+ option is different for each.
+Some translations can be stored on one translation table, others on
+another, and Mobility will handle mapping reads/writes to each. The subclass
+used in this case will be generated from the +association_name+ by
+singularizing it and converting it to camelcase.
+
+For more details, see examples in {Mobility::Backend::ActiveRecord::Table}.
+
+==Backend Options
+
+===+association_name+
+
+Name of association on model. Defaults to +:mobility_model_translations+. If
+specified, ensure name does not overlap with other methods on model or with the
+association name used by other backends on model (otherwise one will overwrite
+the other).
+
+===+table_name+
+
+Name of translations table. By default, if the table used by the model is
++posts+, the table name used for translations will be +post_translations+.
+
+===+foreign_key+
+
+Foreign key to use in defining the association on the model. By default, if the
+model is a +Post+, this will be +post_id+. Generally this does not need to be
+set.
+
+===+subclass_name+
+
+Subclass to use when dynamically generating translation class for model, by
+default +:Translation+. Should be a symbol. Generally this does not need to be
+set.
+
+@see Mobility::Backend::ActiveRecord::Table
+@see Mobility::Backend::Sequel::Table
+=end
+    module Table
+      include OrmDelegator
+
+      # Simple hash cache to memoize translations as a hash so they can be
+      # fetched quickly.
+      class TranslationsCache < Hash
+
+        # @yield [locale] Yields locale to block in case attribute is not yet
+        #   cached, expects a new translation for that locale.
+        # @raise [ArgumentError] if block is not given
+        def initialize
+          raise ArgumentError, "missing block" unless block_given?
+          super() { |hash, locale| hash[locale] = yield(locale) }
+        end
+
+        # Return wrapper class which reads and writes to only one attribute of this cache.
+        # @param [String] attribute
+        # @return [Class] Hash-like wrapper object to be used as attribute cache
+        def for(attribute)
+          cache = self
+
+          Class.new do
+            define_singleton_method :[] do |locale|
+              cache[locale].send(attribute)
+            end
+
+            define_singleton_method :[]= do |locale, value|
+              cache[locale].send("#{attribute}=", value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mobility/backend_resetter.rb

@@ -0,0 +1,44 @@
+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>] attributes 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)
+      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
+          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
+        ActiveRecord::BackendResetter
+      elsif Loaded::ActiveRecord && model_class.ancestors.include?(::ActiveModel::Dirty)
+        ActiveModel::BackendResetter
+      elsif Loaded::Sequel && model_class < ::Sequel::Model
+        Sequel::BackendResetter
+      else
+        self
+      end
+    end
+  end
+end

data/lib/mobility/configuration.rb

@@ -0,0 +1,31 @@
+module Mobility
+=begin
+
+Stores shared Mobility configuration referenced by all backends.
+
+=end
+  class Configuration
+    # Alias for mobility_accessor (defaults to +translates+)
+    # @return [Symbol]
+    attr_accessor :accessor_method
+
+    # Default fallbacks instance
+    # @return [I18n::Locale::Fallbacks]
+    attr_accessor :default_fallbacks
+
+    # Default backend to use (can be symbol or actual backend class)
+    # @return [Symbol,Class]
+    attr_accessor :default_backend
+
+    # Default set of locales to use when defining accessors (defaults to
+    # +I18n.available_locales+)
+    # @return [Array<Symbol>]
+    attr_accessor :default_accessor_locales
+
+    def initialize
+      @accessor_method = :translates
+      @default_fallbacks = I18n::Locale::Fallbacks.new
+      @default_accessor_locales = I18n.available_locales
+    end
+  end
+end

data/lib/mobility/core_ext/nil.rb

@@ -0,0 +1,10 @@
+=begin
+
+Add +blank?+ method to +NilClass+ in case activesupport cannot be loaded.
+
+=end
+class NilClass
+  def blank?
+    true
+  end
+end

data/lib/mobility/core_ext/object.rb

@@ -0,0 +1,19 @@
+=begin
+
+Add +blank?+, +present?+ and +presence+ methods to +Object+ class if
+activesupport cannot be loaded.
+
+=end
+class Object
+  def blank?
+    respond_to?(:empty?) ? !!empty? : !self
+  end
+
+  def present?
+    !blank?
+  end
+
+  def presence
+    self if present?
+  end
+end

data/lib/mobility/core_ext/string.rb

@@ -0,0 +1,16 @@
+=begin
+
+Add String methods +camelize+ and +present?+ to +String+ if activesupport
+cannot be loaded.
+
+=end
+class String
+  # paraphrased from activesupport
+  def camelize
+    sub(/^[a-z\d]*/) { $&.capitalize }.gsub(/(?:_|(\/))([a-z\d]*)/) { "#{$1}#{$2.capitalize}" }.gsub('/', '::')
+  end
+
+  def present?
+    !blank?
+  end
+end

data/lib/mobility/instance_methods.rb

@@ -0,0 +1,34 @@
+module Mobility
+=begin
+
+Instance methods attached to all model classes when model includes or extends
+{Mobility}.
+
+=end
+  module InstanceMethods
+    # Fetch backend for an attribute
+    # @param [String] attribute Attribute
+    def mobility_backend_for(attribute)
+      send(Backend.method_name(attribute))
+    end
+
+    private
+
+    def mobility_get(*args)
+      mobility_read(*args).presence
+    end
+
+    def mobility_present?(*args)
+      mobility_read(*args).present?
+    end
+
+    def mobility_set(attribute, value, locale: Mobility.locale)
+      mobility_backend_for(attribute).write(locale.to_sym, value.presence)
+    end
+
+    def mobility_read(attribute, **options)
+      locale = options.delete(:locale) || Mobility.locale
+      mobility_backend_for(attribute).read(locale.to_sym, options)
+    end
+  end
+end

data/lib/mobility/orm.rb

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

data/lib/mobility/sequel.rb

@@ -0,0 +1,26 @@
+module Mobility
+=begin
+
+Module loading Sequel-specific classes for Mobility models.
+
+=end
+  module Sequel
+    autoload :BackendResetter,   "mobility/sequel/backend_resetter"
+    autoload :ColumnChanges,     "mobility/sequel/column_changes"
+    autoload :ModelTranslation,  "mobility/sequel/model_translation"
+    autoload :StringTranslation, "mobility/sequel/string_translation"
+    autoload :TextTranslation,   "mobility/sequel/text_translation"
+    autoload :Translation,       "mobility/sequel/translation"
+
+    def self.included(model_class)
+      model_class.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # @return [Sequel::Dataset] dataset extended with Mobility query methods.
+      def i18n
+        dataset
+      end
+    end
+  end
+end

data/lib/mobility/sequel/backend_resetter.rb

@@ -0,0 +1,26 @@
+module Mobility
+  module Sequel
+=begin
+
+Backend resetter for Sequel models. Triggers backend reset when +refresh+
+method is called.
+
+=end
+    class BackendResetter < Mobility::BackendResetter
+
+      # @param [Class] model_class Class of model to which backend resetter will be applied
+      def included(model_class)
+        model_reset_method = @model_reset_method
+
+        model_class.class_eval do
+          mod = Module.new do
+            define_method :refresh do
+              super().tap { instance_eval &model_reset_method }
+            end
+          end
+          include mod
+        end
+      end
+    end
+  end
+end

data/lib/mobility/sequel/column_changes.rb

@@ -0,0 +1,29 @@
+module Mobility
+  module Sequel
+=begin
+
+Internal class used to force Sequel model to notice changes when +mobility_set+
+is called.
+
+=end
+    class ColumnChanges < Module
+      # @param [Array<String>] attributes Backend attributes
+      def initialize(attributes)
+        @attributes = attributes
+
+        define_method :mobility_set do |attribute, value, locale: Mobility.locale|
+          if attributes.include?(attribute)
+            column = attribute.to_sym
+            column_with_locale = :"#{attribute}_#{locale}"
+            if mobility_get(attribute) != value
+              @changed_columns << column_with_locale if !changed_columns.include?(column_with_locale)
+              @changed_columns << column             if !changed_columns.include?(column)
+            end
+          end
+          super(attribute, value, locale: locale)
+        end
+        private :mobility_set
+      end
+    end
+  end
+end

data/lib/mobility/sequel/model_translation.rb

@@ -0,0 +1,20 @@
+module Mobility
+  module Sequel
+=begin
+
+Module included in translation class dynamically generated by
+{Backend::Sequel::Table} backend.
+
+=end
+    module ModelTranslation
+      def self.included(base)
+        base.plugin :validation_helpers
+      end
+
+      def validate
+        super
+        validates_presence [:locale]
+      end
+    end
+  end
+end

data/lib/mobility/sequel/string_translation.rb

@@ -0,0 +1,7 @@
+module Mobility
+  module Sequel
+    class StringTranslation < ::Sequel::Model(:mobility_string_translations)
+      include Translation
+    end
+  end
+end

data/lib/mobility/sequel/text_translation.rb

@@ -0,0 +1,7 @@
+module Mobility
+  module Sequel
+    class TextTranslation < ::Sequel::Model(:mobility_text_translations)
+      include Translation
+    end
+  end
+end

data/lib/mobility/sequel/translation.rb

@@ -0,0 +1,53 @@
+module Mobility
+  module Sequel
+    module Translation
+      def self.included(base)
+        base.class_eval do
+          plugin :validation_helpers
+
+          # Paraphased from sequel_polymorphic gem
+          #
+          model = underscore(self.to_s)
+          plural_model = pluralize(model)
+          many_to_one :translatable,
+            reciprocal: plural_model.to_sym,
+            reciprocal_type: :many_to_one,
+            setter: (proc do |able_instance|
+              self[:translatable_id]   = (able_instance.pk if able_instance)
+              self[:translatable_type] = (able_instance.class.name if able_instance)
+            end),
+            dataset: (proc do
+              translatable_type = send :translatable_type
+              translatable_id   = send :translatable_id
+              return if translatable_type.nil? || translatable_id.nil?
+              klass = self.class.send(:constantize, translatable_type)
+              klass.where(klass.primary_key => translatable_id)
+            end),
+            eager_loader: (proc do |eo|
+              id_map = {}
+              eo[:rows].each do |model|
+                model_able_type = model.send :translatable_type
+                model_able_id = model.send :translatable_id
+                model.associations[:translatable] = nil
+                ((id_map[model_able_type] ||= {})[model_able_id] ||= []) << model if !model_able_type.nil? && !model_able_id.nil?
+              end
+              id_map.each do |klass_name, id_map|
+                klass = constantize(camelize(klass_name))
+                klass.where(klass.primary_key=>id_map.keys).all do |related_obj|
+                  id_map[related_obj.pk].each do |model|
+                    model.associations[:translatable] = related_obj
+                  end
+                end
+              end
+            end)
+
+          def validate
+            super
+            validates_presence [:locale, :key, :translatable_id, :translatable_type]
+            validates_unique   [:locale, :key, :translatable_id, :translatable_type]
+          end
+        end
+      end
+    end
+  end
+end