i18n-inflector 1.0.11 → 2.0.0

data/docs/TODO

@@ -1,9 +1,9 @@
+== Near future
 
+* add some negative tests (e.g. empty kind, kinds as nils or empty striongs, tokens as empty strings...)
 
-* 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
-
-* use commas in patterns to separate tokens that should have to the same value
+== Distant future
 
-* use negation symbols (!) in patterns to mark tokens that should generate value if are not matched (processing ends on first negative match)
+* 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
 
-* 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)
+* 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?

data/lib/i18n-inflector/backend.rb

@@ -0,0 +1,268 @@
+# encoding: utf-8
+#
+# Author::    Paweł Wilk (mailto:pw@gnu.org)
+# Copyright:: (c) 2011 by Paweł Wilk
+# License::   This program is licensed under the terms of {file:LGPL GNU Lesser General Public License} or {file:COPYING Ruby License}.
+# 
+# This file contains I18n::Backend::Inflector module,
+# which extends I18n::Backend::Simple by adding the ability
+# to interpolate patterns containing inflection tokens
+# defined in translation data.
+
+module I18n
+
+  # @abstract This namespace is shared with I18n subsystem.
+  module Backend
+
+    # This module contains methods that are adding
+    # tokenized inflection support to internal I18n classes.
+    # It is intened to be included in the Simple backend
+    # module so that it will patch translate method in order
+    # to interpolate additional inflection tokens present in translations.
+    # Usually you don't have to know what's here to use it.
+    module Inflector
+
+      # This accessor allows to reach API methods of the
+      # inflector object associated with this class.
+      def inflector
+        inflector_try_init
+        @inflector
+      end
+
+      # Cleans up internal hashes containg kinds, inflections and aliases.
+      # 
+      # @api public
+      # @note It calls {I18n::Backend::Simple#reload! I18n::Backend::Simple#reload!}
+      # @return [Boolean] the result of calling ancestor's method
+      def reload!
+        @inflector = nil
+        super
+      end
+
+      # Translates given key taking care of inflections.
+      # 
+      # @api public
+      # @see I18n::Inflector::Core#interpolate
+      # @see I18n::Inflector::InflectionOptions
+      # @param [Symbol] locale locale
+      # @param [Symbol,String] key translation key
+      # @param [Hash] options a set of options to pass to the translation routines.
+      # @note Inflector requires at least one of the +options+ to have a value that
+      #   corresponds with token present in a pattern (or its alias). The name of that
+      #   particular option should be the same as the name of a kind of tokens from a pattern.
+      #   All +options+ along with a +string+ and +locale+ are passed to
+      #   {I18n::Backend::Simple#translate I18n::Backend::Simple#translate}
+      #   and the result is processed by {I18n::Inflector::Core#interpolate}
+      # @return [String] the translated string with interpolated patterns
+      def translate(locale, key, options = {})
+        translated_string = super
+
+        return translated_string if locale.to_s.empty?
+
+        unless @inflector.inflected_locale?(locale)
+          return translated_string.gsub(I18n::Inflector::PATTERN,'')
+        end
+
+        unless translated_string.include?(I18n::Inflector::FAST_MATCHER)
+          return translated_string
+        end
+
+        @inflector.interpolate(translated_string, locale, options.dup)
+      end
+
+      # Stores translations in memory.
+      # 
+      # @api public
+      # @raise [I18n::InvalidLocale] if the given +locale+ is invalid
+      # @raise [I18n::BadInflectionToken] if a name of some loaded token is invalid
+      # @raise [I18n::BadInflectionAlias] if a loaded alias points to a token that does not exists
+      # @raise [I18n::DuplicatedInflectionToken] if a token has already appeard in loaded configuration
+      # @note If inflections are changed it will regenerate proper internal
+      #   structures.
+      # @return [Hash] the stored translations 
+      def store_translations(locale, data, options = {})
+        r = super
+        inflector_try_init
+        if data.respond_to?(:has_key?)
+          subdata = (data[:i18n] || data['i18n'])
+          unless subdata.nil?
+            subdata = (subdata[:inflections] || subdata['inflections'])
+            unless subdata.nil?
+              inflection_data = load_inflection_tokens(locale, r[:i18n][:inflections])
+              @inflector.add_database(inflection_data)
+            end
+          end
+        end
+        r
+      end
+
+      protected
+
+      # Initializes internal hashes used for keeping inflections configuration.
+      # 
+      # @return [void]
+      def inflector_try_init
+        return nil if (defined?(@inflector) && !@inflector.nil?)
+        @inflector  = I18n::Inflector::Core.new
+        nil
+      end
+
+      # Takes care of loading inflection tokens
+      # for all languages (locales) that have them
+      # defined.
+      # 
+      # @note It calls {I18n::Backend::Simple#init_translations I18n::Backend::Simple#init_translations}
+      # @raise [I18n::BadInflectionToken] if a name of some loaded token is invalid
+      # @raise [I18n::BadInflectionAlias] if a loaded alias points to a token that does not exists
+      # @raise [I18n::DuplicatedInflectionToken] if a token has already appeard in loaded configuration
+      # @return [Boolean] +true+ if everything went fine
+      def init_translations
+        inflector_try_init
+        super
+      end
+
+      # Gives an access to the internal structure containing configuration data
+      # for a given locale.
+      # 
+      # @note Under some very rare conditions this method may be called while
+      #   translation data is loading. It must always return when translations
+      #   are not initialized. Otherwise it will cause loops and someone in Poland
+      #   will eat a kittien!
+      # @param [Symbol] locale the locale to use
+      # @return [Hash,nil] part of the translation data that
+      #   reflects inflections for a given locale or +nil+
+      #   if translations are not initialized
+      def inflection_subtree(locale)
+        return nil unless initialized?
+        lookup(locale, :"i18n.inflections", [], :fallback => true, :raise => :false)
+      end
+
+      # Resolves an alias for a token if the given +token+ is an alias.
+      # 
+      # @note It does take care of aliasing loops (max traverses is set to 64).
+      # @raise [I18n::BadInflectionToken] if a name of the token that alias points to is corrupted
+      # @raise [I18n::BadInflectionAlias] if an alias points to token that does not exists
+      # @return [Symbol] the true token that alias points to if the given +token+
+      #   is an alias or the given +token+ if it is a true token
+      # @overload shorten_inflection_alias(token, kind, locale)
+      #   Resolves an alias for a token if the given +token+ is an alias for the given +locale+ and +kind+.
+      #   @note This version uses internal subtree and needs the translation data to be initialized.
+      #   @param [Symbol] token the token name
+      #   @param [Symbol] kind the kind of the given token
+      #   @param [Symbol] locale the locale to use
+      #   @return [Symbol] the true token that alias points to if the given +token+
+      #     is an alias or the given +token+ if it is a true token
+      # @overload shorten_inflection_alias(token, kind, locale, subtree)
+      #   Resolves an alias for a token if the given +token+ is an alias for the given +locale+ and +kind+.
+      #   @param [Symbol] token the token name
+      #   @param [Symbol] kind the kind of the given token
+      #   @param [Symbol] locale the locale to use
+      #   @param [Hash] subtree the tree (in a form of nested Hashes) containing inflection tokens to scan
+      #   @return [Symbol] the true token that alias points to if the given +token+
+      #     is an alias or the given +token+ if it is a true token
+      def shorten_inflection_alias(token, kind, locale, subtree=nil, count=0)
+        count += 1
+        return nil if count > 64
+
+        inflections_tree = subtree || inflection_subtree(locale)
+        return nil if (inflections_tree.nil? || inflections_tree.empty?)
+
+        kind_subtree  = inflections_tree[kind]
+        value         = kind_subtree[token].to_s
+
+        if value[0..0] != I18n::Inflector::ALIAS_MARKER
+          if kind_subtree.has_key?(token)
+            return token
+          else
+            # that should never happend but who knows
+            raise I18n::BadInflectionToken.new(locale, token, kind)
+          end
+        else
+          orig_token = token
+          token = value[1..-1]
+          if token.to_s.empty?
+            raise I18n::BadInflectionToken.new(locale, token, kind)
+          end
+          token = token.to_sym
+          if kind_subtree[token].nil?
+            raise BadInflectionAlias.new(locale, orig_token, kind, token)
+          else
+            shorten_inflection_alias(token, kind, locale, inflections_tree, count)
+          end
+        end
+
+      end
+
+      # Uses the inflections subtree and creates internal mappings
+      # to resolve kinds assigned to inflection tokens and aliases, including defaults.
+      # @return [Hash,nil] the internal Hash containing inflections tokens or +nil+ if something went wrong
+      # @raise [I18n::BadInflectionToken] if a name of some loaded token is invalid
+      # @raise [I18n::BadInflectionAlias] if a loaded alias points to a token that does not exists
+      # @raise [I18n::DuplicatedInflectionToken] if a token has already appeard in loaded configuration
+      # @overload load_inflection_tokens(locale)
+      #   @note That version calls the {inflection_subtree} method to obtain internal translations data.
+      #   Loads inflection tokens for the given locale using internal hash of stored translations. Requires
+      #   translations to be initialized.
+      #   @param [Symbol] locale the locale to use and work for
+      #   @return [Hash,nil] the internal Hash containing inflections or +nil+ if translations were not initialized
+      # @overload load_inflection_tokens(locale, subtree)
+      #   Loads inflection tokens for the given locale using data given in an argument
+      #   @param [Symbol] locale the locale to use and work for
+      #   @param [Hash] subtree the tree (in a form of nested Hashes) containing inflection tokens to scan
+      #   @return [Hash,nil] the internal Hash containing inflections or +nil+ if the given subtree was wrong or empty
+      def load_inflection_tokens(locale, subtree=nil)
+        inflections_tree = subtree || inflection_subtree(locale)
+        return nil if (inflections_tree.nil? || inflections_tree.empty?)
+
+        idb = I18n::Inflector::InflectionData.new(locale)
+
+        inflections_tree.each_pair do |kind, tokens|
+          tokens.each_pair do |token, description|
+
+            # test for duplicate
+            if idb.has_token?(token)
+              raise I18n::DuplicatedInflectionToken.new(idb.get_kind(token), kind, token)
+            end
+
+            # validate token's name
+            raise I18n::BadInflectionToken.new(locale, token, kind) if token.to_s.empty?
+
+            # validate token's description
+            if description.nil?
+              raise I18n::BadInflectionToken.new(locale, token, kind, description)
+            elsif description[0..0] == I18n::Inflector::ALIAS_MARKER
+              next
+            end
+
+            # handle default token for a kind
+            if token == :default
+              if idb.has_default_token?(kind) # should never happend unless someone is messing with @translations
+                raise I18n::DuplicatedInflectionToken.new(kind, nil, token)
+              end
+              idb.set_default_token(kind, description)
+              next
+            end
+
+            idb.add_token(token, kind, description)
+          end
+        end
+
+        # handle aliases
+        inflections_tree.each_pair do |kind, tokens|
+          tokens.each_pair do |token, description|
+            next if description[0..0] != I18n::Inflector::ALIAS_MARKER
+            real_token = shorten_inflection_alias(token, kind, locale, inflections_tree)
+            idb.add_alias(token, real_token) unless real_token.nil?
+          end
+        end
+
+        # process and validate defaults
+        valid = idb.validate_default_tokens
+        raise I18n::BadInflectionAlias.new(locale, :default, valid[0], valid[1]) unless valid.nil?
+
+        idb
+      end
+
+    end
+  end
+end

