i18n-inflector 2.1.0 → 2.2.0

data/docs/EXAMPLES

@@ -11,21 +11,21 @@ This data will be used in any further example:
         
         @person:
           i:          "i"
-          you:        "you"
+          u:          "you"
           he:         "he"
           she:        "she"
           it:         "it"
-          u:          @you
+          you:        @u
         
         gender:
           m:          "male"
           f:          "female"
           n:          "neuter"
-          default:    neuter
+          default:    n
         
       
     welcome: "Dear @{f:Lady|m:Sir|n:You|All}!"  
-    sayit:   "@person{i:I|u:You|he:He|she:She|it:It} @person{i:am|u:are|he,she,it:is}"
+    sayit:   "@person{i:I|u:You|he:He|she:She|it:It}{ }{i:am|u:are|he,she,it:is}"
     tobe:    "%{person} @person{i:am|u:are|he,she,it:is}"
   
 
@@ -49,7 +49,7 @@ This data will be used in any further example:
   }})
   
   I18n.backend.store_translations(:en, 'welcome' => 'Dear @{f:Lady|m:Sir|n:You|All}!')
-  I18n.backend.store_translations(:en, 'sayit'   => '@person{i:I|u:You|he:He|she:She|it:It} @person{i:am|u:are|he,she,it:is}')
+  I18n.backend.store_translations(:en, 'sayit'   => '@person{i:I|u:You|he:He|she:She|it:It}{ }{i:am|u:are|he,she,it:is}')
   I18n.backend.store_translations(:en, 'tobe'    => '%{person} @person{i:am|u:are|he,she,it:is}')
   I18n.locale = :en
 
@@ -141,13 +141,17 @@ Getting all known strict kinds:
 
   I18n.inflector.strict.kinds
   #=> [:person]
-  
+
 Getting all known kinds for language 'pl':
 
   I18n.inflector.kinds(:pl)
   #=> []
-  
-<i>to be continued…</i>
+
+=== Listing all known options
+
+  I18n.inflector.options.known
+  #=> [:inflector_cache_aware, :inflector_raises, :inflector_aliased_patterns,
+  #    :inflector_unknown_defaults, :inflector_excluded_defaults]
 
 == Real-life example for Polish language
 
@@ -163,7 +167,7 @@ prefixes and suffixes of words we're able make our patterns compact.
 === YAML
 
   pl:
-    are_you_sure: "@{m,f:Jesteś pew}@{m:ien|f:na}@{n:Na pewno}?"
+    are_you_sure: "@{m,f:Jesteś pew}{m:ien|f:na}{n:Na pewno}?"
     
     i18n:
       inflections:
@@ -173,27 +177,18 @@ prefixes and suffixes of words we're able make our patterns compact.
           n:          "forma bezosobowa"
           masculine:  @m
           facet:      @m
-          chłop:      @m
           chłopak:    @m
-          chłopiec:   @m
-          mąż:        @m
           feminine:   @f
           pani:       @f
           kobieta:    @f
           k:          @f
           dziewczyna: @f
-          baba:       @f
-          babka:      @f
-          facetka:    @f
           impersonal: @n
           default:    n
-        
-      
-    
-  
+
 === Code
 
-  # Using shorter form than YAML-listed
+  # Using shorter form than listed as YAML
   
   I18n.backend.store_translations(:pl, :i18n => { :inflections => { :gender =>
                                   { :f => 'f', :m=>'m', :n=>'n', :kobieta=>:@f, :facet => :@m, :default=>:n }}})
@@ -215,8 +210,102 @@ prefixes and suffixes of words we're able make our patterns compact.
   #=> "Na pewno?"
 
   # It would look like that without commas:
-  I18n.backend.store_translations(:pl, :are_you_sure => "@{m:Jesteś pewien|f:Jesteś pewna}@{n:Na pewno}?")
+  I18n.backend.store_translations(:pl, :are_you_sure => "@{m:Jesteś pewien|f:Jesteś pewna|n:Na pewno}?")
 
   # That would also work but it's less readable.
   # PS: Have you ever configured Sendmail? ;-)
