i18n-inflector 2.0.1 → 2.1.0

data/docs/EXAMPLES

@@ -0,0 +1,222 @@
+
+== Configuring inflections
+
+This data will be used in any further example:
+
+=== YAML
+
+  en:
+    i18n:
+      inflections:
+        
+        @person:
+          i:          "i"
+          you:        "you"
+          he:         "he"
+          she:        "she"
+          it:         "it"
+          u:          @you
+        
+        gender:
+          m:          "male"
+          f:          "female"
+          n:          "neuter"
+          default:    neuter
+        
+      
+    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}"
+    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} @person{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)
+  #=> []
+  
+<i>to be continued…</i>
+
+== 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ł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
+  
+  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}?")

data/docs/HISTORY

@@ -1,3 +1,34 @@
+=== 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

data/docs/LEGAL

@@ -8,4 +8,3 @@ i18n-inflector is copyrighted software owned by Paweł Wilk
 software as long as you comply with either the terms of the LGPL
 (see the file {file:LGPL}),
 or Ruby's license (see the file {file:COPYING}).
-

data/docs/RELATIONS

@@ -1,25 +1,28 @@
 == This library contains
 
 * Module {I18n::Inflector} containing everything
-* Class {I18n::Inflector::Core} used to create inflector object attached to I18n backend
-* Class {I18n::Inflector::InflectionData} used by {I18n::Inflector::Core} instances to store
-  inflection data and manipulate them, also is used by {I18n::Backend::Inflector} instances when loading
-  translations to create new database within {I18n::Inflector::Core} instance attachend to backend
-* Class {I18n::Inflector::InflectionOptions} is used inside of {I18n::Inflector::Core} for keeping
-  switches and options 
+* Class {I18n::Inflector::API} used to create inflector object attached to I18n backend (handles regular and strict kinds)
+* Class {I18n::Inflector::API_Strict} which instance is attached to {I18n::Inflector::API} and handles strict kinds
+* Class {I18n::Inflector::InflectionData} used to store inflection data for regular kinds and tokens
+* Class {I18n::Inflector::InflectionData_Strict} used to store inflection data for strict kinds and tokens
+* Class {I18n::Inflector::InflectionOptions} used for keeping switches and options 
+* Class {I18n::Inflector::LazyHashEnumerator} used to manage lazy evaluation of internal data
 * Module {I18n::Backend::Inflector} used to alter methods of {I18n::Backend::Simple}
+* Several classes for error reporting
 
 == Relations
 
 * {I18n.backend} is the currently used backend and the instance of {I18n::Backend::Simple}
-* {I18n.backend.inflector} is the instance of {I18n::Inflector::Core} attached to backend
+* {I18n.backend.inflector} is the instance of {I18n::Inflector::API} attached to backend
 * {I18n.inflector} is the proxy module method that calls inflector for currently used backend {I18n.backend.inflector}
 * {I18n.backend.inflector.options} is the instance of {I18n::Inflector::InflectionOptions} and
   mainly it controls a behavior of interpolation method
-* {I18n::Inflector::Core} has an instance variable defined that contains database of translation data
-* Each entry in the internal database of {I18n::Inflector::Core} is indexed by locale and is kind of 
-  {I18n::Inflector::InflectionData}
+* {I18n.backend.inflector.strict} is the instance of {I18n::Inflector::API_Strict} and handles strict kinds
+* {I18n.backend.inflector} uses {I18n.backend.inflector.strict} to access strict kinds when it's needed
+* {I18n::Inflector::API} has an instance variable @idb that contains database of inflections indexed by locale
+* {I18n::Inflector::API_Strict} has an instance variable @idb that contains database of inflections indexed by locale
+* Translation databases are kind of {I18n::Inflector::InflectionData} and {I18n::Inflector::InflectionData_Strict}
 * When initializing translations a method from {I18n::Backend::Simple} (altered by {I18n::Backend::Inflector})
-  takes the loaded data, processes the +i18n.inflections+ part for each locale and creates configuration
-  that is keeped as an instance of {I18n::Inflector::InflectionData}. That data is registered within the
-  inflecor object attached to backend that loaded the translations.
+  takes the loaded data, processes their <tt>i18n.inflections</tt> scope for each locale and creates database
+  objects which are kind of {I18n::Inflector::InflectionData} and {I18n::Inflector::InflectionData_Strict}. That
+  objects are then attached to instances of {I18n::Inflector::API} and {I18n::Inflector::API_Strict}.

data/docs/TODO

@@ -1,9 +1,31 @@
 == Near future
 
-* add some negative tests (e.g. empty kind, kinds as nils or empty striongs, tokens as empty strings...)
+* 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
 
-* named patterns: @gender{m:xx|f:xxx|n:xzc} - such pattern may allow multiple tokens but it breaks the logic unless some marker will be given in configuration like !gender: that would inform engine that exact kind must be present in a pattern
+* 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 (?)
 
-* use tilde symbols (~) to allow multiple negative matches. the values will be joined as they are interpolated (with other negative matches or a positive; it just means that the processing won't stop on some particular token) – is this good idea anyway?
+* 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