debugtrace 0.2.6 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a1011528c478c032c1223c1fceb442bb32de6ba1ef40d9df2436b27718327c4
-  data.tar.gz: 5e11c1af69b68a0d8b380d7e4c09b703ad773ea43a23fb11cee1289827dfd926
+  metadata.gz: 4ba0b48484b98dad04cefc154c88afc5e82e88d551ab00d81dd3ddbe323a0e7a
+  data.tar.gz: 6f858f96393d92d0b13f4ec5f34877d9d48623990d0251cd8c6c0f81d6616c1c
 SHA512:
-  metadata.gz: a74c1b4784462f0ebc6a6b40d55c9ebba4df3bd087ec5e421fecd8b0c79cdda06404fa7e5c914d83ddccd96b6aa3dadeef0d21b1f53a3164cbcf0c7932b86298
-  data.tar.gz: e6b556af241a5976d6e7731138cb48d3059ce90b0ec4b274d3844da134532ed0156280bb37d85ae7d03106d1ea855dd399723ba41546fbdd42b71221a41b65e1
+  metadata.gz: 55d162f057c2686e1c350caac7c3b4a48f493d04b344711ea2beb8c5a995ff9066334c845fc58e0d6a82dee76d17cfe001f22a74f76d47841b8ad076877a6e61
+  data.tar.gz: ce01d78482c3fa14a84f21b8d7b7f68a5ffe2efd3dee453d5ae622256818509b4ec7b9df037f121e8caaf032dfe84a10ee3ea205e4b2793877a222a3b7395c1e

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 TODO: Write your name
+Copyright (c) 2025 Masato Kokubo
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/debugtrace/common.rb

@@ -2,16 +2,17 @@
 # (C) 2025 Masato Kokubo
 
 #　Defines commonly used functions.
-# @author Masato Kokubo
 module Common
   # Check the value types.
+  #
   # @param value_name [String] the value name
   # @param value [String] the value
   # @param type [Class] the type
-  # @raise if the value is not an instance of the type or the subclass of the type
+  # @return [String] the value
+  # @raise [TypeError] if the value is not an instance of the type or the subclass of the type
   def self.check_type(value_name, value, type)
-    raise "Argument value_name (=#{value_name}) must be a String" unless value_name.is_a?(String)
-    raise "Argument type (=#{type}) must be a Class" unless type.is_a?(Class)
+    raise TypeError("Argument value_name (=#{value_name}) must be a String") unless value_name.is_a?(String)
+    raise TypeError("Argument type (=#{type}) must be a Class") unless type.is_a?(Class)
 
     error = false
     if type == FalseClass || type == TrueClass
@@ -28,7 +29,7 @@ module Common
       top_type_name = type.name.slice(0).upcase
       a = top_type_name == 'A' || top_type_name == 'I' || top_type_name == 'U' ||
         top_type_name == 'E' || top_type_name == 'O' ? 'an' : 'a'
-      raise "Argument #{value_name} (=#{value_string}) must be #{a} #{type}"
+      raise TypeError("Argument #{value_name} (=#{value_string}) must be #{a} #{type}")
     end
     return value
   end

data/lib/debugtrace/config.rb

@@ -4,7 +4,6 @@ require 'yaml'
 require_relative 'common'
 
 # Retains the contents defined in debugtrace.yml.
-# @author Masato Kokubo
 class Config
   attr_reader :config_path
   attr_reader :config
@@ -36,6 +35,7 @@ class Config
   attr_reader :reflection_limit
 
   # Initializes with a yml file in the config_path.
+  #
   # @param config_path [String] path of the yml file
   def initialize(config_path)
     @config_path = Common.check_type('config_path', config_path, String)
@@ -75,7 +75,8 @@ class Config
   end
 
   # Returns true if logging is enabled, false otherwise.
-  # @return true if logging is enabled, false otherwise
+  #
+  # @return [TrueClass, FalseClass] true if logging is enabled, false otherwise
   def enabled?
     return @enabled
   end
@@ -83,6 +84,7 @@ class Config
   private
 
   # Gets the value related the key from debugtrace.yml file.