data/lib/i18n-inflector/errors.rb

@@ -2,7 +2,7 @@
 #
 # Author::    Paweł Wilk (mailto:pw@gnu.org)
 # Copyright:: (c) 2011 by Paweł Wilk
-# License::   This program is licensed under the terms of {file:LGPL-LICENSE GNU Lesser General Public License} or {file:COPYING Ruby License}.
+# License::   This program is licensed under the terms of {file:LGPL GNU Lesser General Public License} or {file:COPYING Ruby License}.
 # 
 # This file contains error reporting classes for I18n::Backend::Inflector module.
 
@@ -37,7 +37,7 @@ module I18n
             "pattern #{pattern.inspect} is invalid"
     end
   end
-  
+
   # This is raised when an inflection token used in a pattern does not match
   # an assumed kind determined by reading previous tokens from that pattern.
   class MisplacedInflectionToken < ArgumentError
@@ -45,7 +45,7 @@ module I18n
     def initialize(pattern, token, kind)
       @pattern, @token, @kind = pattern, token, kind
       super "inflection token #{token.inspect} from pattern #{pattern.inspect} " +
-            "is not of expected kind #{kind.inspect}"
+            "is not of the expected kind #{kind.inspect}"
     end
   end
 
@@ -69,22 +69,25 @@ module I18n
     def initialize(locale, token, kind, pointer)
       @locale, @token, @kind, @pointer = locale, token, kind, pointer
       what = token == :default ? "default token" : "alias"
