mova 0.1.0

data/lib/mova/interpolation/sprintf.rb

@@ -0,0 +1,73 @@
+module Mova
+  module Interpolation
+    # Wrapper around {http://ruby-doc.org/core/Kernel.html#method-i-sprintf Kernel#sprintf} with
+    # fallback for missing placeholders.
+    #
+    # @since 0.1.0
+    class Sprintf
+      PLACEHOLDER_RE = Regexp.union(
+        /%%/,         # escape character
+        /%\{(\w+)\}/, # %{hello}
+        /%<(\w+)>(.*?\d*\.?\d*[bBdiouxXeEfgGcps])/ # %<hello>.d
+      )
+      ESCAPE_SEQUENCE = "%%".freeze
+      ESCAPE_SEQUENCE_REPLACEMENT = "%".freeze
+
+      # Replaces each placeholder like "%{{hello}}" or "%<hello>3.0f" with given values.
+      # @return [String]
+      # @param string [String]
+      # @param values [Hash{Symbol => String}]
+      #
+      # @example
+      #   interpolator.call("Hello, %{you}!", you: "world") #=> "Hello, world!"
+      # @example Sprintf-like formatting
+      #   # this is the equivalent to `sprintf("%3.0f", 1.0)`
+      #   interpolator.call("%<num>3.0f", num: 1.0) #=> "  1"
+      #
+      # @note Unlike `Kernel#sprintf` it won't raise an exception in case of missing
+      #   placeholder. Instead {#missing_placeholder} will be used to return a default
+      #   replacement.
+      #     sprintf("Hello %{world}", other: "value")  #=>  KeyError: key{world} not found
+      #     interpolator.call("Hello %{world}", other: "value") #=> "Hello %{world}"
+      #
+      # @see http://ruby-doc.org/core/Kernel.html#method-i-sprintf
+      def call(string, values)
+        string.to_str.gsub(PLACEHOLDER_RE) do |match|
+          if match == ESCAPE_SEQUENCE
+            ESCAPE_SEQUENCE_REPLACEMENT
+          else
+            placeholder = ($1 || $2).to_sym
+            replacement = values[placeholder] || missing_placeholder(placeholder, values, string)
+            $3 ? sprintf("%#{$3}", replacement) : replacement
+          end
+        end
+      end
+
+      module Overridable
+        # @return [String] default replacement for missing placeholder
+        # @param placeholder [Symbol]
+        # @param values [Hash{Symbol => String}] all given values for interpolation
+        #
+        # @example Wrap missing placeholders in HTML tag
+        #   interpolator = Mova::Interpolation::Sprintf.new.tap do |i|
+        #     def i.missing_placeholder(placeholder, values)
+        #       "<span class='error'>#{placeholder}<span>"
+        #     end
+        #   end
+        #   interpolator.call("%{my} %{notes}", my: "your") #=> "your <span class='error'>notes</span>"
+        #
+        # @example Raise an exception in case of missing placeholder
+        #   interpolator = Mova::Interpolation::Sprintf.new.tap do |i|
+        #     def i.missing_placeholder(placeholder, values)
+        #       raise KeyError.new("#{placeholder.inspect} is missing, #{values.inspect} given")
+        #     end
+        #   end
+        #   interpolator.call("%{my} %{notes}", my: "your") #=> KeyError: :notes is missing, {my: "your"} given
+        def missing_placeholder(placeholder, values)
+          "%{#{placeholder}}"
+        end
+      end
+      include Overridable
+    end
+  end
+end

data/lib/mova/read_strategy/eager.rb

