i18n-inflector 2.0.1 → 2.1.0

data/lib/i18n-inflector/lazy_enum.rb

@@ -0,0 +1,120 @@
+# 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 lazy enumerators.
+
+module I18n
+  module Inflector
+
+    if RUBY_VERSION.gsub(/\D/,'')[0..1].to_i < 19
+      require 'enumerator' rescue nil
+
+      class LazyHashEnumerator < Object.const_defined?(:Enumerator) ? Enumerator : Enumerable::Enumerator
+
+        # This class allows to initialize the Enumerator with a block
+        class Yielder
+          def initialize(&block)
+            @main_block = block
+          end
+
+          def each(&block)
+            @final_block = block
+            @main_block.call(self)
+          end
+
+          if Proc.method_defined?(:yield)
+            def yield(*arg)
+              @final_block.yield(*arg)
+            end
+          else
+            def yield(*arg)
+              @final_block.call(*arg)
+            end
+          end
+        end
+
+        unless (self.new{} rescue false)
+          def initialize(*args, &block)
+            args.empty? ? super(Yielder.new(&block)) : super(*args, &nil) 
+          end
+        end
+
+        if method_defined?(:with_object) and not method_defined?(:each_with_object)
+          alias_method :with_object, :each_with_object
+        end
+
+      end # class LazyHashEnumerator for ruby18
+
+    else # if RUBY_VERSION >= 1.9.0
+
+      class LazyHashEnumerator < Enumerator
+      end
+
+    end
+
+    # This class implements simple enumerators for hashes
+    # that allow to do lazy operations on them.
+    class LazyHashEnumerator
+
+      # Creates a Hash kind of object by collecting all
+      # data from enumerated collection.
+      # @return [Hash] the resulting hash
+      def to_h
+        Hash[self.to_a]
+      end
+
+      # Hash mapping enumerator
+      # @return [I18n::Inflector::LazyHashEnumerator] the enumerator
+      def map(&block)
+        LazyHashEnumerator.new do |yielder|
+          self.each do |k,v|
+            yielder.yield(k,block.call(k,v))
+          end
+        end
+      end
+
+      # Hash to Array mapping enumerator
+      # @return [I18n::Inflector::LazyEnumerator] the enumerator
+      def ary_map(&block)
+        LazyHashEnumerator.new do |yielder|
+          self.each do |value|
+            yielder.yield(block.call(value))
+          end
+        end
+      end
+
+      # This method converts resulting keys
+      # to array.
+      def keys
+        ary = []
+        self.each{ |k,v| ary << k }
+        return ary
+      end
+
+      # Hash selecting enumerator
+      # @return [I18n::Inflector::LazyHashEnumerator] the enumerator
+      def select(&block)
+        LazyHashEnumerator.new do |yielder|
+          self.each do |k,v|
+            yielder.yield(k,v) if block.call(k,v)
+          end
+        end
+      end
+
+      # Hash rejecting enumerator
+      # @return [I18n::Inflector::LazyHashEnumerator] the enumerator
+      def reject(&block)
+        LazyHashEnumerator.new do |yielder|
+          self.each do |k,v|
+            yielder.yield(k,v) unless block.call(k,v)
+          end
+        end
+      end
+
+    end # class LazyHashEnumerator
+
+  end
+end

data/lib/i18n-inflector/long_comments.rb

@@ -10,10 +10,11 @@
 # 
 
 module I18n
-  # @version 2.0
+  # @version 2.1
   # This module contains inflection classes and modules for enabling
   # the inflection support in I18n translations.
-  # Its submodule overwrites the Simple backend translate method
+  # It is used by the module called {I18n::Backend::Inflector}
+  # that overwrites the Simple backend translate method
   # so that it will interpolate additional inflection tokens present
   # in translations. These tokens may appear in *patterns* which
   # are contained within <tt>@{</tt> and <tt>}</tt> symbols.
@@ -30,6 +31,9 @@ module I18n
   #   i18n.inflector.true_tokens.keys
   #   # => [:f, :m, :n]
   #
