convenient_service 0.15.0 → 0.17.0

data/lib/convenient_service/support/dependency_container/exceptions.rb

@@ -9,14 +9,14 @@ module ConvenientService
           # @param scope [Object]
           # @return [void]
           #
-          def initialize(scope:)
+          def initialize_with_kwargs(scope:)
             message = <<~TEXT
               Scope `#{scope.inspect}` is NOT valid.
 
               Valid options are #{printable_valid_scopes}.
             TEXT
 
-            super(message)
+            initialize(message)
           end
 
           private
@@ -34,14 +34,14 @@ module ConvenientService
           # @param mod [Module]
           # @return [void]
           #
-          def initialize(mod:)
+          def initialize_with_kwargs(mod:)
             message = <<~TEXT
               Module `#{mod}` can NOT export methods.
 
               Did you forget to include `ConvenientService::DependencyContainer::Export` into it?
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
 
@@ -52,7 +52,7 @@ module ConvenientService
           # @param mod [Module]
           # @return [void]
           #
-          def initialize(method_name:, method_scope:, mod:)
+          def initialize_with_kwargs(method_name:, method_scope:, mod:)
             message = <<~TEXT
               Module `#{mod}` does NOT export method `#{method_name}` with `#{method_scope}` scope.
 
@@ -65,7 +65,7 @@ module ConvenientService
               end
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
 
@@ -74,12 +74,12 @@ module ConvenientService
           # @param klass [Class]
           # @return [void]
           #
-          def initialize(klass:)
+          def initialize_with_kwargs(klass:)
             message = <<~TEXT
               `#{klass.inspect}` is NOT a Module.
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
       end

data/lib/convenient_service/support/dependency_container/export.rb

@@ -11,7 +11,7 @@ module ConvenientService
         # @return [Module]
         #
         included do |klass|
-          raise Exceptions::NotModule.new(klass: klass) unless klass.instance_of?(::Module)
+          ::ConvenientService.raise Exceptions::NotModule.new(klass: klass) unless klass.instance_of?(::Module)
         end
 
         class_methods do

data/lib/convenient_service/support/finite_loop.rb

@@ -14,14 +14,14 @@ module ConvenientService
           # @param limit [Integer]
           # @return [void]
           #
-          def initialize(limit:)
+          def initialize_with_kwargs(limit:)
             message = <<~TEXT
               Max iteration count is exceeded. Current limit is #{limit}.
 
               Consider using `max_iteration_count` or `raise_on_exceedance` options if that is not the expected behavior.
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
 
@@ -29,12 +29,12 @@ module ConvenientService
           ##
           # @return [void]
           #
-          def initialize
+          def initialize_without_arguments
             message = <<~TEXT
               `finite_loop` always expects a block to be given.
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
       end
@@ -67,13 +67,13 @@ module ConvenientService
       #   end
       #
       def finite_loop(default: nil, max_iteration_count: MAX_ITERATION_COUNT, raise_on_exceedance: true, &block)
-        raise Exceptions::NoBlockGiven.new unless block
+        ::ConvenientService.raise Exceptions::NoBlockGiven.new unless block
 
         loop.with_index do |_, index|
           if index >= max_iteration_count
             break default unless raise_on_exceedance
 
-            raise Exceptions::MaxIterationCountExceeded.new(limit: max_iteration_count)
+            ::ConvenientService.raise Exceptions::MaxIterationCountExceeded.new(limit: max_iteration_count)
           end
 
           yield(index)

data/lib/convenient_service/support.rb

@@ -9,6 +9,7 @@ require_relative "support/concern"
 
 require_relative "support/abstract_method"
 require_relative "support/arguments"
+require_relative "support/backtrace_cleaner"
 require_relative "support/cache"
 require_relative "support/castable"
 require_relative "support/command"

data/lib/convenient_service/utils/array/exceptions.rb

@@ -5,12 +5,12 @@ module ConvenientService
     module Array
       module Exceptions
         class NonIntegerIndex < ::ConvenientService::Exception