@@ -0,0 +1,25 @@
+module Mova
+  module ReadStrategy
+    # This strategy is more perfomant with a remote storage, where each
+    # read results in a network roundtrip. Even if your cache or database
+    # is located on localhost, reading from a socket is much more slower
+    # than reading from memory.
+    # Instead of making one read per locale/scope fallback, we get combination
+    # of all fallbacks and make one request to the storage.
+    #
+    # @example Instantiating a translator with eager strategy
+    #   dalli = ActiveSupport::Cache::DalliStore.new("localhost:11211")
+    #   translator = Mova::Translator.new(storage: dalli)
+    #   translator.extend Mova::ReadStrategy::Eager
+    #
+    # @since 0.1.0
+    module Eager
+      def read_first(locales, key_with_scopes)
+        locales_with_scopes = Scope.cross_join(locales, key_with_scopes)
+        results = storage.read_multi(*locales_with_scopes)
+        _, value = results.find { |_, value| Mova.presence(value) }
+        value
+      end
+    end
+  end
+end

data/lib/mova/read_strategy/lazy.rb

@@ -0,0 +1,21 @@
+module Mova
+  module ReadStrategy
+    # This strategy is more perfomant with an in-memory storage, where
+    # read is cheap compared to a remote storage.
+    # It is included in {Translator} by default.
+    #
+    # @since 0.1.0
+    module Lazy
+      def read_first(locales, key_with_scopes)
+        locales.each do |locale|
+          key_with_scopes.each do |key|
+            result = storage.read(Scope.join(locale, key))
+            return result if Mova.presence(result)
+          end
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/mova/scope.rb

@@ -0,0 +1,94 @@
+module Mova
+  # Translation keys are usually organized in a tree, where each nesting level
+  # corresponds to a specific part of your application. Such hierarchical organization
+  # allows to reuse the keys and keep their names relatively short.
+  #
+  # Full path to a key forms a scope. Think of a scope as a namespace.
+  #
+  #   # here we have an example YAML file with "blank" keys within different scopes
+  #   activemodel:
+  #     errors:
+  #       blank: Can't be blank
+  #       message:
+  #         blank: Please provide a message
+  #
+  # Since Mova is designed to work with any key-value storage, we need to store a key
+  # with its own full scope and a locale. We use dot-separated strings as it's a common
+  # format in Ruby community.
+  #
+  #   "en.activemodel.errors.blank"
+  #   "en.activemodel.errors.message.blank"
+  #
+  # @note In YAML (and other storages that map to a hash) you can't store a value
+  #   for a nesting level itself.
+  #     errors: !can't have translation here
+  #       blank: Please enter a value
+  #   Other key-value storages usually don't have such limitation, however, it's better
+  #   to not introduce incompatibles in this area.
+  #
+  # @since 0.1.0
+  module Scope
+    extend self
+
+    SEPARATOR = ".".freeze
+
+    # Makes a new scope from given parts.
+    #
+    # @return [String]
+    # @param parts [Array<String, Symbol>, *Array<String, Symbol>]
+    #
+    # @example
+    #   Scope.join("hello", "world") #=> "hello.world"
+    #   Scope.join([:hello, "world"]) #=> "hello.world"
+    def join(*parts)
+      parts.join(SEPARATOR)
+    end
+
+    # Split a scope into parts.
+    #
+    # @return [Array<String>]
+    # @param scope [String]
+    #
+    # @example
+    #   Scope.split("hello.world") #=> ["hello", "world"]
+    def split(scope)
+      scope.split(SEPARATOR)
+    end
+
+    # Recurrently flattens hash by converting its keys to fully scoped ones.
+    #
+    # @return [Hash{String => String}]
+    # @param translations [Hash{String/Symbol => String/Hash}] with multiple
+    #   roots allowed
+    # @param current_scope for internal use
+    #
+    # @example
+    #   Scope.flatten(en: {common: {hello: "hi"}}, de: {hello: "Hallo"}) #=>
+    #     {"en.common.hello" => "hi", "de.hello" => "Hallo"}
+    def flatten(translations, current_scope = nil)
+      translations.each_with_object({}) do |(key, value), memo|
+        scope = current_scope ? join(current_scope, key) : key.to_s
+        if value.is_a?(Hash)
+          memo.merge!(flatten(value, scope))
+        else
+          memo[scope] = value
+        end
+      end
+    end
+
+    # Combines each locale with all keys.
+    #
+    # @return [Array<String>]
+    # @param locales [Array<String, Symbol>]
+    # @param keys [Array<String, Symbol>]
+    #
+    # @example
+    #   Scope.cross_join([:de, :en], [:hello, :hi]) #=>
+    #     ["de.hello", "de.hi", "en.hello", "en.hi"]
+    def cross_join(locales, keys)
+      locales.map do |locale|
+        keys.map { |key| join(locale, key) }
+      end.flatten
+    end
+  end
+end