-  I18n.backend.store_translations(:pl, :are_you_sure => "@{n:Na|m,f:Jesteś} pew@{m:ie}n@{f:a|n:o}?")
+  I18n.backend.store_translations(:pl, :are_you_sure => "@{n:Na|m,f:Jesteś}{ pew}{m:ie}{n}{f:a|n:o}?")
+
+=== Complex pattern usage
+
+  # Store needed translations
+  I18n.backend.store_translations(:pl,
+    :i18n => { :inflections => {
+      :@gender =>
+          { :f       => 'f', :m     => 'm', :n       => 'n',
+            :kobieta => :@f, :facet => :@m, :default => :n },
+      :@tense =>
+          { :t     => 'teraz', :w       => 'przeszły', :j     => 'przyszły',
+            :teraz => :@t,     :wczoraj => :@w,        :jutro => :@j,
+            :default => :t }
+      }})
+  
+  I18n.backend.store_translations(:pl,
+    :msg_receive => "@gender+tense{n+w:Otrzymano|Dosta}{m,f,n+t:jesz|m,f,n+j:niesz|f+w:łaś|m+w:łeś} wiadomość")
+
+  I18n.locale = :pl
+
+  p I18n.translate('msg_receive', :gender => :kobieta)
+  #=> "Dostajesz wiadomość"
+
+  p I18n.translate('msg_receive', :gender => :facet)
+  #=> "Dostajesz wiadomość"
+
+  p I18n.translate('msg_receive')
+  #=> "Dostajesz wiadomość"
+
+  p I18n.translate('msg_receive', :gender => :kobieta, :tense => :wczoraj)
+  #=> "Dostałaś wiadomość"
+
+  p I18n.translate('msg_receive', :gender => :facet, :tense => :wczoraj)
+  #=> "Dostałeś wiadomość"
+  
+  p I18n.translate('msg_receive', :tense => :jutro)
+  #=> "Dostaniesz wiadomość"
+  
+  p I18n.translate('msg_receive', :tense => :wczoraj)
+  #=> "Otrzymano wiadomość"
+
+==== YAML for the example above
+
+The example above may use this YAML content instead of +store_translations+:
+
+  pl:
+    msg_receive: "@gender+tense{n+w:Otrzymano|Dosta}{m,f,n+t:jesz|m,f,n+j:niesz|f+w:łaś|m+w:łeś} wiadomość"
+    
+    i18n:
+      inflections:
+        @gender:
+          m:  'male'
+          f:  'female'
+          n:  'neuter'
+          kobieta:  @f
+          facet:    @m
+          default:  n
+        @tense:
+          t:        'teraźniejszy'
+          w:        'przeszły'
+          j:        'przyszły'
+          teraz:    @t
+          wczoraj:  @w
+          jutro:    @j
+          default:  @t
+
+===== Alternative for +msg_receive+ key
+
+The +msg_receive+ might also be expressed using two infleciton keys:
+
+  pl:
+    @msg_receive_1:
+      @kind:    gender+tense
+      @free:    'Dosta'
+      n+w:      'Otrzymano'
+  
+    @msg_receive_2:
+      @kind:    gender+tense
+      @suffix:  " wiadomość"
+      m,f,n+t:  "jesz"
+      m,f,n+j:  "niesz"
+      f+w:      "łaś"
+      m+w:      "łeś"
+
+But then you have to change the translation call too, e.g.:
+
+  p I18n.translate(['@msg_receive_1','@msg_receive_2'], :gender => :kobieta).join
+  #=> "Dostajesz wiadomość"
+
+The split is necessary because we have two patterns here and no way to express them
+as one inflection key.
+
+<i>to be continued…</i>
+

data/docs/HISTORY

