sord 3.0.1 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c04d27e18791a912df49bf20c04c3d8555c04ce7f4e9d97d566398c705b4d826
-  data.tar.gz: c9868a430d1cace15d5c11463c7718aa768e2f4b195c9877ba0cb9a995bb8d7e
+  metadata.gz: 12567f3b935a14271aedb28b62acfcfef3cb1e3bfb80fd294732947490dfb765
+  data.tar.gz: c40c2790500508fd2e575ab01e471cf7fe0e90f0c6d255285c7474433b65952c
 SHA512:
-  metadata.gz: 2e1266f3b0950874993fb09814431d6ccc7e379128b7146bd46865571d422676df3103ec602534d2cd2e517e1b24b098d8e1edb09cb7002226369fa41d65c127
-  data.tar.gz: c358bd3954399bc55db8883720a40bf1452131771367eb0613637899f5c4d319af6ee3c4d261cb70cb355d83cc21339489562ec1847c47f2893cb40a9c192818
+  metadata.gz: 85435a86928840302557121d0deeafde94a0b70905da93403c642a303ec773f5f4503b316beed31709052839a597e671df9ac554410d4c169843e859aebf361d
+  data.tar.gz: 77795ca64b509b9c7e7da210fac12d2b27bb8fe9e952ab61dc1d87c92189a1d0e457a4546bce2cebac4230a643f96072559c39bd477fc7e345819c98dd0b3bdd

data/.github/workflows/ruby.yml

@@ -0,0 +1,22 @@
+name: Run tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        ruby: [2.7, 3.0, 3.1]
+    continue-on-error: false
+
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+    - name: Install dependencies
+      run: bundle install
+    - name: Run tests
+      run: bundle exec rake

data/CHANGELOG.md

@@ -3,6 +3,49 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [5.0.0] - 2022-10-06
+### Added
+- If a derived class does not provide tags for a method, but it is overridden from a base class
+  which does, then the base class' documentation will be used to generate types for the derived
+  method.
+- When generating RBS, if a duck type matches one of RBS' built-in interfaces, this type will be
+  generated instead. (For example, `#to_s` will generate the type `_ToS`.)
+- Added the `--hide-private` flag, which will omit outputting items with private visibility.
+- To improve resolution, types for gems are now loaded from the RBS collection.
+- If you are using custom YARD tags, Sord can now be made aware of these by passing the `--tags`
+  option.
+
+### Changed
+- **Breaking change**: Support for versions of Ruby prior to 2.7 has been dropped.
+- When Sord runs YARD automatically, it no longer generates HTML documentation, since this isn't
+  necessary for Sord's analysis. If you were relying on this as part of your workflow, then this
+  could be a **breaking change**.
+
+### Fixed
+- Duck-typed methods ending with `?` or `!`, and operator methods like `#[]=`, are now correctly
+  recognised as duck types.
+- Fixed an exception when referring to built-in types with root namespace (`::Array<Foo>`) syntax.
+- `@yieldparams` without a parameter name no longer cause an exception, and instead use default
+  names of the pattern: `arg0`, `arg1`, ...
+
+## [4.0.0] - 2022-07-19
+### Added
+- Constants are now assigned types when generating RBS, using `@return`.
+- Class-level `attr_accessor`s are converted to methods when generating RBS.
+- Added the `--exclude-untyped` flag, which skips generating type signatures for methods with
+  `untyped` return values.
+
+### Changed
+- If YARD tags are present for a block, but there is no block param (such as when using `yield`),
+  the type signature now includes the documented block. This could be a **breaking change** leading
+  to type errors in existing code where such methods are called.
+
+### Fixed
+- Added workaround for YARD syntax error when a default parameter value begins with a unary minus
+- Name resolutions from the root (e.g. `::X`) now behave correctly; previously they may have
+  selected a class named `X` nested within another namespace. This may be a **breaking change** if
+  any part of your generated type signatures was relying on the old, buggy behaviour.
+
 ## [3.0.1] - 2020-12-28
 ### Fixed
 - Fixed `SortedSet` crash on Ruby 3

data/README.md

@@ -12,6 +12,8 @@ type signatures you need!
 Sord is the perfect way to jump-start the adoption of types in your project,
 whether you plan to use Sorbet's RBI format or Ruby 3/Steep's RBS format.
 
