Class: I18n::Inflector::InflectionOptions

Inherits:
Object
  • Object
show all
Defined in:
lib/i18n-inflector/options.rb

Overview

Note:

This class uses modified version of attr_accessor that memorizes any added method name as an option name. These options (with inflector_ prefix added) are accessible through #known method. The last method is used by options preparing routine when the interpolation is performed.

This class contains structures for keeping parsed translation data and basic operations.

All global options are available for current backend’s inflector by calling:

I18n.backend.inflector.options.<option_name>

or just:

I18n.inflector.options.<option_name>

A global option may be overriden by passing a proper option to the translation method. Such option should have the name of a global option but prefixed with inflector_:

translate('welcome', :inflector_<option_name> => value)

Constant Summary collapse

OPTION_PREFIX =

Prefix used to mark option as a controlling option.

'inflector_'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ InflectionOptions

This method initializes all internal structures.



278
279
280
 
# File 'lib/i18n-inflector/options.rb', line 278

def initialize
  reset
end

Instance Attribute Details

#aliased_patterns ⇒ Boolean

Note:

Local option :inflector_aliased_patterns passed to the Backend::Inflector#translate overrides this setting.

This is a switch that enables you to use aliases in patterns. When it’s enabled then aliases may be used in inflection patterns, not only true tokens. This operation may make your translation data a bit messy if you’re not alert. That’s why this switch is by default set to false.

Parameters:

  • state (Boolean) —

    true enables, false disables this switch

Returns:

  • (Boolean) —

    state of the switch



106
107
108
 
# File 'lib/i18n-inflector/options.rb', line 106

def aliased_patterns
  @aliased_patterns
end

#cache_aware ⇒ Boolean

This switch enables cache-aware mode. In that mode inflection options and flags are evaluated before calling original translate method and all options are passed to that method. Because options preparation for inflection methods is explicit (any missing switches and their default values are added to options) then original translate (or proxy caching method) will receive even those options that might have been changed globally.

Caching modules for I18n may use options passed to the translate method (if they are plugged in before inflector) for key transformation since the inflection options may influence the interpolation process and therefore the resulting string.

If however, the caching variant of the translate method is positioned before inflected variant in methods chain, then the only way of knowing all the settings by caching routine is to call options.options.prepare_options!(options) on the used backend, for example:

I18n.backend.inflector.options.prepare(options)

That will alter the options data so they will contain all switches and values.

Parameters:

  • state (Boolean) —

    true enables, false disables this switch

Returns:

  • (Boolean) —

    state of the switch



81
82
83
 
# File 'lib/i18n-inflector/options.rb', line 81

def cache_aware
  @cache_aware
end

#excluded_defaults ⇒ Boolean

Note:

Local option :inflector_excluded_defaults passed to the Backend::Inflector#translate overrides this setting.

When this switch is set to true then inflector falls back to the default token for a kind if the given inflection option is correct but doesn’t exist in a pattern.

There might happen that the inflection option given to #translate method will contain some proper token, but that token will not be present in a processed pattern. Normally an empty string will be generated from such a pattern or a free text (if a local fallback is present in a pattern). You can change that behavior and tell interpolating routine to use the default token for a processed kind in such cases.

This switch is by default set to false.

Examples:

YAML:

en:
  i18n:
    inflections:
      gender:
        o:      "other"
        m:      "male"
        n:      "neuter"
        default: n

  welcome:  'Dear @{n:You|m:Sir}'

Usage of :inflector_excluded_defaults option

I18n.t('welcome', :gender => :o)
# => "Dear "

I18n.t('welcome', :gender => :o, :inflector_excluded_defaults => true)
# => "Dear You"

Parameters:

  • state (Boolean) —

    true enables, false disables this switch

Returns:

  • (Boolean) —

    state of the switch



275
276
277
 
# File 'lib/i18n-inflector/options.rb', line 275

def excluded_defaults
  @excluded_defaults
end

#interpolate_symbols ⇒ Boolean

Note:

Local option :inflector_interpolate_symbols passed to the Backend::Inflector#translate overrides this setting.

This is a switch that enables interpolation of symbols. Whenever interpolation method will receive a collection of symbols as a result of calling underlying translation method it won’t process them, returning as they are, unless this switch is enabled.

Note that using symbols as values in translation data creates I18n aliases. This option is intended to work with arrays of symbols or hashes with symbols as values, if the original translation method returns such structures.

This switch is by default set to false.

Parameters:

  • state (Boolean) —

    true enables, false disables this switch

Returns:

  • (Boolean) —

    state of the switch



143
144
145
 
# File 'lib/i18n-inflector/options.rb', line 143

def interpolate_symbols
  @interpolate_symbols
end

#raises ⇒ Boolean

Note:

Local option :inflector_raises passed to the Backend::Inflector#translate overrides this setting.

This is a switch that enables extended error reporting. When it’s enabled then errors are raised in case of unknown or empty tokens present in a pattern or in options. This switch is by default set to false.

Parameters:

  • state (Boolean) —

    true enables, false disables this switch

Returns:

  • (Boolean) —

    state of the switch



93
94
95
 
# File 'lib/i18n-inflector/options.rb', line 93

def raises
  @raises
end

#traverses ⇒ Boolean

Note:

Local option :inflector_traverses passed to the Backend::Inflector#translate overrides this setting.