@@ -1,3 +1,40 @@
+=== 2.2.0 / 2011-02-09
+
+* major enhancements
+
+  * Added loud tokens support
+  * Added complex patterns support
+  * Added key-based inflection support
+  * Added :cache_aware switch
+  * Improved validation of token and kind identifiers
+
+* minor enhancements
+
+  * Refactored error reporting code
+  * Refactored options gathering code
+  * Removed magic symbols and strings
+  * Removed intermediate array from LazyHashEnumerator#to_h
+  * Added multiple patterns support (syntactic sugar)
+  * Added I18n::Inflector::Config module
+  * Added I18n::Inflector::LazyArrayEnumerator class
+  * Added I18n::Inflector::HSet class for keeping collections of data
+  * Added error classes: I18n::InvalidInflectionOption and I18n::InvalidInflectionKind
+  * Interpolation method moved to I18n::Inflector::Interpolate module
+  * All inflection related exceptions now have the attribute "key" containing key name
+
+* major bugfixes
+
+  * Fixed handling of missing inflection option when :inflector_raises is set
+
+* minor bugfixes
+
+  * Fixed interpolation when :excluded_defaults is on and a kind is strict
+  * Fixed interpolation when pattern is escaped and locale is not inflected
+  * Enabled filtering of reserved names in options
+  * Enabled filtering of inflection options for options that go to original translate method
+  * Updated documentation in a section describing options
+  * Fixed some examples
+
 === 2.1.0 / 2011-01-27
 
 * major enhancements

data/docs/TODO

@@ -1,31 +1,7 @@
 == Near future
 
-* do something with that to_h that creates intermediate array
-
-* add a switch that causes inflection arguments to be gathered and removed before using original
-  version of translate and then injected when interpolating happens (default value
-  for that switch should be true if there is I18n version 4 installed)
-
-  - not so good idea to turn it on by default since the same variable may be used to interpolate
-    inflections and for direct interpolation
-
-* attach inflection key name to some raised errors
-
-* add some external iterators for tokens, aliases, kinds, true_tokens
-
-* allow different descriptions for aliases pointing to the same token, e.g.: now: @present ="description"
-
 == Distant future
 
-* Loud tokens: description substitution, e.g.: "Dear @{u|i:me}" gives "Dear You" if u is described as "You"
-
-* Combined patterns (!!!!!!!!!!!!)
-
-  - @person+time{i+now:am|i+past:was}
-  - @person+time{i+now:am|i+past:was|he,she,it+now:is}
-  - @g_sender+g_receiver{...} - for Hebrew for example
-
-* case-insensitivity switch for inflection options (?)
-
-* think about allowing negative matches to be AND-ed, e.g.: !m&!f:impersonal (?)
-  - that will double positive-matching syntax, and make it even less KISS
+* add "any token" operator - will make it easier to create complex patterns - (use negative matching to non-existant, reserved value)
+* split interpolate_core and make it more reusable by raw data (e.g. pattern content)
+* allow different descriptions for aliases pointing to the same token, e.g.: now: @present ="description"

data/lib/i18n-inflector/api.rb

@@ -44,6 +44,8 @@ module I18n
     # @api public
     class API < API_Strict
 
+      include I18n::Inflector::Interpolate
+
       # Options controlling the engine.
       # 
       # @api public
@@ -64,6 +66,11 @@ module I18n
       #   I18n.translate('welcome', :inflector_raises => true)
       attr_reader :options
 
+      # @private
+      def config
+        I18n::Inflector::Config
+      end
+
       # @private
       def strict
         @strict ||= I18n::Inflector::API_Strict.new(@idb_strict, @options)
@@ -184,7 +191,7 @@ module I18n
       #   @note If +kind+ begins with the +@+ symbol then the variant of this method
       #     operating on strict kinds will be called ({I18n::Inflector::API_Strict#inflected_locales})
       def inflected_locales(kind=nil)
-        if kind.to_s[0..0] == NAMED_MARKER
+        if kind.to_s[0..0] == Markers::PATTERN
           strict.inflected_locales(kind.to_s[1..-1])
         else
           (super + strict.inflected_locales(kind)).uniq
@@ -209,7 +216,7 @@ module I18n
       #   @param [Symbol] locale the locale identifier
       #   @return [Boolean] +true+ if the given +kind+ exists, +false+ otherwise
       def has_kind?(kind, locale=nil)
-        if kind.to_s[0..0] == NAMED_MARKER
+        if kind.to_s[0..0] == Markers::PATTERN
           return strict.has_kind?(kind.to_s[1..-1], locale)
         end
         super
@@ -235,7 +242,7 @@ module I18n
       #     there is no default token
       def default_token(kind, locale=nil)
         return nil if (kind.nil? || kind.to_s.empty?)
-        if kind.to_s[0..0] == NAMED_MARKER
+        if kind.to_s[0..0] == Markers::PATTERN
           return strict.default_token(kind.to_s[1..-1], locale)
         end
         super
