convenient_service 0.20.0 → 0.21.0

data/lib/convenient_service/utils/object/duck_class.rb

@@ -5,91 +5,94 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-# Converts an object to a "duck" class in terms of `Module#method_defined?` or `Module#define_method`.
-#
-# @example Avoid `if` condition for `Module#method_defined?`.
-#
-#   object = Person.new # || Person
-#
-#   if object.is_a?(Module)
-#     ##
-#     # class Person
-#     #   def self.foo
-#     #   end
-#     # end
-#     #
-#     # Does `Person` has class method `foo`?
-#     #
-#     object.singleton_class.method_defined?(:foo)
-#   else
-#     ##
-#     # class Person
-#     #   def foo
-#     #   end
-#     # end
-#     #
-#     # Does `Person` has instance method `foo`?
-#     #
-#     object.class.method_defined?(:foo)
-#   end
-#
-#   ##
-#   # With `ConvenientService::Utils::Object.duck_class` it can be rewritten in the following way:
-#   #
-#   ConvenientService::Utils::Object.duck_class(object).method_defined?(:foo)
-#
-# @example Avoid `if` condition for `Module#define_method`.
-#
-#   object = Person.new # || Person
-#
-#   if object.is_a?(Module)
-#     ##
-#     # Defines class method `foo` in `Person` class.
-#     #
-#     object.singleton_class.define_method(:foo) { :bar }
-#   else
-#     ##
-#     # Defines instance method `foo` in `Person` class.
-#     #
-#     object.class.define_method(:foo) { :bar }
-#   end
-#
-#   ##
-#   # With `ConvenientService::Utils::Object.duck_class` it can be rewritten in the following way:
-#   #
-#   ConvenientService::Utils::Object.duck_class(object).define_method(:foo) { :bar }
-#
-# @example Possible return values.
-#
-#   module Musician
-#   end
-#
-#   class Person
-#   end
-#
-#   person = Person.new
-#
-#   ConvenientService::Utils::Object::DuckClass.call(42)
-#   # => Integer
-#
-#   ConvenientService::Utils::Object::DuckClass.call("foo")
-#   # => String
-#
-#   ConvenientService::Utils::Object::DuckClass.call(person)
-#   # => Person
-#
-#   ConvenientService::Utils::Object::DuckClass.call(Person)
-#   # => #<Class:Person>
-#
-#   ConvenientService::Utils::Object::DuckClass.call(Musician)
-#   # => #<Class:Musician>
-#
 module ConvenientService
   module Utils
     module Object
       ##
-      # TODO: A better name.
+      # Converts an object to a "duck" class in terms of `Module#method_defined?` or `Module#define_method`.
+      #
+      # @api private
+      # @since 1.0.0
+      #
+      # @example Avoid `if` condition for `Module#method_defined?`.
+      #
+      #   object = Person.new # || Person
+      #
+      #   if object.is_a?(Module)
+      #     ##
+      #     # class Person
+      #     #   def self.foo
+      #     #   end
+      #     # end
+      #     #
+      #     # Does `Person` has class method `foo`?
+      #     #
+      #     object.singleton_class.method_defined?(:foo)
+      #   else
+      #     ##
+      #     # class Person
+      #     #   def foo
+      #     #   end
+      #     # end
+      #     #
+      #     # Does `Person` has instance method `foo`?
+      #     #
+      #     object.class.method_defined?(:foo)
+      #   end
+      #
+      #   ##
+      #   # With `ConvenientService::Utils::Object.duck_class` it can be rewritten in the following way:
+      #   #
+      #   ConvenientService::Utils::Object.duck_class(object).method_defined?(:foo)
+      #
+      # @example Avoid `if` condition for `Module#define_method`.
+      #
+      #   object = Person.new # || Person
+      #
+      #   if object.is_a?(Module)
+      #     ##
+      #     # Defines class method `foo` in `Person` class.
+      #     #
+      #     object.singleton_class.define_method(:foo) { :bar }
+      #   else
+      #     ##
+      #     # Defines instance method `foo` in `Person` class.
+      #     #
+      #     object.class.define_method(:foo) { :bar }
+      #   end
+      #
+      #   ##
+      #   # With `ConvenientService::Utils::Object.duck_class` it can be rewritten in the following way:
+      #   #
+      #   ConvenientService::Utils::Object.duck_class(object).define_method(:foo) { :bar }
+      #
+      # @example Possible return values.
+      #
+      #   module Musician
+      #   end
+      #
+      #   class Person
+      #   end
+      #
+      #   person = Person.new
+      #
+      #   ConvenientService::Utils::Object::DuckClass.call(42)
+      #   # => Integer
+      #
+      #   ConvenientService::Utils::Object::DuckClass.call("foo")
+      #   # => String
+      #
+      #   ConvenientService::Utils::Object::DuckClass.call(person)
+      #   # => Person
+      #
+      #   ConvenientService::Utils::Object::DuckClass.call(Person)
+      #   # => #<Class:Person>
+      #
+      #   ConvenientService::Utils::Object::DuckClass.call(Musician)
+      #   # => #<Class:Musician>
+      #
+      # @internal
+      #   TODO: A better name.
       #
       class DuckClass < Support::Command
         ##

data/lib/convenient_service/utils/object/get_own_method.rb

@@ -39,7 +39,7 @@ module ConvenientService
         end
 
         ##
-        # @return [Class]
+        # @return [Method]
         #
         # @internal
         #   NOTE: `own_method.bind(object).call` is logically the same as `own_method.bind_call(object)`.

data/lib/convenient_service/utils/object/instance_variable_delete.rb

@@ -5,9 +5,6 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-#
-#
 module ConvenientService
   module Utils
     module Object

