Class: Traject::TranslationMap
- Inherits:
-
Object
- Object
- Traject::TranslationMap
- 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 (limited subset of) java .properties file.
traject's extract_marc
macro allows you to specify a :translation_map=>filename argument
that will automatically find and use a translation map on the resulting data:
extract_marc("040a", :translation_map => "languages")
Or you can always create one yourself and use it how you like:
map = TranslationMap.new("languages")
In either case, TranslationMap will look for a file named, in that example,
languages.rb
or languages.yaml
or languages.properties
,
somewhere in the ruby $LOAD_PATH in a /translation_maps
subdir.
Also 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 else. 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
Alternatives
Traject::TranslationMap
provides an easy way to deal with the most common translation case:
simple key-value stores with optional default values.
If you need more complex translation, you can simply use #map!
or its kin to work on the accumulator
in a block
# get a lousy language detection of any vernacular title
require 'whatlanguage'
wl = WhatLanguage.new(:all)
to_field 'vernacular_langauge', extract_marc('245', :alternate_script=>:only) do |rec, acc|
# accumulator is already filled with the values of any 880s that reference a 245 because
# of the call to #extract_marc
acc.map! {|x| wl.language(x) }
acc.uniq!
end
Within the block, you may also be interested in using:
Defined Under Namespace
Class Attribute Summary collapse
-
.cache ⇒ Object
Returns the value of attribute cache.
Instance Attribute Summary collapse
-
#default ⇒ Object
readonly
Returns the value of attribute default.
-
#hash ⇒ Object
readonly
Returns the value of attribute hash.
Class Method Summary collapse
Instance Method Summary collapse
- #[](key) ⇒ Object (also: #map)
-
#initialize(defn, options = {}) ⇒ TranslationMap
constructor
A new instance of TranslationMap.
-
#to_hash ⇒ Object
Returns a dup of internal hash, dup so you can modify it if you like.
-
#translate_array(array) ⇒ Object
Run every element of an array through this translation map, return the resulting array.
- #translate_array!(array) ⇒ Object
Constructor Details
#initialize(defn, options = {}) ⇒ TranslationMap
Returns a new instance of TranslationMap.
169 170 171 172 173 174 175 176 177 178 179 180 181 182 |
# File 'lib/traject/translation_map.rb', line 169 def initialize(defn, = {}) if defn.kind_of? Hash @hash = defn else @hash = self.class.cache.lookup(defn) raise NotFound.new(defn) if @hash.nil? end if [:default] @default = [:default] elsif @hash.has_key? "__default__" @default = @hash["__default__"] end end |
Class Attribute Details
.cache ⇒ Object
Returns the value of attribute cache.
161 162 163 |
# File 'lib/traject/translation_map.rb', line 161 def cache @cache end |
Instance Attribute Details
#default ⇒ Object (readonly)
Returns the value of attribute default.
158 159 160 |
# File 'lib/traject/translation_map.rb', line 158 def default @default end |
#hash ⇒ Object (readonly)
Returns the value of attribute hash.
157 158 159 |
# File 'lib/traject/translation_map.rb', line 157 def hash @hash end |
Class Method Details
.reset_cache! ⇒ Object
162 163 164 |
# File 'lib/traject/translation_map.rb', line 162 def reset_cache! cache.reset_cache! end |
Instance Method Details
#[](key) ⇒ Object Also known as: map
184 185 186 187 188 189 190 191 192 193 194 |
# File 'lib/traject/translation_map.rb', line 184 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.
199 200 201 |
# File 'lib/traject/translation_map.rb', line 199 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.
212 213 214 215 216 217 218 219 220 221 |
# File 'lib/traject/translation_map.rb', line 212 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
223 224 225 |
# File 'lib/traject/translation_map.rb', line 223 def translate_array!(array) array.replace( self.translate_array(array)) end |