@@ -278,7 +285,7 @@ module I18n
         unless kind.nil?
           kind = kind.to_s
           reutrn false if kind.empty?
-          if kind[0..0] == NAMED_MARKER
+          if kind[0..0] == Markers::PATTERN
             return strict.has_alias?(token, kind[1..-1], locale)
           end
           kind = kind.to_sym
@@ -324,7 +331,7 @@ module I18n
         unless kind.nil?
           kind = kind.to_s
           return false if kind.empty?
-          if kind[0..0] == NAMED_MARKER
+          if kind[0..0] == Markers::PATTERN
             return strict.has_true_token?(token, kind[1..-1], locale)
           end
           kind = kind.to_sym
@@ -370,7 +377,7 @@ module I18n
          unless kind.nil?
            kind = kind.to_s
            return false if kind.empty?
-           if kind[0..0] == NAMED_MARKER
+           if kind[0..0] == Markers::PATTERN
              return strict.has_token?(token, kind[1..-1], locale)
            end
            kind = kind.to_sym
@@ -420,7 +427,7 @@ module I18n
         unless kind.nil?
           kind = kind.to_s
           return nil if kind.empty?
-          if kind[0..0] == NAMED_MARKER
+          if kind[0..0] == Markers::PATTERN
             return strict.true_token(token, kind[1..-1], locale)
           end
           kind = kind.to_sym
@@ -465,7 +472,7 @@ module I18n
         unless kind.nil?
           kind = kind.to_s
           return nil if kind.empty?
-          if kind[0..0] == NAMED_MARKER
+          if kind[0..0] == Markers::PATTERN
             return strict.kind(token, kind[1..-1], locale)
           end
           kind = kind.to_sym
@@ -507,7 +514,7 @@ module I18n
         unless kind.nil?
           kind = kind.to_s
           return {} if kind.empty?
-          if kind[0..0] == NAMED_MARKER
+          if kind[0..0] == Markers::PATTERN
             return strict.tokens(kind[1..-1], locale)
           end
           kind = kind.to_sym
@@ -548,7 +555,7 @@ module I18n
         unless kind.nil?
           kind = kind.to_s
           return {} if kind.empty?
-          if kind[0..0] == NAMED_MARKER
+          if kind[0..0] == Markers::PATTERN
             return strict.tokens_raw(kind[1..-1], locale)
           end
           kind = kind.to_sym
@@ -586,7 +593,7 @@ module I18n
         unless kind.nil?
           kind = kind.to_s
           return {} if kind.empty?
-          if kind[0..0] == NAMED_MARKER
+          if kind[0..0] == Markers::PATTERN
             return strict.tokens_true(kind[1..-1], locale)
           end
           kind = kind.to_sym
@@ -620,7 +627,7 @@ module I18n
         unless kind.nil?
           kind = kind.to_s
           return nil if kind.empty?
-          if kind[0..0] == NAMED_MARKER
+          if kind[0..0] == Markers::PATTERN
             return strict.aliases(kind[1..-1], locale)
           end
           kind = kind.to_sym
@@ -672,7 +679,7 @@ module I18n
         unless kind.nil?
           kind = kind.to_s
           return nil if kind.empty?
-          if kind[0..0] == NAMED_MARKER
+          if kind[0..0] == Markers::PATTERN
             return strict.token_description(token, kind[1..-1], locale)
           end
           kind = kind.to_sym
@@ -680,225 +687,6 @@ module I18n
         data_safe(locale).get_description(token.to_sym, kind)
       end
 
