tater 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f47c6fb87ebbbaa22bd33575dc6009a31e62fcbf81c9de5bd3d9a9e46d59e79
-  data.tar.gz: 3ba6ff030c7f2aa67163c2d230a2839f43b16381a295f3258d2b538c03283251
+  metadata.gz: bce1afa07abcf6f94618ca249808f14d4a16b107c112bc074b4f0e6e2703b86d
+  data.tar.gz: 3f481fbb8e9551fee057472c3bef0fbc2420c9e267a37e09bf353a19e9877130
 SHA512:
-  metadata.gz: c95c9b85915657d2327d1c92488dda8041fd8a3fc0f8cbdf27681c972723b2a26009b26f021b6b937114c7690acb4c27c58d99e6693fb870c0f905860d267b17
-  data.tar.gz: 5cb0d1ad507632d7ba48368d8df5c26047e1ee7beca54eb591dd7f6e3ab37869ae5eb077d3dc5f5bb7e8c56dd5339904b6a91a4abf49ada5e98a6def48137e1a
+  metadata.gz: 9096e096441db2696735213dd21c313aa333877062f3094680a2ff7bbb14c5e3e699d817a8df59626f570eff345b5b69a942ec99cd19ab3bc74cbdee0cb9b398
+  data.tar.gz: 8511e008cf509bd76869aef9957e98e7f73bb60b50649abe811f09ad4ee01447553689ffe52451f8073110d1338ad430ef7848f25a4e3fce1614c22d60153dc3

data/README.md

@@ -59,7 +59,7 @@ i18n.translate('interpolated', you: 'world') # => 'Hello world!'
 ## Numeric Localization
 
 Numeric localization (`Numeric`, `Integer`, `Float`, and `BigDecimal`) require
-filling in a separater and delimiter. For example:
+filling in a separator and delimiter. For example:
 
 ```yaml
 en:
@@ -74,6 +74,12 @@ With that, you can do things like this:
 i18n.localize(1000.2) # => "1,000.20"
 ```
 
+The separator and delimiter can also be passed in per-call:
+
+```ruby
+i18n.localize(1000.2, delimiter: '_', separator: '+') # => "1_000+20"
+```
+
 
 ## Date and Time Localization
 
@@ -160,6 +166,98 @@ i18n.localize(Date.new(1970, 1, 1), format: 'day') # => 'jeudi'
 ```
 
 
+## Cascading Lookups
+
+Lookups can be cascaded, i.e. pieces of the scope of the can be lopped off
+incrementally.
+
+```ruby
+messages = {
+  'login' => {
+    'title' => 'Login',
+    'description' => 'Normal description.'
+
+    'special' => {
+      'title' => 'Special Login'
+    }
+  }
+}
+
+i18n = Tater.new(messages: messages)
+i18n.translate('login.special.title') # => 'Special Login'
+i18n.translate('login.special.description') # => 'Tater lookup failed'
+
+i18n.translate('login.special.description', cascade: true) # => 'Normal description.'
+```
+
+With cascade, the final key stays the same, but pieces of the scope get lopped
+off. In this case, lookups will be tried in this order:
+
+1. `'login.special.description'`
+2. `'login.description'`
+
+This can be useful when you want to override some messages but don't want to
+have to copy all of the other, non-overwritten messages.
+
+Cascading can also be enabled by default when initializing an instance of Tater.
+
+```ruby
+Tater.new(cascade: true)
+```
+
+Cascading is off by default.
+
+
+## Defaults
+
+If you'd like to default to another value in case of a missed lookup, you can
+provide the `:default` option to `#translate`.
+
+```ruby
+Tater.new.translate('nope', default: 'Yep!') # => 'Yep!'
+```
+
+
+## Procs and Messages in Ruby
+
+Ruby files can be used to store messages in addition to YAML, so long as the
+Ruby file returns a `Hash` when evalled.
+
+```ruby
+{
+  en: {
+    ruby: proc do |key, options = {}|
+      "Hey #{ key }!"
+    end
+  }
+}
+```
+
+
+## Multiple Locales
+
+If you like to check multiple locales and pull the first matching one out, you
+can pass the `:locales` option an array of top-level locale keys.
+
+```ruby
+messages = {
+  'en' => {
+    'title' => 'Login',
+    'description' => 'English description.'
+  },
+  'fr' => {
+    'title' => 'la connexion'
+  }
+}
+
+i18n = Tater.new(messages: messages)
+i18n.translate('title', locales: %w[fr en]) # => 'la connexion'
+i18n.translate('description', locales: %w[fr en]) # => 'English description.'
+```
+
+Locales will tried in order and which one matches first will be returned.
+
+
 ## Limitations
 
 - It is not "pluggable", it does what it does and that's it.

