i18n-inflector-3 3.0.0

data/docs/USAGE

@@ -0,0 +1,967 @@
+= Usage of the I18n Inflector
+
+The {I18n::Inflector I18n Inflector} contains inflection classes
+and modules for enabling the inflection support in I18n translations.
+It is also used by the module called {I18n::Backend::Inflector}
+that overwrites the translate method from the Simple backend
+so it will interpolate additional inflection data present
+in translations. That data may appear in *patterns*
+enclosed within <tt>@{</tt> and <tt>}</tt> symbols. Each pattern
+consist of *tokens* and respective *values*. One of the value will
+be used depending on additional data passed to the translate method.
+That additional data is called <b>inflection options</b>.
+
+== Usage
+  require 'i18-inflector'
+  
+  i18n.translate('welcome', :gender => :f)
+  # => Dear Madam
+  
+  i18n.inflector.kinds
+  # => [:gender]
+
+  i18n.inflector.true_tokens.keys
+  # => [:f, :m, :n]
+
+See the {file:docs/EXAMPLES} for more information about real-life
+usage of Inflector.
+
+== Inflection pattern
+An example inflection pattern stored under a translation key looks like:
+  welcome: "Dear @{f:Madam|m:Sir|n:You|All}"
+
+The +f+, +m+ and +n+ are inflection *tokens* and +Madam+, +Sir+, +You+ and
++All+ are *values*. Only one value is going to replace the whole
+pattern. To select which one an additional option is used. That option
+must be passed to the translate method.
+
+There are also so called <b>named patterns</b> that will be explained
+later.
+
+== Configuration
+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:
+      inflections:
+        gender:
+          f:      "female"
+          m:      "male"
+          n:      "neuter"
+          man:    @m
+          woman:  @f
+          default: n
+
+Elements in the example above are:
+* +en+: language
+* +i18n+: configuration scope
+* +inflections+: inflections configuration scope
+* +gender+: kind scope
+* +f+, +m+, +n+: inflection tokens
+* <tt>"male"</tt>, <tt>"female"</tt>, <tt>"neuter"</tt>: tokens' descriptions
+* +woman+, +man+: inflection aliases
+* <tt>@f</tt>, <tt>@m</tt>: pointers to real tokens 
+* +default+: default token for a kind +gender+
+
+=== Note about YAML parsing
+
+The example above is not compatible with Psych parser, which is used
+by Rails 3. There are two ways to solve that problem.
+
+First is to make a change in a YAML file and replace any value that has
+special meaning with a symbol:
+
+  en:
+    i18n:
+      inflections:
+        gender:
+          f:        "female"
+          m:        "male"
+          n:        "neuter"
+          female:   :@f
+          male:     :@m
+          default:  :n
+  
+Second way is to use other parser by adding to +config/boot.rb+:
+
+  require 'yaml'
+  YAML::ENGINE.yamler = 'syck'
+
+Note that all the examples in this documentation use the less strict format.
+If you will encounter any parsing problems in your application then change
+all problematic inflection values in YAML files into symbols.
+
+=== Kind
+Note the fourth scope selector in the example above (+gender+). It's called
+the *kind* and contains *tokens*. We have the kind
++gender+ to which the inflection tokens +f+, +m+ and +n+ are
+assigned.
+
+You cannot assign the same token to more than one kind.
+Trying to do that will raise {I18n::DuplicatedInflectionToken} exception.
+This is required in order to keep patterns simple and tokens interpolation
+fast.
+
+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. Any pattern may have many tokens
+of the same kind separated by vertical bars. Optionally tokens might
+be groupped using commas (these are token groups; that will be explained
+later). Each token name (or a group of tokens) 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. By default they
+cannot appear in inflection patterns but they are fully recognized
+in options that are be passed to the translation method.
+
+Aliases might be helpful in multilingual applications that are using
+a fixed set of values passed through options to describe some properties
+of messages, e.g. +masculine+ and +feminine+ for a grammatical gender.
+Translators will then use their own tokens (like +f+ and +m+ for English)
+to produce pretty and intuitive patterns.
+
+For example: if some application uses database with gender assigned
+to a user which may be +male+, +female+ or +none+, then a translator
+may find it useful to map impersonal token (<tt>none</tt>)
+to the +neuter+ token, since in translations for his language the
+neuter gender is in use.
+
+Here is the example of such situation:
+
+  en:
+    i18n:
+      inflections:
+        gender:
+          male:     "male"
+          female:   "female"
+          none:     "impersonal form"
+          default:  none 
+  
+  pl:
+    i18n:
+      inflections:
+        gender:
+          k:        "female"
+          m:        "male"
+          n:        "neuter"
+          male:     @k
+          female:   @m
+          none:     @n
+          default:  none
+
+In the case above Polish translator decided to use neuter
+instead of impersonal form when +none+ token will be passed
+through the option +:gender+ to the translate method. He
+also decided that he will use +k+, +m+ or +n+ in patterns,
+because the names are short and correspond to gender names in
+Polish language: +k+ for 'kobieta' (woman), +m+ for 'mężczyzna' (man),
++n+ for 'nijaki' (neuter).
+
+Aliases may point to other aliases. While loading inflections they
+will be internally shortened and they will always point to real tokens,
+not other aliases.
+
+=== Default token
+There is a special token called the +default+, which points
+to a token that should be used if the interpolation routine cannot deduce
+which one it should use because a proper option was not given.
+
+Default tokens may point to aliases and may use aliases' syntax, e.g.:
+  default: @man
+
+=== Descriptions
+The values of keys in the example (+female+, +male+ and +neuter+)
+are *descriptions* which usually are not used by the interpolation routine
+but might be helpful (e.g. in UI). For obvious reasons you cannot
+describe aliases.
+
+== 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 a token name from that
+pattern matches the given value of an option passed to the {I18n.translate} method.
+
+=== Inflection option
+The mentioned option is called the <b>inflection option</b>. Its name should be
+the same as a *kind* of tokens used within a pattern. The first token in a pattern
+determines the kind of all tokens used in that pattern. You can pass
+many inflection options, each one designated for transporting a token of a
+different kind.
+
+==== Examples
+
+*YAML:*
+
+Let's assume that the translation data in YAML format listed
+below is used in any later example, unless other inflections
+are given.
+  en:
+    i18n:
+      inflections:
+        gender:
+          m:       "male"
+          f:       "female"
+          n:       "neuter"
+          default: n
+  
+    welcome:  "Dear @{f:Madam|m:Sir|n:You|All}"
+
+*Code:*
+
+  I18n.translate('welcome', :gender => :m)
+  # => "Dear Sir"
+  
+  I18n.translate('welcome', :gender => :unknown)
+  # => "Dear All"
+  
+  I18n.translate('welcome')
+  # => "Dear You"
+
+In the second example the <b>fallback value</b> +All+ was interpolated
+because the routine had been unable to find the token called +:unknown+.
+That differs from the latest example, in which there was no option given,
+so the default token for a kind had been applied (in this case +n+).
+
+==== Inflection options as Methods or Procs
+The inflection option may contain an object that is a kind of Method or
+a Proc. The token will be obtained by calling the given method or a block when
+interpolation routine will need it.
+
+The passed method or a block should return an object that is a kind of
+Symbol. It will be used as an inflection token.
+
+Optionally the inflection method may make use of a block that is passed
+to it. Currently two parameters can be obtained using the keyword +yield+.
+Fist is the currenty parsed kind (including +@+ character in case of
+a strict kind) and second is the locale; both are the kind of Symbol. Example:
+
+  def get_gender
+    kind, locale = yield  # optional
+    :n                    # return token n
+  end
+  
+  translate('welcome', :gender => method(:get_gender))
+  
+In case of Proc, the arguments are passed in a more comprehensive way,
+as parameters passed to a block. Such a block must handle exactly
+two arguments:
+
+  p = lambda{ |kind, locale| :m }
+  translate('welcome', :gender => p)
+
+Note that if there will be any error that causes exception to be
+raised by such a method or a block then it will be raised regardless
+of +:inflector_raises+ option.
+
+=== Local fallbacks (free text)
+The fallback value will be used when none of the tokens contained
+within a pattern can be interpolated.
+
+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 the given option contains a proper value for some
+kind but it's just not present in a pattern, for example:
+
+*YAML:*
+
+  en:
+    i18n:
+      inflections:
+        gender:
+          n:    'neuter'
+          o:    'other'
+      
+    welcome:    "Dear @{n:You|All}"
+
+*Code:*
+
+  I18n.translate('welcome', :gender => :o, :inflector_raises => true)
+  # => "Dear All"
+  # since the token :o was configured but not used in the pattern
+
+=== Bad 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
+token is present in a pattern. The same thing will happend if the option
+is present but its value is malformed, unknown, empty or +nil+.
+If the default token is not present in a pattern or is not defined in
+a configuration data then the processing of a pattern will result
+in an empty string or in a local fallback value if there is
+a free text placed in a pattern.
+
+You can change this default behavior and force inflector
+not to use a default token when a value of an option for
+a kind is malformed, unknown, empty or +nil+ but only when
+it's not present. To do that you should set option +:inflector_unknown_defaults+
+to +false+ and pass it to the translate method. Other way is to set this
+switch globally using the {I18n::Inflector::InflectionOptions#unknown_defaults}.
+
+=== Unmatched tokens in options
+It might happend that there will be a default token present in a pattern
+but the given inflection option will cause some other token to be picked up,
+which however won't be present in this pattern (although it will be
+correct and assigned to the currently processed kind). In such
+case the given free text or an empty string will be generated.
+You may change that behavior by passing +:inflector_excluded_defaults+
+option set to +true+ or by setting the global option called
+{I18n::Inflector::InflectionOptions#excluded_defaults}. If this
+option is set then any unmatched (excluded but correct) token
+given in an inflection option will cause the default token's value
+to be picked up (of course if a default token will be present
+in a pattern).
+
+=== Mixing inflection and standard interpolation patterns
+The Inflector allows you to include standard <tt>%{}</tt>
+patterns inside of inflection patterns. The value of a standard
+interpolation variable will be evaluated and interpolated *before*
+processing an inflection pattern. For example:
+
+*YAML:*
+
+Note: <em>Uses inflection configuration given in the first example.</em> 
+  en:
+    hi:   "Dear @{f:Lady|m:%{test}}!"
+
+*Code:*
+  I18n.t('hi', :gender => :m, :locale => :xx, :test => "Dude")
+  # => Dear Dude!
+
+=== Token groups
+It is possible to assign some value to more than one token in a patterns.
+You can create group of tokens by separating them using commas.
+The comma has the meaning of logical OR.
+
+*YAML:*
+
+Note: <em>Uses inflection configuration given in the first example.</em> 
+  en:
+    welcome:  "Hello @{m,f:Ladies and Gentlemen|n:You}!"
+
+*Code:*
+  I18n.t('welcome', :gender => :f)
+  # => Hello Ladies and Gentlemen!
+
+=== Inversed matching of tokens
+You can place exclamation mark before a token that should be
+matched negatively. Its value will be used for a pattern
+<b>if the given inflection option contains other token</b>.
+You can use inversed matching of tokens in token groups but
+note that putting more than one inversed token to a group
+will cause the expression to mach every time.
+
+*YAML:*
+
+Note: <em>Uses inflection configuration given in the first example.</em> 
+  en:
+    welcome:  "Hello @{!m:Ladies|n:You}!"
+
+*Code:*
+
+  I18n.t('welcome', :gender => :n)
+  # => Hello Ladies!
+  
+  I18n.t('welcome', :gender => :f)
+  # => Hello Ladies!
+  
+  I18n.t('welcome', :gender => :m)
+  # => Hello !
+  
+=== Wildcard tokens
+You may use the wildcard character, a star (+*+), in place of token
+group to create a virtual token that matches any token of a parsed kind.
+For example:
+
+*YAML:*
+
+Note: <em>Uses inflection configuration given in the first example.</em> 
+
+  en:
+    welcome:  "Hello @{n:you|*:ladies and gentlemen}!"
+
+*Code:*
+
+  I18n.t('welcome', :gender => :n)
+  # => Hello you!
+  
+  I18n.t('welcome', :gender => :f)
+  # => Hello ladies and gentlemen!
+
+Note that for simple patterns you can use free text instead, which works
+almost the same way with one significant difference: free text will be
+evaluated as the last expression, regardless of its placement.
+On the contrary a wildcard token will be evaluated as any other
+token group and may not be used if any previously tested token
+will match (like +n+ in the example above).
+
+While a wildcard token is processed then the interpolation routine
+will validate if the required inflection option exists and if it contains
+a proper token. Using wildcard token is like using a token group
+for any other token group containing all possible true tokens in it.
+
+In case of regular patterns containing just a wildcard token alone
+there is no way to easily decide which kind the expression
+refers to. To deduce it the first valid inflection option will
+be used. In order to work it must contain some valid token
+identifier. If the token identifier is invalid and there are more
+inflection options then they are tried.
+
+Wildcard tokens are useful in so called complex patterns which
+will be explained later.
+
+=== Loud tokens
+Sometimes there might be a need to use descriptions of
+matching tokens instead of some given values. Use <b>loud tokens</b>
+to achieve that. Any matching token in a pattern that has tilde symbol (+~+)
+set as its value will be replaced by its description. In case of
+undescribed aliases, the description from a target token will be used.
+
+*YAML:*
+
+Note: <em>Uses inflection configuration given in the first example.</em> 
+  en:
+    welcome:  "Hello @{m:~|n:~}!"
+
+*Code:*
+
+  I18n.t('welcome', :gender => :n)
+  # => Hello neuter!
+  
+  I18n.t('welcome', :gender => :f)
+  # => Hello female!
+
+To use tilde symbol as the only value of a token you may esape it
+by putting a backslash in front of the symbol.
+
+Using loud token with wildcard token will result in a description
+of first matching token.
+
+=== Aliases in a pattern
+Normally it is possible to use in  patterns only true tokens, 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 pass corresponding +:inflector_aliased_patterns+ option to the translate
+method.
+
+=== Escaping a pattern
+If there is a need to translate something that accidentally matches
+an inflection pattern then the escape symbols can be used to
+disable the interpolation. These symbols are <tt>\\</tt> and +@+
+and they should be placed just before a pattern that should
+be left untouched. For instance:
+
+*YAML:*
+
+Note: <em>Uses inflection configuration given in the first example.</em> 
+  en:
+    welcome:  "This is the @@{pattern}!"
+
+*Code:*
+
+  I18n.t('welcome', :gender => :m, :locale => :xx)
+  # => This is the @{pattern}!
+
+=== More about applying aliases
+It may seem very easy and attractive to use aliases
+in environments where inflection option's value 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 a user may
+enter a gender in some text field and it will be used as value of inflection
+option. 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 an inflection option (e.g. +:gender+).
+In such scenario you don't have to rely on resolving aliases
+any time translation is performed and you will gain some speed.
+
+== Named patterns
+
+A named pattern is a pattern that contains 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 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+: <b>strict kind</b> 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 tokens of the same strict kind should still
+be unique.) That implies a requirement of passing the
+identifier of a kind in patterns when referring to such tokens.
+
+Here is the example configuration using strict kinds:
+
+  en:
+    i18n:
+      inflections:
+        @gender:
+          f:      "female"
+          m:      "male"
+          n:      "neuter"
+          man:    @m
+          woman:  @f
+          default: n
+        @title:
+          s:      "sir"
+          l:      "lady"
+          u:      "you"
+          m:      @s
+          f:      @l
+          default: u
+
+The only thing that syntactically distinguishes strict kinds
+from regular kinds is a presence of the +@+ symbol.
+
+You can mix regular and strict kinds having the same names in
+one translation entry, but not in one inflection pattern.
+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 inflection options
+The interpolation routine recognizes strict kinds passed as names of
+inflection options in almost the same way that it does 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 the same name but 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 kinds of the same name 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
+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 +:@gender+
+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
+
+== Multiple patterns
+You can make use of some syntactic sugar when having more than
+one pattern (regular or named) in your string. To not repeat
+a kind identifier(s) you may join pattern contents as in the
+following example:
+
+  welcome: "You are @gender{f:pretty|m,n:handsome}{ }{f:lady|m:sir|n:human}"
+
+As you can see there should be no spaces or any other characters
+between successive patterns. That's why in this example an
+empty pattern content is used. This is in fact a pattern
+containing no tokens but just a free text consisting
+of single space character.
+
+== Complex patterns
+A <b>complex pattern</b> is a named pattern that uses more than
+one inflection kind and sets of a respective tokens. The given identifiers
+of kinds should be separated by the plus sign and instead of single
+tokens there should be token sets (a tokens separated by the plus
+sign too).
+
+Example:
+
+  welcome:  "Dear @gender+number{f+s:Lady|f+p:Ladies|m+s:Sir|m+p:Gentlemen|All}"
+
+In the example above the complex pattern uses +gender+ and +number+
+inflection kinds and a token set (e.g. <tt>f+s</tt>) matches when
+both tokens match interpolation options (e.g. <tt>:gender => :f</tt>,
+<tt>:number => :s</tt>). The order of tokens in sets has meaning
+and should reflect the order of declared kinds.
+
+Note, that the count of tokens in each set should reflect the count
+of kinds that are used. Otherwise the interpolation routine will
+interpolate a free text (if given) or an empty string. If the switch
+{InflectionOptions#raises} is on then the {I18n::ComplexPatternMalformed}
+exception will be raised.
+
+The inflection tokens used in sets may make use of any features mentioned
+before (defaults, excluded defaults, negative matching, token groups,
+aliases, aliased patterns, loud tokens, wildcards).
+
+=== Loud tokens in complex patterns
+In case of loud tokens (having values taken from their
+descriptions), the complex pattern will be replaced by
+the descriptions of matching tokens joined with a single space
+character. So, for instance, when the translation data looks like:
+
+  i18n:
+    inflections:
+      @person:
+        i: 'I'
+        u: 'You'
+      @tense:
+        now:  'am'
+        past: 'were'
+  welcome: "@person+tense{i+now:~|u+past:~}"
+
+the translate method will give the following results:
+
+  I18n.translate('welcome', :person => :i, :tense => :now)
+  # => "I am"
+
+  I18n.translate('welcome', :person => :you, :tense => :past)
+  # => "You were"
+
+This example is abstract, since the combination of +:i+
+and +:past+ will result in <tt>i were</tt> string, which is
+probably something unexpected. To achieve that kind of logic
+simply use combined patterns with the given values instead
+of loud tokens.
+
+=== Wildcard tokens in complex patterns
+The wildcard tokens might be extremely helpful in complex
+patterns since there is one shared free text for a whole pattern
+yet there might be a need to match any token for some subkind.
+For example:
+
+  welcome: @person+tense{i+present:am|u+present:are|*+present:is}
+
+Note that in the example above +*+ matches 'i', 'you', 'he', 'she' and 'it'
+but 'i' and 'u' are effectively matched before. The equivalent pattern without
+a wildcard token would look like:
+
+  welcome: @person+tense{i+present:am|u+present:are|i,u,he,she,it+present:is}
+
+== Inflection keys
+There is a way of storing inflected strings in keys instead
+of patterns. To use it you should simply assign subkeys to
+some translation key instead of string containing a pattern.
+The key-based inflection group is contained within a key
+which name begins with the +@+ symbol.
+
+The translation key containing a pattern:
+
+  welcome:  "Dear @{f:Lady|m:Sir|n:You|All}!"
+
+Can be easily written as:
+
+  @welcome:
+    f:        "Lady"
+    m:        "Sir"
+    n:        "You"
+    @free:    "All"
+    @prefix:  "Dear "
+    @suffix:  "!"
+ 
+You can also use strict kind or even the inflection sets, token
+groups, etc.:
+
+  welcome:  "@gender+tense{f+past:She was|m+present:He is|n+future:You will be}"
+
+Can be written as:
+
+  @welcome:
+    f+past:     "She was"
+    m+present:  "He is"
+    n+future:   "You will be"
+    @kind:      "gender+tense"
+
+There are special, optional subkeys that may give you
+more control over inflection process. These are:
+
+* +@kind+: a kind or kinds in case of strict kinds
+* +@prefix+: a prefix to be put before the interpolated data
+* +@suffix+: a suffix to be put after the interpolated data
+* +@free+: a free text that is to be used when no token will match
+
+=== Limitations
+
+Inflection keys look compact and clean but obviously
+you cannot use the key-based inflection to simply replace
+a string containing more than one inflection pattern.
+
+Also, <b>you have to be very careful when using this method
+with Ruby 1.8</b> because the order of processed token sets
+may change. That may break the logic in case of inflection
+sets where order has meaning (e.g. tokens with inverted
+matching).
+
+== Errors
+By default the module will silently ignore non-critical interpolation
+errors. You can turn off this default behavior by passing +:inflector_raises+
+option set to +true+. Note that most errors is reported because of
+wrong data in patterns or in configuration. In case of inflection
+options only malformed, empty or +nil+ values are reported
+when the mentioned switch is turned on. For inflection options
+containing unknown tokens no errors are generated.
+
+=== Usage of +:inflector_raises+ option
+
+*YAML:*
+
+Note: <em>Uses inflection configuration given in the first example.</em> 
+  en:
+    welcome:  "Dear @{m:Sir|f:Madam|Fallback}"
+
+*Code:*
+
+  I18n.t('welcome', :inflector_raises => true)
+  # => I18n::InflectionOptionNotFound: en.welcome:
+  #      @{m:Sir|f:Madam|Fallback}" - required option :gender was not found
+
+=== Exception meanings
+Here are the exceptions that may be raised when the option +:inflector_raises+
+is set to +true+:
+
+* {I18n::InvalidInflectionToken I18n::InvalidInflectionToken}
+* {I18n::InvalidInflectionKind I18n::InvalidInflectionKind}
+* {I18n::InvalidInflectionOption I18n::InvalidInflectionOption}
+* {I18n::MisplacedInflectionToken I18n::MisplacedInflectionToken}
+* {I18n::InflectionOptionNotFound I18n::InflectionOptionNotFound}
+* {I18n::InflectionOptionIncorrect I18n::InflectionOptionIncorrect}
+* {I18n::ComplexPatternMalformed I18n::ComplexPatternMalformed}
+
+There are also exceptions that are raised regardless of :+inflector_raises+
+presence or value.
+These are usually caused by critical errors encountered during processing
+inflection data or exceptions raised by I18n. Note that the pure I18n's
+exceptions are not described here.
+
+* {I18n::ArgumentError I18n::ArgumentError}
+* {I18n::InvalidLocale I18n::InvalidLocale}
+* {I18n::DuplicatedInflectionToken I18n::DuplicatedInflectionToken}
+* {I18n::BadInflectionKind I18n::BadInflectionKind}
+* {I18n::BadInflectionToken I18n::BadInflectionToken}
+* {I18n::BadInflectionAlias I18n::BadInflectionAlias}
+
+=== Exception hierarchy
+  I18n::ArgumentError
+  |
+  `-- I18n::InvalidLocale
+  |
+  `-- I18n::InflectionException
+      |
+      `-- I18n::InflectionPatternException
+      |   |
+      |   |-- I18n::InvalidInflectionToken
+      |   |-- I18n::InvalidInflectionKind
+      |   |-- I18n::MisplacedInflectionToken
+      |   |-- I18n::ComplexPatternMalformed
+      |   `-- I18n::InvalidOptionForKind
+      |       |-- I18n::InflectionOptionNotFound
+      |       `-- I18n::InflectionOptionIncorrect
+      |
+      `-- I18n::InflectionConfigurationException
+          |
+          |-- I18n::DuplicatedInflectionToken
+          |-- I18n::BadInflectionAlias
+          |-- I18n::BadInflectionToken
+          `-- I18n::BadInflectionKind
+
+== Reserved names and characters
+Some strings cannot be used as names and/or identifiers of
+kinds and tokens. There are also some reserved characters
+that cannot be used within them.
+
+=== Reserved keys
+Reserved keys, that cannot be used as names of inflection
+options and as names of kinds in the configuration
+are available after issuing:
+
+  I18n::Inflector::Config::Reserved::KEYS.to_a
+
+Here is the current list: <tt>:scope, :default, :separator,
+:resolve, :object, :fallback, :format, :cascade,
+:raise, :rescue_format, :inflector_cache_aware,
+:inflector_raises, :inflector_aliased_patterns,
+:inflector_unknown_defaults, :inflector_excluded_defaults</tt>.
+
+Additionally all Symbols or Strings beginning with
++inflector_+ are prohibited, since they are reserved as
+controlling options.
+
+=== Reserved characters
+All characters that have special meaning (operators and
+markers) are not allowed in patterns, in configuration
+and in options.
+
+==== Reserved characters in kinds
+===== Passed as inflection options
+
+* *Constant:* {I18n::Inflector::Config::Reserved::Kinds::OPTION}
+
+* *List:* <tt>+ | : ! { }</tt> and <tt>,</tt> (comma).
+
+===== Given in a configuration
+
+* *Constant:* {I18n::Inflector::Config::Reserved::Kinds::DB}
+
+* *List:* <tt>+ | : ! { }</tt> and <tt>,</tt> (comma).
+
+===== Placed in patterns
+
+* *Constant:* {I18n::Inflector::Config::Reserved::Kinds::PATTERN}
+
+* *List:* <tt>+ | : , ! @ { }</tt> and <tt>,</tt> (comma).
+
+==== Reserved characters in tokens
+===== Passed as values of inflection options
+
+* *Constant:* {I18n::Inflector::Config::Reserved::Tokens::OPTION}
+
+* *List:* <tt>* + | : ! @ { }</tt> and <tt>,</tt> (comma).
+
+===== Given in a configuration
+
+* *Constant:* {I18n::Inflector::Config::Reserved::Tokens::DB}
+
+* *List:* <tt>* + | : ! @ { }</tt> and <tt>,</tt> (comma).
+
+===== Placed in patterns
+
+* *Constant:* {I18n::Inflector::Config::Reserved::Tokens::PATTERN}
+
+* *List:* <tt>+ | : ! @ { }</tt> and <tt>,</tt> (comma).
+
+== Operators and markers
+Here is more formal definition of operators and markers used in patterns.
+
+=== Pattern
+  @[kind][+kind ...]{token_set[|token_set ...][|free_text]}
+
+* +@+ is the pattern marker
+* +{+ and +}+ are pattern delimiters
+* +free_text+ is an optional free text value
+* +kind+ is a kind identifier
+* <tt>+</tt> is the +AND+ operator that joins kinds (produces complex kinds)
+
+==== +token_set+
+  *|token_group[+token_group ...]:value
+
+* +:+ is the +ASSIGNMENT+ operator
+* +value+ is a value to be picked up then a token set matches; value may also
+  be the loud marker (+~+)
+* <tt>+</tt> is the +AND+ operator that joins many token groups into a set
+* +*+ is the +WILDCARD+ operator
+
+===== +token_group+
+  [!]token[,[!]token ...]
+
+* +token+ is a token identifier
+* +!+ is the +NOT+ operator
+* +,+ is the +OR+ operator
+
+=== Operator precedence
+
+* Single token level
+  * +NOT+ operators for inversed matching of tokens (<tt>!</tt>)
+  * +OR+ operators for joining tokens into token groups (<tt>,</tt>)
+* Token group level
+  * +WILDCARD+ operators for matching any token (<tt>*</tt>)
+  * +AND+ operators for joining token groups into sets (<tt>+</tt>)
+* Token set level
+  * +ASSIGNMENT+ operators for assigning values to token sets (<tt>:</tt>)
+  * +OR+ operators for separating token sets and/or free texts (<tt>|</tt>)
+* Pattern name level
+  * +AND+ operators for kind identifiers (<tt>+</tt>)
+* Pattern level
+  * Pattern marker and pattern delimiters
+
+== Classes and relations
+
+=== Library contents
+
+* Module {I18n::Inflector} containing everything
+* 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::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.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 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}.