-          def initialize(index:)
+          def initialize_with_kwargs(index:)
             message = <<~TEXT
               Index `#{index.inspect}` is NOT an integer.
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
       end

data/lib/convenient_service/utils/array/merge.rb

@@ -55,7 +55,7 @@ module ConvenientService
 
           return if overrides.size == integer_key_overrides.size
 
-          raise Exceptions::NonIntegerIndex.new(index: non_integer_index)
+          ::ConvenientService.raise Exceptions::NonIntegerIndex.new(index: non_integer_index)
         end
 
         ##

data/lib/convenient_service/utils/hash/assert_valid_keys.rb

@@ -41,7 +41,7 @@ module ConvenientService
           hash.each_key do |key|
             next if valid_keys.include?(key)
 
-            raise ::ArgumentError.new("Unknown key: #{key.inspect}. Valid keys are: #{valid_keys.map(&:inspect).join(", ")}")
+            ::ConvenientService.raise ::ArgumentError.new("Unknown key: #{key.inspect}. Valid keys are: #{valid_keys.map(&:inspect).join(", ")}")
           end
         end
       end

data/lib/convenient_service/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ConvenientService
-  VERSION = "0.15.0"
+  VERSION = "0.17.0"
 end

data/lib/convenient_service.rb

@@ -51,5 +51,103 @@ module ConvenientService
     def logger
       Logger.instance
     end
+
+    ##
+    # Returns Convenient Service root folder. Inspired by `Rails.root`.
+    # For example, it may return something like: `/Users/user/.asdf/installs/ruby/2.7.0/lib/ruby/gems/2.7.0/gems/convenient_service-0.16.0`.
+    #
+    # @api public
+    #
+    # @return [Pathname]
+    #
+    # @see https://ruby-doc.org/core-2.7.1/Kernel.html#method-i-__dir__
+    # @see https://api.rubyonrails.org/classes/Rails.html#method-c-root
+    #
+    def root
+      @root ||= ::Pathname.new(::File.expand_path(::File.join(__dir__, "..")))
+    end
+
+    ##
+    # Returns Convenient Service Examples folder.
+    # For example, it may return something like: `/Users/user/.asdf/installs/ruby/2.7.0/lib/ruby/gems/2.7.0/gems/convenient_service-0.16.0/lib/convenient_service/examples`.
+    #
+    # @api private
+    #
+    # @return [Pathname]
+    #
+    def examples_root
+      @examples_root ||= ::Pathname.new(::File.join(root, "lib", "convenient_service", "examples"))
+    end
+
+    ##
+    # @api public
+    #
+    # @return [ConvenientService::Support::BacktraceCleaner]
+    #
+    def backtrace_cleaner
+      @backtrace_cleaner ||= Support::BacktraceCleaner.new
+    end
+
+    ##
+    # @api public
+    #
+    # @param original_exception [StandardError]
+    #
+    # @raise [StandardError]
+    #
+    # @internal
+    #   NOTE: `rescue ::StandardError => exception` is the same as `rescue => exception`.
+    #
+    #   IMPORTANT: CRuby `Kernel.raise` supports `cause` keyword starting from 2.6.
+    #   JRuby 9.4 says that it is Ruby 3.1 compatible, but it still does NOT support `cause` keyword.
+    #   - https://ruby-doc.org/core-2.5.0/Kernel.html#method-i-raise
+    #   - https://ruby-doc.org/core-2.6/Kernel.html#method-i-raise
+    #   - https://github.com/jruby/jruby/blob/9.4.0.0/core/src/main/java/org/jruby/RubyKernel.java#L881
+    #   - https://github.com/ruby/spec/blob/master/core/kernel/raise_spec.rb#L5
+    #
+    if Dependencies.ruby.jruby?
+      def raise(original_exception)
+        ::Kernel.raise original_exception
+      rescue => exception
+        ::Kernel.raise exception.class, exception.message, backtrace_cleaner.clean(exception.backtrace)
+      end
+    else
+      def raise(original_exception)
+        ::Kernel.raise original_exception
+      rescue => exception
+        ::Kernel.raise exception.class, exception.message, backtrace_cleaner.clean(exception.backtrace), cause: exception.cause
+      end
+    end
+
+    ##
+    # @api public
+    #
+    # @return [Object] Can be any type.
+    #
+    # @raise [StandardError]
+    #
+    # @internal
+    #   NOTE: `rescue ::StandardError => exception` is the same as `rescue => exception`.
+    #
+    #   IMPORTANT: CRuby `Kernel.raise` supports `cause` keyword starting from 2.6.
+    #   JRuby 9.4 says that it is Ruby 3.1 compatible, but it still does NOT support `cause` keyword.
+    #   - https://ruby-doc.org/core-2.5.0/Kernel.html#method-i-raise
+    #   - https://ruby-doc.org/core-2.6/Kernel.html#method-i-raise
+    #   - https://github.com/jruby/jruby/blob/9.4.0.0/core/src/main/java/org/jruby/RubyKernel.java#L881
+    #   - https://github.com/ruby/spec/blob/master/core/kernel/raise_spec.rb#L5
+    #
+    if Dependencies.ruby.jruby?
+      def reraise
+        yield
+      rescue => exception
+        ::Kernel.raise exception.class, exception.message, backtrace_cleaner.clean(exception.backtrace)
+      end
+    else
+      def reraise
+        yield
+      rescue => exception
+        ::Kernel.raise exception.class, exception.message, backtrace_cleaner.clean(exception.backtrace), cause: exception.cause
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: convenient_service
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Marian Kostyk
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-20 00:00:00.000000000 Z
+date: 2024-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: appraisal
@@ -84,16 +84,16 @@ dependencies:
   name: commonmarker
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.23.10
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.23.10
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -192,34 +192,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 5.18.0
-- !ruby/object:Gem::Dependency
-  name: mutant
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.11.21
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.11.21
-- !ruby/object:Gem::Dependency
-  name: mutant-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.11.21
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.11.21
 - !ruby/object:Gem::Dependency
   name: paint
   requirement: !ruby/object:Gem::Requirement