This is a switch that enables you to interpolate patterns contained in resulting nested Hashes. It is used when the original translation method returns a subtree of translation data because the given key is not pointing to a leaf of the data but to some collection.

This switch is by default set to true. When you turn it off then the Inflector won’t touch nested results and will return them as they are.

Parameters:

  • state (Boolean) —

    true enables, false disables this switch

Returns:

  • (Boolean) —

    state of the switch



122
123
124
 
# File 'lib/i18n-inflector/options.rb', line 122

def traverses
  @traverses
end

#unknown_defaults ⇒ Boolean

Note:

Local option :inflector_unknown_defaults passed to the Backend::Inflector#translate overrides this setting.

When this switch is set to true then inflector falls back to the default token for a kind if an inflection option passed to the Backend::Inflector#translate is unknown or nil. Note that the value of the default token will be interpolated only when this token is present in a pattern. This switch is by default set to true.

Examples:

YAML:

en:
 i18n:
   inflections:
     gender:
       n:       'neuter'
       o:       'other'
       default:  n

 welcome:         "Dear @{n:You|o:Other}"
 welcome_free:    "Dear @{n:You|o:Other|Free}"

Example 1


# :gender option is not present,
# unknown tokens in options are falling back to default

I18n.t('welcome')
# => "Dear You"

# :gender option is not present,
# unknown tokens from options are not falling back to default

I18n.t('welcome', :inflector_unknown_defaults => false)
# => "Dear You"

# other way of setting an option – globally

I18n.inflector.options.unknown_defaults = false
I18n.t('welcome')
# => "Dear You"

# :gender option is not present, free text is present,
# unknown tokens from options are not falling back to default

I18n.t('welcome_free', :inflector_unknown_defaults => false)
# => "Dear You"

Example 2


# :gender option is nil,
# unknown tokens from options are falling back to default token for a kind

I18n.t('welcome', :gender => nil)
# => "Dear You"

# :gender option is nil
# unknown tokens from options are not falling back to default token for a kind

I18n.t('welcome', :gender => nil, :inflector_unknown_defaults => false)
# => "Dear "

# :gender option is nil, free text is present
# unknown tokens from options are not falling back to default token for a kind

I18n.t('welcome_free', :gender => nil, :inflector_unknown_defaults => false)
# => "Dear Free"

Example 3


# :gender option is unknown,
# unknown tokens from options are falling back to default token for a kind

I18n.t('welcome', :gender => :unknown_blabla)
# => "Dear You"

# :gender option is unknown,
# unknown tokens from options are not falling back to default token for a kind

I18n.t('welcome', :gender => :unknown_blabla, :inflector_unknown_defaults => false)
# => "Dear "

# :gender option is unknown, free text is present
# unknown tokens from options are not falling back to default token for a kind

I18n.t('welcome_free', :gender => :unknown_blabla, :inflector_unknown_defaults => false)
# => "Dear Free"

Parameters:

  • state (Boolean) —

    true enables, false disables this switch

Returns:

  • (Boolean) —

    state of the switch



236
237
238
 
# File 'lib/i18n-inflector/options.rb', line 236

def unknown_defaults
  @unknown_defaults
end

Class Method Details

.attr_accessor(*args) ⇒ Object 



44
45
46
47
48
49
50
51
52
 
# File 'lib/i18n-inflector/options.rb', line 44

def attr_accessor(*args)
  r = old_attr_accessor(*args)
  @known ||= Hash.new
  args.each do |arg|
    key = '@' << arg.to_s
    @known[key.to_sym] = ("" << OPTION_PREFIX << arg.to_s).to_sym
  end
  r
end

Instance Method Details

#clean_for_translate!(options) ⇒ Hash

Note:

It modifies the given object.

This method prepares options for translate method. That means removal of all kind-related options and all options that are flags.

Parameters:

  • options (Hash) —

    the given options

Returns:

  • (Hash) —

    the given options



319
320
321
322
 
# File 'lib/i18n-inflector/options.rb', line 319

def clean_for_translate!(options)
  self.class.known.each { |name,long| options.delete long }
  options
end

#known ⇒ Array<Symbol>

Lists all known options in a long format (each name preceeded by inflector_).

Returns:

  • (Array<Symbol>) —

    the known options



329
330
331
 
# File 'lib/i18n-inflector/options.rb', line 329

def known
  self.class.known.values
end

#prepare_options!(options) ⇒ Hash

Note:

It modifies the given object.

This method processes the given argument in a way that it will use default values for options that are missing.

Parameters:

  • options (Hash) —

    the options

Returns:

  • (Hash) —

    the given options



304
305
306
307
308
309
 
# File 'lib/i18n-inflector/options.rb', line 304

def prepare_options!(options)
  self.class.known.
  reject { |name,long| options.has_key?(long) }.
  each   { |name,long| options[long] = instance_variable_get(name) }
  options
end

#reset

This method returns an undefined value.

This method resets all options to their default values.



285
286
287
288
289
290
291
292
293
294
 
# File 'lib/i18n-inflector/options.rb', line 285

def reset
  @unknown_defaults   = true
  @traverses          = true
  @interpolate_symbols= false
  @excluded_defaults  = false
  @aliased_patterns   = false
  @cache_aware        = false
  @raises             = false
  nil
end