Class: Traject::TranslationMap

Inherits:
Object
  • Object
show all
Defined in:
lib/traject/translation_map.rb

Overview

A TranslationMap is basically just something that has a hash-like #[] method to map from input strings to output strings:

translation_map["some_input"] #=> some_output

Input is assumed to always be string, output is either string or array of strings.

What makes it more useful than a stunted hash is it’s ability to load the hash definitions from configuration files, either pure ruby, yaml, or java .properties. (Limited basic .properties, don’t try any fancy escaping please, no = or : in key names, no split lines.)

TranslationMap.new(“dir/some_file”)

Will look through the entire ruby $LOAD_PATH, for a translation_maps subdir that contains either some_file.rb OR some_file.yaml OR some_file.properties.

  • Looks for “/translation_maps” subdir in load paths, so for instance you can have a gem that keeps translation maps in ./lib/translation_maps, and it Just Works.

  • Note you do NOT supply the .rb, .yaml, or .properties suffix yourself,

it’ll use whichever it finds (allows calling code to not care which is used).

Ruby files just need to have their last line eval to a hash. They file will be run through eval, don’t do it with untrusted content (naturally)

You can also pass in a Hash for consistency to TranslationMap.new, although I don’t know why you’d want to.

Special default handling

The key “__default__” in the hash is treated specially. If set to a string, that string will be returned by the TranslationMap for any input not otherwise included. If set to the special string “__passthrough__”, then for input not mapped, the original input string will be returned.

This is most useful for YAML definition files, if you are using an actual ruby hash, you could just set the hash to do what you want using Hash#default_proc etc.

Or, when calling TranslationMap.new(), you can pass in options over-riding special key too:

TranslationMap.new("something", :default => "foo")
TranslationMap.new("something", :default => :passthrough)

Output: String or array of strings

The output can be a string or an array of strings, or nil. It should not be anything When used with the #translate_array! method, one string can be replaced by multiple values (array of strings) or removed (nil)

There’s no way to specify multiple return values in a .properties, use .yaml or .rb for that.

Caching

Lookup and loading of configuration files will be cached, for efficiency. You can reset with TranslationMap.reset_cache!

YAML example:

key: value
key2: value2 multiple words fine
key2b: "Although you can use quotes if you want: Or need."
key3:
  - array
  - of
  - values look like this

Defined Under Namespace

Classes: Cache, NotFound

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(defn, options = {}) ⇒ TranslationMap

Returns a new instance of TranslationMap.



137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/traject/translation_map.rb', line 137

def initialize(defn, options = {})
  if defn.kind_of? Hash
    @hash = defn
  else
    @hash = self.class.cache.lookup(defn)
    raise NotFound.new(defn) if @hash.nil?
  end

  if options[:default]
    @default = options[:default]
  elsif @hash.has_key? "__default__"
    @default = @hash["__default__"]
  end
end

Class Attribute Details

.cache ⇒ Object

Returns the value of attribute cache.



129
130
131
 
# File 'lib/traject/translation_map.rb', line 129

def cache
  @cache
end

Instance Attribute Details

#default ⇒ Object (readonly)

Returns the value of attribute default.



126
127
128
 
# File 'lib/traject/translation_map.rb', line 126

def default
  @default
end

#hash ⇒ Object (readonly)

Returns the value of attribute hash.



125
126
127
 
# File 'lib/traject/translation_map.rb', line 125

def hash
  @hash
end

Class Method Details

.reset_cache! ⇒ Object 



130
131
132
 
# File 'lib/traject/translation_map.rb', line 130

def reset_cache!
  cache.reset_cache!
end

Instance Method Details

#[](key) ⇒ Object Also known as: map 



152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/traject/translation_map.rb', line 152

def [](key)
  if self.default && (! @hash.has_key?(key))
    if self.default == "__passthrough__"
      return key
    else
      return self.default
    end
  end

  @hash[key]
end

#to_hash ⇒ Object

Returns a dup of internal hash, dup so you can modify it if you like.



167
168
169
 
# File 'lib/traject/translation_map.rb', line 167

def to_hash
  @hash.dup
end

#translate_array(array) ⇒ Object

Run every element of an array through this translation map, return the resulting array. If translation map returns nil, original element will be missing from output.

If an input maps to an array, each element of the array will be flattened into the output.

If an input maps to nil, it will cause the input element to be removed entirely.



180
181
182
183
184
185
186
187
188
189
 
# File 'lib/traject/translation_map.rb', line 180

def translate_array(array)
  array.each_with_object([]) do |input_element, output_array|
    output_element = self.map(input_element)
    if output_element.kind_of? Array
      output_array.concat output_element
    elsif ! output_element.nil?
      output_array << output_element
    end
  end
end

#translate_array!(array) ⇒ Object 



191
192
193
 
# File 'lib/traject/translation_map.rb', line 191

def translate_array!(array)
  array.replace( self.translate_array(array))
end