@@ -450,28 +422,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.28
+        version: 0.9.34
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.28
+        version: 0.9.34
 - !ruby/object:Gem::Dependency
   name: yard-junk
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.0.9
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.0.9
 - !ruby/object:Gem::Dependency
   name: service_actor
   requirement: !ruby/object:Gem::Requirement
@@ -570,6 +542,7 @@ files:
 - ".dev/.tmuxinator.yml"
 - ".dockerignore"
 - ".gem_release.yml"
+- ".github/contributing.md"
 - ".github/issue_template.md"
 - ".github/pull_request_template.md"
 - ".github/workflows/cd.yml"
@@ -589,6 +562,7 @@ files:
 - ".yardopts"
 - Appraisals
 - CHANGELOG.md
+- COMM-LICENSE.txt
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -608,6 +582,8 @@ files:
 - docker/3.2/Dockerfile
 - docker/jruby-9.4/Dockerfile
 - docker/truffleruby-22.3/Dockerfile
+- docs/.gitkeep
+- docs/api/.gitkeep
 - env.rb
 - gemfiles/.gitkeep
 - lib/convenient_service.rb
@@ -658,6 +634,13 @@ files:
 - lib/convenient_service/common/plugins/has_constructor/concern.rb
 - lib/convenient_service/common/plugins/has_constructor_without_initialize.rb
 - lib/convenient_service/common/plugins/has_constructor_without_initialize/concern.rb
+- lib/convenient_service/common/plugins/has_instance_proxy.rb
+- lib/convenient_service/common/plugins/has_instance_proxy/commands.rb
+- lib/convenient_service/common/plugins/has_instance_proxy/commands/create_instance_proxy_class.rb
+- lib/convenient_service/common/plugins/has_instance_proxy/concern.rb
+- lib/convenient_service/common/plugins/has_instance_proxy/entities.rb
+- lib/convenient_service/common/plugins/has_instance_proxy/entities/instance_proxy.rb
+- lib/convenient_service/common/plugins/has_instance_proxy/middleware.rb
 - lib/convenient_service/common/plugins/has_internals.rb
 - lib/convenient_service/common/plugins/has_internals/commands.rb
 - lib/convenient_service/common/plugins/has_internals/commands/create_internals_class.rb
