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_'

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ InflectionOptions

This method initializes all internal structures.



273
274
275
 
# File 'lib/i18n-inflector/options.rb', line 273

def initialize
  reset
end

Class Attribute Details

.known ⇒ Object (readonly) 



36
37
38
 
# File 'lib/i18n-inflector/options.rb', line 36

def known
  @known
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



101
102
103
 
# File 'lib/i18n-inflector/options.rb', line 101

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



76
77
78
 
# File 'lib/i18n-inflector/options.rb', line 76

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



270
271
272
 
# File 'lib/i18n-inflector/options.rb', line 270

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



138
139
140
 
# File 'lib/i18n-inflector/options.rb', line 138

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



88
89
90
 
# File 'lib/i18n-inflector/options.rb', line 88

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



117
118
119
 
# File 'lib/i18n-inflector/options.rb', line 117

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



231
232
233
 
# File 'lib/i18n-inflector/options.rb', line 231

def unknown_defaults
  @unknown_defaults
end

Class Method Details

.attr_accessor(*args) ⇒ Object 



40
41
42
43
44
45
46
47
48
 
# File 'lib/i18n-inflector/options.rb', line 40

def attr_accessor(*args)
  r = old_attr_accessor(*args)
  @known ||= {}
  args.each do |arg|
    key = "@#{arg}"
    @known[key.to_sym] = (OPTION_PREFIX + arg.to_s).to_sym
  end
  r
end

.old_attr_accessor ⇒ Object 



39
 
# File 'lib/i18n-inflector/options.rb', line 39

alias_method :old_attr_accessor, :attr_accessor

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



314
315
316
317
 
# File 'lib/i18n-inflector/options.rb', line 314

def clean_for_translate!(options)
  self.class.known.each_value { |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



324
325
326
 
# File 'lib/i18n-inflector/options.rb', line 324

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



299
300
301
302
303
304
 
# File 'lib/i18n-inflector/options.rb', line 299

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

#reset ⇒ void

This method returns an undefined value.

This method resets all options to their default values.



280
281
282
283
284
285
286
287
288
289
 
# File 'lib/i18n-inflector/options.rb', line 280

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