wurm 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8a44f02498b11753018c46aef5ea14d106138176038977b3211ccab82f170037
+  data.tar.gz: bffa1c99607dea7216111c4a35bfeed5010ce766859fd674f173ea595435c4b8
+SHA512:
+  metadata.gz: 3ab658556fb75c646b5c3db2c7b16bc2e3e14335733d88a17d0c1c8ae351a70b56b7568cc3499b3447ccf4d6e662f3db66185b569d6374ac34d42e28d6946860
+  data.tar.gz: a41706e65aacbcc70d0e21ef90e4a5103f3fb4bba34e187ea838724daf6e3893ac233bc931a0ed57058c24c91f9890f6f938098bc4efd5e3a265e7c53ae36a94

data/README.md

@@ -0,0 +1,221 @@
+# Wurm
+
+[![Gem Version](https://img.shields.io/gem/v/wurm?color=168AFE&logo=rubygems&logoColor=FE1616)](https://rubygems.org/gems/wurm)
+[![Downloads](https://img.shields.io/gem/dt/wurm?color=168AFE&logo=rubygems&logoColor=FE1616)](https://rubygems.org/gems/wurm)
+[![GitHub Build](https://img.shields.io/github/actions/workflow/status/matique/wurm/rake.yml?logo=github)](https://github.com/matique/wurm/actions/workflows/rake.yml)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-168AFE.svg)](https://github.com/standardrb/standard)
+[![MIT License](https://img.shields.io/badge/license-MIT-168AFE.svg)](http://choosealicense.com/licenses/mit/)
+
+*Wurm* is a lightweight recursive pretty printer for Ruby objects.
+
+It displays the structure of Ruby objects in a readable, indented format,
+including nested hashes, arrays, structs, and custom objects.
+
+*Wurm* also detects circular references and shared object references,
+preventing infinite recursion
+and making complex object graphs easier to inspect.
+
+## Features
+
+- Recursive inspection of Ruby objects.
+- Support for Hash, Array, and Struct.
+- Support for custom objects through a *wurm* method.
+- Circular reference detection.
+- Shared object reference detection.
+- Object class and object ID information.
+- Special formatting for Date, DateTime, and Time.
+- Configurable output destination through an IO object.
+- No external runtime dependencies.
+
+
+## Installation
+
+As usual:
+
+~~~~ruby
+# Gemfile
+...
+gem "wurm"
+...
+~~~~
+
+and run "bundle install".
+
+
+## Basic example
+
+~~~~ruby
+require "wurm"
+...
+Wurm.pp("Hello World")
+Wurm.pp("legend", "Hello World")
+...
+~~~~
+
+Output:
+~~~~ruby
+--- "Hello World"
+Legend "Hello World"
+~~~~
+
+
+## Hashes and arrays
+~~~~ruby
+data = {
+  name: "Alice",
+  age: 30,
+  address: {
+    city: "Berlin",
+    country: "Germany"
+  },
+  hobbies: ["Ruby", "Programming"]
+}
+
+Wurm.pp(data)
+~~~~
+
+Output:
+~~~~ruby
+--- <Hash ID: 0x5a8>
+  name: "Alice"
+  age: 30
+  address: <Hash ID: 0x5b0>
+    city: "Berlin"
+    country: "Germany"
+  hobbies: <Array ID: 0x5b8>
+    [0] "Ruby"
+    [1] "Programming"
+~~~~
+
+
+## Custom objects
+
+Custom objects can define a *wurm* method that returns an array of
+attribute names to inspect.
+
+~~~~ruby
+class Person
+  attr_accessor :name, :age, :address
+
+  def initialize(name, age, address)
+    @name = name
+    @age = age
+    @address = address
+  end
+
+  def wurm
+    %i[name age address]
+  end
+end
+
+person = Person.new(
+  "Alice",
+  30,
+  { city: "Berlin", country: "Germany" }
+)
+
+Wurm.pp(person)
+~~~~
+
+*Wurm* recursively displays nested structures and their values.
+
+Output:
+~~~~ruby
+--- <Person ID: 0x5a8>
+  name "Alice"
+  age 30
+  address <Hash ID: 0x5b0>
+    city: "Berlin"
+    country: "Germany"
+~~~~
+
+
+## Circular references
+
+*Wurm* detects circular references using object identity.
+ruby
+
+~~~~ruby
+person = { name: "Alice" }
+person[:friend] = person
+
+Wurm.pp(person)
+~~~~
+
+Instead of entering an infinite recursion,
+*Wurm* prints a reference to the previously visited object.
+
+Output:
+~~~~ruby
+--- <Hash ID: 0x5a8>
+  name: "Alice"
+  friend: -> reference to --- <Hash ID: 0x5a8>
+~~~~
+
+
+## Shared references
+
+*Wurm* also detects objects referenced from multiple locations.
+
+~~~~ruby
+shared = { value: 42 }
+
+data = {
+  first: shared,
+  second: shared
+}
+
+Wurm.pp(data)
+~~~~
+
+The second occurrence is displayed as a reference to the first occurrence.
+
+Output:
+~~~~ruby
+--- <Hash ID: 0x5a8>
+  first: <Hash ID: 0x5b0>
+    value: 42
+  second: -> reference to first: <Hash ID: 0x5b0>
+~~~~
+
+
+## Custom output destination
+
+By default, output is written to $stdout.
+
+You can provide another IO object:
+
+~~~~ruby
+require "stringio"
+
+output = StringIO.new
+
+Wurm.pp({ name: "Alice" }, io: output)
+
+puts output.string
+~~~~
+
+
+## Supported types
+
+|Ruby type      | Handling |
+|---------------|----------|
+|NilClass       | Scalar |
+|TrueClass      | Scalar |
+|FalseClass     | Scalar |
+|Numeric        | Scalar |
+|Symbol         | Scalar |
+|String         | Scalar |
+|Regexp         | Scalar |
+|Time           | ISO 8601 |
+|Date           | ISO 8601 |
+|DateTime       | ISO 8601 |
+|Hash           | Recursive |
+|Array          | Recursive |
+|Struct         | Recursive |
+|Custom objects | Via wurm method |
+
+## Miscellaneous
+
+Copyright (c) 2026 Dittmar Krall (www.matiq.com),
+released under the [MIT license](https://opensource.org/licenses/MIT).

data/lib/wurm.rb

@@ -0,0 +1,62 @@
+require "wurm2"
+require "date"
+require "time"
+
+module Wurm
+  INDENT = "  "
+
+  ATOMIC_TYPES = [
+    NilClass, TrueClass, FalseClass,
+    Numeric, Symbol, String,
+    Regexp,
+    Time, Date
+  ].freeze
+
+  def self.pp(*args, io: $stdout)
+    name, object =
+      case args.length
+      when 1 then ["---", args.first]
+      when 2 then args
+      else
+        raise ArgumentError, "Expected 1 or 2 arguments"
+      end
+
+    pp1(name, object, seen: {}.compare_by_identity, io:)
+  end
+
+  def self.pp1(name, object, seen:, io:, prefix: "")
+    if scalar?(object)
+      scalar(name, object, prefix:, io:)
+      return
+    end
+
+    if seen.key?(object)
+      io.puts "#{prefix}#{name} -> reference to #{seen[object]}"
+      return
+    end
+
+    label = label_for(name, object)
+    seen[object] = label
+
+    recursive(name, object, seen:, prefix:, io:)
+  end
+
+  def self.scalar?(object)
+    ATOMIC_TYPES.any? { |type| type === object }
+  end
+
+  def self.label_for(name, object)
+    legend =
+      if object.is_a?(Class)
+        "Class: #{object}"
+      else
+        object.class.to_s
+      end
+
+    id = "0x#{object.object_id.to_s(16)}"
+
+    "#{name} <#{legend} ID: #{id}>"
+  end
+
+  private_class_method :pp1, :scalar?, :label_for
+end

data/lib/wurm2.rb

@@ -0,0 +1,45 @@
+require "date"
+
+module Wurm
+  def self.scalar(name, object, prefix:, io:)
+    value = case object
+    when DateTime, Time, Date then object.iso8601
+    else object.inspect
+    end
+    io.puts "#{prefix}#{name} #{value}"
+  end
+
+  def self.recursive(name, object, seen:, prefix:, io:)
+    io.puts "#{prefix}#{label_for(name, object)}"
+
+    child_prefix = prefix + INDENT
+
+    case object
+    when Struct
+      object.each_pair do |key, value|
+        pp1("#{key}:", value, prefix: child_prefix, seen:, io:)
+      end
+    when Hash
+      object.each do |key, value|
+        if key.is_a?(Symbol)
+          pp1("#{key}:", value, prefix: child_prefix, seen:, io:)
+        else
+          pp1("#{key.inspect} =>", value, prefix: child_prefix, seen:, io:)
+        end
+      end
+    when Array
+      object.each_with_index do |value, index|
+        pp1("[#{index}]", value, prefix: child_prefix, seen:, io:)
+      end
+    else
+      list = object.wurm if object.respond_to?(:wurm)
+      list ||= []
+      list.each do |attribute|
+        value = object.send(attribute)
+        pp1(attribute, value, prefix: child_prefix, seen:, io:)
+      end
+    end
+  end
+
+  private_class_method :scalar, :recursive
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: wurm
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Dittmar Krall
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A pretty printer for Ruby objects with circular reference detection.
+email:
+- dittmar.krall@matiq.com
+- dittmar.krall@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/wurm.rb
+- lib/wurm2.rb
+homepage: https://github.com/matique/wurm
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: A recursive Ruby object pretty printer
+test_files: []