i18n-inflector-3 3.0.0

data/docs/EXAMPLES

@@ -0,0 +1,357 @@
+
+== Configuring inflections
+
+This data will be used in any further example:
+
+=== YAML
+
+  en:
+    i18n:
+      inflections:
+        
+        @person:
+          i:          "i"
+          u:          "you"
+          he:         "he"
+          she:        "she"
+          it:         "it"
+          you:        @u
+        
+        gender:
+          m:          "male"
+          f:          "female"
+          n:          "neuter"
+          default:    n
+        
+      
+    welcome: "Dear @{f:Lady|m:Sir|n:You|All}!"  
+    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}"
+  
+
+=== Code
+
+  I18n.backend.store_translations(:en, :i18n => { :inflections => {
+    :gender => {
+      :m          => 'male',
+      :f          => 'female',
+      :n          => 'neuter',
+      :default    => :n
+      },
+    :@person => {
+      :i          => 'i',
+      :u          => 'you',
+      :he         => 'he',
+      :she        => 'she',
+      :it         => 'it',
+      :you        => :@u
+      }
+  }})
+  
+  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}{ }{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
+
+== Simple interpolation
+
+When no option, it falls back to default token (n):
+
+  I18n.translate('welcome')
+  #=> "Dear You!"
+
+When :m, it interpolates the m token's value:
+
+  I18n.translate('welcome', :gender => :m)
+  #=> "Dear Sir!"
+
+When unknown, it falls back to default token (n):
+
+  I18n.translate('welcome', :gender => :unknown)
+  #=> "Dear You!"
+
+When +nil+, it falls back to default token (n):
+
+  I18n.translate('welcome', :gender => nil)
+  #=> "Dear You!"
+
+=== <tt>inflector_unknown_defaults</tt>
+
+When <tt>:inflector_unknown_defaults</tt> is false, it falls back to free text:
+
+  I18n.translate('welcome', :gender => :unknown, :inflector_unknown_defaults => false)
+  #=> "Dear All!"
+
+It also falls back when an inflection option is nil or empty:
+
+  I18n.translate('welcome', :gender => nil, :inflector_unknown_defaults => false)
+  #=> "Dear All!"
+
+== Named pattern
+
+Regular inflection option will be used if there is no strict inflection option:
+
+  I18n.translate('sayit', :person => :i)
+  #=> "I am"
+
+Strict inflection option has precedence:
+
+  I18n.translate('sayit', :person => :i, :@person => :u)
+  #=> "You are"
+
+
+Strict inflection option has precedence even if the option's value is messy:
+ 
+  I18n.translate('sayit', :person => :i, :@person => :unknown)
+  #=> " "
+  
+=== Using with interpolation argument
+
+First part is interpolated using standard interpolation variable while
+second part of the sentence comes from interpolation of inflection pattern.
+The same option is feeding both engines.
+
+  I18n.translate('tobe', :person => :i)
+  #=> "i am"
+
+Note funny thing. The interpolation variable +test+ takes value (+i+) from
++:person+ while option +:@person+ takes precedence when it comes to inflections.
+Keep that in mind when combining regular interpolation variables with named patterns
+while using the same variable for controlling both. Choose non-strict notation
+for an option then.
+
+  I18n.translate('tobe', :person => :i, :@person => :u)
+  #=> "i are"
+
+No free text in 'tobe' so the empty string is interpolated when strict kind is unknown:
+
+  I18n.translate('tobe', :person => :i, :@person => :unknown)
+  #=> "i "
+
+== API
+
+=== Getting kinds
+
+Getting all known regular kinds:
+
+  I18n.inflector.kinds
+  #=> [:gender]
+
+Getting all known strict kinds:
+
+  I18n.inflector.strict.kinds
+  #=> [:person]
+
+Getting all known kinds for language 'pl':
+
+  I18n.inflector.kinds(:pl)
+  #=> []
+
+=== 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
+
+Polish is highly inflected language. Additionally, position of a word in
+a sentence is mutually coupled with meaning. That makes it extreemly
+hard to create finite-state machine that would handle Polish grammar.
+However, flection means that the same cores are combined with suffixes
+and prefixes depending on many different kinds: gender, tense, form,
+animation, declination and more. That makes Polish (and other Slavic
+languages) alphabetically redundant. By interpolating common cores,
+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}?"
+    
+    i18n:
+      inflections:
+        gender:
+          f:          "rodzaj żeński"
+          m:          "rodzaj męski"
+          n:          "forma bezosobowa"
+          masculine:  @m
+          facet:      @m
+          chłopak:    @m
+          feminine:   @f
+          pani:       @f
+          kobieta:    @f
+          k:          @f
+          dziewczyna: @f
+          impersonal: @n
+          default:    n
+
+=== Code
+
+  # 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 }}})
+  
+  # Making use of commas makes it easy to implement DRY
+  # and re-use some parts of the words that are the same in two or more phrases
+  
+  I18n.backend.store_translations(:pl, :are_you_sure => "@{m,f:Jesteś pew}@{m:ien|f:na}@{n:Na pewno}?")
+    
+  I18n.locale = :pl
+  
+  I18n.translate('are_you_sure', :gender => :kobieta)
+  #=> "Jesteś pewna?"
+    
+  I18n.translate('are_you_sure', :gender => :facet)
+  #=> "Jesteś pewien?"  
+  
+  I18n.translate('are_you_sure')
+  #=> "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}?")
+
+  # 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}?")
+
+=== 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}{*+t:jesz|*+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}{*+t:jesz|*+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.
+
+== To be or not to be
+
+Here is the example pattern that inflects English <i>to be</i> by tense,
+person and grammatical number:
+
+  en:
+    i18n:
+        inflections:
+          @person:
+              1: first
+              2: second
+              3: third
+              i:    :@1
+              you:  :@2
+              He:   :@3
+              She:  :@3
+              it:   :@3
+          @tense:
+            past:      past
+            present:   present
+            now:       @present
+            default:   present
+          @num:
+            s: singular
+            p: plural
+            default: s
+    
+    to_be: >
+            @num+person{s+1:I|*+2:You|s+3:%{person}|p+3:They|p+1:We}
+            @num+person+tense{s+1+present:am|s+2+present:are|s+3+present:is|
+            p+*+present:are|s+1,3+past:was|p+*+past:were|s+2+past:were}
+
+And the code that prints all possible combinations:
+
+  [:i, :you, :He, :She, :It].each do |person|
+    puts  I18n.translate(:to_be, :num => :s, :person => person, :tense => :now) + "\t| " +
+          I18n.translate(:to_be, :num => :s, :person => person, :tense => :past)
+  end
+  
+  puts
+  
+  (1..3).each do |person|
+    puts  I18n.translate(:to_be, :num => :p, :person => person, :tense => :now) + " | " +
+          I18n.translate(:to_be, :num => :p, :person => person, :tense => :past)
+  end
+
+<i>to be continued…</i>
+

data/docs/HISTORY

@@ -0,0 +1,280 @@
+=== 3.0.0 / 2025-11-30
+
+* major compatibility fixes
+
+  * Ruby 4.0.0-preview2 compatibility: Fixed HSet to use public Set API (include?) instead of internal @hash
+  * Ruby 3.4+ compatibility: Fixed frozen string literal issues
+
+* major enhancements
+
+  * Migrated from Hoe to Bundler build system
+  * Migrated tests from Test::Unit to Minitest
+  * Updated gemspec with modern Ruby requirements (>= 3.4)
+
+=== 2.6.7 / 2013-06-18
+
+* major compatibility fixes
+
+  * Removed deprecation warnings for Ruby 2.0
+
+* minor enhancements
+
+  * Updated gem dependencies
+
+=== 2.6.6 / 2012-03-14
+
+* major enhancements
+
+  * Added support for integers as token names
+  * Added nice example of "to be" inflection in English
+
+* minor enhancements
+
+  * Documentation updated
+  * Added instance method empty? to LazyEnumerator
+
+=== 2.6.5 / 2012-03-10
+
+* minor enhancements
+
+  * Back to Psych YAML parser while creating gem
+
+=== 2.6.4 / 2012-03-10
+
+* minor enhancements
+
+  * Changed documentation examples for calling rake
+  * Tested against Ruby 1.9.3-p0
+  * Updated dependencies
+  * Updated copyright notices
+  * Started codenaming each version (including minor version numbers)
+
+=== 2.6.2 / 2011-08-07
+
+* minor bugfixes
+
+  * Applied a workaround against a buggy parser in Rubygems
+
+=== 2.6.1 / 2011-07-10
+
+* major enhancements
+
+  * Handling of methods and Proc objects used to obtain inflection options improved by caching
+  * Added caching for methods reporting locales that support inflection
+  * Lazy operations optimized
+
+* minor enhancements
+
+  * Fixed documentation links
+  * Dependencies updated
+
+=== 2.6.0 / 2011-03-08
+
+* minor enhancements
+
+  * Strings concatenation optimized
+  * API methods simplified
+  * Added lazy iteration methods to I18n::Inflector::InflectionData and I18n::Inflector::InflectionData_Strict
+  * Added lazy iteration methods to I18n::Inflector::API and I18n::Inflector::API_Strict
+
+=== 2.5.1 / 2011-02-25
+
+* minor enhancements
+
+  * Added the ability to use symbols as descriptions (values) in a configuration
+
+=== 2.5.0 / 2011-02-24
+
+* major enhancements
+
+  * Interpolation wrapper refactored; works with many types of results
+  * Added :inflector_interpolate_symbols switch
+
+* minor enhancements
+
+  * Added TOKENS_RESTR, MULTI_RESTR and PATTERN_RESTR configuration constants
+  * Dependencies updated
+
+* major bugfixes
+
+  * Fixed interpolation of Arrays
+
+* minor bugfixes
+
+  * Fixed pattern filtering when locale is invalid or not inflected
+
+=== 2.4.0 / 2011-02-23
+
+* major enhancements
+
+  * Added nested translations (collections) support
+  * Added :inflector_traverses switch
+
+=== 2.3.1 / 2011-02-14
+
+* major enhancements
+
+  * Added wildcard tokens support
+  * Proc and Method kind of objects might be passed as inflection options
+
+* minor enhancements
+
+  * Added I18n::Inflector::Config::Markers::STRICT_KIND (character used when passing strict kinds)
+  * Important documentation moved to the USAGE file
+
+* minor bugfixes
+
+  * Fixed parsing of named patterns when :inflector_excluded_defaults is used
+  * Fixed links in documentation
+
+=== 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
+
+  * Added named patterns support (strict kinds)
+  * API improved: major class is I18n::Inflector::API
+  * Added class I18n::Inflector::API_Strict for accessing strict inflections
+  * Added lazy enumerators for internal hashes, which saves some memory
+  * Added strict kinds detection (@-style kind names) to most of the methods from main API class
+  * Added new error classes: InflectionOptionNotFound and InflectionOptionIncorrect
+  * Added class for handling inflection data for strict kinds: I18n::Inflector::InflectionData_Strict
+  * Inflections for regular and strict kinds are handled by separate data structures and objects
+  * Documentation updated
+
+* minor bugfixes
+
+  * Error reporting fixed in some places
+  * Strict kinds interpolation improved
+  * Removed some slow blocks
+  * Loading inflection tokens cleaned up
+
+=== 2.0.1 / 2011-01-15
+
+* minor enhancements
+
+  * Documentation updated
+
+* minor bugfixes
+
+  * Fixed duplicated dependency generation in Hoe
+
+=== 2.0.0 / 2011-01-14
+
+* major enhancements
+
+  * API changed
+  * Added a class for keeping internal inflection data: I18n::Inflector::InflectionData
+  * Added a class for keeping options: I18n::Inflector::InflectionOptions
+  * Added a class for controlling the inflection: I18n::Inflector::Core
+  * Added a module for utilities: I18n::Inflector::Util
+  * Added token groups support
+  * Added inversed matching of tokens in inflection patterns
+  * Added support for aliases in inflection patterns
+  * Most of the methods from I18n::Backend::Inflector moved to Core submodule
+  * Most methods rewritten
+
+=== 1.0.10 / 2011-01-10
+
+* major bugfixes
+
+  * Removed cause of infinite loops while initializing translations
+  * Disabled lookup from being used before translations are initialized
+  * Fixed initialization routine (dangerous typo when setting booleans)
+
+* minor enhancements
+
+  * Switched to lazy loading of inflection data for certain locales
+
+=== 1.0.8 / 2011-01-08
+
+* major enhancements
+
+  * Enabled escaping of patterns using @@{pattern} or \@{pattern}
+
+=== 1.0.7 / 2011-01-07
+
+* major bugfixes
+
+  * Fixed interpolation when a translated string begins with a pattern
+
+=== 1.0.6 / 2010-12-30
+
+* minor enhancements
+
+  * Added API method inflection_kind(token)
+  * Added API method inflection_true_token(token)
+  * Added API method inflected_locale(locale)
+
+=== 1.0.5 / 2010-12-29
+
+* major enhancements
+
+  * Compatible with i18n >= 0.4.1
+
+=== 1.0.4 / 2010-12-27
+
+* minor enhancements
+
+  * Documentation updated
+
+=== 1.0.3 / 2010-12-25
+
+* major enhancements
+
+  * YARD documentation updated with metatags
+
+* minor enhancements
+
+  * Some changes in accessors for interpolation switches
+
+=== 1.0.2 / 2010-12-22
+
+* minor enhancements
+
+  * Switched to YARD documentation
+  * Tests simplified
+  * Depandencies simplified
+
+=== 1.0.0 / 2010-12-22
+
+* 1 major enhancement
+
+  * Birthday!
+

data/docs/LEGAL

@@ -0,0 +1,10 @@
+LEGAL NOTICE INFORMATION
+------------------------
+
+i18n-inflector is Copyright (C) 2011,2012 by Paweł Wilk.
+
+i18n-inflector is copyrighted software owned by Paweł Wilk
+(pw@gnu.org). You may redistribute and/or modify this
+software as long as you comply with either the terms of the LGPL
+(see the file {file:docs/LGPL}),
+or Ruby's license (see the file {file:docs/COPYING}).