i18n-inflector 2.1.0 → 2.2.0

data/lib/i18n-inflector/backend.rb

@@ -22,6 +22,9 @@ module I18n
     # Usually you don't have to know what's here to use it.
     module Inflector
 
+      # Shortcut to configuration module.
+      InflectorCfg = I18n::Inflector::Config
+
       # This accessor allows to reach API methods of the
       # inflector object associated with this class.
       def inflector
@@ -47,28 +50,61 @@ module I18n
       # @param [Symbol] locale locale
       # @param [Symbol,String] key translation key
       # @param [Hash] options a set of options to pass to the translation routines.
-      # @note Inflector requires at least one of the +options+ to have a value that
-      #   corresponds with token present in a pattern (or its alias). The name of that
-      #   particular option should be the same as the name of a kind of tokens from a pattern.
-      #   All +options+ along with a +string+ and +locale+ are passed to
+      # @note The given +options+ along with a translated string and the given
+      #   +locale+ are passed to
       #   {I18n::Backend::Simple#translate I18n::Backend::Simple#translate}
-      #   and the result is processed by {I18n::Inflector::API#interpolate}
+      #   and then the result is processed by {I18n::Inflector::API#interpolate}
       # @return [String] the translated string with interpolated patterns
       def translate(locale, key, options = {})
-        orig_options = options.dup
+        inflector_try_init
+
+        # take care about cache-awareness
+        cached = options.has_key?(:inflector_cache_aware) ?
+                 options[:inflector_cache_aware] : @inflector.options.cache_aware
+
+        if cached
+          interpolate_options = options
+          @inflector.options.prepare_options!(options)
+        else
+          interpolate_options = options.dup
+          @inflector.options.clean_for_translate!(options)
+        end
+
+        # translate string using original translate
         translated_string = super
 
-        return translated_string if (locale.nil? || locale.to_s.empty?)
+        # generate a pattern from key-based inflection object
+        if (translated_string.is_a?(Hash) && key.to_s[0..0] == InflectorCfg::Markers::PATTERN)
+          translated_string = @inflector.key_to_pattern(translated_string)
+        end
 
-        unless @inflector.inflected_locale?(locale)
-          return translated_string.gsub(I18n::Inflector::PATTERN,'')
+        # return immediatelly if something is wrong with locale (preventive)
+        # return if locale is not inflected - return string cleaned from pattern
+        if (locale.nil? || !@inflector.inflected_locale?(locale))
+          return translated_string.gsub(InflectorCfg::PATTERN_REGEXP) do
+            InflectorCfg::Escapes::PATTERN[$1] ? $& : ''
+          end
         end
 
-        unless translated_string.include?(I18n::Inflector::FAST_MATCHER)
+        # no pattern in a string - return string as is
+        unless translated_string.include?(InflectorCfg::Markers::PATTERN)
           return translated_string
         end
 
-        @inflector.interpolate(translated_string, locale, orig_options)
+        # interpolate string
+        begin
+
+          @inflector.options.prepare_options!(interpolate_options) unless cached
+          @inflector.interpolate(translated_string, locale, interpolate_options)
+
+        # complete the exception by adding translation key
+        rescue I18n::InflectionException => e
+
+          e.key = key
+          raise
+
+        end
+
       end
 
       # Stores translations in memory.
@@ -77,6 +113,7 @@ module I18n
       # @raise [I18n::InvalidLocale] if the given +locale+ is invalid
       # @raise [I18n::BadInflectionToken] if a name of some loaded token is invalid
       # @raise [I18n::BadInflectionAlias] if a loaded alias points to a token that does not exists
+      # @raise [I18n::BadInflectionKind] if a loaded kind identifier is invalid
       # @raise [I18n::DuplicatedInflectionToken] if a token has already appeard in loaded configuration
       # @note If inflections are changed it will regenerate proper internal
       #   structures.
@@ -115,6 +152,7 @@ module I18n
       # @note It calls {I18n::Backend::Simple#init_translations I18n::Backend::Simple#init_translations}
       # @raise [I18n::BadInflectionToken] if a name of some loaded token is invalid
       # @raise [I18n::BadInflectionAlias] if a loaded alias points to a token that does not exists