-      super "the #{what} #{token.inspect} of kind #{kind.inspect} " +
-            "for language #{locale.inspect} points to an unknown token #{pointer.inspect}"
+      lang = locale.nil? ? "" : "for language #{locale.inspect} "
+      kinn = kind.nil? ?   "" : "of kind #{kind.inspect} "
+      super "the #{what} #{token.inspect}" + kinn + lang +
+            "points to an unknown token #{pointer.inspect}"
     end
   end
-  
+
   # This is raised when an inflection token or its description has a bad name. This
   # includes an empty name or a name containing prohibited characters.
   class BadInflectionToken < ArgumentError
     attr_reader :locale, :token, :kind, :description
-    def initialize(locale, token, kind, description=nil)
+    def initialize(locale, token, kind=nil, description=nil)
       @locale, @token, @kind, @description = locale, token, kind, description
+      kinn = kind.nil? ? "" : "of kind #{kind.inspect} "
       if description.nil?
-        super "Inflection token #{token.inspect} of kind #{kind.inspect} "+
+        super "Inflection token #{token.inspect} " + kinn +
               "for language #{locale.inspect} has a bad name"
       else
-        super "Inflection token #{token.inspect} of kind #{kind.inspect} "+
+        super "Inflection token #{token.inspect} " + kinn +
               "for language #{locale.inspect} has a bad description #{description.inspect}"
       end
     end