data/lib/convenient_service/utils/object/instance_variable_fetch.rb

@@ -5,9 +5,6 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-#
-#
 module ConvenientService
   module Utils
     module Object

data/lib/convenient_service/utils/object/memoize_including_falsy_values.rb

@@ -5,9 +5,6 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-#
-#
 module ConvenientService
   module Utils
     module Object

data/lib/convenient_service/utils/object/resolve_type.rb

@@ -5,20 +5,22 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-# @example
-#   ConvenientService::Utils::Object::ResolveType.call("foo")
-#   # => "instance"
-#
-#   ConvenientService::Utils::Object::ResolveType.call(Array)
-#   # => "class"
-#
-#   ConvenientService::Utils::Object::ResolveType.call(Kernel)
-#   # => "module"
-#
 module ConvenientService
   module Utils
     module Object
+      ##
+      # @api private
+      # @since 1.0.0
+      # @example Common usage.
+      #   ConvenientService::Utils::Object::ResolveType.call("foo")
+      #   # => "instance"
+      #
+      #   ConvenientService::Utils::Object::ResolveType.call(Array)
+      #   # => "class"
+      #
+      #   ConvenientService::Utils::Object::ResolveType.call(Kernel)
+      #   # => "module"
+      #
       class ResolveType < Support::Command
         ##
         # @!attribute [r] object

data/lib/convenient_service/utils/object/safe_send.rb

@@ -70,6 +70,8 @@ module ConvenientService
         ##
         # @return [Object] Can be any type.
         #
+        # @note `SafeSend` is similar to `JSON::SafeParse` in a sense that it never raises exceptions.
+        #
         # @internal
         #   NOTE: `true` in `respond_to?(method, true)` means to look for protected and private methods as well.
         #   - https://ruby-doc.org/core-2.7.0/Object.html#method-i-respond_to-3F

data/lib/convenient_service/utils/string/enclose.rb

@@ -5,20 +5,20 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-# @example Common usage.
-#   ConvenientService::Utils::String::Enclose.call("foo", "_")
-#   # => "_foo_"
-#
-#   ConvenientService::Utils::String::Enclose.call("", "_")
-#   # => "_"
-#
-#   ConvenientService::Utils::String::Enclose.call(nil, "_")
-#   # => "_"
-#
 module ConvenientService
   module Utils
     module String
+      ##
+      # @example Common usage.
+      #   ConvenientService::Utils::String::Enclose.call("foo", "_")
+      #   # => "_foo_"
+      #
+      #   ConvenientService::Utils::String::Enclose.call("", "_")
+      #   # => "_"
+      #
+      #   ConvenientService::Utils::String::Enclose.call(nil, "_")
+      #   # => "_"
+      #
       class Enclose < Support::Command
         ##
         # @!attribute [r] string

data/lib/convenient_service/utils/string/tab.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Utils
+    module String
+      ##
+      # @example Common usage.
+      #   ConvenientService::Utils::String::Tab.call("foo\nbar\nbaz")
+      #   # => "  foo\n  bar\n  baz"
+      #
+      #   ConvenientService::Utils::String::Tab.call("foo\nbar\nbaz", tab_size: 4)
+      #   # => "    foo\n    bar\n    baz"
+      #
+      class Tab < Support::Command
+        ##
+        # @!attribute [r] string
+        #   @return [String]
+        #
+        attr_reader :string
+
+        ##
+        # @!attribute [r] tab_size
+        #   @return [Integer]
+        #
+        attr_reader :tab_size
+
+        ##
+        # @param string [String]
+        # @param tab_size [Integer]
+        # @return [void]
+        #
+        def initialize(string, tab_size: 2)
+          @string = string.to_s
+          @tab_size = tab_size
+        end
+
+        ##
+        # @return [String]
+        #
+        def call
+          string.lines.map { |line| "#{tab}#{line}" }.join
+        end
+
+        private
+
+        ##
+        # @return [String]
+        #
+        def tab
+          @tab ||= " " * tab_size
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/string.rb

@@ -9,6 +9,7 @@ require_relative "string/camelize"
 require_relative "string/demodulize"
 require_relative "string/enclose"
 require_relative "string/split"
+require_relative "string/tab"
 require_relative "string/truncate"
 
 module ConvenientService
@@ -27,6 +28,10 @@ module ConvenientService
           Enclose.call(...)
         end
 
+        def tab(...)
+          Tab.call(...)
+        end
+
         def split(...)
           Split.call(...)
         end

data/lib/convenient_service/utils.rb

@@ -8,6 +8,7 @@
 require_relative "utils/array"
 require_relative "utils/bool"
 require_relative "utils/class"
+require_relative "utils/enumerable"
 require_relative "utils/hash"
 require_relative "utils/kernel"
 require_relative "utils/method"
@@ -17,6 +18,14 @@ require_relative "utils/string"
 require_relative "utils/object"
 
 module ConvenientService
+  ##
+  # Namespace for Convenient Service utilities that can be expressed as "functions".
+  #
+  # @api private
+  # @since 1.0.0
+  # @note Utilities from the `Utils` module are NOT expected to be used by the end-users directly.
+  # @note Plugin developers usually can rely on the `Utils` module, but it is always a good idea to open an issue with the corresponding usage example. This way, the custom plugin may be added to the CI pipeline. So that any breaking change is caught before the new Convenient Service release.
+  #
   module Utils
     class << self
       ##

data/lib/convenient_service/version.rb

@@ -6,5 +6,12 @@
 ##
 
 module ConvenientService
-  VERSION = "0.20.0"
+  ##
+  # Returns current Convenient Service version.
+  #
+  # @api public
+  # @since 1.0.0
+  # @return [String]
+  #
+  VERSION = "0.21.0"
 end