mobility 0.0.1 → 0.1.0

data/lib/mobility/backend/cache.rb

@@ -0,0 +1,110 @@
+module Mobility
+  module Backend
+=begin
+
+Caches values fetched from the backend so subsequent fetches can be performed
+more quickly.
+
+By default, the cache stores cached values in a simple hash, returned from the
+{new_cache} method added to the including backend instance class. To use a
+different cache class, simply define a +new_cache+ method in the backend and
+return a new instance of the cache class (many backends do this, see
+{Mobility::Backend::KeyValue} for one example.)
+
+The cache is reset by the {clear_cache} method, which by default simply assigns
+the result of {new_cache} to the +@cache+ instance variable. This behaviour can
+also be customized by defining a +new_cache+ method on the backend class (see
+{Mobility::Backend::ActiveRecord::Table#new_cache} for an example of a backend that does this).
+
+The cache is reset when one of a set of events happens (saving, reloading,
+etc.). See {BackendResetter} for details.
+
+Values are added to the cache in two ways:
+
+1. first read from backend
+2. any write to backend
+
+The latter can be customized by defining the {write_to_cache?} method, which by
+default returns +false+. If set to +true+, then writes will only update the
+cache and not hit the backend. This is a sensible setting in case the cache is
+actually an object which directly stores the translation (see one of the
+ORM-specific implementations of {Mobility::Backend::KeyValue} for examples of
+this).
+
+=end
+    module Cache
+      # @group Backend Accessors
+      # @!macro backend_reader
+      def read(locale, **options)
+        if write_to_cache? || cache.has_key?(locale)
+          cache[locale]
+        else
+          cache[locale] = super
+        end
+      end
+
+      # @!macro backend_writer
+      def write(locale, value, **options)
+        cache[locale] = write_to_cache? ? value : super
+      end
+      # @!endgroup
+
+      # Adds hook to {Backend::Setup#setup_model} to include instance of
+      # model-specific {BackendResetter} subclass when setting up
+      # model class, to trigger cache resetting at specific events (saving,
+      # reloading, etc.)
+      module Setup
+        # @param model_class Model class
+        # @param [Array<String>] attributes Backend attributes
+        # @param [Hash] options Backend options
+        def setup_model(model_class, attributes, **options)
+          super
+          model_class.include BackendResetter.for(model_class).new(attributes) { clear_cache }
+        end
+      end
+
+      # @!group Cache Methods
+      # @!parse
+      #   def new_cache
+      #     {}
+      #   end
+      #
+      # @!parse
+      #   def write_to_cache?
+      #     false
+      #   end
+      #
+      # @!parse
+      #   def clear_cache
+      #     @cache = new_cache
+      #   end
+      # @!endgroup
+
+      # Includes cache methods to backend (unless they are already defined) and
+      # extends backend class with {Mobility::Cache::Setup} for backend resetting.
+      def self.included(backend_class)
+        backend_class.class_eval do
+          extend Setup
+
+          def new_cache
+            {}
+          end unless method_defined?(:new_cache)
+
+          def write_to_cache?
+            false
+          end unless method_defined?(:write_to_cache?)
+
+          def clear_cache
+            @cache = new_cache
+          end unless method_defined?(:clear_cache)
+        end
+      end
+
+      private
+
+      def cache
+        @cache ||= new_cache
+      end
+    end
+  end
+end

data/lib/mobility/backend/column.rb

@@ -0,0 +1,52 @@
+module Mobility
+  module Backend
+=begin
+
+Stores translated attribute as a column on the model table.
+
+To use this backend, ensure that the model table has columns named
++<attribute>_<locale>+ for every locale in +I18n.available_locales+.
+
+==Backend Options
+
+There are no options for this backend. Also, the +locale_accessors+ option will
+be ignored if set, since it would cause a conflict with column accessors.
+
+@see Mobility::Backend::ActiveRecord::Column
+@see Mobility::Backend::Sequel::Column
+
+=end
+    module Column
+      include OrmDelegator
+
+      # @!group Backend Accessors
+      #
+      # @!macro backend_reader
+      def read(locale, **options)
+        model.send(column(locale))
+      end
+
+      # @!macro backend_writer
+      def write(locale, value, **options)
+        model.send("#{column(locale)}=", value)
+      end
+      # @!endgroup
+
+      # Returns name of column where translated attribute is stored
+      # @param [Symbol] locale
+      # @return [String]
+      def column(locale = Mobility.locale)
+        Column.column_name_for(attribute, locale)
+      end
+
+      # Returns name of column where translated attribute is stored
+      # @param [String] attribute
+      # @param [Symbol] locale
+      # @return [String]
+      def self.column_name_for(attribute, locale = Mobility.locale)
+        normalized_locale = locale.to_s.downcase.sub("-", "_")
+        "#{attribute}_#{normalized_locale}".to_sym
+      end
+    end
+  end
+end

data/lib/mobility/backend/dirty.rb

@@ -0,0 +1,28 @@
+module Mobility
+  module Backend
+=begin
+
+Dirty tracking for Mobility attributes. See class-specific implementations for
+details.
+
+@see Mobility::Backend::ActiveModel::Dirty
+@see Mobility::Backend::Sequel::Dirty
+
+=end
+    module Dirty
+      # @param model_class Class of model this backend is defined on.
+      # @return [Backend]
+      # @raise [ArgumentError] if model class does not support dirty tracking
+      def self.for(model_class)
+        model_class ||= Object
+        if Loaded::ActiveRecord && model_class.ancestors.include?(::ActiveModel::Dirty)
+          Backend::ActiveModel::Dirty
+        elsif Loaded::Sequel && model_class < ::Sequel::Model
+          Backend::Sequel::Dirty
+        else
+          raise ArgumentError, "#{model_class.to_s} does not support Dirty module."
+        end
+      end
+    end
+  end
+end

data/lib/mobility/backend/fallbacks.rb

@@ -0,0 +1,89 @@
+module Mobility
+  module Backend
+=begin
+
+Falls back to one or more alternative locales in case no value is defined for a
+given locale.
+
+For +fallbacks: true+, Mobility will use the value of
+{Mobility::Configuration#default_fallbacks} for the fallbacks instance. This
+defaults to an instance of +I18n::Locale::Fallbacks+, but can be configured
+(see {Mobility::Configuration}).
+
+If a hash is passed to the +fallbacks+ option, a new fallbacks instance will be
+created for the model with the hash defining additional fallbacks. 
+
+In addition, fallbacks can be disabled when reading by passing `fallbacks:
+false` to the reader method. This can be useful to determine the actual value
+of the translated attribute, including a possible +nil+ value.
+
+@see https://github.com/svenfuchs/i18n/wiki/Fallbacks I18n Fallbacks
+
+@example With default fallbacks enabled (falls through to default locale)
+  class Post
+    translates :title, fallbacks: true
+  end
+
+  I18n.default_locale = :en
+  Mobility.locale = :en
+  post = Post.new(title: "foo")
+
+  Mobility.locale = :ja
+  post.title
+  #=> "foo"
+ 
+  post.title = "bar"
+  post.title
+  #=> "bar"
+
+@example With additional fallbacks enabled
+  class Post
+    translates :title, fallbacks: { :'en-US' => 'de-DE', :pt => 'de-DE' }
+  end
+
+  Mobility.locale = :'de-DE'
+  post = Post.new(title: "foo")
+
+  Mobility.locale = :'en-US'
+  post.title
+  #=> "foo"
+
+  post.title = "bar"
+  post.title
+  #=> "bar"
+
+@example Disabling fallbacks when reading value
+  class Post
+    translates :title, fallbacks: true
+  end
+
+  I18n.default_locale = :en
+  Mobility.locale = :en
+  post = Post.new(title: "foo")
+
+  Mobility.locale = :ja
+  post.title
+  #=> "foo"
+  post.title(fallbacks: false)
+  #=> nil
+=end
+    module Fallbacks
+      # @!group Backend Accessors
+      # @!macro backend_reader
+      # @option options [Boolean] fallbacks +false+ to disable fallbacks on lookup
+      def read(locale, **options)
+        return super if options[:fallbacks] == false
+        fallbacks[locale].detect do |locale|
+          value = super(locale)
+          break value if value.present?
+        end
+      end
+
+      private
+
+      def fallbacks
+        @fallbacks ||= Mobility.default_fallbacks
+      end
+    end
+  end
+end

data/lib/mobility/backend/hstore.rb

@@ -0,0 +1,21 @@
+module Mobility
+  module Backend
+
+=begin
+
+Stores translations as hash on Postgres hstore column.
+
+==Backend Options
+
+This backend has no options.
+
+@see Mobility::Backend::ActiveRecord::Hstore
+@see Mobility::Backend::Sequel::Hstore
+@see https://www.postgresql.org/docs/current/static/hstore.html PostgreSQL Documentation for hstore
+
+=end
+    module Hstore
+      include OrmDelegator
+    end
+  end
+end

data/lib/mobility/backend/jsonb.rb

@@ -0,0 +1,21 @@
+module Mobility
+  module Backend
+
+=begin
+
+Stores translations as hash on Postgres jsonb column.
+
+==Backend Options
+
+This backend has no options.
+
+@see Mobility::Backend::ActiveRecord::Jsonb
+@see Mobility::Backend::Sequel::Jsonb
+@see https://www.postgresql.org/docs/current/static/datatype-json.html PostgreSQL Documentation for JSON Types
+
+=end
+    module Jsonb
+      include OrmDelegator
+    end
+  end
+end

data/lib/mobility/backend/key_value.rb

@@ -0,0 +1,71 @@
+module Mobility
+  module Backend
+=begin
+
+Stores attribute translation as attribute/value pair on a shared translations
+table, using a polymorphic relationship between a translation class and models
+using the backend. By default, two tables are assumed to be present supporting
+string and text translations: a +mobility_text_translations+ table for text-valued translations and a
++mobility_string_translations+ table for string-valued translations (the only
+difference being the column type of the +value+ column on the table).
+
+==Backend Options
+
+===+association_name+
+
+Name of association on model. Defaults to +mobility_text_translations+ (if
++type+ is +:text+) or +mobility_string_translations+ (if +type+ is +:string+).
+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).
+
+===+type+
+
+Currently, either +:text+ or +:string+ is supported. Determines which class to
+use for translations, which in turn determines which table to use to store
+translations (by default +mobility_text_translations+ for text type,
++mobility_string_translations+ for string type).
+
+===+class_name+
+
+Class to use for translations when defining association. By default,
+{Mobility::ActiveRecord::TextTranslation} or
+{Mobility::ActiveRecord::StringTranslation} for ActiveRecord models (similar
+for Sequel models). If string is passed in, it will be constantized to get the
+class.
+
+@see Mobility::Backend::ActiveRecord::KeyValue
+@see Mobility::Backend::Sequel::KeyValue
+
+=end
+    module KeyValue
+      include OrmDelegator
+
+      # Simple cache to memoize translations as a hash so they can be fetched
+      # quickly.
+      class TranslationsCache
+        # @param backend Instance of KeyValue backend to cache
+        # @return [TranslationsCache]
+        def initialize(backend)
+          @cache = Hash.new { |hash, locale| hash[locale] = backend.translation_for(locale) }
+        end
+
+        # @param locale [Symbol] Locale to fetch
+        def [](locale)
+          @cache[locale].value
+        end
+
+        # @param locale [Symbol] Locale to set
+        # @param value [String] Value to set
+        def []=(locale, value)
+          @cache[locale].value = value
+        end
+
+        # @yield [locale, translation]
+        def each_translation &block
+          @cache.each_value &block
+        end
+      end
+    end
+  end
+end

data/lib/mobility/backend/null.rb

@@ -0,0 +1,24 @@
+module Mobility
+  module Backend
+=begin
+
+Backend which does absolutely nothing. Mostly for testing purposes.
+
+=end
+    class Null
+      include Backend
+
+      # @!group Backend Accessors
+      # @return [NilClass]
+      def read(*); end
+
+      # @return [NilClass]
+      def write(*); end
+      # @!endgroup
+
+      # @!group Backend Configuration
+      def self.configure!(*); end
+      # @!endgroup
+    end
+  end
+end

data/lib/mobility/backend/orm_delegator.rb

@@ -0,0 +1,33 @@
+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::Backend::KeyValue.for(Post)
+  #=> Mobility::Backend::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)
+        if Loaded::ActiveRecord && model_class < ::ActiveRecord::Base
+          const_get(name.split("::").insert(-2, "ActiveRecord").join("::"))
+        elsif Loaded::Sequel && model_class < ::Sequel::Model
+          const_get(name.split("::").insert(-2, "Sequel").join("::"))
+        else
+          raise ArgumentError, "#{name.split('::').last} backend can only be used by ActiveRecord or Sequel models"
+        end
+      end
+
+      def self.included(base)
+        base.extend(self)
+      end
+    end
+  end
+end