data/lib/i18n-inflector/inflection_data.rb

@@ -0,0 +1,329 @@
+# encoding: utf-8
+#
+# Author::    Paweł Wilk (mailto:pw@gnu.org)
+# Copyright:: (c) 2011 by Paweł Wilk
+# License::   This program is licensed under the terms of {file:LGPL GNU Lesser General Public License} or {file:COPYING Ruby License}.
+# 
+# This file contains utility methods,
+# that are used by I18n::Inflector and I18n::Backend::Inflector.
+
+# @abstract This namespace is shared with I18n subsystem.
+module I18n
+  module Inflector
+
+    # This class contains structures for keeping parsed translation data
+    # and basic operations for performing on them.
+    class InflectionData
+
+      # Initializes internal structures.
+      def initialize(locale=nil)
+        dummy_token = {:kind=>nil,:target=>nil,:description=>nil}
+        @kinds      = Hash.new(false)
+        @tokens     = Hash.new(dummy_token)
+        @defaults   = {}
+        @locale     = locale
+      end
+
+      # Locale that this database works on.
+      attr_reader :locale
+
+      # Adds an alias (overwriting existing alias).
+      # 
+      # @param [Symbol] name the name of an alias
+      # @param [Symbol] target the target token for the given +alias+
+      # @return [Boolean] +true+ if everything went ok, +false+ otherwise
+      #  (in case of bad or +nil+ names or non-existent targets)
+      def add_alias(name, target)
+        target  = target.to_s
+        name    = name.to_s
+        return false if (name.empty? || target.empty?)
+        name    = name.to_sym
+        target  = target.to_sym
+        kind    = get_kind(target)
+        return false if kind.nil?
+        @tokens[name] = {}
+        @tokens[name][:kind]         = kind
+        @tokens[name][:target]       = target
+        @tokens[name][:description]  = @tokens[target][:description]
+        true
+      end
+
+      # Adds a token (overwriting existing token).
+      # 
+      # @param [Symbol] token the name of a token to add
+      # @param [Symbol] kind the kind of a token
+      # @param [String] description the description of a token
+      # @return [void]
+      def add_token(token, kind, description)
+        token = token.to_sym
+        @tokens[token] = {}
+        @tokens[token][:kind]         = kind.to_sym
+        @tokens[token][:description]  = description.to_s
+        @kinds[kind] = true
+      end
+
+      # Sets the default token for a kind.
+      # 
+      # @param [Symbol] kind the kind to which the default
+      #   token should be assigned
+      # @param [Symbol] target the token to set
+      # @return [void]
+      def set_default_token(kind, target)
+        @defaults[kind.to_sym] = target.to_sym
+      end
+
+      # Tests if the token is a true token.
+      # 
+      # @overload has_true_token?(token)
+      #   Tests if the token is a true token.
+      #   @param [Symbol] token the identifier of a token
+      #   @return [Boolean] +true+ if the given +token+ is
+      #     a token and not an alias, +false+ otherwise 
+      # @overload has_true_token?(token, kind)
+      #   Tests if the token is a true token.
+      #   @param [Symbol] token the identifier of a token
+      #   @param [Symbol] kind the identifier of a kind
+      #   @return [Boolean] +true+ if the given +token+ is
+      #     a token and not an alias, and is a kind of
+      #     the given kind, +false+ otherwise 
+      def has_true_token?(token, kind=nil)
+        o = @tokens[token]
+        k = o[:kind]
+        return false if (k.nil? || !o[:target].nil?)
+        kind.nil? ? true : k == kind
+      end
+
+      # Tests if a token (or alias) is present.
+      # 
+      # @overload has_token(token)
+      #   Tests if a token (or alias) is present.
+      #   @param [Symbol] token the identifier of a token
+      #   @return [Boolean] +true+ if the given +token+ 
+      #     (which may be an alias) exists
+      # @overload has_token(token, kind)
+      #   Tests if a token (or alias) is present.
+      #   @param [Symbol] token the identifier of a token
+      #   @param [Symbol] kind the identifier of a kind
+      #   @return [Boolean] +true+ if the given +token+ 
+      #     (which may be an alias) exists and if kind of
+      #     the given kind
+      def has_token?(token, kind=nil)
+        k = @tokens[token][:kind]
+        kind.nil? ? !k.nil? : k == kind
+      end
+
+      # Tests if a kind exists.
+      # 
+      # @param [Symbol] kind the identifier of a kind
+      # @return [Boolean] +true+ if the given +kind+ exists
+      def has_kind?(kind)
+        @kinds.has_key?(kind)
+      end
+
+      # Tests if a kind has a default token assigned.
+      # 
+      # @param [Symbol] kind the identifier of a kind
+      # @return [Boolean] +true+ if there is a default
+      #   token of the given kind
+      def has_default_token?(kind)
+        @defaults.has_key?(kind)
+      end
+
+      # Tests if a given alias is really an alias.
+      # 
+      # @overload has_alias?(alias_name)
+      #   Tests if a given alias is really an alias.
+      #   @param [Symbol] alias_name the identifier of an alias
+      #   @return [Boolean] +true+ if the given alias is really an alias,
+      #     +false+ otherwise
+      # @overload has_alias?(alias_name, kind)
+      #   Tests if a given alias is really an alias.
+      #   @param [Symbol] alias_name the identifier of an alias
+      #   @param [Symbol] kind the identifier of a kind
+      #   @return [Boolean] +true+ if the given alias is really an alias
+      #     being a kind of the given kind, +false+ otherwise
+      def has_alias?(alias_name, kind=nil)
+        o = @tokens[alias_name]
+        return false if o[:target].nil?
+        kind.nil? ? true : o[:kind] == kind
+      end
+
+      # Reads the all the true tokens (not aliases).
+      # 
+      # @return [Hash] the true tokens in a
+      #     form of Hash (<tt>token => description</tt>)
+      # @overload get_true_tokens(kind)
+      #   Reads the all the true tokens (not aliases).
+      #   @return [Hash] the true tokens in a
+      #     form of Hash (<tt>token => description</tt>)
+      # @overload get_true_tokens(kind)
+      #   Reads the all the true tokens (not aliases).
+      #   @param [Symbol] kind the identifier of a kind
+      #   @return [Hash] the true tokens of the given kind in a
+      #     form of Hash (<tt>token => description</tt>)
+      def get_true_tokens(kind=nil)
+        tokens = @tokens.reject{|k,v| !v[:target].nil?}
+        tokens = tokens.reject{|k,v| v[:kind]!=kind} unless kind.nil?
+        tokens.merge(tokens){|k,v| v[:description]}
+      end
+
+      # Reads the all the aliases.
+      # 
+      # @return [Hash] the aliases in a
+      #     form of Hash (<tt>alias => target</tt>)
+      # @overload get_aliases(kind)
+      #   Reads the all the aliases.
+      #   @return [Hash] the aliases in a
+      #     form of Hash (<tt>alias => target</tt>)
+      # @overload get_aliases(kind)
+      #   Reads the all the aliases.
+      #   @param [Symbol] kind the identifier of a kind
+      #   @return [Hash] the aliases of the given kind in a
+      #     form of Hash (<tt>alias => target</tt>)
+      def get_aliases(kind=nil)
+        aliases = @tokens.reject{|k,v| v[:target].nil?}
+        aliases = aliases.reject{|k,v| v[:kind]!=kind} unless kind.nil?
+        aliases.merge(aliases){|k,v| v[:target]}
+      end
+
+      # Reads the all the tokens in a way that it is possible to
+      # distinguish true tokens from aliases.
+      # 
+      # @note True tokens have descriptions (String) and aliases
+      #   have targets (Symbol) assigned.
+      # @return [Hash] the tokens in a
+      #     form of Hash (<tt>token => description|target</tt>)
+      # @overload get_raw_tokens
+      #   Reads the all the tokens.
+      #   @return [Hash] the tokens in a
+      #     form of Hash (<tt>token => description|target</tt>)
+      # @overload get_raw_tokens(kind)
+      #   Reads the all the tokens.
+      #   @param [Symbol] kind the identifier of a kind
+      #   @return [Hash] the tokens of the given kind in a
+      #     form of Hash (<tt>token => description|target</tt>)
+      def get_raw_tokens(kind=nil)
+        get_true_tokens(kind).merge(get_aliases(kind))
+      end
+
+      # Reads the all the tokens (including aliases).
+      # 
+      # @note Use {get_raw_tokens} if you want to distinguish
+      #   true tokens from aliases.
+      # @return [Hash] the tokens in a
+      #     form of Hash (<tt>token => description</tt>)
+      # @overload get_raw_tokens(kind)
+      #   Reads the all the tokens (including aliases).
+      #   @return [Hash] the tokens in a
+      #     form of Hash (<tt>token => description</tt>)
+      # @overload get_raw_tokens(kind)
+      #   Reads the all the tokens (including aliases).
+      #   @param [Symbol] kind the identifier of a kind
+      #   @return [Hash] the tokens of the given kind in a
+      #     form of Hash (<tt>token => description</tt>)
+      def get_tokens(kind=nil)
+        tokens = @tokens
+        tokens = tokens.reject{|k,v| v[:kind]!=kind} unless kind.nil?
+        tokens.merge(tokens){|k,v| v[:description]}
+      end
+
+      # Gets a target token for the alias.
+      # 
+      # @param [Symbol] alias_name the identifier of an alias
+      # @return [Symbol,nil] the token that the given alias points to
+      #   or +nil+ if it isn't really an alias
+      def get_target_for_alias(alias_name)
+        @tokens[alias_name][:target]
+      end
+
+      # Gets a kind of the given token or alias.
+      # 
+      # @param [Symbol] token identifier of a token
+      # @return [Symbol,nil] the kind of the given +token+
+      #   or +nil+ if the token is unknown
+      def get_kind(token)
+        @tokens[token][:kind]
+      end
+
+      # Gets a true token for the given identifier.
+      # 
+      # @note If the given +token+ is really an alias it will
+      #   be resolved and the real token pointed by that alias
+      #   will be returned.
+      # @overload get_true_token(token)
+      #   Gets a true token for the given token identifier.
+      #   @param [Symbol] token the identifier of a token
+      #   @return [Symbol,nil] the true token for the given +token+
+      #     or +nil+ if the token is unknown
+      # @overload get_true_token(token, kind)
+      #   Gets a true token for the given token identifier and the
+      #     given kind.
+      #   @param [Symbol] token the identifier of a token
+      #   @param [Symbol] kind the identifier of a kind
+      #   @return [Symbol,nil] the true token for the given +token+
+      #     or +nil+ if the token is unknown or is not kind of the
+      #     given kind
+      def get_true_token(token, kind=nil)
+        o = @tokens[token]
+        k = o[:kind]
+        return nil if k.nil?
+        r = (o[:target] || token)
+        return r if kind.nil?
+        k == kind ? r : nil
+      end
+
+      # Gets all known kinds.
+      # 
+      # @return [Array<Symbol>] an array containing all the known kinds
+      def get_kinds
+        @kinds.keys
+      end
+
+      # Reads the default token of a kind.
+      # 
+      # @note It will always return true token (not an alias).
+      # @param [Symbol] kind the identifier of a kind
+      # @return [Symbol,nil] the default token of the given +kind+
+      #   or +nil+ if there is no default token set
+      def get_default_token(kind)
+        @defaults[kind]
+      end
+
+      # Gets a description of a token or alias.
+      # 
+      # @note If the token is really an alias it will resolve the alias first.
+      # @param [Symbol] token the identifier of a token
+      # @return [String,nil] the string containing description of the given
+      #   token (which may be an alias) or +nil+ if the token is unknown
+      def get_description(token)
+        @tokens[token][:description]
+      end
+
+      # This method validates default tokens assigned
+      # for kinds and replaces targets with true tokens
+      # if they are aliases.
+      # 
+      # @return [nil,Array<Symbol>] +nil+ if everything went fine,
+      #   two dimensional array containing kind and target
+      #   in case of error while geting a token
+      def validate_default_tokens
+        @defaults.each_pair do |kind, pointer|
+          ttok = get_true_token(pointer)
+          return [kind, pointer] if ttok.nil?
+          set_default_token(kind, ttok) 
+        end
+        return nil
+      end
+
+      # Test if the inflection data have no elements.
+      # 
+      # @return [Boolean] +true+ if the inflection data
+      #   have no elements
+      def empty?
+        @tokens.empty?
+      end
+
+    end # InflectionData
+
+  end
+end