data/lib/mova/storage/chain.rb

@@ -0,0 +1,124 @@
+module Mova
+  module Storage
+    # Allows to wrap several storages and treat them as one. All methods are called on
+    # each storage in order defined in the initializer.
+    #
+    # @since 0.1.0
+    class Chain
+      attr_reader :storages
+
+      def initialize(*storages)
+        @storages = storages
+
+        # Performance optimizations:
+        # * replace loop with OR operator in places where we know beforehand
+        #   all iterated elements (storages)
+        # * avoid reading from the next storage if possible
+        instance_eval <<-EOM, __FILE__, __LINE__ + 1
+          def read(key)
+            #{
+              calls_to_each_storage = storages.map.each_with_index do |s, i|
+                "Mova.presence(storages[#{i}].read(key))"
+              end
+              calls_to_each_storage.join(" || ")
+            }
+          end
+
+          def read_multi(*keys)
+            #{
+              initialize_results = storages.map.each_with_index do |s, i|
+                "results#{i} = nil"
+              end
+              initialize_results.join("\n")
+            }
+            keys.each_with_object({}) do |key, memo|
+              result = \
+                #{
+                  calls_to_each_storage = storages.map.each_with_index do |s, i|
+                    "Mova.presence((results#{i} ||= storages[#{i}].read_multi(*keys))[key])"
+                  end
+                  calls_to_each_storage.join(" || ")
+                }
+              memo[key] = result if result
+            end
+          end
+        EOM
+      end
+
+      # @!method read(key)
+      # @return [String, nil] first non-empty value while trying each storage in order defined
+      #   in the initializer.
+      # @param key [String]
+      #
+      # @example
+      #   storage1.write("hello", "ruby")
+      #   storage2.write("hello", "world")
+      #   storage2.write("bye", "war")
+      #   chain = Mova::Storage::Chain.new(storage1, storage2)
+      #   chain.read("hello") #=> "ruby"
+      #   chain.read("bye") #=> "war"
+      #
+      # @!parse
+      #   def read(key)
+      #     Mova.presence(storages[0].read(key)) || Mova.presence(storages[1].read(key)) || etc
+      #   end
+
+      # @!method read_multi(*keys)
+      # @return [Hash{String => String}] composed result of all non-empty values. Hashes are merged
+      #   backwards, so results from a first storage win over results from next one. However,
+      #   non-empty value wins over empty one.
+      # @param keys [*Array<String>]
+      #
+      # @example
+      #   storage1.write("hello", "ruby")
+      #   storage1.write("empty", "")
+      #   storage2.write("hello", "world")
+      #   storage2.write("empty", "not so much")
+      #   storage2.write("bye", "war")
+      #   chain = Mova::Storage::Chain.new(storage1, storage2)
+      #   chain.read_multi("hello", "bye", "empty") #=> {"hello" => "ruby", "bye" => "war", "empty" => "not so much"}
+      #
+      # @!parse
+      #  def read_multi(*keys)
+      #    results0 = nil
+      #    results1 = nil
+      #    etc
+      #    keys.each_with_object({}) do |key, memo|
+      #      result =
+      #        Mova.presence((results0 ||= storages[0].read_multi(*keys))[key]) ||
+      #        Mova.presence((results1 ||= storages[1].read_multi(*keys))[key]) || etc
+      #      memo[key] = result if result
+      #    end
+      #  end
+
+      # @return [void]
+      # @param key [String]
+      # @param value [String, nil]
+      #
+      # @note Each storage will receive #write. Use {Readonly} if you wish to protect
+      #   certain storages.
+      def write(key, value)
+        storages.each { |s| s.write(key, value) }
+      end
+
+      # @return [void]
+      #
+      # @note Each storage will receive #clear. Use {Readonly} if you wish to protect
+      #   certain storages.
+      def clear
+        storages.each { |s| s.clear }
+      end
+
+      # @return [Boolean]
+      # @param key [String]
+      def exist?(key)
+        storages.any? { |s| s.exist?(key) }
+      end
+
+      # @private
+      def inspect
+        "<##{self.class.name} storages=#{storages.inspect}>"
+      end
+    end
+  end
+end

