messages_dictionary 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 270aca02bdc13e851f345d7ce783fbd8329e95f2054c3865fa5b5c1cc2b09c6c
-  data.tar.gz: be5c5615e7c87d7423019fcd96afdf6695ea8527b7c63777c550ca8f6c4fdde7
+  metadata.gz: 3a6f7d3a4a63be59119844b7d3139f10b82118a7a726cbfb59f078dc68edb916
+  data.tar.gz: 1884503b8aad4f2c452666833a7a48867c2c0fa55c74854e94ea0a5a6c0bed79
 SHA512:
-  metadata.gz: 9661d7b64b05ee3d68042938cf05f56b4606107104122e087b39ee86c0b45db79e6ec304e89785d53c1565e7f18a200e542f3ef0cff81acf94afd1cae31aa222
-  data.tar.gz: e401f904c1e3efa0215a0551a33f4dced1a915f7173705232aee7f660c21f04b0f4f6853b2b280a167183d9e8c2960d6287ad0f156f7f54e967f85eba88d2781
+  metadata.gz: 2979cbdfacfdfdd47985304f3d6535ce4fe121ca240807e1700a8f9a15aa54e4301e487eeddbcaf9f456f4814f0f51d881e026cdafd65a23ce96d3c539b29057
+  data.tar.gz: eb7c8163836c469604d4fb1af38c84fc9c4d3a450dba73cb429e018a741e55768b0b25fa4f6be2715157e9ec794daf31bd21505db0179f9fe84f23b75cd289d6

data/CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 
-## 2.0.0
+## 2.1.0 (22-Nov-2022)
+
+* `pou` and `pretty_output` are now available inside class methods
+* `DICTIONARY_CONF` now contains an instance of the `Config` class that takes care of all configuration options
+* Added `lazy` option that enables lazy loading
+* Added `on_key_missing` option which is set to `:raise` by default. You can pass a proc or a lambda to this option in order to provide a custom handler that fires when a given key cannot be found.
+* Added `file_loader` option to handle custom file loading
+
+## 2.0.0 (21-Nov-2022)
 
 This is a major re-write of the gem. All core features stay the same and there should not be any breaking changes, except for one thing: you should not use "destructive" methods when transforming your messages.
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    messages_dictionary (2.0.0)
+    messages_dictionary (2.1.0)
       hashie (~> 5.0)
       zeitwerk (~> 2.4)
 
@@ -70,6 +70,7 @@ PLATFORMS
 
 DEPENDENCIES
   codecov (~> 0.1)
+  json (~> 2)
   messages_dictionary!
   rake (~> 13.0)
   rspec (~> 3.6)

data/README.md