+**Try Sord online at: [sord.aaronc.cc](https://sord.aaronc.cc)**
+
 Sord has the following features:
   - Automatically generates signatures for modules, classes and methods
   - Support for multiple parameter or return types (`T.any`/`|`)
@@ -81,6 +83,10 @@ Sord also takes some flags to alter the generated file:
     take a comma-separated list of logging kinds, for example `omit,infer`.
     When using `--include-messages`, the `done` kind is included by default.
     (You cannot specify both `--include-messages` and `--exclude-messages`.)
+  - `--exclude-untyped`: Exclude methods and attributes with untyped return
+    values.
+  - `--tags TAGS`: Provide a list of comma-separated tags as understood by the
+    `yard` command. E.g. `--tags 'mytag:My Description,mytag2:My New Description'
 
 ## Example
 

data/exe/sord

@@ -22,7 +22,10 @@ command :gen do |c|
   c.option '--include-messages STRING', String, 'Whitelists a comma-separated string of log message types'
   c.option '--keep-original-comments', 'Retains original YARD comments rather than converting them to Markdown'
   c.option '--skip-constants', 'Excludes constants from generated file'
+  c.option '--hide-private', 'Exclude any object marked with @!visibility private'
   c.option '--use-original-initialize-return', 'Uses the specified return type for #initialize rather than void'
+  c.option '--exclude-untyped', 'Exclude methods and attributes with untyped return values'
+  c.option '--tags TAGS', Array, 'Tag parameters for the YARD command'
 
   c.action do |args, options|
     options.default(
@@ -33,21 +36,24 @@ command :gen do |c|
       break_params: 4,
       replace_errors_with_untyped: false,
       replace_unresolved_with_untyped: false,
+      hide_private: false,
       exclude_messages: nil,
       include_messages: nil,
       keep_original_comments: false,
       skip_constants: false,
       use_original_initialize_return: false,
+      exclude_untyped: false,
+      tags: [],
     )
 
     if args.length != 1
       Sord::Logging.error('Must specify filename')
       exit 1
     end
-    
+
     plugin_options = options.__hash__
-    plugin_options[:exclude_options] = plugin_options[:exclude_options]&.split(',')
-    plugin_options[:include_options] = plugin_options[:include_options]&.split(',')
+    plugin_options[:exclude_messages] = plugin_options[:exclude_messages]&.split(',')
+    plugin_options[:include_messages] = plugin_options[:include_messages]&.split(',')
 
     if !(plugin_options[:rbi] || plugin_options[:rbs])
       if args.first
@@ -84,7 +90,7 @@ command :gen do |c|
 
     plugin.parlour = klass.new(break_params: plugin_options[:break_params])
     plugin.generate(plugin.parlour.root)
-    
+
     File.write(args.first, plugin.parlour.send(generator_method))
   end
 end

data/lib/sord/generator.rb

@@ -8,16 +8,16 @@ require 'rainbow'
 module Sord
   # Converts the current working directory's YARD registry into an type
   # signature file.
-  class Generator    
+  class Generator
     VALID_MODES = [:rbi, :rbs]
 
-    # @return [Integer] The number of objects this generator has processed so 
+    # @return [Integer] The number of objects this generator has processed so
     #   far.
     def object_count
       @namespace_count + @method_count
     end
 
-    # @return [Array<Array(String, YARD::CodeObjects::Base, Integer)>] The 
+    # @return [Array<Array(String, YARD::CodeObjects::Base, Integer)>] The
     #   errors encountered by by the generator. Each element is of the form
     #   [message, item, line].
     attr_reader :warnings
@@ -28,6 +28,7 @@ module Sord
     # @option options [Integer] break_params
     # @option options [Boolean] replace_errors_with_untyped
     # @option options [Boolean] replace_unresolved_with_untyped
+    # @option options [Boolean] hide_private
     # @option options [Boolean] comments
     # @option options [Parlour::Generator] generator
     # @option options [Parlour::TypedObject] root
@@ -53,12 +54,28 @@ module Sord
       @replace_errors_with_untyped = options[:replace_errors_with_untyped]
       @replace_unresolved_with_untyped = options[:replace_unresolved_with_untyped]
       @keep_original_comments = options[:keep_original_comments]
+      @hide_private = options[:hide_private]
       @skip_constants = options[:skip_constants]
       @use_original_initialize_return = options[:use_original_initialize_return]
+      @exclude_untyped = options[:exclude_untyped]
+
+      @type_converter_config = TypeConverter::Configuration.new(
+        output_language: @mode,
+        replace_errors_with_untyped: @replace_errors_with_untyped,
+        replace_unresolved_with_untyped: @replace_unresolved_with_untyped,
+      )
 
       # Hook the logger so that messages are added as comments
-      Logging.add_hook do |type, msg, item|
-        @current_object.add_comment_to_next_child("sord #{type} - #{msg}")
+      Logging.add_hook do |type, msg, item, **opts|
+        # Hack: the "exclude untyped" log message needs to print somewhere, but
+        # if there's no future object for that comment to associate with, it'll
+        # never be printed!
+        # Instead, add an arbitrary containing the comment
+        if opts[:immediate]
+          @current_object.create_arbitrary(code: "# sord #{type} - #{msg}")
+        else
+          @current_object.add_comment_to_next_child("sord #{type} - #{msg}")
+        end
       end if options[:sord_comments]
 
       # Hook the logger so that warnings are collected
@@ -110,7 +127,8 @@ module Sord
     def add_constants(item)
       inserted_constant_names = Set.new
 
-      item.constants(included: false).each do |constant|      
+      item.constants(included: false).each do |constant|
+        next if @hide_private && constant.visibility == :private
         # Take a constant (like "A::B::CONSTANT"), split it on each '::', and
         # set the constant name to the last string in the array.
         constant_name = constant.to_s.split('::').last
@@ -119,7 +137,7 @@ module Sord
           next
         end
         inserted_constant_names << constant_name
-        
+
         # Add the constant to the current object being generated.
         case @mode
         when :rbi
@@ -127,7 +145,18 @@ module Sord
             c.add_comments(constant.docstring.all.split("\n"))
           end
         when :rbs
-          @current_object.create_constant(constant_name, type: Parlour::Types::Untyped.new) do |c|
+          return_tags = constant.tags('return')
+          returns = if return_tags.empty?
+            Logging.omit("no YARD return type given, using untyped", constant)
+            Parlour::Types::Untyped.new
+          else
+            TypeConverter.yard_to_parlour(
+              return_tags.map(&:types).flatten,
+              constant,
+              @type_converter_config,
+            )
+          end
+          @current_object.create_constant(constant_name, type: returns) do |c|
             c.add_comments(constant.docstring.all.split("\n"))
           end
         end
@@ -225,12 +254,33 @@ module Sord
       end
     end
 
+    # @param method [YARD::CodeObjects::MethodObject]
+    # @param tag_name [String]
+    # @return [Array<YARD::Tags::Tag>]
+    def method_tags(method, tag_name)
+      tags = method.tags(tag_name)
+      return tags if tags.any? || method.overridden_method.nil?
+
+      method.overridden_method.tags(tag_name)
+    end
+
+    # @param method [YARD::CodeObjects::MethodObject]
+    # @param tag_name [String]
+    # @return [YARD::Tags::Tag, nil]
+    def method_tag(method, tag_name)
+      tag = method.tag(tag_name)
+      return tag if tag || method.overridden_method.nil?
+
+      method.overridden_method.tag(tag_name)
+    end
+
     # Given a YARD NamespaceObject, add lines defining its methods and their
     # signatures to the current file.
     # @param [YARD::CodeObjects::NamespaceObject] item
     # @return [void]
     def add_methods(item)
       item.meths(inherited: false).each do |meth|
+        next if @hide_private && meth.visibility == :private
         count_method
 
         # If the method is an alias, skip it so we don't define it as a
@@ -243,37 +293,44 @@ module Sord
         if meth.is_attribute?
           next
         end
-      
+
         # Sort parameters
         meth.parameters.reverse.sort! { |pair1, pair2| sort_params(pair1, pair2) }
-        # This is better than iterating over YARD's "@param" tags directly 
+
+        # This is better than iterating over YARD's "@param" tags directly
         # because it includes parameters without documentation
         # (The gsubs allow for better splat-argument compatibility)
         parameter_names_and_defaults_to_tags = meth.parameters.map do |name, default|
-          [[name, default], meth.tags('param')
+          [[name, fix_default_if_unary_minus(default)], method_tags(meth, 'param')
             .find { |p| p.name&.gsub('*', '')&.gsub(':', '') == name.gsub('*', '').gsub(':', '') }]
         end.to_h
 
+        # Add block param if there is no named param but YARD tags are present
+        if !parameter_names_and_defaults_to_tags.any? { |((name, _), _)| name.start_with? '&' } \
+            && (method_tags(meth, 'yieldparam').any? || method_tag(meth, 'yieldreturn'))
+          parameter_names_and_defaults_to_tags[['&blk']] = nil
+        end
+
         parameter_types = parameter_names_and_defaults_to_tags.map do |name_and_default, tag|
           name = name_and_default.first
 
           if tag
-            TypeConverter.yard_to_parlour(tag.types, meth, @replace_errors_with_untyped, @replace_unresolved_with_untyped)
+            TypeConverter.yard_to_parlour(tag.types, meth, @type_converter_config)
           elsif name.start_with? '&'
             # Find yieldparams and yieldreturn
-            yieldparams = meth.tags('yieldparam')
-            yieldreturn = meth.tag('yieldreturn')&.types
+            yieldparams = method_tags(meth, 'yieldparam')
+            yieldreturn = method_tag(meth, 'yieldreturn')&.types
             yieldreturn = nil if yieldreturn&.length == 1 &&
               yieldreturn&.first&.downcase == 'void'
 
             # Create strings
-            params = yieldparams.map do |param|
+            params = yieldparams.map.with_index do |param, i|
               Parlour::Types::Proc::Parameter.new(
-                param.name.gsub('*', ''),
-                TypeConverter.yard_to_parlour(param.types, meth, @replace_errors_with_untyped, @replace_unresolved_with_untyped)
+                param.name&.gsub('*', '') || "arg#{i}",
+                TypeConverter.yard_to_parlour(param.types, meth, @type_converter_config)
               )
             end
-            returns = TypeConverter.yard_to_parlour(yieldreturn, meth, @replace_errors_with_untyped, @replace_unresolved_with_untyped)
+            returns = TypeConverter.yard_to_parlour(yieldreturn, meth, @type_converter_config)
 
             # Create proc types, if possible
             if yieldparams.empty? && yieldreturn.nil?
@@ -288,36 +345,36 @@ module Sord
 
             unless getter
               if parameter_names_and_defaults_to_tags.length == 1 \
-                && meth.tags('param').length == 1 \
-                && meth.tag('param').types
-  
+                && method_tags(meth, 'param').length == 1 \
+                && method_tag(meth, 'param').types
+
                 Logging.infer("argument name in single @param inferred as #{parameter_names_and_defaults_to_tags.first.first.first.inspect}", meth)
-                next TypeConverter.yard_to_parlour(meth.tag('param').types, meth, @replace_errors_with_untyped, @replace_unresolved_with_untyped)
-              else  
+                next TypeConverter.yard_to_parlour(method_tag(meth, 'param').types, meth, @type_converter_config)
+              else
                 Logging.omit("no YARD type given for #{name.inspect}, using untyped", meth)
                 next Parlour::Types::Untyped.new
               end
             end
 
-            return_types = getter.tags('return').flat_map(&:types)
+            return_types = method_tags(getter, 'return').flat_map(&:types)
             unless return_types.any?
               Logging.omit("no YARD type given for #{name.inspect}, using untyped", meth)
               next Parlour::Types::Untyped.new
             end
             inferred_type = TypeConverter.yard_to_parlour(
-              return_types, meth, @replace_errors_with_untyped, @replace_unresolved_with_untyped)
-            
+              return_types, meth, @type_converter_config)
+
             Logging.infer("inferred type of parameter #{name.inspect} as #{inferred_type.describe} using getter's return type", meth)
             inferred_type
           else
             # Is this the only argument, and was a @param specified without an
             # argument name? If so, infer it
             if parameter_names_and_defaults_to_tags.length == 1 \
-              && meth.tags('param').length == 1 \
-              && meth.tag('param').types
+              && method_tags(meth, 'param').length == 1 \
+              && method_tag(meth, 'param').types
 
               Logging.infer("argument name in single @param inferred as #{parameter_names_and_defaults_to_tags.first.first.first.inspect}", meth)
-              TypeConverter.yard_to_parlour(meth.tag('param').types, meth, @replace_errors_with_untyped, @replace_unresolved_with_untyped)
+              TypeConverter.yard_to_parlour(method_tag(meth, 'param').types, meth, @type_converter_config)
             else
               Logging.omit("no YARD type given for #{name.inspect}, using untyped", meth)
               Parlour::Types::Untyped.new
@@ -325,7 +382,7 @@ module Sord
           end
         end
 
-        return_tags = meth.tags('return')
+        return_tags = method_tags(meth, 'return')
         returns = if meth.name == :initialize && !@use_original_initialize_return
           nil
         elsif return_tags.length == 0
@@ -334,14 +391,14 @@ module Sord
         elsif return_tags.length == 1 && %w{void nil}.include?(return_tags&.first&.types&.first&.downcase)
           nil
         else
-          TypeConverter.yard_to_parlour(meth.tag('return').types, meth, @replace_errors_with_untyped, @replace_unresolved_with_untyped)
+          TypeConverter.yard_to_parlour(method_tag(meth, 'return').types, meth, @type_converter_config)
         end
 
         rbs_block = nil
         parlour_params = parameter_names_and_defaults_to_tags
           .zip(parameter_types)
           .map do |((name, default), _), type|
-            # If the default is "nil" but the type is not nilable, then it 
+            # If the default is "nil" but the type is not nilable, then it
             # should become nilable
             # (T.untyped can include nil, so don't alter that)
             type = Parlour::Types::Nilable.new(type) \
@@ -369,10 +426,15 @@ module Sord
           end
           .compact
 
+        if @exclude_untyped && parlour_params.all? { |p| p.type.is_a?(Parlour::Types::Untyped) } && returns.is_a?(Parlour::Types::Untyped)
+          Logging.omit("excluding untyped", meth, immediate: true)
+          next
+        end
+
         case @mode
         when :rbi
           @current_object.create_method(
-            meth.name.to_s, 
+            meth.name.to_s,
             parameters: parlour_params,
             returns: returns,
             class_method: meth.scope == :class
@@ -391,7 +453,7 @@ module Sord
           ) do |m|
             add_comments(meth, m)
           end
-        end  
+        end
       end
     end
 
@@ -415,10 +477,12 @@ module Sord
           # Get all given types
           yard_types = []
           if reader
+            next if @hide_private && reader.visibility == :private
             yard_types += reader.tags('return').flat_map(&:types).compact.reject { |x| x.downcase == 'void' } +
               reader.tags('param').flat_map(&:types)
           end
           if writer
+            next if @hide_private && writer.visibility == :private
             yard_types += writer.tags('return').flat_map(&:types).compact.reject { |x| x.downcase == 'void' } +
               writer.tags('param').flat_map(&:types)
           end
@@ -433,7 +497,7 @@ module Sord
             parlour_type = Parlour::Types::Untyped.new
           else
             parlour_type = TypeConverter.yard_to_parlour(
-              yard_types, reader || writer, @replace_errors_with_untyped, @replace_unresolved_with_untyped)
+              yard_types, reader || writer, @type_converter_config)
           end
 
           # Generate attribute
@@ -445,6 +509,11 @@ module Sord
             kind = :writer
           end
 
+          if @exclude_untyped && parlour_type.is_a?(Parlour::Types::Untyped)
+            Logging.omit("excluding untyped attribute", reader || writer, immediate: true)
+            next
+          end
+
           case @mode
           when :rbi
             @current_object.create_attribute(
@@ -457,7 +526,31 @@ module Sord
             end
           when :rbs
             if attr_loc == :class
-              Logging.warn("RBS doesn't support class attributes, dropping", reader || writer)
+              # RBS doesn't support class attr_accessors so create individual methods
+
+              if reader
+                @current_object.create_method(
+                  name.to_s,
+                  [Parlour::RbsGenerator::MethodSignature.new([], parlour_type)],
+                  class_method: true
+                ) do |m|
+                  add_comments(reader, m)
+                end
+              end
+
+              if writer
+                @current_object.create_method(
+                  "#{name}=",
+                  [Parlour::RbsGenerator::MethodSignature.new([Parlour::RbsGenerator::Parameter.new(
+                    "value",
+                    type: parlour_type,
+                    required: true
+                  )], parlour_type)],
+                  class_method: true
+                ) do |m|
+                  add_comments(writer, m)
+                end
+              end
             else
               @current_object.create_attribute(
                 name.to_s,
@@ -477,6 +570,7 @@ module Sord
     # @param [YARD::CodeObjects::NamespaceObject] item
     # @return [void]
     def add_namespace(item)
+      return if @hide_private && item.visibility == :private
       count_namespace
 
       superclass = nil
@@ -499,7 +593,7 @@ module Sord
       @current_object = parent
     end
 
-    # Populates the generator with the contents of the YARD registry. You 
+    # Populates the generator with the contents of the YARD registry. You
     # must load the YARD registry first!
     # @return [void]
     def populate
@@ -597,5 +691,20 @@ module Sord
 
       return pair_type_order[pair1_type] <=> pair_type_order[pair2_type]
     end
+
+    # Removes the last character of a default parameter value if it begins with
+    # '-', working around a bug in YARD. (See lsegal/yard #894)
+    #
+    # @param [String] default
+    # @return [String, nil]
+    def fix_default_if_unary_minus(default)
+      if default.nil?
+        nil
+      elsif default[0] == '-' && !default.start_with?('->')
+        default[0..-2]
+      else
+        default
+      end
+    end
   end
 end

data/lib/sord/logging.rb

@@ -70,16 +70,17 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.generic(kind, header, msg, item)
+    def self.generic(kind, header, msg, item, **opts)
       return unless enabled_types.include?(kind)
 
-      if item
-        puts "#{header} (#{Rainbow(item.path).bold}) #{msg}" unless silent?
+      message = if item
+        "#{header} (#{Rainbow(item.path).bold}) #{msg}"
       else
-        puts "#{header} #{msg}" unless silent?
+        "#{header} #{msg}"
       end
+      puts message unless silent?
 
-      invoke_hooks(kind, msg, item)
+      invoke_hooks(kind, msg, item, **opts)
     end
 
     # Print a warning message. This should be used for things which require the
@@ -89,8 +90,8 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.warn(msg, item = nil)
-      generic(:warn, Rainbow('[WARN ]').yellow, msg, item)
+    def self.warn(msg, item = nil, **opts)
+      generic(:warn, Rainbow('[WARN ]').yellow, msg, item, **opts)
     end
 
     # Print an info message. This should be used for generic informational
@@ -100,8 +101,8 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.info(msg, item = nil)
-      generic(:info, '[INFO ]', msg, item)
+    def self.info(msg, item = nil, **opts)
+      generic(:info, '[INFO ]', msg, item, **opts)
     end
 
     # Print a duck-typing message. This should be used when the YARD 
@@ -112,8 +113,8 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.duck(msg, item = nil)
-      generic(:duck, Rainbow('[DUCK ]').cyan, msg, item)
+    def self.duck(msg, item = nil, **opts)
+      generic(:duck, Rainbow('[DUCK ]').cyan, msg, item, **opts)
     end
 
     # Print an error message. This should be used for things which require the
@@ -123,8 +124,8 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.error(msg, item = nil)
-      generic(:error, Rainbow('[ERROR]').red, msg, item)
+    def self.error(msg, item = nil, **opts)
+      generic(:error, Rainbow('[ERROR]').red, msg, item, **opts)
     end
 
     # Print an infer message. This should be used when the user should be told
@@ -135,8 +136,8 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.infer(msg, item = nil)
-      generic(:infer, Rainbow('[INFER]').blue, msg, item)
+    def self.infer(msg, item = nil, **opts)
+      generic(:infer, Rainbow('[INFER]').blue, msg, item, **opts)
     end
 
     # Print an omit message. This should be used as a special type of warning
@@ -147,8 +148,8 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.omit(msg, item = nil)
-      generic(:omit, Rainbow('[OMIT ]').magenta, msg, item)
+    def self.omit(msg, item = nil, **opts)
+      generic(:omit, Rainbow('[OMIT ]').magenta, msg, item, **opts)
     end
 
     # Print a done message. This should be used when a process completes
@@ -158,8 +159,8 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.done(msg, item = nil)
-      generic(:done, Rainbow('[DONE ]').green, msg, item)
+    def self.done(msg, item = nil, **opts)
+      generic(:done, Rainbow('[DONE ]').green, msg, item, **opts)
     end
 
     # Invokes all registered hooks on the logger.
@@ -169,9 +170,9 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.invoke_hooks(kind, msg, item)
+    def self.invoke_hooks(kind, msg, item, **opts)
       @@hooks.each do |hook|
-        hook.(kind, msg, item) rescue nil
+        hook.(kind, msg, item, **opts)
       end
     end