+  #
   # @param key [String] the key
   # @param defalut_value [Object] value to return if the value related the key is undefined
   # @return [Object] value related the key

data/lib/debugtrace/log_buffer.rb

@@ -3,17 +3,23 @@
 require_relative 'common'
 
 # Buffers logs.
-# @author Masato Kokubo
 class LogBuffer
+  # Contains a single line indentation level and log content.
   class LevelAndLog
+    attr_reader :nest_level, :log
+
     # Initializes this object.
+    #
+    # @param nest_level [Integer] the nesting level
+    # @param log [String] the log message
     def initialize(nest_level, log)
       @nest_level = Common.check_type('nest_level', nest_level, Integer)
       @log = Common.check_type('log', log, String)
     end
 
-    attr_reader :nest_level, :log
-
+    # Returns a string representation of this object.
+    #
+    # @return [String] a string representation of this object.
     def to_s
       return "(LogBuffer.LevelAndLog){nest_level: #{@nest_level}, log: \"#{@log}\"}"
     end
@@ -50,11 +56,12 @@ class LogBuffer
   end
 
   # Appends a string representation of the value.
+  #
   # @param value [Object] The value to append
   # @param nest_level (int, optional): The nest level of the value. Defaults to 0
   # @param no_break (bool, optional): If true, does not break even if the maximum width is exceeded.
   #         Defaults to false
-  # @return LogBuffer: This object
+  # @return [LogBuffer] this object
   def append(value, nest_level = 0, no_break = false)
     Common.check_type('nest_level', nest_level, Integer)
     Common.check_type('no_break', no_break, TrueClass)
@@ -69,17 +76,18 @@ class LogBuffer
 
   # Appends a string representation of the value.
   # Does not break even if the maximum width is exceeded.
+  #
   # @param value [Object] The value to append
-  # @return LogBuffer: This object
+  # @return [LogBuffer] this object
   def no_break_append(value)
     return append(value, 0, true)
   end
 
   # Appends lines of another LogBuffer.
-  # @param
-  # @param separator [String] The separator string to append if not ''
-  # @param buff (LogBuffer): Another LogBuffer
-  # @returns LogBuffer: This object
+  #
+  # @param separator [String] the separator string to append if not ''
+  # @param buff [LogBuffer] another LogBuffer
+  # @return [LogBuffer] this object
   def append_buffer(separator, buff)
     Common.check_type('separator', separator, String)
     Common.check_type('buff', buff, LogBuffer)
@@ -98,12 +106,16 @@ class LogBuffer
     return @last_line.length
   end
 
-  # true if multiple line, false otherwise.
+  # Returns true if multiple line, false otherwise.
+  #
+  # @return [FalseClass, TrueClass] true if multiple line, false otherwise.
   def multi_lines?
     return @lines.length > 1 || @lines.length == 1 && length > 0
   end
 
-  # A list of tuple of data indentation level && log string.
+  # Returns the LevelAndLog objects.
+  #
+  # @return [Array<LevelAndLog>] the LevelAndLog objects.
   def lines
     lines = @lines.dup
     lines << LevelAndLog.new(@nest_level, @last_line) if length > 0

data/lib/debugtrace/loggers.rb

@@ -4,13 +4,13 @@ require 'logger'
 require_relative 'common'
 require_relative 'config'
 
-# Abstract base class for logger classes.
-# @author Masato Kokubo
+# @abstract Base class for logger classes.
 class LoggerBase
-  # Outputs the message.
+  # @abstract Outputs the message.
   # @param message [String] The message to output
+  # @raise [Exception] always
   def print(message)
-    raise 'LoggerBase.print is an abstract method.'
+    raise Exception.new('LoggerBase.print is an abstract method.')
   end
 
   # Returns a string representation of this object.
@@ -23,18 +23,19 @@ end
 # Abstract base class for StdOut and StdErr classes.
 class StdLogger < LoggerBase
   # Initializes this object.
-  # @param iostream: Output destination
-  def initialize(config, iostream)
+  # @param [IO] Output destination
+  def initialize(config, output)
     @config = Common::check_type("config", config, Config)
-    @iostream = iostream
+    @output = output
   end
 
   # Outputs the message.