+  # See the {file:EXAMPLES} for more information about real-life
+  # usage of Inflector.
+  # 
   # == Inflection pattern
   # An example inflection pattern contained in a translation record looks like:
   #   welcome: "Dear @{f:Madam|m:Sir|n:You|All}"
@@ -39,9 +43,12 @@ module I18n
   # pattern. To select which one an additional option is used. That option
   # must be passed to translate method.
   # 
+  # There are also so called <b>named patterns</b> that will be explained
+  # later.
+  # 
   # == Configuration
-  # To recognize tokens present in patterns this module uses keys grouped
-  # in the scope called `inflections` for a given locale. For instance
+  # To recognize tokens present in patterns keys grouped
+  # in the scope called +inflections+ for the given locale are used. For instance
   # (YAML format):
   #   en:
   #     i18n:
@@ -76,19 +83,30 @@ module I18n
   # This is required in order to keep patterns simple and tokens interpolation
   # fast.
   # 
-  # Kind is also used to instruct I18n.translate method which
-  # token it should pick. This will be explained later.
+  # Kind is also used to instruct {I18n::Backend::Inflector#translate} method which
+  # token it should pick. This is done through options and
+  # will be explained later.
+  # 
+  # There is also a class of kind called <b>strict kind</b> used by
+  # named patterns; that will be explained later.
   # 
   # === Tokens
-  # The token is an element of a pattern. A pattern may have many tokens
+  # The token is an element of a pattern. Any pattern may have many tokens
   # of the same kind separated by vertical bars. Each token name used in a
   # pattern should end with colon sign. After this colon a value should
   # appear (or an empty string).
-  #
+  # 
+  # Tokens also appear in a configuration data. They are assigned to kinds.
+  # Token names must be unique across all kinds, since it would be impossible
+  # for interpolation routine to guess a kind of a token present in a pattern.
+  # There is however a class of kinds called strict kinds, for which tokens
+  # must be unique only within a kind. The named patterns that are using
+  # strict kinds will be explained later.
+  # 
   # === Aliases
   # Aliases are special tokens that point to other tokens. They cannot
-  # be used in inflection patterns but they are fully recognized values
-  # of options while evaluating kinds.
+  # be used in inflection patterns but they are fully recognized options
+  # that can be passed to +translate+ method.
   # 
   # Aliases might be helpful in multilingual applications that are using
   # a fixed set of values passed through options to describe some properties
@@ -150,6 +168,133 @@ module I18n
   # but might be helpful (e.g. in UI). For obvious reasons you cannot
   # describe aliases.
   # 