+      # @raise [I18n::BadInflectionKind] if a loaded kind identifier is invalid
       # @raise [I18n::DuplicatedInflectionToken] if a token has already appeard in loaded configuration
       # @return [Boolean] +true+ if everything went fine
       def init_translations
@@ -171,7 +209,7 @@ module I18n
         kind_subtree  = inflections_tree[kind]
         value         = kind_subtree[token].to_s
 
-        if value[0..0] != I18n::Inflector::ALIAS_MARKER
+        if value[0..0] != InflectorCfg::Markers::ALIAS
           if kind_subtree.has_key?(token)
             return token
           else
@@ -181,9 +219,10 @@ module I18n
           orig_token = token
           token = value[1..-1]
 
-          if (token.nil? || token.to_s.empty?)
+          if InflectorCfg::Reserved::Tokens.invalid?(token, :DB)
             raise I18n::BadInflectionToken.new(locale, token, kind)
           end
+
           token = token.to_sym
           if kind_subtree[token].nil?
             raise BadInflectionAlias.new(locale, orig_token, kind, token)
@@ -198,7 +237,8 @@ module I18n
       # to resolve kinds assigned to inflection tokens and aliases, including defaults.
       # @return [I18n::Inflector::InflectionData,nil] the database containing inflections tokens
       #   or +nil+ if something went wrong
-      # @raise [I18n::BadInflectionToken] if a name of some loaded token is invalid
+      # @raise [I18n::BadInflectionToken] if a token identifier is invalid
+      # @raise [I18n::BadInflectionKind] if a kind identifier is invalid
       # @raise [I18n::BadInflectionAlias] if a loaded alias points to a token that does not exists
       # @raise [I18n::DuplicatedInflectionToken] if a token has already appeard in loaded configuration
       # @overload load_inflection_tokens(locale)
@@ -223,23 +263,32 @@ module I18n
 
         return nil if (idb.nil? || idb_strict.nil?)
 
-        inflections = prepare_inflections(inflections_tree, idb, idb_strict)
+        inflections = prepare_inflections(locale, inflections_tree, idb, idb_strict)
 
         inflections.each do |orig_kind, kind, strict_kind, subdb, tokens|
+
+          # validate token's kind
+          if (kind.to_s.empty? || InflectorCfg::Reserved::Kinds.invalid?(orig_kind, :DB))
+            raise I18n::BadInflectionKind.new(locale, orig_kind)
+          end
+
           tokens.each_pair do |token, description|
 
             # test for duplicate
             if subdb.has_token?(token, strict_kind)
-              raise I18n::DuplicatedInflectionToken.new(subdb.get_kind(token, strict_kind), orig_kind, token)
+              raise I18n::DuplicatedInflectionToken.new(locale, token, orig_kind,
+                                                        subdb.get_kind(token, strict_kind))
             end
 
             # validate token's name
-            raise I18n::BadInflectionToken.new(locale, token, orig_kind) if (token.nil? || token.to_s.empty?)
+            if InflectorCfg::Reserved::Tokens.invalid?(token, :DB)
+              raise I18n::BadInflectionToken.new(locale, token, orig_kind)
+            end
 
             # validate token's description
             if description.nil?
               raise I18n::BadInflectionToken.new(locale, token, orig_kind, description)
-            elsif description[0..0] == I18n::Inflector::ALIAS_MARKER
+            elsif description[0..0] == InflectorCfg::Markers::ALIAS
               next
             end
 
@@ -254,7 +303,7 @@ module I18n
         inflections.each do |orig_kind, kind, strict_kind, subdb, tokens|
           tokens.each_pair do |token, description|
             next if token == :default
-            next if description[0..0] != I18n::Inflector::ALIAS_MARKER
+            next if description[0..0] != InflectorCfg::Markers::ALIAS
             real_token = shorten_inflection_alias(token, orig_kind, locale, inflections_tree)
             subdb.add_alias(token, real_token, kind) unless real_token.nil?
           end
