debugtrace 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a9dbd0ded97b4a2115a8f5b86cbac05a7db29da09cefae334091cfbe8652ad1b
+  data.tar.gz: 7e121c90bbeecf411b3c7079bf900ac646998a3ec08a3a3f71c11faa56e6fc0d
+SHA512:
+  metadata.gz: ec993125ba921db2f15a4079c57a23735a49a820566b6100e79a3387c9b111a711c4d143eb4350a06913397c3d3a589a5290e4e36bd71bcb352fa16ad591d0ff
+  data.tar.gz: 32f7121dfb3f6c8fc125a775db3c60eecf53590925df24ef1cbfb0d73327f3c9d830063d1c1058cc1718b561f4ed3f2a332ad25c5dc0c2c36c4e93179cbfacdd

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2022-12-10
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,40 @@
+# DebugTrace-rb
+A Ruby library to output logs for debugging.
+
+# DebugTrace
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/debugtrace`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+$ bundle add debugtrace
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+$ gem install debugtrace
+```
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test-unit` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/debugtrace.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/debugtrace/common.rb

@@ -0,0 +1,27 @@
+# common.rb
+# (C) 2023 Masato Kokubo
+module Common
+  def self.check_type(value_name, value, type)
+    if !(value_name.is_a? String); raise "Argument value_name (=#{value_name}) must be a String"; end
+    if !(type.is_a? Class); raise "Argument type (=#{type}) must be a Class"; end
+
+    error = false
+    if type == FalseClass || type == TrueClass
+      # false or true
+      if value.class != FalseClass && value.class != TrueClass
+        check_error = true
+      end
+    else
+        error = value.class != type
+    end
+
+    if error
+      value_string = value.class == String ? "\"#{value}\"" : "#{value}"
+      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}"
+    end
+    value
+  end
+end

data/lib/debugtrace/config.rb

@@ -0,0 +1,92 @@
+# config.rb
+# (C) 2023 Masato Kokubo
+require 'yaml'
+require_relative 'common'
+
+class Config
+  def initialize(config_path)
+    @config_path = Common::check_type('config_path', config_path, String)
+    if File.exist?(@config_path)
+      @config = YAML.load_file(@config_path)
+    else
+      @config_path = '<No config file>'
+      @config = nil
+    end
+    @logger_name               = _get_config_value 'logger'                    , 'stderr'
+    @logging_destination       = _get_config_value 'logging_destination'       , 'STDERR'
+    @logging_format            = _get_config_value 'logging_format'            , "%2$s %1$s %4$s\n"
+    @logging_datetime_format   = _get_config_value 'logging_datetime_format'   , '%Y-%m-%d %H:%M:%S.%L%:z'
+    @enabled                   = _get_config_value 'enabled?'                  , true
+    @enter_format              = _get_config_value 'enter_format'              , 'Enter %1$s (%2$s:%3$d) <- %4$s (%5$s:%6$d)'
+    @leave_format              = _get_config_value 'leave_format'              , 'Leave %1$s (%2$s:%3$d) duration: %4$s'
+    @thread_boundary_format    = _get_config_value 'thread_boundary_format'    , '______________________________ %1$s #%2$s ______________________________'
+    @maximum_indents           = _get_config_value 'maximum_indents'           , 32
+    @indent_string             = _get_config_value 'indent_string'             , '| '
+    @data_indent_string        = _get_config_value 'data_indent_string'        , '  '
+    @limit_string              = _get_config_value 'limit_string'              , '...'
+    @non_output_string         = _get_config_value 'non_output_string'         , '...'
+    @cyclic_reference_string   = _get_config_value 'cyclic_reference_string'   , '*** Cyclic Reference ***'
+    @varname_value_separator   = _get_config_value 'varname_value_separator'   , ' = '
+    @key_value_separator       = _get_config_value 'key_value_separator'       , ': '
+    @print_suffix_format       = _get_config_value 'print_suffix_format'       , ' (%2$s:%3$d)'
+    @count_format              = _get_config_value 'count_format'              , 'count:%d'
+    @minimum_output_count      = _get_config_value 'minimum_output_count'      , 16
+    @length_format             = _get_config_value 'length_format'             , 'length:%d'
+    @minimum_output_length     = _get_config_value 'minimum_output_length'     , 16
+    @maximum_data_output_width = _get_config_value 'maximum_data_output_width' , 70
+    @bytes_count_in_line       = _get_config_value 'bytes_count_in_line'       , 16
+    @collection_limit          = _get_config_value 'collection_limit'          , 128
+    @bytes_limit               = _get_config_value 'bytes_limit'               , 256
+    @string_limit              = _get_config_value 'string_limit'              , 256
+    @reflection_nest_limit     = _get_config_value 'reflection_nest_limit'     , 4
+  end
+
+  def config_path              ; @config_path              ; end
+  def logger_name              ; @logger_name              ; end
+  def logging_destination      ; @logging_destination      ; end
+  def logging_format           ; @logging_format           ; end
+  def logging_datetime_format  ; @logging_datetime_format  ; end
+  def enabled?                 ; @enabled                  ; end
+  def enter_format             ; @enter_format             ; end
+  def leave_format             ; @leave_format             ; end
+  def thread_boundary_format   ; @thread_boundary_format   ; end
+  def maximum_indents          ; @maximum_indents          ; end
+  def indent_string            ; @indent_string            ; end
+  def data_indent_string       ; @data_indent_string       ; end
+  def limit_string             ; @limit_string             ; end
+  def non_output_string        ; @non_output_string        ; end
+  def cyclic_reference_string  ; @cyclic_reference_string  ; end
+  def varname_value_separator  ; @varname_value_separator  ; end
+  def key_value_separator      ; @key_value_separator      ; end
+  def print_suffix_format      ; @print_suffix_format      ; end
+  def count_format             ; @count_format             ; end
+  def minimum_output_count     ; @minimum_output_count     ; end
+  def length_format            ; @length_format            ; end
+  def minimum_output_length    ; @minimum_output_length    ; end
+  def maximum_data_output_width; @maximum_data_output_width; end
+  def bytes_count_in_line      ; @bytes_count_in_line      ; end
+  def collection_limit         ; @collection_limit         ; end
+  def bytes_limit              ; @bytes_limit              ; end
+  def string_limit             ; @string_limit             ; end
+  def reflection_nest_limit    ; @reflection_nest_limit    ; end
+
+  private
+
+  # Gets the value related the key from debugtrace.ini file.
+  # @param key (String): The key
+  # @param defalut_value (Object): Value to return when the value related the key is undefined
+  # @return  Object: Value related the key
+  def _get_config_value(key, defalut_value)
+    Common::check_type('key', key, String)
+    value = defalut_value
+    if @config != nil
+      value = @config[key]
+      if value == nil
+        value = defalut_value
+      else
+        Common::check_type("config[#{key}]", value, defalut_value.class)
+      end
+    end
+    value
+  end
+end

data/lib/debugtrace/log_buffer.rb

@@ -0,0 +1,125 @@
+# log_buffer.rb
+# (C) 2023 Masato Kokubo
+require_relative 'common'
+
+# Buffers logs.
+class LogBuffer
+  class LevelAndLog
+    # Initializes this object.
+    def initialize(nest_level, log)
+      @nest_level = Common.check_type('nest_level', nest_level, Integer)
+      @log = Common.check_type('log', log, String)
+    end
+
+    def nest_level
+      @nest_level
+    end
+
+    def log
+      @log
+    end
+    
+    def to_s
+      "(LogBuffer.LevelAndLog){nest_level: #{@nest_level}, log: \"#{@log}\"}"
+    end
+  end
+
+  # Initializes this object.
+  def initialize(maximum_data_output_width)
+    @maximum_data_output_width = Common.check_type('maximum_data_output_width', maximum_data_output_width, Integer)
+    @nest_level = 0
+    @append_nest_level = 0
+
+    # tuples of data indentation level && log string
+    @lines = []
+
+    # buffer for a line of logs
+    @last_line = ""
+  end
+
+  # Breaks the current line.
+  def line_feed
+    @lines << LevelAndLog.new(@nest_level + @append_nest_level, @last_line.rstrip())
+    @append_nest_level = 0
+    @last_line = ''
+  end
+
+  # Ups the data nest level.
+  def up_nest
+    @nest_level += 1
+  end
+
+  # Downs the data nest level.
+  def down_nest
+    @nest_level -= 1
+  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
+  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)
+    if value != nil
+      string = value.to_s
+      if !no_break && length > 0 && length + string.length > @maximum_data_output_width
+        line_feed()
+      end
+      @append_nest_level = nest_level
+      @last_line += string
+    end
+    self
+  end
+
+  # 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
+  def no_break_append(value)
+    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
+  def append_buffer(separator, buff)
+    Common.check_type('separator', separator, String)
+    Common.check_type('buff', buff, LogBuffer)
+    if separator != ""
+      append(separator, 0, true)
+    end
+    index = 0
+    for line in buff.lines
+      if index > 0
+        line_feed()
+      end
+      append(line.nest_level, line.log, index == 0 && separator != "")
+      index += 1
+    end
+    self
+  end
+
+  # The length of the last line.
+  def length
+    @last_line.length
+  end
+
+  # true if multiple line, false otherwise.
+  def multi_lines?
+    @lines.length > 1 || @lines.length == 1 && length > 0
+  end
+
+  # A list of tuple of data indentation level && log string.
+  def lines
+    lines = @lines.dup
+    if length > 0
+      lines << LevelAndLog.new(@nest_level, @last_line)
+    end
+    lines
+  end
+end

data/lib/debugtrace/loggers.rb

@@ -0,0 +1,131 @@
+# loggers.rb
+# (C) 2023 Masato Kokubo
+require 'logger'
+require_relative 'common'
+require_relative 'config'
+
+# Abstract base class for logger classes.
+class LoggerBase
+  # Outputs the message.
+  # @param message (String): The message to output
+  def print(message)
+    raise 'LoggerBase.print is an abstract method.'
+  end
+end
+
+# Abstract base class for StdOut and StdErr classes.
+class StdLogger < LoggerBase
+  # Initializes this object.
+  # @param iostream: Output destination
+  def initialize(config, iostream)
+    @config = Common::check_type("config", config, Config)
+    @iostream = iostream
+  end
+
+  # Outputs the message.
+  # @param message (String): The message to output
+  def print(message)
+    Common::check_type("message", message, String)
+    datetime_str = Time.now().strftime(@config.logging_datetime_format)
+    @iostream.puts "#{datetime_str} #{message}"
+  end
+
+end
+
+# A logger class that outputs to $stdout.
+class StdOutLogger < StdLogger
+  # Initializes this object.
+  def initialize(config)
+    super(config, $stdout)
+  end
+
+  # Returns a string representation of this object.
+  # @return String: A string representation of this object
+  def to_s
+    '$stdout logger'
+  end
+end
+
+# A logger class that outputs to $stderr.
+class StdErrLogger < StdLogger
+  # Initializes this object.
+  def initialize(config)
+    super(config, $stderr)
+  end
+
+  # Returns a string representation of this object.
+  # @return String: A string representation of this object
+  def to_s
+    '$stderr logger'
+  end
+end
+
+# A logger class that outputs using the logging library.
+class LoggerLogger
+  private
+
+  class Formatter
+    def initialize(config)
+      @config = config
+    end
+
+    def call(severity, datetime, progname, msg)
+      datetime_str = datetime.strftime(@config.logging_datetime_format)
+      format(@config.logging_format, severity, datetime_str, progname, msg)
+    end
+  end
+
+  public
+
+  def initialize(config)
+    @config = Common::check_type("config", config, Config)
+    @logger = Logger.new(
+        @config.logging_destination,
+        formatter: Formatter.new(@config),
+        datetime_format: @config.logging_datetime_format)
+  end
+
+  # Outputs the message.
+  # @param message (String): The message to output
+  def print(message)
+    Common::check_type("message", message, String)
+    @logger.log(Logger::Severity::DEBUG, message, 'DebugTrace-rb')
+  end
+
+  # Returns a string representation of this object.
+  # @return String: A string representation of this object
+  def to_s
+    'logging.Logger logger'
+  end
+end
+
+# A logger class that outputs the file.
+class FileLogger < LoggerBase
+  def initialize(config, log_path)
+    @config = Common::check_type("config", config, Config)
+    Common::check_type("log_path", log_path, String)
+    dir_path = File.dirname(log_path)
+    if Dir.exist?(dir_path)
+      @log_path = log_path
+    else
+      $stderr.puts "DebugTrace-rb: FileLogger: The directory '#{dir_path}' cannot be found."
+      @log_path = ''
+    end
+  end
+  
+  def print(message)
+    Common::check_type("message", message, String)
+    if @log_path != ''
+      File.open(@log_path, 'a') {|file|
+        datetime_str = Time.now().strftime(@config.logging_datetime_format)
+        file.puts "#{datetime_str} #{message}"
+      }
+    end
+  end
+
+  # Returns a string representation of this object.
+  # @return String: A string representation of this object
+  def to_s
+    "File logger: '#{@log_path}"
+  end
+end

data/lib/debugtrace/print_options.rb

@@ -0,0 +1,24 @@
+# print_options.rb
+# (C) 2023 Masato Kokubo
+# Hold output option values.
+class PrintOptions
+  # Initializes this object.
+  # @param force_reflection (bool): If true, outputs using reflection even if it has a @_str__or @_repr__ method
+  # @param output_private (bool): If true, also outputs private members when using reflection
+  # @param output_method (bool): If true, also outputs method members when using reflection
+  # @param collection_limit (Integer): Output limit of collection elements (overrides debugtarace.ini value)
+  # @param string_limit (Integer): Output limit of string characters (overrides debugtarace.ini value)
+  # @param bytes_limit (Integer): Output limit of byte array elements (overrides debugtarace.ini value)
+  # @param reflection_nest_limit (Integer): Nest limits when using reflection (overrides debugtarace.ini value)
+  def initialize(
+    force_reflection, output_private, output_method,
+    collection_limit, string_limit, bytes_limit, reflection_nest_limit)
+    @force_reflection      = force_reflection
+    @output_private        = output_private
+    @output_method         = output_method
+    @collection_limit      = collection_limit      == -1 ? @config.collection_limit      : collection_limit   
+    @string_limit          = string_limit          == -1 ? @config.string_limit          : string_limit     
+    @bytes_limit           = bytes_limit           == -1 ? @config.bytes_limit           : bytes_limit      
+    @reflection_nest_limit = reflection_nest_limit == -1 ? @config.reflection_nest_limit : reflection_nest_limit
+  end
+end

data/lib/debugtrace/state.rb

@@ -0,0 +1,65 @@
+# state.rb
+# (C) 2023 Masato Kokubo
+require_relative 'common'
+
+# Have the trace state for a thread
+class State
+  def initialize(thread_id)
+    @thread_id = Common::check_type('thread_id', thread_id, Integer)
+    reset()
+  end
+
+  # @return the thread id.
+  def thread_id
+    @thread_id
+  end
+
+  # @return the nest level.
+  def nest_level
+    @nest_level
+  end
+
+  # @return the previous nest level.
+  def previous_nest_level
+    @previous_nest_level
+  end
+
+  # @return the previous line count.
+  def previous_line_count
+    @previous_line_count
+  end
+
+  # Sets the previous line count.
+  # @param value the previous line count
+  def previous_line_count=(value)
+    @previous_line_count = Common::check_type('value', value, Integer)
+  end
+
+  def reset
+    @nest_level = 0
+    @previous_nest_level = 0
+    @previous_line_count = 0
+    @times = []
+  end
+
+  def to_s()
+      "(State){thread_id: #{@thread_id}, nest_level: #{@nest_level}, previous_nest_level: #{@previous_nest_level}, previous_line_count: #{@previous_line_count}, times: #{@times}}"
+  end
+
+  # Ups the nest level.
+  def up_nest
+      @previous_nest_level = @nest_level
+      if (@nest_level >= 0)
+          @times.push(Time.now)
+      end
+      @nest_level += 1
+  end
+
+  #Downs the nest level.
+  # @return Time: The time when the corresponding upNest method was invoked
+  def down_nest
+      @previous_nest_level = @nest_level
+      @nest_level -= 1
+      return @times.length > 0 ? @times.pop() : Time.now
+  end
+end

data/lib/debugtrace/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DebugTrace
+  VERSION = '0.1.0'
+end