+  # == Named patterns
+  # 
+  # A named pattern is a pattern that may contain special clause
+  # containing name of a kind that tokens from a pattern
+  # are assigned to. It looks like:
+  # 
+  #   welcome: "Dear @gender{f:Madam|m:Sir|n:You|All}"
+  # 
+  # === Configuring named patterns
+  # 
+  # To recognize tokens present in a named patterns,
+  # inflector uses keys grouped in the scope called +inflections+
+  # for the given locale. For instance (YAML format):
+  #   en:
+  #     i18n:
+  #       inflections:
+  #         @gender:
+  #           f:      "female"
+  #           woman:  @f
+  #           default: f
+  # 
+  # Elements in the example above are:
+  # * +en+: language
+  # * +i18n+: configuration scope
+  # * +inflections+: inflections configuration scope
+  # * +gender+: <bb>strict kind</bb> scope
+  # * +f+: inflection token
+  # * <tt>"female"</tt>: token's description
+  # * +woman+: inflection alias
+  # * <tt>@f</tt>: pointer to real token
+  # * +default+: default token for a strict kind +gender+
+  # 
+  # === Strict kinds
+  # 
+  # In order to handle named patterns properly a new data structure
+  # is used. It is called the <b>strict kind</b>. Strict kinds are defined
+  # in a configuration in a similar way the regular kinds are but
+  # tokens assigned to them may have the same names across a whole
+  # configuration. (Note that within a strict kind tokens should still
+  # be unique.) That implies a requirement of passing the
+  # identifier of a kind when referring to such tokens.
+  # 
+  # Here is the example configuration using strict kinds:
+  # 
+  #   en:
+  #     i18n:
+  #       inflections:
+  #         @gender:
+  #           f:      "female"
+  #           m:      "male"
+  #           n:      "neuter"
+  #           woman:  @f
+  #           man:    @m
+  #           default: n
+  #         @title:
+  #           s:      "sir"
+  #           l:      "lady"
+  #           u:      "you"
+  #           m:      @s
+  #           f:      @l
+  #           default: u
+  # 
+  # The only thing that syntactically distinguishes named kinds
+  # from regular kinds is a presence of the +@+ symbol.
+  # 
+  # You can mix regular and strict kinds having the same names.
+  # The proper class of kind will be picked up by interpolation
+  # method easily, since the first mentioned class uses
+  # patterns that are not named, and the second uses named patterns.
+  # 
+  # ==== Strict kinds in options
+  # 
+  # The interpolation routine recognizes strict kinds passed as
+  # options in almost the same way that it does it for regular
+  # kinds. The only difference is that you can override usage
+  # of a regular kind inflection option (if there is any) by
+  # putting a strict kind option with name prefixed by +@+ symbol.
+  # The inflection options starting with this symbol have
+  # precedence over inflection options without it;
+  # that is of course only true for strict kinds and has any effect
+  # only when both options describing the same kind are present.
+  # 
+  # In other words: interpolation routine is looking for
+  # strict kinds in inflection options using their names
+  # with +@+ in front. When that fails it falls back to
+  # trying an option named like the strict kind but without
+  # the +@+ symbol. Examples:
+  # 
+  #  I18n.translate(welcome, :gender => :m, :@gender => :f)
+  #  # the :f will be picked for the strict kind gender
+  #  
+  #  I18n.translate(welcome, :@gender => :f)
+  #  # the :f will be picked for the strict kind gender
+  #  
+  #  I18n.translate(welcome, :gender => :f)
+  #  # the :f will be picked for the strict kind gender
+  # 
+  # In the example above we assume that +welcome+ is defined
+  # like that:
+  # 
+  #   welcome: "Dear @gender{f:Madam|m:Sir|n:You|All}"
+  # 
+  # Note that for regular kinds the option named <tt>:@gender</tt>
+  # will have no meaning.
+  # 
+  # ==== Note for developers
+  # 
+  # Strict kinds that are used to handle named patterns
+  # are internally stored in a different database and handled by
+  # similar but different API methods than regular kinds. However
+  # most of the {I18n::Inflector::API} methods are also aware of strict kinds
+  # and will call proper methods oprating on strict inflections
+  # data when the +@+ symbol is detected at the beginning of
+  # the identifier of a kind passed as an argument. For example:
+  # 
+  #   I18n.inflector.has_token?(:m, :@gender)
+  # 
+  # will effectively call:
+  # 
+  #  I18n.inflector.strict.has_token?(:m, :gender)
+  # 
+  # As you can see above, to access {API_Strict} methods for strict kinds
+  # (and strict kinds data) only, associated with default I18n backend,
+  # use:
+  # 
+  #   I18n.inflector.strict
+  # 
   # == Interpolation
   # The value of each token present in a pattern is to be picked by the interpolation
   # routine and will replace the whole pattern, when the token name from that
@@ -197,7 +342,7 @@ module I18n
   # 
   # Be aware that enabling extended error reporting makes it unable
   # to use fallback values in most cases. Local fallbacks will then be
-  # applied only when a given option contains a proper value for some
+  # applied only when the given option contains a proper value for some
   # kind but it's just not present in a pattern, for example:
   # 
   # ===== YAML:
@@ -214,7 +359,7 @@ module I18n
   #   I18n.translate('welcome', :gender => :o, :raises => true)
   #   # => "Dear All"
   #   # since the token :o was configured but not used in the pattern
-  #
+  # 
   # === Unknown and empty tokens in options
   # If an option containing token is not present at all then the interpolation
   # routine will try the default token for a processed kind if the default