@@ -264,11 +313,11 @@ module I18n
         inflections.each do |orig_kind, kind, strict_kind, subdb, tokens|
           next unless tokens.has_key?(:default)
           if subdb.has_default_token?(kind)
-            raise I18n::DuplicatedInflectionToken.new(orig_kind, nil, :default)
+            raise I18n::DuplicatedInflectionToken.new(locale, :default, kind, orig_kind)
           end
           orig_target = tokens[:default]
           target = orig_target.to_s
-          target = target[1..-1] if target[0..0] == I18n::Inflector::ALIAS_MARKER
+          target = target[1..-1] if target[0..0] == InflectorCfg::Markers::ALIAS
           if target.empty?
             raise I18n::BadInflectionToken.new(locale, token, orig_kind, orig_target)
           end
@@ -283,13 +332,19 @@ module I18n
       end
 
       # @private
-      def prepare_inflections(inflections, idb, idb_strict)
+      def prepare_inflections(locale, inflections, idb, idb_strict)
+        unless inflections.respond_to?(:has_key?)
+          raise I18n::BadInflectionKind.new(locale, :INFLECTIONS_ROOT)
+        end
         I18n::Inflector::LazyHashEnumerator.new(inflections).ary_map do |kind, tokens|
           next if (tokens.nil? || tokens.empty?)
+          unless tokens.respond_to?(:has_key?)
+            raise I18n::BadInflectionKind.new(locale, kind)
+          end
           subdb       = idb
           strict_kind = nil
           orig_kind   = kind
-          if kind.to_s[0..0] == I18n::Inflector::NAMED_MARKER
+          if kind.to_s[0..0] == InflectorCfg::Markers::PATTERN
             kind        = kind.to_s[1..-1]
             next if kind.empty?
             kind        = kind.to_sym

data/lib/i18n-inflector/config.rb