-      # Interpolates inflection values in the given +string+
-      # using kinds given in +options+ and a matching tokens.
-      # 
-      # @param [String] string the translation string
-      #  containing patterns to interpolate
-      # @param [String,Symbol] locale the locale identifier 
-      # @param [Hash] options the options
-      # @option options [Boolean] :inflector_excluded_defaults (false) local switch
-      #   that overrides global setting (see: {I18n::Inflector::InflectionOptions#excluded_defaults})
-      # @option options [Boolean] :inflector_unknown_defaults (true) local switch
-      #   that overrides global setting (see: {I18n::Inflector::InflectionOptions#unknown_defaults})
-      # @option options [Boolean] :inflector_raises (false) local switch
-      #   that overrides global setting (see: {I18n::Inflector::InflectionOptions#raises})
-      # @option options [Boolean] :inflector_aliased_patterns (false) local switch
-      #   that overrides global setting (see: {I18n::Inflector::InflectionOptions#aliased_patterns})
-      # @return [String] the string with interpolated patterns
-      def interpolate(string, locale, options = {})
-        used_kinds        = options.except(*INFLECTOR_RESERVED_KEYS)
-        sw, op            = @options, options
-        raises            = (s=op.delete :inflector_raises).nil?            ? sw.raises            : s
-        aliased_patterns  = (s=op.delete :inflector_aliased_patterns).nil?  ? sw.aliased_patterns  : s
-        unknown_defaults  = (s=op.delete :inflector_unknown_defaults).nil?  ? sw.unknown_defaults  : s
-        excluded_defaults = (s=op.delete :inflector_excluded_defaults).nil? ? sw.excluded_defaults : s
-
-        idb               = @idb[locale]
-        idb_strict        = @idb_strict[locale]
-
-        string.gsub(PATTERN) do
-          pattern_fix     = $1
-          strict_kind     = $2
-          pattern_content = $3
-          ext_pattern     = $&
-          ext_value       = nil
-          ext_freetext    = ''
-          found           = false
-          parsed_default_v= nil
-
-          # leave escaped pattern as-is
-          unless pattern_fix.empty?
-            ext_pattern = ext_pattern[1..-1]
-            next ext_pattern if ESCAPES[pattern_fix]
-          end
-
-          # set parsed kind if strict kind is given (named pattern is parsed) 
-          if strict_kind.empty?
-            parsed_symbol = nil
-            strict_kind   = nil
-            parsed_kind   = nil
-            default_token = nil
-            subdb         = idb
-          else
-            parsed_symbol = (NAMED_MARKER + strict_kind).to_sym
-            strict_kind   = strict_kind.to_sym
-            parsed_kind   = strict_kind
-            subdb         = idb_strict
-            default_token = subdb.get_default_token(parsed_kind)
-          end
-
-          # process pattern content's
-          pattern_content.scan(TOKENS) do
-            ext_token     = $1.to_s
-            ext_value     = $2.to_s
-            ext_freetext  = $3.to_s
-            tokens        = Hash.new(false)
-            negatives     = Hash.new(false)
-            kind          = nil
-            option        = nil
-
-            # token not found?
-            if ext_token.empty?
-              # free text not found too? that should never happend.
-              if ext_freetext.empty?
-                raise I18n::InvalidInflectionToken.new(ext_pattern, ext_token) if raises
-              end
-              next
-            end
-
-            # split tokens if comma is present and put into fast list
-            ext_token.split(OPERATOR_MULTI).each do |t|
-              # token name corrupted
-              if t.empty?
-                raise I18n::InvalidInflectionToken.new(ext_pattern, t) if raises
-                next
-              end
-
-              # mark negative-matching tokens and put them to negatives fast list
-              if t[0..0] == OPERATOR_NOT
-                t = t[1..-1]
-                if t.empty?
-                  raise I18n::InvalidInflectionToken.new(ext_pattern, t) if raises
-                  next
-                end
-                t = t.to_sym
-                t = subdb.get_true_token(t, strict_kind) if aliased_patterns
-                negatives[t] = true
-              end
-
-              t = t.to_sym
-              t = subdb.get_true_token(t, strict_kind) if aliased_patterns
-
-              # get kind for that token
-              kind  = subdb.get_kind(t, strict_kind)
-              if kind.nil?
-                raise I18n::InvalidInflectionToken.new(ext_pattern, t) if raises
-                next
-              end
-
-              # set processed kind after matching first token in a pattern
-              if parsed_kind.nil?
-                parsed_kind   = kind
-                parsed_symbol = kind.to_sym
-                default_token = subdb.get_default_token(parsed_kind)
-              elsif parsed_kind != kind
-                # tokens of different kinds in one regular (not named) pattern are prohibited
-                if raises
-                  raise I18n::MisplacedInflectionToken.new(ext_pattern, t, parsed_symbol)
-                end
-                next
-              end
-
-              # use that token
-              tokens[t] = true unless negatives[t]
-            end
-
-            # self-explanatory
-            if (tokens.empty? && negatives.empty?)
-              raise I18n::InvalidInflectionToken.new(ext_pattern, ext_token) if raises
-            end
-
-            # try @-style option for strict kind, fallback to regular if not found
-            # and memorize option name for error reporting
-            oname = !strict_kind.nil? && options.has_key?(parsed_symbol) ?
-                    parsed_symbol : (options.has_key?(kind) ? kind : nil)
-
-            # Get option if possible and memorize for error reporting;
-            # fallback to default token if option still not found
-            if oname.nil?
-              option      = default_token
-              orig_option = nil
-            else
-              option      = options[oname]
-              orig_option = option
-            end
-
-            if (option.nil? || option.to_s.empty?)
-              # if option is given but is unknown, empty or nil
-              # then use default option for a kind if unknown_defaults is switched on
-              option = unknown_defaults ? default_token : nil
-            else
-              # validate option and if it's unknown try in aliases
-              option = subdb.get_true_token(option.to_sym, strict_kind)
-
-              # if still nothing then fall back to default value
-              # for a kind if unknown_defaults switch is on
-              if option.nil?
-                option = unknown_defaults ? default_token : nil
-              end
-            end
-
-            # if the option is still unknown or bad
-            # raise an exception
-            if option.nil?
-              if raises
-                if oname.nil?
-                  ex          = InflectionOptionNotFound
-                  oname       = parsed_symbol
-                  orig_option = nil
-                else
-                  ex          = InflectionOptionIncorrect
-                end
-                raise ex.new(ext_pattern, oname, ext_token, orig_option)
-              end
-              next
-            end
-
-            # memorize default value for further processing
-            # outside this block if excluded_defaults switch is on
-            parsed_default_v = ext_value if (excluded_defaults && !default_token.nil?)
-
-            # throw the value if the given option matches one of the tokens from group
-            # or negatively matches one of the negated tokens
-            case negatives.count
-            when 0 then next unless tokens[option]
-            when 1 then next if  negatives[option]
-            end
-
-            # skip further evaluation of the pattern
-            # since the right token has been found
-            found = true
-            break
-
-          end # single token (or a group) processing
-
-          result = nil
-
-          # return value of a token that matches option's value
-          # given for a kind or try to return a free text
-          # if it's present
-          if found
-            result = ext_value
-          elsif (excluded_defaults && !parsed_kind.nil?)
-            # if there is excluded_defaults switch turned on
-            # and a correct token was found in an inflection option but
-            # has not been found in a pattern then interpolate
-            # the pattern with a value picked for the default
-            # token for that kind if a default token was present
-            # in a pattern
-            kind    = nil
-            token   = options[parsed_kind]
-            kind    = subdb.get_kind(token)
-            result  = parsed_default_v unless kind.nil?
-          end
-
-          pattern_fix + (result || ext_freetext)
-
-        end # single pattern processing
-
-      end
-
       protected
 
       # @private