@@ -287,9 +432,22 @@ module I18n
   # Normally it possible to use only true tokens in patterns, not aliases.
   # However, if you feel lucky and you're not affraid of messy patterns
   # you can use the switch {I18n::Inflector::InflectionOptions#aliased_patterns}
-  # or corresponding +:inflector_aliased_patterns+ option passed to translation
+  # or corresponding <tt>:inflector_aliased_patterns</tt> option passed to translation
   # method.
   # 
+  # It may seem very easy and attractive to use aliased patterns, especially
+  # in the environments where token comes from a user. In such cases aliases
+  # may be used as database that translates common words to inflection tokens
+  # that have meanings. For example user may enter a gender in some text
+  # field and it will be used as inflection token. To map different names
+  # (e.g. male, boy, sir, female, girl, lady) to exact inflection tokens
+  # the aliases would be used. Note hovewer, that you can make use of
+  # <tt>I18n.inflector.true_token</tt> method (see {I18n::Inflector::API#true_token}
+  # that will resolve any alias and then use that data to feed some inflection option
+  # (e.g. <tt>:gender</tt>). In such scenario you don't have to rely on aliases
+  # in patterns and you will gain some speed since resolving will occur just once,
+  # not each time translated text is interpolated.
+  # 
   # === Escaping a pattern
   # If there is a need to translate something that matches an inflection
   # pattern the escape symbols can be used to disable the interpolation. These
@@ -335,9 +493,40 @@ module I18n
   # * {I18n::DuplicatedInflectionToken I18n::DuplicatedInflectionToken}
   # * {I18n::BadInflectionToken I18n::BadInflectionToken}
   # * {I18n::BadInflectionAlias I18n::BadInflectionAlias}
-  #
   module Inflector
 
+    class API
+
+      # This reader allows to reach a reference of the
+      # object that is a kind of {I18n::Inflector::API_Strict}
+      # and handles inflections for named patterns (strict kinds).
+      # 
+      # @api public
+      # @return [I18n::Inflector::API_Strict] the object containing
+      #   database and operations for named patterns (strict kinds)
+      attr_reader :strict
+
+      # Gets known regular inflection kinds.
+      # 
+      # @api public
+      # @note To get all inflection kinds (regular and strict) for default inflector
+      #   use: <tt>I18n.inflector.kinds + I18n.inflector.strict.kinds</tt>
+      # @return [Array<Symbol>] the array containing known inflection kinds
+      # @raise [I18n::InvalidLocale] if there is no proper locale name
+      # @overload kinds
+      #   Gets known inflection kinds for the current locale.
+      #   @return [Array<Symbol>] the array containing known inflection kinds
+      # @overload kinds(locale)
+      #   Gets known inflection kinds for the given +locale+.
+      #   @param [Symbol] locale the locale for which operation has to be done
+      #   @return [Array<Symbol>] the array containing known inflection kinds
+      def kinds(locale=nil)
+        super
+      end
+      alias_method :inflection_kinds, :kinds
+
+    end
+
   end
 
   # @abstract This exception class is defined in package I18n. It is raised when

data/lib/i18n-inflector/version.rb

@@ -14,7 +14,7 @@ module I18n
     # @private
     EMAIL       = 'pw@gnu.org'
     # @private
-    VERSION     = '2.0.1'
+    VERSION     = '2.1.0'
     # @private
     NAME        = 'i18n-inflector'
     # @private

data/lib/i18n-inflector.rb

@@ -3,12 +3,14 @@
 require 'i18n'
 
 require 'i18n-inflector/version'
-require 'i18n-inflector/errors'
-require 'i18n-inflector/util'
+require 'i18n-inflector/lazy_enum'
+require 'i18n-inflector/inflection_data_strict'
 require 'i18n-inflector/inflection_data'
 require 'i18n-inflector/options'
 require 'i18n-inflector/backend'
 require 'i18n-inflector/inflector'
+require 'i18n-inflector/errors'
+require 'i18n-inflector/api_strict'
+require 'i18n-inflector/api'
 
 I18n::Backend::Simple.send(:include, I18n::Backend::Inflector)
-