tater 1.3.1 → 2.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcee8d4b1aa16306c1ca8b0ce013e2210a317a05b4c3b466a37203600fb90237
-  data.tar.gz: a00686eebe67c2c0e8cb92c6d0c82c45664cacddc17111f6f4fcb6f539439841
+  metadata.gz: 7e5ec34021f3488e2ef8ef3365abc37258813e5d9a79b8dbd0a49fb8254c946a
+  data.tar.gz: 8613b2a54d59d0b4a64f84790e60f55316447714d6013a6751041a2aa9dada6a
 SHA512:
-  metadata.gz: 4157223bbd415daaf23d494aea0c16a42708d92629119b8c1f3071bf424dfa29775aac52b136af669fe5b24b17c4f521271f76921f3c7d04da8c15921227ee7d
-  data.tar.gz: 29ab82f420856629db3c559594fa0bf8a6abb8b5bc24295913528945cfb823f80eb3646b616ae749ad88d4b457229fd5b6005d50bc9b6aece52617152313c457
+  metadata.gz: f65062d798ace02b68084b1a9189f09c092e32f2a819bd88909d651038a205a36b60816f8c6e890614c9aaea1a17e074b89a7f3a5163969bf10c6f35a8eac56e
+  data.tar.gz: cf3ae7da9a2d911f90aa93dd1f2e088425becf21d2b5558c485d86002bcccf09a4bdccfed39385442a7865a27e76196aa68bf90b259ea30f5b8beeda8eb1807c

data/{README.md → README.org}

@@ -1,112 +1,111 @@
-# Tater 
+* Tater
 