@@ -947,9 +735,9 @@ module I18n
       def tkl_args(args)
         token, kind, locale = case args.count
         when 1 then [args[0], nil, nil]
-        when 2 then args[1].to_s[0..0] == NAMED_MARKER ? [args[0], args[1], nil] : [args[0], nil, args[1]]
+        when 2 then args[1].to_s[0..0] == Markers::PATTERN ? [args[0], args[1], nil] : [args[0], nil, args[1]]
         when 3 then args
-        else raise ArgumentError.new("wrong number of arguments: #{args.count} for (1..3)")
+        else raise I18n::ArgumentError.new("wrong number of arguments: #{args.count} for (1..3)")
         end
         [token,kind,locale]
       end

data/lib/i18n-inflector/api_strict.rb

@@ -491,7 +491,7 @@ module I18n
         when 1 then [args[0], nil, nil]
         when 2 then [args[0], args[1], nil]
         when 3 then args
-        else raise ArgumentError.new("wrong number of arguments: #{args.count} for (1..3)")
+        else raise I18n::ArgumentError.new("wrong number of arguments: #{args.count} for (1..3)")
         end
         token = token.nil? || token.to_s.empty? ? nil : token.to_sym
         kind  = kind.nil?  || kind.to_s.empty?  ? nil : kind.to_sym