i18n-inflector-3 3.0.0

data/lib/i18n-inflector/backend.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+#
+# Author::    Paweł Wilk (mailto:pw@gnu.org)
+# Copyright:: (c) 2011,2012,2013 by Paweł Wilk
+# License::   This program is licensed under the terms of {file:docs/LGPL GNU Lesser General Public License} or {file:docs/COPYING Ruby License}.
+#
+# This file contains I18n::Backend::Inflector module,
+# which extends I18n::Backend::Simple by adding the ability
+# to interpolate patterns containing inflection tokens
+# defined in translation data.
+
+module I18n
+  # @abstract This namespace is shared with I18n subsystem.
+  module Backend
+    # This module contains methods that add
+    # tokenized inflection support to internal I18n classes.
+    # It is intened to be included in the Simple backend
+    # module so that it will patch translate method in order
+    # to interpolate additional inflection tokens present in translations.
+    # 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
+        inflector_try_init
+        @inflector
+      end
+
+      # Cleans up internal hashes containg kinds, inflections and aliases.
+      #
+      # @api public
+      # @note It calls {I18n::Backend::Simple#reload! I18n::Backend::Simple#reload!}
+      # @return [Boolean] the result of calling ancestor's method
+      def reload!
+        @inflector = nil
+        super
+      end
+
+      # Translates given key taking care of inflections.
+      #
+      # @api public
+      # @see I18n::Inflector::API#interpolate
+      # @see I18n::Inflector::InflectionOptions
+      # @param [Symbol] locale locale
+      # @param [Symbol,String] key translation key
+      # @param [Hash] options a set of options to pass to the translation routines.
+      # @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 then the result is processed by {I18n::Inflector::API#interpolate}
+      # @return [String] the translated string with interpolated patterns
+      def translate(locale, key, options = {})
+        inflector_try_init
+
+        # take care about cache-awareness
+        cached = if options.key?(:inflector_cache_aware)
+                   options[:inflector_cache_aware]
+                 else
+                   @inflector.options.cache_aware
+                 end
+
+        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
+
+        # generate a pattern from key-based inflection object
+        if translated_string.is_a?(Hash) && key.to_s[0..0] == InflectorCfg::Markers::STRICT_KIND
+          translated_string = @inflector.key_to_pattern(translated_string)
+        end
+
+        # 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.
+      #
+      # @api public
+      # @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.
+      # @return [Hash] the stored translations
+      def store_translations(locale, data, options = {})
+        r = super
+        inflector_try_init
+        if data.respond_to?(:has_key?)
+          subdata = data[:i18n] || data['i18n']
+          unless subdata.nil?
+            subdata = subdata[:inflections] || subdata['inflections']
+            unless subdata.nil?
+              db, db_strict = load_inflection_tokens(locale, r[:i18n][:inflections])
+              @inflector.add_database(db, db_strict)
+            end
+          end
+        end
+        r
+      end
+
+      protected
+
+      # Initializes internal hashes used for keeping inflections configuration.
+      #
+      # @return [void]
+      def inflector_try_init
+        return if defined?(@inflector) && !@inflector.nil?
+
+        @inflector = I18n::Inflector::API.new
+        init_translations unless initialized?
+      end
+
+      # Takes care of loading inflection tokens
+      # for all languages (locales) that have them
+      # defined.
+      #
+      # @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
+        @inflector = I18n::Inflector::API.new unless defined?(@inflector) && !@inflector.nil?
+        super
+      end
+
+      # Gives an access to the internal structure containing configuration data
+      # for the given locale.
+      #
+      # @note Under some very rare conditions this method may be called while
+      #   translation data is loading. It must always return when translations
+      #   are not initialized. Otherwise it will cause loops and someone in Poland
+      #   will eat a kittien!
+      # @param [Symbol] locale the locale to use
+      # @return [Hash,nil] part of the translation data that
+      #   reflects inflections for the given locale or +nil+
+      #   if translations are not initialized
+      def inflection_subtree(locale)
+        return nil unless initialized?
+
+        lookup(locale, :'i18n.inflections', [], fallback: true, raise: false)
+      end
+
+      # Resolves an alias for a token if the given +token+ is an alias.
+      #
+      # @note It does take care of aliasing loops (max traverses is set to 64).
+      # @raise [I18n::BadInflectionToken] if a name of the token that alias points to is corrupted
+      # @raise [I18n::BadInflectionAlias] if an alias points to token that does not exists
+      # @return [Symbol] the true token that alias points to if the given +token+
+      #   is an alias or the given +token+ if it is a true token
+      # @overload shorten_inflection_alias(token, kind, locale)
+      #   Resolves an alias for a token if the given +token+ is an alias for the given +locale+ and +kind+.
+      #   @note This version uses internal subtree and needs the translation data to be initialized.
+      #   @param [Symbol] token the token name
+      #   @param [Symbol] kind the kind of the given token
+      #   @param [Symbol] locale the locale to use
+      #   @return [Symbol] the true token that alias points to if the given +token+
+      #     is an alias or the given +token+ if it is a true token
+      # @overload shorten_inflection_alias(token, kind, locale, subtree)
+      #   Resolves an alias for a token if the given +token+ is an alias for the given +locale+ and +kind+.
+      #   @param [Symbol] token the token name
+      #   @param [Symbol] kind the kind of the given token
+      #   @param [Symbol] locale the locale to use
+      #   @param [Hash] subtree the tree (in a form of nested Hashes) containing inflection tokens to scan
+      #   @return [Symbol] the true token that alias points to if the given +token+
+      #     is an alias or the given +token+ if it is a true token
+      def shorten_inflection_alias(token, kind, locale, subtree = nil, count = 0)
+        count += 1
+        return nil if count > 64
+
+        inflections_tree = subtree || inflection_subtree(locale)
+        return nil if inflections_tree.nil? || inflections_tree.empty?
+
+        kind_subtree  = inflections_tree[kind]
+        value         = kind_subtree[token].to_s
+
+        if value[0..0] == InflectorCfg::Markers::ALIAS
+          orig_token = token
+          token = value[1..]
+
+          raise I18n::BadInflectionToken.new(locale, token, kind) if InflectorCfg::Reserved::Tokens.invalid?(token, :DB)
+
+          token = token.to_sym
+          raise BadInflectionAlias.new(locale, orig_token, kind, token) if kind_subtree[token].nil?
+
+          shorten_inflection_alias(token, kind, locale, inflections_tree, count)
+
+        else
+          return token if kind_subtree.key?(token)
+
+          raise I18n::BadInflectionToken.new(locale, token, kind)
+
+        end
+      end
+
+      # Uses the inflections subtree and creates internal mappings
+      # 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 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)
+      #   @note That version calls the {inflection_subtree} method to obtain internal translations data.
+      #   Loads inflection tokens for the given locale using internal hash of stored translations. Requires
+      #   translations to be initialized.
+      #   @param [Symbol] locale the locale to use and work for
+      #   @return [I18n::Inflector::InflectionData,nil] the database containing inflections tokens
+      #     or +nil+ if something went wrong
+      # @overload load_inflection_tokens(locale, subtree)
+      #   Loads inflection tokens for the given locale using datthe given in an argument
+      #   @param [Symbol] locale the locale to use and work for
+      #   @param [Hash] subtree the tree (in a form of nested Hashes) containing inflection tokens to scan
+      #   @return [I18n::Inflector::InflectionData,nil] the database containing inflections tokens
+      #     or +nil+ if something went wrong
+      def load_inflection_tokens(locale, subtree = nil)
+        inflections_tree = subtree || inflection_subtree(locale)
+        return nil if inflections_tree.nil? || inflections_tree.empty?
+
+        inflections_tree = deep_symbolize(inflections_tree)
+
+        idb         = I18n::Inflector::InflectionData.new(locale)
+        idb_strict  = I18n::Inflector::InflectionData_Strict.new(locale)
+
+        return nil if idb.nil? || idb_strict.nil?
+
+        inflections = prepare_inflections(locale, inflections_tree, idb, idb_strict)
+
+        # add inflection tokens and kinds to internal database
+        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(locale, token, orig_kind,
+                subdb.get_kind(token, strict_kind))
+            end
+
+            # validate token's name
+            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.to_s[0..0] == InflectorCfg::Markers::ALIAS
+              next
+            end
+
+            # skip default token for later processing
+            next if token == :default
+
+            subdb.add_token(token, kind, description)
+          end
+        end
+
+        # handle aliases
+        inflections.each do |orig_kind, kind, _strict_kind, subdb, tokens|
+          tokens.each_pair do |token, description|
+            next if token == :default
+            next if description.to_s[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
+
+          # handle default tokens
+          next unless tokens.key?(:default)
+
+          if subdb.has_default_token?(kind)
+            raise I18n::DuplicatedInflectionToken.new(locale, :default, kind,
+              orig_kind)
+          end
+
+          orig_target = tokens[:default]
+          target = orig_target.to_s
+          target = target[1..] if target[0..0] == InflectorCfg::Markers::ALIAS
+          raise I18n::BadInflectionToken.new(locale, token, orig_kind, orig_target) if target.empty?
+
+          target = subdb.get_true_token(target.to_sym, kind)
+          raise I18n::BadInflectionAlias.new(locale, :default, orig_kind, orig_target) if target.nil?
+
+          subdb.set_default_token(kind, target)
+        end
+
+        [idb, idb_strict]
+      end
+
+      # @private
+      def prepare_inflections(locale, inflections, idb, idb_strict)
+        raise I18n::BadInflectionKind.new(locale, :INFLECTIONS_ROOT) unless inflections.respond_to?(:has_key?)
+
+        I18n::Inflector::LazyHashEnumerator.for(inflections).ary_map do |kind, tokens|
+          next if tokens.nil? || tokens.empty?
+          raise I18n::BadInflectionKind.new(locale, kind) unless tokens.respond_to?(:has_key?)
+
+          subdb       = idb
+          strict_kind = nil
+          orig_kind   = kind
+          if kind.to_s[0..0] == InflectorCfg::Markers::STRICT_KIND
+            kind = kind.to_s[1..]
+            next if kind.empty?
+
+            kind        = kind.to_sym
+            subdb       = idb_strict
+            strict_kind = kind
+          end
+          [orig_kind, kind, strict_kind, subdb, tokens]
+        end
+      end
+
+      # @private
+      def deep_symbolize(obj)
+        obj.each_with_object({}) do |(key, value), result|
+          value = deep_symbolize(value) if value.is_a?(Hash)
+          result[begin
+            key.to_s.to_sym
+          rescue StandardError
+            key
+          end || key] = value
+        end
+      end
+    end
+  end
+end

data/lib/i18n-inflector/config.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+#
+# Author::    Paweł Wilk (mailto:pw@gnu.org)
+# Copyright:: (c) 2011,2012,2013 by Paweł Wilk
+# License::   This program is licensed under the terms of {file:docs/LGPL GNU Lesser General Public License} or {file:docs/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.filter_map do |c|
+          v = obj.const_get(c)
+          (v.is_a?(f) && c != 'ALL') ? v : nil
+        end.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.
+        PATTERN       = '@'
+
+        # A character that is used to mark a strict kind.
+        STRICT_KIND   = '@'
+
+        # 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 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
+
+      # 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    = ':'
+
+          # A character used to create a virtual token
+          # that always matches.
+          WILDCARD  = '*'
+
+          # All token groups operators.
+          ALL       = Config.all_consts(self)
+        end
+
+        # 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
+
+        # All operators.
+        ALL = Tokens::ALL | Token::ALL
+      end
+
+      # 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]
+
+          # Reserved characters in token identifiers passed as options.
+          OPTION    = DB
+
+          # Reserved characters in token identifiers placed in patterns.
+          PATTERN   = OPTION - [Operators::Tokens::WILDCARD]
+
+          # 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
+
+          # 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
+
+        # 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]
+
+          # 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]
+
+          # 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
+
+          # 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
+      end
+
+      # A string for regular expression that catches patterns.
+      PATTERN_RESTR = "(.?)#{Markers::PATTERN}" \
+                      "([^\\#{Markers::PATTERN_BEGIN}]*)\\#{Markers::PATTERN_BEGIN}" \
+                      "([^\\#{Markers::PATTERN_END}]+)\\#{Markers::PATTERN_END}" \
+                      "((?:\\#{Markers::PATTERN_BEGIN}([^\\#{Markers::PATTERN_BEGIN}" \
+                      "]+)\\#{Markers::PATTERN_END})*)".freeze
+
+      # A string for regular expression that extracts additional patterns attached.
+      MULTI_RESTR = "\\#{Markers::PATTERN_BEGIN}" \
+                    "([^\\#{Markers::PATTERN_END}]+)\\" \
+                    "#{Markers::PATTERN_END}".freeze
+
+      # A regular expression that catches token groups or single tokens.
+      TOKENS_RESTR = '(?:' \
+                     "([^#{Operators::Tokens::ASSIGN}\\#{Operators::Tokens::OR}]+)" \
+                     "#{Operators::Tokens::ASSIGN}+" \
+                     "([^\\#{Operators::Tokens::OR}]+)\\1?)" \
+                     "|([^#{Operators::Tokens::ASSIGN}\\#{Operators::Tokens::OR}]+)".freeze
+
+      # A regular expression that catches patterns.
+      PATTERN_REGEXP  = Regexp.new PATTERN_RESTR
+
+      # A regular expression that extracts additional patterns attached.
+      MULTI_REGEXP    = Regexp.new MULTI_RESTR
+
+      # A regular expression that catches token groups or single tokens.
+      TOKENS_REGEXP   = Regexp.new TOKENS_RESTR
+    end
+
+    # @private
+    PATTERN_MARKER  = Config::Markers::PATTERN
+    # @private
+    NAMED_MARKER    = Config::Markers::STRICT_KIND
+    # @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
+end