@@ -746,6 +729,7 @@ files:
 - lib/convenient_service/dependencies/extractions/active_support_concern/concern.rb
 - lib/convenient_service/dependencies/extractions/b.rb
 - lib/convenient_service/dependencies/extractions/byebug_syntax_highlighting.rb
+- lib/convenient_service/dependencies/extractions/ce.rb
 - lib/convenient_service/dependencies/extractions/ruby_middleware.rb
 - lib/convenient_service/dependencies/extractions/ruby_middleware/middleware.rb
 - lib/convenient_service/dependencies/extractions/ruby_middleware/middleware/builder.rb
@@ -928,7 +912,6 @@ files:
 - lib/convenient_service/examples/standard/v1/gemfile/services/format_header.rb
 - lib/convenient_service/examples/standard/v1/gemfile/services/merge_sections.rb
 - lib/convenient_service/examples/standard/v1/gemfile/services/parse_content.rb
-- lib/convenient_service/examples/standard/v1/gemfile/services/print_shell_command.rb
 - lib/convenient_service/examples/standard/v1/gemfile/services/read_file_content.rb
 - lib/convenient_service/examples/standard/v1/gemfile/services/replace_file_content.rb
 - lib/convenient_service/examples/standard/v1/gemfile/services/run_shell_command.rb
@@ -980,8 +963,10 @@ files:
 - lib/convenient_service/feature/plugins/aliases.rb
 - lib/convenient_service/feature/plugins/can_have_entries.rb
 - lib/convenient_service/feature/plugins/can_have_entries/commands.rb
+- lib/convenient_service/feature/plugins/can_have_entries/commands/define_entries.rb
 - lib/convenient_service/feature/plugins/can_have_entries/commands/define_entry.rb
 - lib/convenient_service/feature/plugins/can_have_entries/concern.rb
+- lib/convenient_service/feature/plugins/can_have_entries/exceptions.rb
 - lib/convenient_service/logger.rb
 - lib/convenient_service/rspec.rb
 - lib/convenient_service/rspec/helpers.rb
@@ -1415,6 +1400,7 @@ files:
 - lib/convenient_service/support/abstract_method/exceptions.rb
 - lib/convenient_service/support/arguments.rb
 - lib/convenient_service/support/arguments/null_arguments.rb
+- lib/convenient_service/support/backtrace_cleaner.rb
 - lib/convenient_service/support/cache.rb
 - lib/convenient_service/support/cache/constants.rb
 - lib/convenient_service/support/cache/entities.rb
@@ -1540,7 +1526,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.4.1
 signing_key:
 specification_version: 4
 summary: Service object pattern implementation in Ruby.

data/lib/convenient_service/examples/standard/v1/gemfile/services/print_shell_command.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-##
-# Usage example:
-#
-#   ConvenientService::Examples::Standard::V1::Gemfile::Services::PrintShellCommand.result(command: "ls -a")
-#
-module ConvenientService
-  module Examples
-    module Standard
-      module V1
-        class Gemfile
-          module Services
-            class PrintShellCommand
-              include ConvenientService::Standard::V1::Config
-
-              attr_reader :command, :skip, :out
-
-              def initialize(command:, skip: false, out: $stdout)
-                @command = command
-                @skip = skip
-                @out = out
-              end
-
-              def result
-                return failure(command: "Command is `nil`") if command.nil?
-                return failure(command: "Command is empty?") if command.empty?
-
-                return error("Printing of shell command `#{command}` is skipped") if skip
-
-                out.puts
-
-                out.puts ::Paint["$ #{command}", :blue, :bold]
-
-                success
-              end
-
-              def fallback_error_result
-                success
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-end