@@ -0,0 +1,297 @@
+# encoding: utf-8
+#
+# Author::    Paweł Wilk (mailto:pw@gnu.org)
+# Copyright:: (c) 2011 by Paweł Wilk
+# License::   This program is licensed under the terms of {file:LGPL GNU Lesser General Public License} or {file:COPYING Ruby License}.
+# 
+# This file contains configuration of I18n::Inflector module.
+
+module I18n
+
+  module Inflector
+
+    # This module contains submodules and module
+    # methods for handling global configuration
+    # of the engine.
+    module Config
+
+      # @private
+      def get_i18n_reserved_keys
+        return I18n::RESERVED_KEYS                  if defined?(I18n::RESERVED_KEYS)
+        return I18n::Backend::Base::RESERVED_KEYS   if defined?(I18n::Backend::Base::RESERVED_KEYS)
+        return I18n::Backend::Simple::RESERVED_KEYS if defined?(I18n::Backend::Simple::RESERVED_KEYS)
+        return RESERVED_KEYS                        if defined?(RESERVED_KEYS)
+        []
+      end
+      module_function :get_i18n_reserved_keys
+
+      # @private
+      def all_consts(obj, f=String)
+        obj.constants.map do |c|
+          v = obj.const_get(c)
+          (v.is_a?(f) && c != 'ALL') ? v : nil
+        end.compact.uniq
+      end
+      module_function :all_consts
+
+      # @private
+      def gen_regexp(ary)
+        ::Regexp.new '[' + ary.join + ']'
+      end
+      module_function :gen_regexp
+
+      # Prefix that makes option a controlling option.
+      OPTION_PREFIX = InflectionOptions::OPTION_PREFIX
+
+      # Regexp matching a prefix that makes option
+      # a controlling option.
+      OPTION_PREFIX_REGEXP = Regexp.new '^' + OPTION_PREFIX
+
+      # This module contains keys that have special
+      # meaning.
+      module Keys
+
+        # A Symbol that is used to mark default token
+        # in configuration and in options.
+        DEFAULT_TOKEN = :default
+
+        # All keys
+        ALL = HSet.new Config.all_consts(self, Symbol)
+      end
+
+      # This module contains characters that are markers
+      # giving the shape for a pattern and its elements.
+      module Markers
+
+        # A character that is used to mark pattern
+        # and a strict kind.
+        PATTERN       = '@'
+
+        # A character that is used to open a pattern.
+        PATTERN_BEGIN = '{'
+
+        # A character that ends a pattern.
+        PATTERN_END   = '}'
+
+        # A character that indicates an alias.
+        ALIAS         = '@'
+
+        # A character used to mark token value as loud.
+        LOUD_VALUE    = '~'
+
+        # All markers.
+        ALL = Config.all_consts(self)
+
+      end # module Markers
+
+      module Escapes
+
+        # A general esape symbol.
+        ESCAPE    = '\\'
+
+        # A regular expression that catches escape symbols.
+        ESCAPE_R  = /\\([^\\])/
+
+        # A list of escape symbols that cause a pattern to be escaped.
+        PATTERN   = HSet[Markers::PATTERN, Escapes::ESCAPE]
+
+      end # module Escapes
+
+      # This module contains constants that define
+      # operators in patterns.
+      module Operators
+
+        # This module contains constants that define
+        # operators in patterns that handle token
+        # groups or tokens.
+        module Tokens
+
+          # A character used to mark patterns as complex
+          # and to separate token groups assigned to different
+          # strict kinds.
+          AND     = '+'
+
+          # A character that is used to separate tokens
+          # or token groups within a pattern. 
+          OR      = '|'
+
+          # A character used to assign value to a token
+          # or a group of tokens.
+          ASSIGN  = ':'
+
+          # All token groups operators.
+          ALL     = Config.all_consts(self)
+
+        end # module Tokens
+
+        # This module contains constants that are operators
+        # in patterns that handle token groups or tokens.
+        module Token
+
+          # A character used to separate multiple tokens.
+          OR      = ','
+
+          # A character used to mark tokens as negative.
+          NOT     = '!'
+
+          # All token operators.
+          ALL     = Config.all_consts(self)
+
+        end # module Token
+
+        # All operators.
+        ALL = (Tokens::ALL + Token::ALL).uniq
+
+      end # module Operators
+
+      # This module contains constants defining
+      # reserved characters in tokens and kinds.
+      module Reserved
+
+        # Reserved keys.
+        KEYS = HSet.new  Config.get_i18n_reserved_keys  +
+                         Config::Keys::ALL.to_a         +
+                         InflectionOptions.known.values
+
+        # This module contains constants defining
+        # reserved characters in token identifiers.
+        module Tokens
+
+          # Reserved characters in token identifiers placed in configuration.
+          DB        = (Operators::ALL + Markers::ALL - [Markers::LOUD_VALUE]).uniq
+
+          # Reserved characters in token identifiers passed as options.
+          OPTION    = DB
+
+          # Reserved characters in token identifiers placed in patterns.
+          PATTERN   = OPTION
+
+          # This module contains constants defining
+          # regular expressions for reserved characters
+          # in token identifiers.
+          module Regexp
+
+            # Reserved characters in token identifiers placed in configuration.
+            DB      = Config.gen_regexp Tokens::DB
+
+            # Reserved characters in token identifiers passed as options.
+            OPTION  = Config.gen_regexp Tokens::OPTION
+
+            # Reserved characters in token identifiers placed in patterns.
+            PATTERN = Config.gen_regexp Tokens::PATTERN
+
+          end # module Regexp
+
+          # This method checks if the given +token+ is invalid,
+          # that means it's either +nil+ or empty or it matches
+          # the refular expression given as +root+.
+          # 
+          # @api public
+          # @param [Symbol,String] token the identifier of a token
+          # @param [Regexp] root the regular expression used to test
+          # @return [Boolean] +true+ if the given +token+ is
+          #   invalid, +false+ otherwise
+          def invalid?(token, root)
+            token = token.to_s
+            token.empty?                                          ||
+            (root == Regexp::PATTERN && Keys::ALL[token.to_sym])  ||
+            Regexp.const_get(root) =~ token
+          end
+          module_function :invalid?
+
+        end # module Tokens
+
+        # This module contains constants defining
+        # reserved characters in kind identifiers.
+        module Kinds
+
+          # Reserved characters in kind identifiers placed in configuration.
+          DB        = (Operators::ALL + Markers::ALL - [Markers::ALIAS, Markers::LOUD_VALUE]).uniq
+
+          # Reserved characters in kind identifiers passed as option values.
+          OPTION    = DB
+
+          # Reserved characters in kind identifiers placed in patterns.
+          PATTERN   = (Operators::ALL + Markers::ALL - [Markers::LOUD_VALUE]).uniq
+
+          # This module contains constants defining
+          # regular expressions for reserved characters
+          # in kind identifiers.
+          module Regexp
+
+            # Reserved characters in kind identifiers placed in configuration.
+            DB      = Config.gen_regexp Kinds::DB
+
+            # Reserved characters in kind identifiers passed as option values.
+            OPTION  = Config.gen_regexp Kinds::OPTION
+
+            # Reserved characters in kind identifiers placed in patterns.
+            PATTERN = Config.gen_regexp Kinds::PATTERN
+
+          end # module Regexp
+
+          # This method checks if the given +kind+ is invalid,
+          # that means it's either +nil+ or empty or it matches
+          # the refular expression given as +root+.
+          # 
+          # @api public
+          # @param [Symbol,String] kind the identifier of a kind
+          # @param [Regexp] root the regular expression used to test
+          # @return [Boolean] +true+ if the given +kind+ is
+          #   invalid, +false+ otherwise
+          def invalid?(kind, root)
+            kind = kind.to_s
+            kind.empty?                                           ||
+             (root != Regexp::OPTION &&
+             (KEYS[kind.to_sym] || OPTION_PREFIX_REGEXP =~ kind)) ||
+            Regexp.const_get(root) =~ kind
+          end
+          module_function :invalid?
+
+        end # module Kinds
+
+      end # module Reserved
+
+      # A regular expression that catches patterns.
+      PATTERN_REGEXP  = Regexp.new  '(.?)'  + Markers::PATTERN       +
+                                    '([^\\' + Markers::PATTERN_BEGIN + ']*)\\' + Markers::PATTERN_BEGIN +
+                                    '([^\\' + Markers::PATTERN_END   + ']+)\\' + Markers::PATTERN_END   +
+                                    '((?:\\'+ Markers::PATTERN_BEGIN + '([^\\' + Markers::PATTERN_BEGIN +
+                                    ']+)\\' + Markers::PATTERN_END   + ')*)'
+
+      # A regular expression that extracts additional patterns attached.
+      MULTI_REGEXP    = Regexp.new  '\\'    + Markers::PATTERN_BEGIN          +
+                                    '([^\\' + Markers::PATTERN_END + ']+)\\'  +
+                                    Markers::PATTERN_END
+
+      # A regular expression that catches token groups or single tokens.
+      TOKENS_REGEXP   = Regexp.new  '(?:'   +
+                                    '([^'   + Operators::Tokens::ASSIGN + '\\'      + Operators::Tokens::OR + ']+)' +
+                                              Operators::Tokens::ASSIGN + '+'       +
+                                    '([^\\' + Operators::Tokens::OR     + ']+)\1?)' +
+                                    '|([^'  + Operators::Tokens::ASSIGN + '\\'      + Operators::Tokens::OR + ']+)'
+
+    end # module Config
+
+    # @private
+    PATTERN_MARKER  = Config::Markers::PATTERN
+    # @private
+    NAMED_MARKER    = Config::Markers::PATTERN
+    # @private
+    ALIAS_MARKER    = Config::Markers::ALIAS
+    # @private
+    ESCAPE          = Config::Escapes::ESCAPE
+    # @private
+    ESCAPE_R        = Config::Escapes::ESCAPE_R
+    # @private
+    ESCAPES         = Config::Escapes::PATTERN
+    # @private
+    PATTERN         = Config::PATTERN_REGEXP
+    # @private
+    TOKENS          = Config::TOKENS_REGEXP
+    # @private
+    INFLECTOR_RESERVED_KEYS = Config::Reserved::KEYS
+
+  end # module Inflector
+
+end # module I18n