data/lib/tater.rb

@@ -82,7 +82,8 @@ class Tater
   # @return [Hash]
   attr_reader :messages
 
-  def initialize(path: nil, messages: nil, locale: DEFAULT_LOCALE)
+  def initialize(path: nil, messages: nil, locale: DEFAULT_LOCALE, cascade: false)
+    @cascade = cascade
     @locale = locale
     @messages = {}
 
@@ -90,6 +91,11 @@ class Tater
     load(messages: messages) if messages
   end
 
+  # @return [Boolean]
+  def cascades?
+    @cascade
+  end
+
   # An array of the available locale codes.
   #
   # @return [Array]
@@ -114,7 +120,11 @@ class Tater
   def load(path: nil, messages: nil)
     if path
       Dir.glob(File.join(path, '**', '*.{yml,yaml}')).each do |file|
-        Utils.deep_merge!(@messages, YAML.safe_load(File.read(file)))
+        Utils.deep_merge!(@messages, YAML.load_file(file))
+      end
+
+      Dir.glob(File.join(path, '**', '*.rb')).each do |file|
+        Utils.deep_merge!(@messages, Utils.deep_stringify_keys!(eval(IO.read(file), binding, file)))
       end
     end
 
@@ -144,8 +154,8 @@ class Tater
     when String
       object
     when Numeric
-      delimiter = lookup('numeric.delimiter', locale_override)
-      separator = lookup('numeric.separator', locale_override)
+      delimiter = options.delete(:delimiter) || lookup('numeric.delimiter', locale_override)
+      separator = options.delete(:separator) || lookup('numeric.separator', locale_override)
       precision = options.fetch(:precision) { 2 }
 
       raise(MissingLocalizationFormat, "Numeric localization delimiter ('numeric.delimiter') missing") unless delimiter
@@ -198,10 +208,22 @@ class Tater
   #
   # @return
   #   Basically anything that can be stored in YAML, including nil.
-  def lookup(key, locale_override = nil)
+  def lookup(key, locale_override = nil, cascade_override = nil)
     path = key.split(SEPARATOR).prepend(locale_override || locale).map(&:to_s)
 
-    @messages.dig(*path)
+    if cascade_override.nil? ? @cascade : cascade_override
+      while path.length >= 2 do
+        attempt = @messages.dig(*path)
+
+        if attempt
+          break attempt
+        else
+          path.delete_at(path.length - 2)
+        end
+      end
+    else
+      @messages.dig(*path)
+    end
   end
 
   # Translate a key path and optional interpolation arguments into a string.
@@ -212,14 +234,36 @@ class Tater
   #
   # @param key [String]
   #   The period-separated key path to look within our messages for.
+  # @option options [Boolean] :cascade
+  # @option options [String] :default
+  # @option options [String] :locale
   #
   # @return [String]
   #   The translated and interpreted string, if found, or any data at the
   #   defined key.
   def translate(key, options = {})
+    cascade_override = options.delete(:cascade)
+    default = options.delete(:default)
     locale_override = options.delete(:locale)