@@ -35,9 +35,7 @@ Another, a bit more complex, use case in the [lessons_indexer gem](https://githu
 * [Other classes simply inherit from it](https://github.com/bodrovis/lessons_indexer/blob/master/lib/lessons_indexer/indexer.rb#L2)
 * [Messages are fetched easily](https://github.com/bodrovis/lessons_indexer/blob/master/lib/lessons_indexer/indexer.rb#L45)
 
-## Usage
-
-### Basic Example
+## Basic usage
 
 Suppose you have the following program:
 
@@ -86,7 +84,7 @@ class MyOtherClass
   def greet
     pretty_output(:welcome)
     # Or simply
-    pou(:welcome)
+    pou :welcome
   end
 end
 ```
@@ -156,9 +154,9 @@ class MyClass
 end
 ```
 
-### Further Customization
+## Further Customization
 
-#### Specifying File Name and Directory
+### Specifying File Name and Directory
 
 By default `messages_dictionary` will search for a *.yml* file named after your class (converted to snake case,
 so for the `MyClass` the file should be named *my_class.yml*)
@@ -170,13 +168,29 @@ inside the same directory. However, this behavior can be easily changed with the
 ```ruby
 class MyClass
   include MessagesDictionary
-  has_messages_dictionary file: 'some_file.yml', dir: 'C:\my_docs'
+  has_messages_dictionary file: 'some_file.yml', dir: 'my_docs'
 end
 ```
 
 Both of these options are not mandatory.
 
-#### Specifying Messages Hash
+### Providing a custom file loader
+
+By default the gem a messages file in YAML format. However, you might want to use a different format: for example, JSON. In this case you'll have to provide a custom loader:
+
+```ruby
+class MyClass
+  include MessagesDictionary
+  has_messages_dictionary file: 'test_file.json', dir: 'my_dir',
+                          file_loader: ->(file_path) { JSON.parse(File.read(file_path)) }
+end
+```
+
+The `:file_loader` option accepts a proc or a lambda that receives a path to your messages file as an argument. This lambda must return a hash object with keys and the corresponding values.
+
+The default value for the `:file_loader` is `->(f) { YAML.load_file(f) }`.
+
+### Specifying Messages Hash
 
 Instead of loading messages from a file, you can pass hash to the `has_messages_dictionary` using `:messages` option:
 
@@ -189,7 +203,7 @@ end
 
 Nesting and all other features are supported as well.
 
-#### Specifying Output and Display Method
+### Specifying Output and Display Method
 
 By default all messages will be outputted to `STDOUT` using `puts` method, however this can be changed:
 
@@ -204,7 +218,32 @@ class MyClass
 end
 ```
 
-#### Providing Custom Transformation Logic
+### "Lazy" mode
+
+By default this gem will load all messages from the given file. However, you can enable a "lazy" mode so that messages are not loaded until `pou` or `pretty_output` methods have been called. The "lazy" mode can only be enabled when the `:file` option is provided (in other words, `:lazy` has no effect with the `:messages` setting):
+
+```ruby
+class MyClass
+  include MessagesDictionary
+  has_messages_dictionary lazy: true, file: 'my_file.yml'
+
+  def greet
+    pou :hi
+  end
+end
+
+# At this point no messages are loaded from the given file
+
+obj = MyClass.new
+
+# ... doing some other stuff ...
+
+# Messages are still not loaded at this point!
+
+obj.greet # Now all messages will be loaded from the YAML file
+```
+
+### Providing Custom Transformation Logic
 
 Suppose you want to transform your message somehow or even simply return it instead of printing on the screen.
 `pretty_output` method accepts an optional block for this purpose:
@@ -262,6 +301,45 @@ def greet
 end
 ```
 
+### Handling missing keys
+
+By default when a non-existent key is requested, an error will be raised:
+
+```ruby
+class MyClass
+  include MessagesDictionary
+  has_messages_dictionary messages: {key: 'value'}
+
+  def greet
+    pou :unknown_key # trying to use some unknown key...
+  end
+end
+
+obj = MyClass.new
+
+obj.greet # KeyError is raised here!
+```
+
+However, you can adjust the `:on_key_missing` option and provide a custom proc or lambda to handle all missing keys:
+
+```ruby
+class MyClass
+  include MessagesDictionary
+  has_messages_dictionary messages: {key: 'value'},
+                          on_key_missing: ->(key) { key } # We simply return the requested key itself
+
+  def greet
+    pou :unknown_key
+  end
+end
+
+obj = MyClass.new
+
+obj.greet # Prints "unknown_key" to the screen, no errors will be raised
+```
+
+So, in the example above we simply return the key itself if it was not found in the messages hash.
+
 ## License
 
 Licensed under the [MIT License](https://github.com/bodrovis-learning/messages_dictionary/blob/master/LICENSE).

data/lib/messages_dictionary/config.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module MessagesDictionary
+  # This class contains all configuration params
+  class Config
+    using MessagesDictionary::Utils::StringUtils
+
+    attr_reader :msgs, :output_target, :output_method, :transform, :file, :on_key_missing, :file_loader
+
+    def initialize(opts, klass)
+      @__klass = klass
+      @__lazy = opts[:lazy]
+
+      prepare_storage_for opts
+
+      @on_key_missing = opts[:on_key_missing] || :raise
+      @output_target = opts[:output] || $stdout
+      @output_method = (opts[:method] || :puts).to_sym
+      @transform = opts[:transform]
+
+      load_messages
+    end
+
+    # This method loads messages from a file but respects the "lazy" option.
+    # In other words, it does not load anything if "lazy" is "true".
+    # To force messages loading, use the load_messages! method instead.
+    def load_messages
+      return if @__lazy
+
+      do_load_messages!
+    end
+
+    # Loads messages from the file even if "lazy" is "true"
+    def load_messages!
+      do_load_messages!
+    end
+
+    private
+
+    def do_load_messages!
+      return if @__storage == :hash || @__loaded
+
+      begin
+        data = @file_loader.call @file
+      rescue Errno::ENOENT
+        raise Errno::ENOENT, "File #{@file} does not exist..."
+      else
+        @msgs = MessagesDictionary::Utils::Dict.new data
+        @__loaded = true
+      end
+    end
+
+    def prepare_storage_for(opts)
+      if opts.key?(:messages)
+        @__storage = :hash
+        @msgs = MessagesDictionary::Utils::Dict.new opts[:messages]
+        @__loaded = true
+      else
+        @__storage = :file
+        @file = opts[:file] || "#{@__klass.name.nil? ? 'unknown' : @__klass.name.snakecase}.yml"
+        @file = File.expand_path(@file, opts[:dir] || '.')
+        @file_loader = opts[:file_loader] || ->(f) { YAML.load_file(f) }
+      end
+    end
+  end
+end

data/lib/messages_dictionary/injector.rb

@@ -3,11 +3,10 @@
 module MessagesDictionary
   # Main module that injects all the necessary methods in the target class
   module Injector
-    using MessagesDictionary::Utils::StringUtils
-
     def self.included(klass)
       klass.extend ClassMethods
       klass.include InstanceMethods
+      klass.extend InstanceMethods
     end
 
     # Class methods to be defined in the target (where the module was included)
@@ -17,27 +16,8 @@ module MessagesDictionary
       # with all the necesary goodies
       def has_messages_dictionary(opts = {})
         # rubocop:enable Naming/PredicateName
-        messages = MessagesDictionary::Utils::Dict.new(
-          opts.fetch(:messages) { __from_file(opts) }
-        )
-
-        const_set(:DICTIONARY_CONF, {msgs: messages,
-                                     output: opts[:output] || $stdout,
-                                     method: opts[:method] || :puts,
-                                     transform: opts[:transform]})
-      end
-
-      private
-
-      def __from_file(opts)
-        file = opts[:file] || "#{name.nil? ? 'unknown' : name.snakecase}.yml"
-        file = File.expand_path(file, opts[:dir]) if opts[:dir]
 
-        begin
-          YAML.load_file(file)
-        rescue Errno::ENOENT
-          abort "File #{file} does not exist..."
-        end
+        const_set :DICTIONARY_CONF, MessagesDictionary::Config.new(opts, self)
       end
     end
 
@@ -46,8 +26,10 @@ module MessagesDictionary
       # This method will output your messages, perform interpolation,
       # and transformations
       def pretty_output(key, values = {}, &block)
-        msg = self.class::DICTIONARY_CONF[:msgs].deep_fetch(*key.to_s.split('.')) do
-          raise KeyError, "#{key} cannot be found in the provided file..."
+        __config.load_messages!
+
+        msg = __config.msgs.deep_fetch(*key.to_s.split('.')) do
+          handle_key_missing(key)
         end
 
         __process(
@@ -61,6 +43,16 @@ module MessagesDictionary
 
       private
 
+      def handle_key_missing(key)
+        raise KeyError, "#{key} cannot be found..." if __config.on_key_missing == :raise
+
+        __config.on_key_missing.call(key)
+      end
+
+      def __config
+        @__config ||= respond_to?(:const_get) ? const_get(:DICTIONARY_CONF) : self.class.const_get(:DICTIONARY_CONF)
+      end
+
       def __replace(msg, values)
         values.each do |k, v|
           msg.gsub!(Regexp.new("\\{\\{#{k}\\}\\}"), v.to_s)
@@ -70,12 +62,12 @@ module MessagesDictionary
       end
 
       def __process(msg, &block)
-        transform = block || self.class::DICTIONARY_CONF[:transform]
+        transform = block || __config.transform
 
         if transform
           transform.call(msg)
         else
-          self.class::DICTIONARY_CONF[:output].send(self.class::DICTIONARY_CONF[:method].to_sym, msg)
+          __config.output_target.send(__config.output_method, msg)
         end
       end
     end

data/lib/messages_dictionary/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MessagesDictionary
-  VERSION = '2.0.0'
+  VERSION = '2.1.0'
 end

data/messages_dictionary.gemspec

@@ -24,6 +24,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'zeitwerk', '~> 2.4'
 
   spec.add_development_dependency 'codecov', '~> 0.1'
+  spec.add_development_dependency 'json', '~> 2'
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.6'
   spec.add_development_dependency 'rubocop',             '~> 1.6'

data/spec/lib/messages_dictionary/injector_spec.rb

@@ -1,16 +1,38 @@
 # frozen_string_literal: true
 
+require 'json'
+
 RSpec.describe MessagesDictionary::Injector do
   let(:dummy) { Class.new { include MessagesDictionary::Injector } }
 
   context 'with messages' do
+    context 'when lazy-loading' do
+      it 'loads messages on demand' do
+        in_dir 'my_test_file.yml', 'my_test_dir' do
+          dummy.class_eval do
+            has_messages_dictionary file: 'my_test_file.yml', dir: 'my_test_dir', lazy: true
+          end
+
+          expect(dummy::DICTIONARY_CONF.instance_variable_get(:@__loaded)).to be_falsey
+          expect(dummy::DICTIONARY_CONF.msgs).to be_nil
+
+          object = dummy.new
+          expect(object.send(:pretty_output, :test) { |msg| msg }).to eq('string')
+          expect(object.send(:pretty_output, :interpolated, a: 42) { |msg| msg }).to eq('Value is 42')
+
+          expect(dummy::DICTIONARY_CONF.instance_variable_get(:@__loaded)).to be true
+          expect(dummy::DICTIONARY_CONF.msgs.keys).to include('test', 'interpolated')
+        end
+      end
+    end
+
     context 'when outputting' do
       it 'uses STDOUT by default' do
         dummy.class_eval do
           has_messages_dictionary messages: {test: 'string'}
         end
 
-        expect(dummy::DICTIONARY_CONF[:output]).to eq($stdout)
+        expect(dummy::DICTIONARY_CONF.output_target).to eq($stdout)
       end
 
       it 'uses puts method by default' do
@@ -18,7 +40,7 @@ RSpec.describe MessagesDictionary::Injector do
           has_messages_dictionary messages: {test: 'string'}
         end
 
-        expect(dummy::DICTIONARY_CONF[:method]).to eq(:puts)
+        expect(dummy::DICTIONARY_CONF.output_method).to eq(:puts)
       end
 
       it 'allows customizing output and method' do
@@ -52,6 +74,22 @@ RSpec.describe MessagesDictionary::Injector do
 
         expect(output).to have_received(:puts).with('string').exactly(1).time
       end
+
+      it 'works for class methods' do
+        dummy.class_eval do
+          has_messages_dictionary messages: {test: 'string'}
+
+          define_singleton_method :run_klass do
+            pou(:test)
+          end
+        end
+
+        allow($stdout).to receive(:puts).with('string')
+
+        dummy.run_klass
+
+        expect($stdout).to have_received(:puts).exactly(1).time
+      end
     end
 
     context 'when passed as hash' do
@@ -60,6 +98,7 @@ RSpec.describe MessagesDictionary::Injector do
           has_messages_dictionary messages: {parent: {child: 'child_string'}}
         end
 
+        expect(dummy::DICTIONARY_CONF.instance_variable_get(:@__loaded)).to be true
         object = dummy.new
         expect(object.send(:pretty_output, 'parent.child') { |msg| msg }).to eq('child_string')
       end
@@ -101,6 +140,19 @@ RSpec.describe MessagesDictionary::Injector do
           expect(object.send(:pretty_output, :interpolated, a: 42) { |msg| msg }).to eq('Value is 42')
         end
       end
+
+      it 'allows providing a custom file loader' do
+        in_dir 'test_file.json', 'my_dir' do
+          dummy.class_eval do
+            has_messages_dictionary file: 'test_file.json', dir: 'my_dir',
+                                    file_loader: ->(f) { JSON.parse(File.read(f)) }
+          end
+
+          object = dummy.new
+          expect(object.send(:pretty_output, 'nested.test') { |msg| msg }).to eq('string')
+          expect(object.send(:pretty_output, :interpolated, a: 42) { |msg| msg }).to eq('Value is 42')
+        end
+      end
     end
   end
 
@@ -110,8 +162,28 @@ RSpec.describe MessagesDictionary::Injector do
         has_messages_dictionary messages: {test: 'string'}
       end
 
+      key = :does_not_exist
+
+      object = dummy.new
+      expect { object.send(:pretty_output, key) }.to raise_error(
+        an_instance_of(KeyError).
+        and(
+          having_attributes(message: "#{key} cannot be found...")
+        )
+      )
+    end
+
+    it 'is allows to use custom missing key handler' do
+      dummy.class_eval do
+        has_messages_dictionary messages: {test: 'string'},
+                                on_key_missing: ->(key) { key.upcase.split('.') },
+                                transform: ->(msg) { msg }
+      end
+
+      key = 'does.not.exist'
+
       object = dummy.new
-      expect { object.send(:pretty_output, :does_not_exist) }.to raise_error(KeyError)
+      expect(object.send(:pou, key)).to eq(%w[DOES NOT EXIST])
     end
 
     it 'is raised when file is not found and the program aborts' do
@@ -120,8 +192,12 @@ RSpec.describe MessagesDictionary::Injector do
           has_messages_dictionary dir: 'random', file: 'not_exist.yml'
         end
       end.to raise_error(
-        an_instance_of(SystemExit).
-        and(having_attributes(message: "File #{File.expand_path('random/not_exist.yml')} does not exist..."))
+        an_instance_of(Errno::ENOENT).
+        and(having_attributes(
+              message: "No such file or directory - File #{File.expand_path(
+                'random/not_exist.yml'
+              )} does not exist..."
+            ))
       )
     end
   end

data/spec/support/spec_files_setup.rb

@@ -8,12 +8,38 @@ module SpecFilesSetup
 
     FileUtils.mkdir_p full_path
 
-    f = File.new(File.join(full_path, file), 'w+')
-    f.write("test: string\ninterpolated: Value is {{a}}")
-    f.close
+    File.open(File.join(full_path, file), 'w+') do |f|
+      if /\.ya?ml\z/i.match?(file)
+        f.write yaml_data
+      else
+        f.write json_data
+      end
+    end
   end
 
   def clear_env!(path)
     FileUtils.remove_entry("#{RSPEC_ROOT}/dummy/#{path}")
+  rescue Errno::EACCES
+    puts "Cannot remove #{path}"
+  end
+
+  private
+
+  def json_data
+    <<~DATA
+      {
+        "nested": {
+          "test": "string"
+        },
+        "interpolated": "Value is {{a}}"
+      }
+    DATA
+  end
+
+  def yaml_data
+    <<~DATA
+      test: string
+      interpolated: Value is {{a}}
+    DATA
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: messages_dictionary
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Ilya Krukowski
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-21 00:00:00.000000000 Z
+date: 2022-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
@@ -53,6 +53,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -179,6 +193,7 @@ files:
 - README.md
 - Rakefile
 - lib/messages_dictionary.rb
+- lib/messages_dictionary/config.rb
 - lib/messages_dictionary/injector.rb
 - lib/messages_dictionary/utils/dict.rb
 - lib/messages_dictionary/utils/string_utils.rb