-  # @param message [String] The message to output
+  # @param message [String] the message to output
+  # @return [String] the message
   def print(message)
     Common::check_type("message", message, String)
     datetime_str = Time.now().strftime(@config.logging_datetime_format)
-    @iostream.puts "#{datetime_str} #{message}"
+    @output.puts "#{datetime_str} #{message}"
   end
 
 end
@@ -42,6 +43,7 @@ end
 # A logger class that outputs to $stdout.
 class StdOutLogger < StdLogger
   # Initializes this object.
+  # config [Config] a configuration object
   def initialize(config)
     super(config, $stdout)
   end
@@ -50,18 +52,21 @@ end
 # A logger class that outputs to $stderr.
 class StdErrLogger < StdLogger
   # Initializes this object.
+  # config [Config] a configuration object
   def initialize(config)
     super(config, $stderr)
   end
 end
 
-# A logger class that outputs using the logging library.
+# A logger class that outputs using Ruby Logger.
 class RubyLogger
   private
 
   class Formatter
+    # Initializes this object.
+    # config [Config] a configuration object
     def initialize(config)
-      @config = config
+      @config = Common::check_type("config", config, Config)
     end
 
     def call(severity, datetime, progname, msg)
@@ -72,6 +77,9 @@ class RubyLogger
 
   public
 