+    locales = options.delete(:locales)
+
+    message =
+      if locale_override || !locales
+        lookup(key, locale_override, cascade_override)
+      elsif locales
+        locales.find do |accept|
+          found = lookup(key, accept, cascade_override)
+
+          break found if found
+        end
+      end
+
+    # Call procs that should return a string.
+    if message.is_a?(Proc)
+      message = message.call(key, options)
+    end
 
-    Utils.interpolate(lookup(key, locale_override), options) || "Tater lookup failed: #{ locale_override || locale }.#{ key }"
+    Utils.interpolate(message, options) || default || "Tater lookup failed: #{ locale_override || locales || locale }.#{ key }"
   end
   alias t translate
 end

data/test/{fixtures.yml → fixtures/fixtures.yml}

@@ -1,4 +1,6 @@
 en:
+  english: 'Found in English'
+
   title: 'This is a title'
   interpolated: 'This has some %{fancy} text'
   double: '%{first} %{second}!'
@@ -23,7 +25,15 @@ en:
     delimiter: 'TURKEYS'
     separator: 'NAH'
 
+  cascade:
+    tacos: 'Delicious'
+
+    another:
+      crazy: 'Whoaa'
+
 fr:
+  french: 'Found in French'
+
   time:
     am: 'am'
     pm: 'pm'

data/test/fixtures/ruby.rb

@@ -0,0 +1,10 @@
+{
+  en: {
+    ruby: proc do |key, options = {}|
+      "Hey #{ key }!"
+    end,
+    options: proc do |_key, options = {}|
+      "Hey %{options}!"
+    end
+  }
+}

data/test/tater_test.rb

@@ -49,7 +49,7 @@ describe Tater do
 
   describe '#available?' do
     let :i18n do
-      Tater.new(path: File.expand_path('test'))
+      Tater.new(path: File.expand_path('test/fixtures'))
     end
 
     it 'tells you if the locale is available' do
@@ -60,14 +60,14 @@ describe Tater do
 
   describe '#load' do
     it 'loads from a path on initialization' do
-      i18n = Tater.new(path: File.expand_path('test'))
+      i18n = Tater.new(path: File.expand_path('test/fixtures'))
 
       assert_instance_of(Hash, i18n.messages)
     end
 
     it 'loads from a path after initialization' do
       i18n = Tater.new
-      i18n.load(path: File.expand_path('test'))
+      i18n.load(path: File.expand_path('test/fixtures'))
 
       assert_instance_of(Hash, i18n.messages)
     end
@@ -88,7 +88,7 @@ describe Tater do
 
   describe '#available' do
     let :i18n do
-      Tater.new(path: File.expand_path('test'))
+      Tater.new(path: File.expand_path('test/fixtures'))
     end
 
     it 'returns an array with the available locales (i.e. the top-level keys in our messages hash)' do
@@ -98,7 +98,7 @@ describe Tater do
 
   describe '#lookup' do
     let :i18n do
-      Tater.new(path: File.expand_path('test'))
+      Tater.new(path: File.expand_path('test/fixtures'))
     end
 
     it 'returns keys from messages' do
@@ -112,11 +112,17 @@ describe Tater do
     it 'returns nil for missing lookups' do
       assert_nil i18n.lookup('nope')
     end
+
+    it 'cascades' do
+      assert_equal 'Delicious', i18n.lookup('cascade.nope.tacos', nil, true)
+      assert_equal 'Whoaa', i18n.lookup('cascade.another.nope.crazy', nil, true)
+      assert_nil i18n.lookup('cascade.nahhhhhh')
+    end
   end
 
   describe '#translate' do
     let :i18n do
-      Tater.new(path: File.expand_path('test'))
+      Tater.new(path: File.expand_path('test/fixtures'))
     end
 
     it 'translates strings' do
@@ -148,11 +154,32 @@ describe Tater do
     it 'is aliased as t' do
       assert_equal 'This is a title', i18n.t('title')
     end