-[![Gem Version](https://badge.fury.io/rb/tater.svg)](https://badge.fury.io/rb/tater)
-[![Build Status](https://secure.travis-ci.org/evanleck/tater.svg)](https://travis-ci.org/evanleck/tater)
+[[https://badge.fury.io/rb/tater][https://badge.fury.io/rb/tater.svg]]
 
 Tater is an internationalization (i18n) and localization (l10n) library designed
 for simplicity. It doesn't do everything that other libraries do, but that's by
 design.
 
-Under the hood, Tater uses a Hash to store the messages, the `dig` method for
-lookups, `strftime` for date and time localizations, and `format` for
+Under the hood, Tater uses a Hash to store the messages, the =dig= method for
+lookups, =strftime= for date and time localizations, and =format= for
 interpolation. That's probably 90% of what Tater does.
 
-
-## Installation
+** Installation
 
 Tater requires Ruby 2.5 or higher. To install Tater, add this line to your
 application's Gemfile (or gems.rb):
 
-```ruby
+#+begin_src ruby
 gem 'tater'
-```
+#+end_src
 
 And then execute:
 
-```sh
+#+begin_src sh
 bundle
-```
+#+end_src
 
-Or install it yourself as:
+Or install it yourself by running:
 
-```sh
+#+begin_src sh
 gem install tater
-```
-
+#+end_src
 
-## Usage
+** Usage
 
-```ruby
+#+begin_src ruby
 require 'tater'
 
 messages = {
-  'some' => {
-    'key' => 'This here string!'
-  },
-  'interpolated' => 'Hello %{you}!'
+  'en' => {
+    'some' => {
+      'key' => 'This here string!'
+    },
+    'interpolated' => 'Hello %{you}!'
+  }
 }
 
-i18n = Tater.new
+i18n = Tater.new(locale: 'en')
 i18n.load(messages: messages)
 
+# OR
+i18n = Tater.new(locale: 'en', messages: messages)
+
 # Basic lookup:
 i18n.translate('some.key') # => 'This here string!'
 
 # Interpolation:
 i18n.translate('interpolated', you: 'world') # => 'Hello world!'
-```
-
+#+end_src
 
-## Array Localization
+** Array localization
 
 Given an array, Tater will do it's best to join the elements of the array into a
 sentence based on how many elements there are.
 
-```yaml
+#+begin_example
 en:
   array:
     last_word_connector: ", and "
     two_words_connector: " and "
     words_connector: ", "
-```
+#+end_example
 
-```ruby
+#+begin_src ruby
 i18n.localize(%w[tacos enchiladas burritos]) # => "tacos, enchiladas, and burritos"
-```
-
+#+end_src
 
-## Numeric Localization
+** Numeric localization
 
-Numeric localization (`Numeric`, `Integer`, `Float`, and `BigDecimal`) require
+Numeric localization (=Numeric=, =Integer=, =Float=, and =BigDecimal=) require
 filling in a separator and delimiter. For example:
 
-```yaml
+#+begin_example
 en:
   numeric:
     delimiter: ','
     separator: '.'
-```
+#+end_example
 
 With that, you can do things like this:
 
-```ruby
+#+begin_src ruby
 i18n.localize(1000.2) # => "1,000.20"
-```
+#+end_src
 
 The separator and delimiter can also be passed in per-call:
 
-```ruby
+#+begin_src ruby
 i18n.localize(1000.2, delimiter: '_', separator: '+') # => "1_000+20"
-```
+#+end_src
 
+** Date and time localization
 
-## Date and Time Localization
-
-Date and time localization (`Date`, `Time`, and `DateTime`) require filling in
+Date and time localization (=Date=, =Time=, and =DateTime=) require filling in
 all of the needed names and abbreviations for days and months. Here's the
 example for French, which is used in the tests.
 
-```yaml
+#+begin_example
 fr:
   time:
     am: 'am'
@@ -169,96 +168,95 @@ fr:
       - oct.
       - nov.
       - déc.
-```
+#+end_example
 
-The statically defined keys for dates are `days`, `abbreviated_days`, `months`,
-and `abbreviated_months`. Only `am` and `pm` are needed for times and only if
-you plan on using the `%p` or `%P` format strings.
+The statically defined keys for dates are =days=, =abbreviated_days=, =months=,
+and =abbreviated_months=. Only =am= and =pm= are needed for times and only if
+you plan on using the =%p= or =%P= format strings.
 
 With all of that, you can do something like:
 
-```ruby
+#+begin_src ruby
 i18n.localize(Date.new(1970, 1, 1), format: '%A') # => 'jeudi'
 
 # Or, using a key defined in "formats":
 i18n.localize(Date.new(1970, 1, 1), format: 'day') # => 'jeudi'
-```
-
+#+end_src
 
-## Cascading Lookups
+** Cascading lookups
 
-Lookups can be cascaded, i.e. pieces of the scope of the can be lopped off
+Lookups can be cascaded, i.e. pieces of the scope of the can be lopped off
 incrementally.
 
-```ruby
+#+begin_src ruby
 messages = {
-  'login' => {
-    'title' => 'Login',
-    'description' => 'Normal description.'
+  'en' => {
+    'login' => {
+      'title' => 'Login',
+      'description' => 'Normal description.'
 
-    'special' => {
-      'title' => 'Special Login'
+      'special' => {
+        'title' => 'Special Login'
+      }
     }
   }
 }
 
-i18n = Tater.new(messages: messages)
+i18n = Tater.new(locale: 'en', 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.'
-```
+#+end_src
 
 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'`
+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
+#+begin_src ruby
 Tater.new(cascade: true)
-```
+#+end_src
 
 Cascading is off by default.
 
-
-## Defaults
+** Defaults
 
 If you'd like to default to another value in case of a missed lookup, you can
-provide the `:default` option to `#translate`.
+provide the =:default= option to =#translate=.
 
-```ruby
+#+begin_src ruby
 Tater.new.translate('nope', default: 'Yep!') # => 'Yep!'
-```
-
+#+end_src
 
-## Procs and Messages in Ruby
+** 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 file returns a =Hash= when evalled.
 
-```ruby
+#+begin_src ruby
 {
-  en: {
+  'en' => {
     ruby: proc do |key, options = {}|
       "Hey #{ key }!"
     end
   }
 }
-```
-
+#+end_src
 
-## Multiple Locales
+** 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.
+If you would like to check multiple locales and pull the first matching one out,
+you can pass the =:locales= option to initialization or the =translate= method
+with an array of top-level locale keys.
 
-```ruby
+#+begin_src ruby
 messages = {
   'en' => {
     'title' => 'Login',
@@ -272,31 +270,28 @@ messages = {
 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.
+# OR
+i18n = Tater.new(messages: messages, locales: %w[fr en])
+i18n.translate('title') # => 'la connexion'
+i18n.translate('description') # => 'English description.'
+#+end_src
 
+Locales will be tried in order and whichever one matches first will be returned.
 
-## Limitations
+** Limitations
 
-- It is not "pluggable", it does what it does and that's it.
+- It is not pluggable, it does what it does and that's it.
 - It doesn't handle pluralization yet, though it may in the future.
-- It doesn't cache anything, that's up to you.
-
-
-## Why?
-
-Because [Ruby I18n][rubyi18n] is amazing and I wanted to try to create a minimum
-viable implementation of the bits of I18n that I use 90% of the time. Tater is a
-single file that handles the basics of lookup and interpolation.
 
+** Why?
 
-## Trivia
+Because [[https://github.com/ruby-i18n/i18n][Ruby I18n]] is amazing and I wanted to try to create a minimum viable
+implementation of the bits of I18n that I use 90% of the time. Tater is a single
+file that handles the basics of lookup and interpolation.
 
-I was orininally going to call this library "Translator" but with a
-[numeronym][numeronym] like I18n: "t8r". I looked at it for a while but I read
-it as "tater" instead of "tee-eight-arr" so I figured I'd just name it Tater.
-Tater the translator.
+** Trivia
 
-[numeronym]: https://en.wikipedia.org/wiki/Numeronym
-[rubyi18n]: https://github.com/ruby-i18n/i18n
+I was orininally going to call this library "Translator" but with a [[https://en.wikipedia.org/wiki/Numeronym][numeronym]]
+like I18n: "t8r".  I looked at it for a while but I read it as "tater" instead
+of "tee-eight-arr" so I figured I'd just name it Tater. Tater the translator.

data/lib/tater.rb

@@ -1,25 +1,28 @@
 # frozen_string_literal: true
 require 'bigdecimal'
+require 'date'
+require 'time'
 require 'yaml'
 
 # Tater is a internationalization (i18n) and localization (l10n) library
 # designed for speed and simplicity.
 class Tater
   class MissingLocalizationFormat < ArgumentError; end
+
   class UnLocalizableObject < ArgumentError; end
 
   module Utils # :nodoc:
     # Merge all the way down.
     #
     # @param to [Hash]
-    #   The target Hash to merge into. Note that modification is done in-place,
-    #   not on a copy of the object.
+    #   The target Hash to merge into.
     # @param from [Hash]
     #   The Hash to copy values from.
-    def self.deep_merge!(to, from)
-      to.merge!(from) do |_key, left, right|
+    # @return [Hash]
+    def self.deep_merge(to, from)
+      to.merge(from) do |_key, left, right|
         if left.is_a?(Hash) && right.is_a?(Hash)
-          Utils.deep_merge!(left, right)
+          Utils.deep_merge(left, right)
         else
           right
         end
@@ -29,18 +32,32 @@ class Tater
     # Transform keys all the way down.
     #
     # @param hash [Hash]
-    #   The Hash to modify. Note that modification is done in-place, not on a copy
-    #   of the object.
-    def self.deep_stringify_keys!(hash)
-      hash.transform_keys!(&:to_s).transform_values! do |value|
+    #   The Hash to stringify keys for.
+    # @return [Hash]
+    def self.deep_stringify_keys(hash)
+      hash.transform_keys(&:to_s).transform_values do |value|
         if value.is_a?(Hash)
-          Utils.deep_stringify_keys!(value)
+          Utils.deep_stringify_keys(value)
         else
           value
         end
       end
     end
 
+    # Freeze all the way down.
+    #
+    # @param hash [Hash]
+    # @return [Hash]
+    def self.deep_freeze(hash)
+      hash.transform_keys(&:freeze).transform_values do |value|
+        if value.is_a?(Hash)
+          Utils.deep_freeze(value)
+        else
+          value.freeze
+        end
+      end.freeze
+    end
+
     # Try to interpolate these things, if one of them is a string.
     #
     # @param string [String]
@@ -49,8 +66,9 @@ class Tater
     #   The values to interpolate into the target string.
     #
     # @return [String]
-    def self.interpolate(string, options = {})
+    def self.interpolate(string, options = HASH)
       return string unless string.is_a?(String)
+      return string if options.empty?
 
       format(string, options)
     end
@@ -71,8 +89,8 @@ class Tater
   end
 
   DEFAULT = 'default'
-  DEFAULT_LOCALE = 'en'
   DELIMITING_REGEX = /(\d)(?=(\d\d\d)+(?!\d))/.freeze
+  HASH = {}.freeze
   SEPARATOR = '.'
   SUBSTITUTION_REGEX = /%(|\^)[aAbBpP]/.freeze
 
@@ -82,7 +100,16 @@ class Tater
   # @return [Hash]
   attr_reader :messages
 
-  def initialize(path: nil, messages: nil, locale: DEFAULT_LOCALE, cascade: false)
+  # @param cascade [Boolean]
+  #   A boolean indicating if lookups should cascade by default.
+  # @param locale [String]
+  #   The default locale.
+  # @param messages [Hash]
+  #   A hash of messages ready to be loaded in.
+  # @param path [String]
+  #   A path to search for YAML or Ruby files to load messages from.
+  def initialize(cascade: false, locale: nil, messages: nil, path: nil)
+    @cache = {}
     @cascade = cascade
     @locale = locale
     @messages = {}
@@ -98,11 +125,11 @@ class Tater
     @cascade
   end
 
-  # An array of the available locale codes.
+  # An array of the available locale codes found in loaded messages.
   #
   # @return [Array]
   def available
-    messages.keys.map(&:to_s)
+    @available ||= messages.keys
   end
 
   # Is this locale available in our current set of messages?
@@ -113,24 +140,36 @@ class Tater
   end
 
   # Load messages into our internal cache, either from a path containing YAML
-  # files or a collection of messages.
+  # files or a Hash of messages.
   #
   # @param path [String]
   #   A path to search for YAML or Ruby files to load messages from.
   # @param messages [Hash]
   #   A hash of messages ready to be loaded in.
   def load(path: nil, messages: nil)
+    return if path.nil? && messages.nil?
+
     if path
       Dir.glob(File.join(path, '**', '*.{yml,yaml}')).each do |file|
-        Utils.deep_merge!(@messages, YAML.load_file(file))
+        @messages = 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))) # rubocop:disable Security/Eval
+        @messages = Utils.deep_merge(@messages, Utils.deep_stringify_keys(eval(IO.read(file), binding, file))) # rubocop:disable Security/Eval
       end
     end
 
-    Utils.deep_merge!(@messages, Utils.deep_stringify_keys!(messages)) if messages
+    @messages = Utils.deep_merge(@messages, Utils.deep_stringify_keys(messages)) if messages
+    @messages = Utils.deep_freeze(@messages)
+
+    # Gotta recalculate available locales after updating.
+    remove_instance_variable(:@available) if instance_variable_defined?(:@available)
+
+    # Not only does this clear our cache but it establishes the basic structure
+    # that we rely on in other methods.
+    @messages.each_key do |key|
+      @cache[key] = { true => {}, false => {} }
+    end
   end
 
   # Set the current locale, if it's available.
@@ -143,7 +182,7 @@ class Tater
 
   # Localize an Array, Date, Time, DateTime, or Numeric object.
   #
-  # @param object [Date, Time, DateTime, Numeric]
+  # @param object [Array<String>, Date, Time, DateTime, Numeric]
   #   The object to localize.
   # @param options [Hash]
   #   Options to configure localization.
@@ -153,9 +192,9 @@ class Tater
   # @option options [String] :locale
   #   The locale to use in lieu of the current default.
   # @option options [String] :delimiter
-  #   The delimiter to use when localizing numberic values.
+  #   The delimiter to use when localizing numeric values.
   # @option options [String] :separator
-  #   The separator to use when localizing numberic values.
+  #   The separator to use when localizing numeric values.
   # @option options [String] :two_words_connector
   #   The string used to join two array elements together e.g. " and ".
   # @option options [String] :words_connector
@@ -166,75 +205,16 @@ class Tater
   #
   # @return [String]
   #   A localized version of the object passed in.
-  def localize(object, options = {})
-    format_key = options.delete(:format) || DEFAULT
-    locale_override = options.delete(:locale)
-
+  def localize(object, options = HASH)
     case object
     when String
       object
     when Numeric
-      delimiter = options.delete(:delimiter) || lookup('numeric.delimiter', locale_override)
-      separator = options.delete(:separator) || lookup('numeric.separator', locale_override)
-      precision = options.delete(:precision) || 2
-
-      raise(MissingLocalizationFormat, "Numeric localization delimiter ('numeric.delimiter') missing or not passed as option :delimiter") unless delimiter
-      raise(MissingLocalizationFormat, "Numeric localization separator ('numeric.separator') missing or not passed as option :separator") unless separator
-
-      # Heavily cribbed from Rails.
-      integer, fraction = Utils.string_from_numeric(object).split('.')
-      integer.gsub!(DELIMITING_REGEX) do |number|
-        "#{ number }#{ delimiter }"
-      end
-
-      if precision.zero?
-        integer
-      else
-        [integer, fraction&.ljust(precision, '0')].compact.join(separator)
-      end
+      localize_numeric(object, options)
     when Date, Time, DateTime
-      key = object.class.to_s.downcase
-      format = lookup("#{ key }.formats.#{ format_key }", locale_override) || format_key
-
-      # Heavily cribbed from I18n, many thanks to the people who sorted this out
-      # before I worked on this library.
-      format = format.gsub(SUBSTITUTION_REGEX) do |match|
-        case match
-        when '%a'  then lookup('date.abbreviated_days', locale_override)[object.wday]
-        when '%^a' then lookup('date.abbreviated_days', locale_override)[object.wday].upcase
-        when '%A'  then lookup('date.days', locale_override)[object.wday]
-        when '%^A' then lookup('date.days', locale_override)[object.wday].upcase
-        when '%b'  then lookup('date.abbreviated_months', locale_override)[object.mon - 1]
-        when '%^b' then lookup('date.abbreviated_months', locale_override)[object.mon - 1].upcase
-        when '%B'  then lookup('date.months', locale_override)[object.mon - 1]
-        when '%^B' then lookup('date.months', locale_override)[object.mon - 1].upcase
-        when '%p'  then lookup("time.#{ object.hour < 12 ? 'am' : 'pm' }", locale_override).upcase if object.respond_to?(:hour) # rubocop:disable Metrics/BlockNesting
-        when '%P'  then lookup("time.#{ object.hour < 12 ? 'am' : 'pm' }", locale_override).downcase if object.respond_to?(:hour) # rubocop:disable Metrics/BlockNesting
-        end
-      end
-
-      object.strftime(format)
+      localize_datetime(object, options)
     when Array
-      case object.length
-      when 0
-        ''
-      when 1
-        object[0]
-      when 2
-        two_words_connector = options.delete(:two_words_connector) || lookup('array.two_words_connector', locale_override)
-
-        raise(MissingLocalizationFormat, "Sentence localization connector ('array.two_words_connector') missing or not passed as option :two_words_connector") unless two_words_connector
-
-        "#{ object[0] }#{ two_words_connector }#{ object[1] }"
-      else
-        last_word_connector = options.delete(:last_word_connector) || lookup('array.last_word_connector', locale_override)
-        words_connector = options.delete(:words_connector) || lookup('array.words_connector', locale_override)
-
-        raise(MissingLocalizationFormat, "Sentence localization connector ('array.last_word_connector') missing or not passed as option :last_word_connector") unless last_word_connector
-        raise(MissingLocalizationFormat, "Sentence localization connector ('array.words_connector') missing or not passed as option :words_connector") unless words_connector
-
-        "#{ object[0...-1].join(words_connector) }#{ last_word_connector }#{ object[-1] }"
-      end
+      localize_array(object, options)
     else
       raise(UnLocalizableObject, "The object class #{ object.class } cannot be localized by Tater.")
     end
@@ -244,26 +224,36 @@ class Tater
   # Lookup a key in the messages hash, using the current locale or an override.
   #
   # @param key [String]
-  # @param locale_override [String]
+  # @param locale [String]
   #   A locale to use instead of our current one.
-  # @param cascade_override [Boolean]
+  # @param cascade [Boolean]
   #   A boolean to forcibly set the cascade option for this lookup.
   #
   # @return
-  #   Basically anything that can be stored in YAML, including nil.
-  def lookup(key, locale_override = nil, cascade_override = nil)
-    path = key.split(SEPARATOR).prepend(locale_override || locale).map(&:to_s)
+  #   Basically anything that can be stored in your messages Hash.
+  def lookup(key, locale: nil, cascade: nil)
+    locale = locale.nil? ? @locale : locale
+    cascade = cascade.nil? ? @cascade : cascade
 
-    if cascade_override.nil? ? @cascade : cascade_override
-      while path.length >= 2
-        attempt = @messages.dig(*path)
+    cached(key, locale, cascade) || begin
+      return nil unless @messages.key?(locale.to_s)
 
-        break attempt if attempt
+      path = key.split(SEPARATOR).prepend(locale).map(&:to_s)
 
-        path.delete_at(path.length - 2)
-      end
-    else
-      @messages.dig(*path)
+      message =
+        if cascade
+          while path.length >= 2
+            attempt = @messages.dig(*path)
+
+            break attempt unless attempt.nil?
+
+            path.delete_at(path.length - 2)
+          end
+        else
+          @messages.dig(*path)
+        end
+
+      cache(key, locale, cascade, message)
     end
   end
 
@@ -283,20 +273,18 @@ class Tater
   #   An array of locales to look within.
   #
   # @return [Boolean]
-  def includes?(key, options = {})
-    cascade_override = options.delete(:cascade)
-    locale_override = options.delete(:locale)
-    locales = options.delete(:locales)
-
+  def includes?(key, options = HASH)
     message =
-      if locale_override || !locales
-        lookup(key, locale_override, cascade_override)
-      else
-        locales.find do |accept|
-          found = lookup(key, accept, cascade_override)
+      if options.key?(:locales)
+        options[:locales].append(@locale) if @locale && !options[:locales].include?(@locale)
+
+        options[:locales].find do |accept|
+          found = lookup(key, locale: accept, cascade: options[:cascade])
 
-          break found if found
+          break found unless found.nil?
         end
+      else
+        lookup(key, locale: options[:locale], cascade: options[:cascade])
       end
 
     !message.nil?
@@ -306,7 +294,7 @@ class Tater
   # It's effectively a combination of #lookup and #interpolate.
   #
   # @example
-  #   Tater.new(messages: { 'en' => { 'hi' => 'Hello' }}).translate('hi') # => 'Hello'
+  #   Tater.new(locale: 'en', messages: { 'en' => { 'hi' => 'Hello' }}).translate('hi') # => 'Hello'
   #
   # @param key [String]
   #   The period-separated key path to look within our messages for.
@@ -318,36 +306,162 @@ class Tater
   # @option options [String] :default
   #   A default string to return, should lookup fail.
   # @option options [String] :locale
-  #   A specific locale to lookup within. This will take precedence over the
-  #   :locales option.
+  #   A specific locale to lookup within.
   # @option options [Array<String>] :locales
-  #   An array of locales to look within.
+  #   An array of locales to look within. This will take precedence over the
+  #   :locale option and will append the default :locale option passed during
+  #   initialization if present.
   #
   # @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)
-    locale_override = options.delete(:locale)
-    locales = options.delete(:locales)
-
+  def translate(key, options = HASH)
     message =
-      if locale_override || !locales
-        lookup(key, locale_override, cascade_override)
-      else
-        locales.find do |accept|
-          found = lookup(key, accept, cascade_override)
+      if options.key?(:locales)
+        options[:locales].append(@locale) if @locale && !options[:locales].include?(@locale)
 
-          break found if found
+        options[:locales].find do |accept|
+          found = lookup(key, locale: accept, cascade: options[:cascade])
+
+          break found unless found.nil?
         end
+      else
+        lookup(key, locale: options[:locale], cascade: options[:cascade])
       end
 
     # Call procs that should return a string.
-    if message.is_a?(Proc)
-      message = message.call(key, options)
-    end
+    message = message.call(key, options) if message.is_a?(Proc)
 
-    Utils.interpolate(message, options) || options.delete(:default) { "Tater lookup failed: #{ locale_override || locales || locale }.#{ key }" }
+    Utils.interpolate(message, options) || options[:default] || "Tater lookup failed: #{ options[:locale] || options[:locales] || locale }.#{ key }"
   end
   alias t translate
+
+  private
+
+  # @param key [String]
+  #   The cache key, often in the form "something.nested.like.this"
+  # @param locale [String]
+  #   The locale to store the value for.
+  # @param cascade [Boolean]
+  #   Was this a cascading lookup?
+  # @param message [String]
+  #   The message being cached, often a String.
+  # @return [String]
+  #   Whatever value is being cached, often a String.
+  def cache(key, locale, cascade, message)
+    @cache[locale][cascade][key] = message
+  end
+
+  # @param key [String]
+  #   The cache key, often in the form "something.nested.like.this"
+  # @param locale [String]
+  #   The locale to store the value for.
+  # @param cascade [Boolean]
+  #   Was this a cascading lookup?
+  # @return [String, nil]
+  #   The cached message or nil.
+  def cached(key, locale, cascade)
+    @cache.dig(locale, cascade, key)
+  end
+
+  # Localize an Array object.
+  #
+  # @param object [Array<String>]
+  #   The array to localize.
+  # @param options [Hash]
+  #   Options to configure localization.
+  # @return [String]
+  #   The localize array string.
+  def localize_array(object, options)
+    case object.length
+    when 0
+      ''
+    when 1
+      object[0]
+    when 2
+      two_words_connector = options[:two_words_connector] || lookup('array.two_words_connector', locale: options[:locale])
+
+      raise(MissingLocalizationFormat, "Sentence localization connector ('array.two_words_connector') missing or not passed as option :two_words_connector") unless two_words_connector
+
+      "#{ object[0] }#{ two_words_connector }#{ object[1] }"
+    else
+      last_word_connector = options[:last_word_connector] || lookup('array.last_word_connector', locale: options[:locale])
+      words_connector = options[:words_connector] || lookup('array.words_connector', locale: options[:locale])
+
+      raise(MissingLocalizationFormat, "Sentence localization connector ('array.last_word_connector') missing or not passed as option :last_word_connector") unless last_word_connector
+      raise(MissingLocalizationFormat, "Sentence localization connector ('array.words_connector') missing or not passed as option :words_connector") unless words_connector
+
+      "#{ object[0...-1].join(words_connector) }#{ last_word_connector }#{ object[-1] }"
+    end
+  end
+
+  # Localize a Date, DateTime, or Time object.
+  #
+  # @param object [Date, DateTime, Time]
+  #   The date-ish object to localize.
+  # @param options [Hash]
+  #   Options to configure localization.
+  # @return [String]
+  #   The localized date string.
+  def localize_datetime(object, options)
+    frmt = options[:format] || DEFAULT
+    loc = options[:locale]
+    format = lookup("#{ object.class.to_s.downcase }.formats.#{ frmt }", locale: loc) || frmt
+
+    # Heavily cribbed from I18n, many thanks to the people who sorted this out
+    # before I worked on this library.
+    format = format.gsub(SUBSTITUTION_REGEX) do |match|
+      case match
+      when '%a'  then lookup('date.abbreviated_days', locale: loc)[object.wday]
+      when '%^a' then lookup('date.abbreviated_days', locale: loc)[object.wday].upcase
+      when '%A'  then lookup('date.days', locale: loc)[object.wday]
+      when '%^A' then lookup('date.days', locale: loc)[object.wday].upcase
+      when '%b'  then lookup('date.abbreviated_months', locale: loc)[object.mon - 1]
+      when '%^b' then lookup('date.abbreviated_months', locale: loc)[object.mon - 1].upcase
+      when '%B'  then lookup('date.months', locale: loc)[object.mon - 1]
+      when '%^B' then lookup('date.months', locale: loc)[object.mon - 1].upcase
+      when '%p'  then lookup("time.#{ object.hour < 12 ? 'am' : 'pm' }", locale: loc).upcase if object.respond_to?(:hour)
+      when '%P'  then lookup("time.#{ object.hour < 12 ? 'am' : 'pm' }", locale: loc).downcase if object.respond_to?(:hour)
+      end
+    end
+
+    if format.include?('%')
+      object.strftime(format)
+    else
+      format
+    end
+  end
+
+  # Localize a Numeric object.
+  #
+  # @param object [Array<String>, Date, Time, DateTime, Numeric]
+  #   The object to localize.
+  # @param options [Hash]
+  #   Options to configure localization.
+  # @return [String]
+  #   The localized numeric string.
+  def localize_numeric(object, options)
+    delimiter = options[:delimiter] || lookup('numeric.delimiter', locale: options[:locale])
+    separator = options[:separator] || lookup('numeric.separator', locale: options[:locale])
+    precision = options[:precision] || 2
+
+    raise(MissingLocalizationFormat, "Numeric localization delimiter ('numeric.delimiter') missing or not passed as option :delimiter") unless delimiter
+    raise(MissingLocalizationFormat, "Numeric localization separator ('numeric.separator') missing or not passed as option :separator") unless separator
+
+    # Break the number up into integer and fraction parts.
+    integer = Utils.string_from_numeric(object)
+    integer, fraction = integer.split('.') unless object.is_a?(Integer)
+
+    if object >= 1_000
+      integer.gsub!(DELIMITING_REGEX) do |number|
+        "#{ number }#{ delimiter }"
+      end
+    end
+
+    if precision.zero? || fraction.nil?
+      integer
+    else
+      "#{ integer }#{ separator }#{ fraction.ljust(precision, '0').slice(0, precision) }"
+    end
+  end
 end

data/test/tater_test.rb

@@ -5,24 +5,34 @@ require 'date'
 
 describe Tater do
   describe Tater::Utils do
-    describe '#deep_merge!' do
-      it 'deeply merges two hashes, modifying the first' do
+    describe '#deep_merge' do
+      it 'deeply merges two hashes, returning a new one' do
         first = { 'one' => 'one', 'two' => { 'three' => 'three' } }
         second = { 'two' => { 'four' => 'four' } }
 
-        Tater::Utils.deep_merge!(first, second)
+        third = Tater::Utils.deep_merge(first, second)
 
-        assert_equal({ 'one' => 'one', 'two' => { 'three' => 'three', 'four' => 'four' } }, first)
+        assert_equal({ 'one' => 'one', 'two' => { 'three' => 'three', 'four' => 'four' } }, third)
       end
     end
 
-    describe '#deep_stringify_keys!' do
-      it 'converts all keys into strings, recursively modifying the hash passed in' do
+    describe '#deep_stringify_keys' do
+      it 'converts all keys into strings, recursively' do
         start = { en: { login: { title: 'Hello!' } } }
+        finish = Tater::Utils.deep_stringify_keys(start)
 
-        Tater::Utils.deep_stringify_keys!(start)
+        assert_equal({ 'en' => { 'login' => { 'title' => 'Hello!' } } }, finish)
+      end
+    end
 
-        assert_equal({ 'en' => { 'login' => { 'title' => 'Hello!' } } }, start)
+    describe '#deep_freeze' do
+      it 'freezes the keys and values, recursively' do
+        start = Tater::Utils.deep_stringify_keys({ en: { login: { title: 'Hello!' } } })
+        finish = Tater::Utils.deep_freeze(start)
+
+        assert finish.frozen?
+        assert finish.keys.all?(&:frozen?)
+        assert finish.values.all?(&:frozen?)
       end
     end
 
@@ -31,25 +41,29 @@ describe Tater do
         assert_equal 'this thing', Tater::Utils.interpolate('this %{what}', what: 'thing')
       end
 
-      it 'raises a KeyError when an argument is missing' do
+      it 'raises a KeyError when an argument is missing (but options are passed)' do
         assert_raises(KeyError) do
-          Tater::Utils.interpolate('this %{what}')
+          Tater::Utils.interpolate('this %{what}', nope: 'thing')
         end
       end
+
+      it 'returns the string unchanged when options are empty (does not raise a KeyError)' do
+        assert_equal 'this %{what}', Tater::Utils.interpolate('this %{what}')
+      end
     end
 
     describe '#string_from_numeric' do
       it 'converts numerics to decimal-ish strings' do
         assert_equal '1', Tater::Utils.string_from_numeric(1)
         assert_equal '1.0', Tater::Utils.string_from_numeric(1.0)
-        assert_equal '1.0', Tater::Utils.string_from_numeric(BigDecimal(1))
+        assert_equal '1.0', Tater::Utils.string_from_numeric(BigDecimal('1'))
       end
     end
   end
 
   describe '#available?' do
     let :i18n do
-      Tater.new(path: File.expand_path('test/fixtures'))
+      Tater.new(path: File.expand_path('test/fixtures'), locale: 'en')
     end
 
     it 'tells you if the locale is available' do
@@ -84,6 +98,14 @@ describe Tater do
 
       assert_instance_of(Hash, i18n.messages)
     end
+
+    it 'freezes messages after loading' do
+      i18n = Tater.new(messages: { 'hey' => 'Oh hi' })
+
+      assert i18n.messages.frozen?
+      assert i18n.messages.keys.all?(&:frozen?)
+      assert i18n.messages.values.all?(&:frozen?)
+    end
   end
 
   describe '#available' do
@@ -94,11 +116,17 @@ describe Tater do
     it 'returns an array with the available locales (i.e. the top-level keys in our messages hash)' do
       assert_equal %w[en delimiter_only separator_only fr].sort, i18n.available.sort
     end
+
+    it 'updates the available list when new messages are loaded' do
+      i18n.load(messages: { 'added' => { 'hey' => 'yeah' } })
+
+      assert_equal %w[en delimiter_only separator_only fr added].sort, i18n.available.sort
+    end
   end
 
   describe '#lookup' do
     let :i18n do
-      Tater.new(path: File.expand_path('test/fixtures'))
+      Tater.new(path: File.expand_path('test/fixtures'), locale: 'en')
     end
 
     it 'returns keys from messages' do
@@ -114,16 +142,16 @@ describe Tater do
     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.another.nope.crazy', nil, false)
+      assert_equal 'Delicious', i18n.lookup('cascade.nope.tacos', cascade: true)
+      assert_equal 'Whoaa', i18n.lookup('cascade.another.nope.crazy', cascade: true)
+      assert_nil i18n.lookup('cascade.another.nope.crazy', cascade: false)
       assert_nil i18n.lookup('cascade.nahhhhhh')
     end
   end
 
   describe '#translate' do
     let :i18n do
-      Tater.new(path: File.expand_path('test/fixtures'))
+      Tater.new(path: File.expand_path('test/fixtures'), locale: 'en')
     end
 
     it 'translates strings' do
@@ -181,7 +209,7 @@ describe Tater do
 
   describe '#localize' do
     let :i18n do
-      Tater.new(path: File.expand_path('test/fixtures'))
+      Tater.new(path: File.expand_path('test/fixtures'), locale: 'en')
     end
 
     let :fr do
@@ -237,6 +265,30 @@ describe Tater do
       assert_equal '1NAH12', i18n.localize(BigDecimal('1.12'))
     end
 
+    describe 'precision option' do
+      it 'defaults to 2' do
+        assert_equal '10NAH00', i18n.localize(BigDecimal('10'))
+        assert_equal '10NAH00', i18n.localize(10.0)
+      end
+
+      it 'defaults to zero for integers' do
+        assert_equal '10', i18n.localize(10)
+      end
+
+      it 'removes fractional pieces when the precision is 0' do
+        assert_equal '10', i18n.localize(BigDecimal('10.123456'), precision: 0)
+        assert_equal '10', i18n.localize(10.123456, precision: 0)
+
+        assert_equal '10', i18n.localize(BigDecimal('10.12'), precision: 0)
+        assert_equal '10', i18n.localize(10.12, precision: 0)
+      end
+
+      it 'truncates long values to the desired precision' do
+        assert_equal '10NAH00', i18n.localize(BigDecimal('10.00234'))
+        assert_equal '10NAH00', i18n.localize(10.00234)
+      end
+    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')
@@ -332,7 +384,7 @@ describe Tater do
 
   describe '#locale=' do
     let :i18n do
-      Tater.new(path: File.expand_path('test/fixtures'))
+      Tater.new(path: File.expand_path('test/fixtures'), locale: 'en')
     end
 
     it 'overrides the locale when available' do
@@ -366,7 +418,7 @@ describe Tater do
 
   describe '#includes?' do
     let :i18n do
-      Tater.new(path: File.expand_path('test/fixtures'))
+      Tater.new(path: File.expand_path('test/fixtures'), locale: 'en')
     end
 
     it 'tells you if you have a translation' do

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: tater
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 2.0.3
 platform: ruby
 authors:
 - Evan Lecklider
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-08-18 00:00:00.000000000 Z
+date: 2021-06-22 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -24,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -38,6 +66,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Minimal internationalization and localization library.
 email:
 - evan@lecklider.com
@@ -46,7 +116,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE.txt
-- README.md
+- README.org
 - lib/tater.rb
 - test/fixtures/another.yml
 - test/fixtures/fixtures.yml
@@ -74,13 +144,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '2.0'
 requirements: []
-rubygems_version: 3.0.4
+rubygems_version: 3.2.15
 signing_key: 
 specification_version: 4
 summary: Minimal internationalization and localization library.
 test_files:
+- test/fixtures/another.yml
+- test/fixtures/fixtures.yml
 - test/fixtures/messages/more.yml
 - test/fixtures/ruby.rb
-- test/fixtures/fixtures.yml
-- test/fixtures/another.yml
 - test/tater_test.rb