+  # Initializes this object.
+  #
+  # @param config [Config] a configuration object
   def initialize(config)
     @config = Common::check_type("config", config, Config)
     @logger = Logger.new(
@@ -81,6 +89,7 @@ class RubyLogger
   end
 
   # Outputs the message.
+  #
   # @param message [String] The message to output
   def print(message)
     Common::check_type("message", message, String)
@@ -89,6 +98,7 @@ class RubyLogger
   end
 
   # Returns a string representation of this object.
+  #
   # @return [String] A string representation of this object
   def to_s
     return "Ruby #{Logger.name} path: #{@config.log_path}"
@@ -99,6 +109,9 @@ end
 class FileLogger < LoggerBase
   @@log_path_default = 'debugtrace.log'
 
+  # Initializes this object.
+  #
+  # @parm config [Config] a configuration object
   def initialize(config)
     @log_path = @@log_path_default
     @config = Common::check_type("config", config, Config)
@@ -125,8 +138,11 @@ class FileLogger < LoggerBase
     end
   end
   
+  # Outputs the message.
+  #
+  # @param message [String] the message to output
+  # @return [String] the message
   def print(message)
-  # Common::check_type("message", message, String)
     if File.exist?(@log_path)
       File.open(@log_path, 'a') { |file|
         datetime_str = Time.now().strftime(@config.logging_datetime_format)
@@ -137,6 +153,7 @@ class FileLogger < LoggerBase
   end
 
   # Returns a string representation of this object.
+  #
   # @return [String] A string representation of this object
   def to_s
     return "#{self.class.name} path: #{@log_path}, append: #{@append}"

data/lib/debugtrace/state.rb

@@ -2,24 +2,30 @@
 # (C) 2025 Masato Kokubo
 require_relative 'common'
 
-# Have the trace state for a thread
-# @author Masato Kokubo
+# Contains the trace state for a thread
 class State
   attr_reader :thread_id
   attr_reader :nest_level
   attr_reader :previous_nest_level
 
+  # Initializes this object.
+  #
+  # @param thread_id [Integer] the object id of the thread
   def initialize(thread_id)
-    @thread_id = thread_id
+    @thread_id = Common.check_type('thread_id', thread_id, Integer)
     reset()
   end
 
+  # Resets this object
   def reset
     @nest_level = 0
     @previous_nest_level = 0
     @times = []
   end
 
+  # Returns a string representation of this object.
+  #
+  # @return [String] A string representation of this object
   def to_s()
       return "(State){thread_id: #{@thread_id}, nest_level: #{@nest_level}, previous_nest_level: #{@previous_nest_level}, times: #{@times}}"
   end
@@ -31,11 +37,11 @@ class State
           @times.push(Time.now)
       end
       @nest_level += 1
-      return nil
   end
 
-  #Downs the nest level.
-  # @return Time: The time when the corresponding upNest method was invoked
+  # Downs the nest level.
+  #
+  # @return [Float] The time when the corresponding up_nest method was invoked
   def down_nest
       @previous_nest_level = @nest_level
       @nest_level -= 1

data/lib/debugtrace/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module DebugTrace
-  VERSION = '0.2.6'
+  VERSION = '0.2.7'
 end

data/lib/debugtrace.rb

@@ -10,7 +10,7 @@ require_relative 'debugtrace/log_buffer'
 require_relative 'debugtrace/loggers'
 require_relative 'debugtrace/state'
 
-# @author Masato Kokubo
+# The main module of DebugTrace-rb.
 module DebugTrace
   # Configuration values
   @@config = nil
@@ -37,6 +37,9 @@ module DebugTrace
   # The logger used by DebugTrace-py
   @@logger = nil
 
+  # Initialize this class
+  #
+  # @option [String] config_path the path to the configuration file. ./debugtrace.yml if not specified.
   def self.initialize(config_path = './debugtrace.yml')
     @@config = Config.new(config_path)
 
@@ -65,11 +68,22 @@ module DebugTrace
     @@logger.print("  logger: #{@@logger}")
   end
 
+  # Contains options to pass to the print method.
   class PrintOptions
-    attr_reader :minimum_output_size, :minimum_output_length,
+    attr_reader :reflection, :minimum_output_size, :minimum_output_length,
                 :collection_limit, :bytes_limit, :string_limit, :reflection_limit
 
+    # Initializes this object.
+    #
+    # @param reflection [TrueClass, FalseClass] use reflection if true
+    # @param minimum_output_size [Integer] the minimum value to output the number of elements for Array and Hash (overrides debugtarace.yml value)
+    # @param minimum_output_length [Integer] the minimum value to output the length of String and byte array (overrides debugtarace.yml value)
+    # @param collection_limit [Integer] Output limit of collection elements (overrides debugtarace.yml value)
+    # @param bytes_limit [Integer] the limit value of elements for bytes and bytearray to output (overrides debugtarace.yml value)
+    # @param string_limit [Integer] the limit value of characters for string to output (overrides debugtarace.yml value)
+    # @param reflection_limit [Integer] reflection limits when using reflection (overrides debugtarace.yml value)
     def initialize(
+      reflection,
       minimum_output_size,
       minimum_output_length,
       collection_limit,
@@ -77,6 +91,7 @@ module DebugTrace
       string_limit,
       reflection_limit
     )
+      @reflection = reflection
       @minimum_output_size = minimum_output_size == -1 ? DebugTrace.config.minimum_output_size : minimum_output_size
       @minimum_output_length = minimum_output_length == -1 ? DebugTrace.config.minimum_output_length : minimum_output_length
       @collection_limit = collection_limit == -1 ? DebugTrace.config.collection_limit : collection_limit
@@ -86,6 +101,9 @@ module DebugTrace
     end
   end
 
+  # Returns the current state.
+  #
+  # @return [State] the current state
   def self.current_state
     thread_id = Thread.current.object_id
 
@@ -99,12 +117,22 @@ module DebugTrace
     return state
   end
 
+  # Returns the current indent string.
+  #
+  # @param nest_level [Integer] the code nesting level
+  # @param data_nest_level [Integer] the data nesting level
+  # @return [Sring] the current indent string
   def self.get_indent_string(nest_level, data_nest_level)
     indent_str = @@config.indent_string * [[0, nest_level].max, @@config.maximum_indents].min
     data_indent_str = @@config.data_indent_string * [[0, data_nest_level].max, @@config.maximum_indents].min
     return indent_str + data_indent_str
   end
 
+  # Returns a string representation of the variable contents.
+  #
+  # @param name [String] the variable name
+  # @param value [Object] the value
+  # @param print_options [PrintOptions] the print options
   def self.to_string(name, value, print_options)
     buff = LogBuffer.new(@@config.maximum_data_output_width)
 
@@ -126,7 +154,8 @@ module DebugTrace
     when Module
       buff.no_break_append(separator).append(value.name).no_break_append(' module')
     when String
-      value_buff = to_string_str(value, print_options)
+      value_buff = value.encoding == Encoding::ASCII_8BIT ?
+          to_string_bytes(value, print_options) : to_string_str(value, print_options)
       buff.append_buffer(separator, value_buff)
     when DateTime
       buff.no_break_append(separator).append(value.strftime('%Y-%m-%d %H:%M-%S.%L%:z'))
@@ -138,25 +167,33 @@ module DebugTrace
       value_buff = to_string_enumerable(value, print_options)
       buff.append_buffer(separator, value_buff)
     else
-      # use reflection
-      value_buff = LogBuffer.new(@@config.maximum_data_output_width)
-      if @@reflected_objects.any? { |obj| value.equal?(obj) }
-        # cyclic reference
-        value_buff.no_break_append(@@config.cyclic_reference_string)
-      elsif @@reflected_objects.length > print_options.reflection_limit
-        # over reflection level limitation
-        value_buff.no_break_append(@@config.limit_string)
+      if print_options.reflection
+        # use reflection
+        value_buff = LogBuffer.new(@@config.maximum_data_output_width)
+        if @@reflected_objects.any? { |obj| value.equal?(obj) }
+          # cyclic reference
+          value_buff.no_break_append(@@config.cyclic_reference_string)
+        elsif @@reflected_objects.length > print_options.reflection_limit
+          # over reflection level limitation
+          value_buff.no_break_append(@@config.limit_string)
+        else
+          @@reflected_objects.push(value)
+          value_buff = to_string_reflection(value, print_options)
+          @@reflected_objects.pop
+        end
+        buff.append_buffer(separator, value_buff)
       else
-        @@reflected_objects.push(value)
-        value_buff = to_string_reflection(value, print_options)
-        @@reflected_objects.pop
+        buff.no_break_append(separator).append(value.to_s)
       end
-      buff.append_buffer(separator, value_buff)
     end
 
     return buff
   end
 
+  # Returns a string representation of the string value
+  #
+  # @param value [String] the value
+  # @param print_options [PrintOptions] the print options
   def self.to_string_str(value, print_options)
     has_single_quote = false
     has_double_quote = false
@@ -219,16 +256,13 @@ module DebugTrace
     return has_single_quote && !has_double_quote ? double_quote_buff : single_quote_buff
   end
 
+  # Returns a string representation of the string value which encoding is ASCII_8BIT.
+  #
+  # @param value [String] the value
+  # @param print_options [PrintOptions] the print options
   def self.to_string_bytes(value, print_options)
     bytes_length = value.length
     buff = LogBuffer.new(@@config.maximum_data_output_width)
-    buff.no_break_append('(')
-
-    if value.is_a?(String)
-      buff.no_break_append('bytes')
-    elsif value.is_a?(Array)
-      buff.no_break_append('bytearray')
-    end
 
     if bytes_length >= @@config.minimum_output_length
       buff.no_break_append(format(@@config.size_format, bytes_length))
@@ -280,6 +314,10 @@ module DebugTrace
     return buff
   end
 
+  # Returns a string representation of the value using reflection.
+  #
+  # @param value [Object] the value
+  # @param print_options [PrintOptions] the print options
   def self.to_string_reflection(value, print_options)
     buff = LogBuffer.new(@@config.maximum_data_output_width)
 
@@ -306,6 +344,10 @@ module DebugTrace
     return buff
   end
 
+  # Returns a string representation of the value using reflection.
+  #
+  # @param value [Object] the value
+  # @param print_options [PrintOptions] the print options
   def self.to_string_reflection_body(value, print_options)
     buff = LogBuffer.new(@@config.maximum_data_output_width)
 
@@ -330,6 +372,10 @@ module DebugTrace
     return buff
   end
 
+  # Returns a string representation of an Array, Set or Hash.
+  #
+  # @param value [Array, Set, Hash] the value
+  # @param print_options [PrintOptions] the print options
   def self.to_string_enumerable(values, print_options)
     open_char = '[' # Array 
     close_char = ']'
@@ -369,6 +415,10 @@ module DebugTrace
     return buff
   end
 
+  # Returns a string representation of the Array, Set or Hash value.
+  #
+  # @param value [Array, Set, Hash] the value
+  # @param print_options [PrintOptions] the print options
   def self.to_string_enumerable_body(values, print_options)
     buff = LogBuffer.new(@@config.maximum_data_output_width)
 
@@ -403,6 +453,11 @@ module DebugTrace
     return buff
   end
 
+  # Returns a string representation the key and the value.
+  #
+  # @param key [Object] the key
+  # @param value [Object] the value
+  # @param print_options [PrintOptions] the print options
   def self.to_string_key_value(key, value, print_options)
     buff = LogBuffer.new(@@config.maximum_data_output_width)
     key_buff = to_string('', key, print_options)
@@ -411,28 +466,24 @@ module DebugTrace
     buff
   end
 
-  def self.get_type_name(value, count = -1)
+  # Returns the type name.
+  #
+  # @param value [Object] the value
+  # @option size [Object] the size of Array, Set or Hash
+  def self.get_type_name(value, size = -1)
     type_name = value.class.to_s
     type_name = '' if %w[Array Hash Set].include?(type_name)
 
-    if count >= @@config.minimum_output_size
-      type_name += @@config.size_format % count
+    if size >= @@config.minimum_output_size
+      type_name += @@config.size_format % size
     end
 
     return type_name
   end
 
-  def self.has_to_s_method?(value)
-    begin
-      value.public_method('to_s')
-    rescue
-      return false
-    end
-    return true
-  end
-
   @@before_thread_id = nil
 
+  # Called at the start of the print method.
   def self.print_start
     if @@before_thread_id == nil
       DebugTrace.initialize
@@ -452,7 +503,19 @@ module DebugTrace
 
   @@DO_NOT_OUTPUT = 'Do not output'
 
+  # Prints the message or the value.
+  #
+  # @param name [String] a message if the value is not specified, otherwise the value name
+  # @option value [Object] the value
+  # @option reflection [TrueClass, FalseClass] use reflection if true
+  # @option minimum_output_size [Integer] the minimum value to output the number of elements for Array and Hash (overrides debugtarace.yml value)
+  # @option minimum_output_length [Integer] the minimum value to output the length of String and byte array (overrides debugtarace.yml value)
+  # @option collection_limit [Integer] Output limit of collection elements (overrides debugtarace.yml value)
+  # @option bytes_limit [Integer] the limit value of elements for bytes and bytearray to output (overrides debugtarace.yml value)
+  # @option string_limit [Integer] the limit value of characters for string to output (overrides debugtarace.yml value)
+  # @option reflection_limit [Integer] reflection limits when using reflection (overrides debugtarace.yml value)
   def self.print(name, value = @@DO_NOT_OUTPUT,
+      reflection: false,
       minimum_output_size: -1, minimum_output_length: -1,
       collection_limit: -1, bytes_limit: -1,
       string_limit: -1, reflection_limit: -1)
@@ -472,6 +535,7 @@ module DebugTrace
       else
         # with value
         print_options = PrintOptions.new(
+          reflection,
           minimum_output_size, minimum_output_length,
           collection_limit, bytes_limit,
           string_limit, reflection_limit
@@ -503,6 +567,7 @@ module DebugTrace
     return value
   end
 
+  # Prints the start of the method.
   def self.enter
     @@thread_mutex.synchronize do
       print_start
@@ -536,6 +601,10 @@ module DebugTrace
     end
   end
 
+  # Prints the end of the method.
+  #
+  # @option [Object] the return value
+  # @return [Object] return_value if specified, otherwise nil
   def self.leave(return_value = nil)
     @@thread_mutex.synchronize do
       print_start
@@ -564,9 +633,10 @@ module DebugTrace
     end
   end
 
+  # Returns the last print string.
   def self.last_print_string
     lines = @@last_log_buff.lines
-    buff_string = lines.map { |line| _config.data_indent_string * line[0] + line[1] }.join("\n")
+    buff_string = lines.map { |line| @@config.data_indent_string * line.nest_level + line.log }.join("\n")
 
     state = nil
     @@thread_mutex.synchronize do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: debugtrace
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.7
 platform: ruby
 authors:
 - Masato Kokubo