+
+    it 'cascades lookups' do
+      assert_equal 'Tater lookup failed: en.cascade.nope.tacos', i18n.translate('cascade.nope.tacos')
+      assert_equal 'Delicious', i18n.translate('cascade.nope.tacos', cascade: true)
+    end
+
+    it 'defaults lookups' do
+      assert_equal 'Tater lookup failed: en.default.missing', i18n.translate('default.missing')
+      assert_equal 'Nope', i18n.translate('default.missing', default: 'Nope')
+    end
+
+    it 'does lookups across different locales' do
+      assert_equal 'Found in French', i18n.translate('french', locales: %w[fr en])
+      assert_equal 'Found in English', i18n.translate('english', locales: %w[fr en])
+      assert_equal 'Tater lookup failed: ["fr", "en"].neither', i18n.translate('neither', locales: %w[fr en])
+    end
+
+    it 'finds Ruby files as well' do
+      assert_equal 'Hey ruby!', i18n.translate('ruby')
+      assert_equal 'Hey options!', i18n.translate('options', options: 'options')
+    end
   end
 
   describe '#localize' do
     let :i18n do
-      Tater.new(path: File.expand_path('test'))
+      Tater.new(path: File.expand_path('test/fixtures'))
     end
 
     it 'localizes Dates' do
@@ -179,6 +206,11 @@ describe Tater do
       assert_equal '1NAH12', i18n.localize(BigDecimal('1.12'))
     end
 
+    it 'allows overriding the delimiter and separator' do
+      assert_equal '10WOO000NAH12', i18n.localize(10_000.12, delimiter: 'WOO')
+      assert_equal '10TURKEYS000YA12', i18n.localize(10_000.12, separator: 'YA')
+    end
+
     it 'accepts other formats' do
       assert_equal '1 something 1 oh my 1970', i18n.localize(Date.new(1970, 1, 1), format: 'ohmy')
     end
@@ -205,7 +237,7 @@ describe Tater do
 
     describe 'month, day, and AM/PM names' do
       let :i18n do
-        Tater.new(path: File.expand_path('test'), locale: 'fr')
+        Tater.new(path: File.expand_path('test/fixtures'), locale: 'fr')
       end
 
       it 'localizes day names' do
@@ -269,7 +301,7 @@ describe Tater do
 
   describe '#locale=' do
     let :i18n do
-      Tater.new(path: File.expand_path('test'))
+      Tater.new(path: File.expand_path('test/fixtures'))
     end
 
     it 'overrides the locale when available' do
@@ -282,4 +314,22 @@ describe Tater do
       assert_equal 'en', i18n.locale
     end
   end
+
+  describe '#cascades?' do
+    let :default do
+      Tater.new
+    end
+
+    let :cascade do
+      Tater.new(cascade: true)
+    end
+
+    it 'returns false by default' do
+      refute default.cascades?
+    end
+
+    it 'returns true when passed during initialization' do
+      assert cascade.cascades?
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tater
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Evan Lecklider
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-17 00:00:00.000000000 Z
+date: 2019-07-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -48,9 +48,10 @@ files:
 - LICENSE.txt
 - README.md
 - lib/tater.rb
-- test/another.yml
-- test/fixtures.yml
-- test/messages/more.yml
+- test/fixtures/another.yml
+- test/fixtures/fixtures.yml
+- test/fixtures/messages/more.yml
+- test/fixtures/ruby.rb
 - test/tater_test.rb
 homepage: https://github.com/evanleck/tater
 licenses:
@@ -71,14 +72,15 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.0.4
 signing_key: 
 specification_version: 4
 summary: Minimal internationalization and localization library.
 test_files:
-- test/messages/more.yml
-- test/fixtures.yml
+- test/fixtures/messages/more.yml
+- test/fixtures/ruby.rb
+- test/fixtures/fixtures.yml
+- test/fixtures/another.yml
 - test/tater_test.rb
-- test/another.yml