data/lib/mova/storage/memory.rb

@@ -0,0 +1,67 @@
+module Mova
+  module Storage
+    # Thin wrapper around Hash.
+    #
+    # @note This class was designed to be *not* thread-safe for the sake of
+    #   speed. However, if you store translations in static YAML files and
+    #   do not write to the storage during application runtime, this is not a
+    #   big deal.
+    #
+    #   If you need thread-safe in-memory implemenation, use
+    #   {http://api.rubyonrails.org/classes/ActiveSupport/Cache/MemoryStore.html ActiveSupport::Cache::MemoryStore}.
+    #
+    #   Also note that with any in-memory implementation you'll have a copy of all
+    #   translations data in each spawned worker. Depending on number of your locales,
+    #   translation keys and workers, it may take up a lot of memory. This is the fastest
+    #   storage though.
+    #
+    # @since 0.1.0
+    class Memory
+      def initialize
+        @storage = {}
+      end
+
+      # @return [String, nil]
+      # @param key [String]
+      def read(key)
+        @storage[key]
+      end
+
+      # @return [Hash]
+      # @param keys [*Array<String>]
+      # @example
+      #   storage.write("foo", "bar")
+      #   storage.write("baz", "qux")
+      #   storage.read_multi("foo", "baz") #=> {"foo" => "bar", "baz" => "qux"}
+      def read_multi(*keys)
+        keys.each_with_object({}) do |key, memo|
+          result = read(key)
+          memo[key] = result if result
+        end
+      end
+
+      # @return [void]
+      # @param key [String]
+      # @param value [String, nil]
+      def write(key, value)
+        @storage[key] = value
+      end
+
+      # @return [Boolean]
+      # @param key [String]
+      def exist?(key)
+        @storage.key?(key)
+      end
+
+      # @return [void]
+      def clear
+        @storage.clear
+      end
+
+      # @private
+      def inspect
+        "<##{self.class.name}>"
+      end
+    end
+  end
+end

data/lib/mova/storage/readonly.rb

@@ -0,0 +1,51 @@
+module Mova
+  module Storage
+    # Wrapper around a storage that protects from writes.
+    #
+    # @since 0.1.0
+    class Readonly
+      attr_reader :storage
+
+      def initialize(storage)
+        @storage = storage
+      end
+
+      # @return [String, nil]
+      # @param key [String]
+      def read(key)
+        storage.read(key)
+      end
+
+      # @return [Hash{String => String}]
+      # @param keys [*Array<String>]
+      def read_multi(*keys)
+        storage.read_multi(*keys)
+      end
+
+      # @return [Boolean]
+      # @param key [String]
+      def exist?(key)
+        storage.exist?(key)
+      end
+
+      # @return [void]
+      # @param key [String]
+      # @param value [String, nil]
+      #
+      # @note Does nothing
+      def write(key, value)
+      end
+
+      # @return [void]
+      #
+      # @note Does nothing
+      def clear
+      end
+
+      # @private
+      def inspect
+        "<##{self.class.name} storage=#{storage.inspect}>"
+      end
+    end
+  end
+end