toolbox 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8bc49b89f83b1baa5270a63e16df4c63dfc3de61fa98e8c6da8fabbcde66e87
-  data.tar.gz: cd5b34b044e80e8aa2b278a67fa138cd5230829da83aa9710b04b8b77478b8ff
+  metadata.gz: 47056303f26efc916f64b03caf6c67278818e8c2bfb79b00b23b9ed752ce393f
+  data.tar.gz: 3a3860fadb6e0a7e4f5d591344801d459480da891d95c87ecc2b1cb2044c9ce8
 SHA512:
-  metadata.gz: 891326e75355c9a42cbed524b63345f7b47e6ee8ed29f5c08ee96a5c8a40cb495ad1913bfeb0043b2479f1e08ff4c763d93b4f8231a30f5b958a356eabc0ae46
-  data.tar.gz: c3edb1db9689d4b399c96a112876d8b8ba3f3b4754903d61e2fafb999d2913409509f4ee2a4964096a4ed5b30ccec0647deee5843a31d77b8700de0ef62ee9b9
+  metadata.gz: 272ee139aec5ae2ce7ba7b08ae57d329e64dfd4f370cfa99649621978c9d588266de01e902d5f88a26ad90981bbc062f270015d8422d60dbc7ed1f8421f5df5c
+  data.tar.gz: b96fc5c29410655d1f3538df655eaa865237f549c553250ef4ea3586ac0b0d01d0902d27505e9d17cf31a70cf2b3822352a0e59b6f9215a1d40ec1907909931e

data/data/toolbox/heap.py

@@ -531,8 +531,18 @@ class RubyHeapScanHandler:
 		"""
 		import constants
 		
-		# Try as a constant name first
-		type_value = constants.get(type_arg)
+		# Try as a Ruby type constant (RUBY_T_*) first, using defaults table
+		if type_arg.startswith('RUBY_T_'):
+			try:
+				return constants.type(type_arg)
+			except Exception:
+				pass
+		
+		# Try as a general constant name
+		try:
+			type_value = constants.get(type_arg)
+		except Exception:
+			type_value = None
 		
 		if type_value is None:
 			# Try parsing as a number (hex or decimal)
@@ -675,5 +685,176 @@ class RubyHeapScanHandler:
 			traceback.print_exc()
 
 
+class RubyHeapDumpHandler:
+	"""Dump the Ruby heap to a JSON file.
+	
+	Usage: rb-heap-dump --output FILE [--type TYPE] [--pretty]
+	
+	Iterates the entire Ruby heap and writes each live object as a JSON record.
+	Each record includes the object's address, type, and type-specific metadata.
+	
+	Options:
+	  --output FILE  Path to the output JSON file (required)
+	  --type TYPE    Filter by Ruby type (e.g., RUBY_T_STRING, 0x05); omit for all types
+	  --pretty       Pretty-print the JSON output (default: compact)
+	
+	JSON format:
+	  {
+	    "total": N,
+	    "objects": [
+		      { "address": "0x...", "type": "T_STRING", "properties": { ... } },
+	      ...
+	    ]
+	  }
+	
+	Examples:
+	  rb-heap-dump --output /tmp/heap.json
+	  rb-heap-dump --output /tmp/strings.json --type RUBY_T_STRING --pretty
+	"""
+	
+	USAGE = command.Usage(
+		summary="Dump the Ruby heap to a JSON file",
+		parameters=[],
+		options={
+			'output': (str, None, 'Output file path (required)'),
+			'type': (str, None, 'Filter by Ruby type (e.g., RUBY_T_STRING, or 0x05)'),
+			'limit': (int, None, 'Stop after dumping N objects'),
+		},
+		flags=[('pretty', 'Pretty-print the JSON output')],
+		examples=[
+			("rb-heap-dump --output /tmp/heap.json", "Dump the entire heap"),
+			("rb-heap-dump --output /tmp/strings.json --type RUBY_T_STRING --pretty", "Dump all strings, pretty-printed"),
+			("rb-heap-dump --output /tmp/strings.json --type RUBY_T_STRING --limit 1 --pretty", "Dump first string, pretty-printed"),
+		]
+	)
+	
+	def _parse_type(self, type_arg):
+		"""Parse a type argument and return the type value (reuse scan handler logic)."""
+		import constants
+		
+		if type_arg.startswith('RUBY_T_'):
+			try:
+				return constants.type(type_arg)
+			except Exception:
+				pass
+		
+		try:
+			type_value = constants.get(type_arg)
+		except Exception:
+			type_value = None
+		
+		if type_value is None:
+			try:
+				if type_arg.startswith('0x') or type_arg.startswith('0X'):
+					type_value = int(type_arg, 16)
+				else:
+					type_value = int(type_arg)
+			except ValueError:
+				print(f"Error: Unknown type constant '{type_arg}'")
+				print("Use a constant like RUBY_T_STRING or a numeric value like 0x05")
+				return None
+		
+		return type_value
+	
+	def _object_to_dict(self, obj, flags):
+		"""Serialize a heap object to a JSON-compatible dict.
+		
+		Args:
+			obj: GDB VALUE for the heap object
+			flags: Integer flags value read from the object's RBasic header
+		
+		Returns:
+			Dict with 'address', 'type', and 'data' keys
+		"""
+		import rvalue
+		import rbasic as rbasic_mod
+		
+		addr = int(obj)
+		type_name = rbasic_mod.type_name(obj)
+		
+		record = {
+			"address": f"0x{addr:x}",
+			"type": type_name,
+		}
+		
+		try:
+			interpreted = rvalue.interpret(obj)
+			properties = interpreted.as_json()
+			if properties:
+				record["properties"] = properties
+		except Exception:
+			pass
+		
+		return record
+	
+	def invoke(self, arguments, terminal):
+		"""Execute the heap dump command."""
+		import json
+		
+		output_path = arguments.get_option('output')
+		if output_path is None:
+			print("Error: --output FILE is required")
+			return
+		
+		pretty = arguments.has_flag('pretty')
+		
+		limit = None
+		limit_option = arguments.get_option('limit')
+		if limit_option is not None:
+			try:
+				limit = int(limit_option)
+			except ValueError:
+				print("Error: --limit must be a number")
+				return
+		
+		type_value = None
+		type_option = arguments.get_option('type')
+		if type_option is not None:
+			type_value = self._parse_type(type_option)
+			if type_value is None:
+				return
+		
+		heap = RubyHeap()
+		if not heap.initialize():
+			return
+		
+		if type_value is not None:
+			type_desc = f"type 0x{type_value:02x}"
+		else:
+			type_desc = "all types"
+		
+		print(f"Scanning heap ({type_desc}), writing to {output_path}...")
+		
+		objects = []
+		count = 0
+		
+		for obj, flags, address in heap.iterate_heap():
+			if type_value is not None and (flags & RBASIC_FLAGS_TYPE_MASK) != type_value:
+				continue
+			
+			count += 1
+			if count % 10000 == 0:
+				print(f"  Processed {count} objects...", file=sys.stderr)
+			
+			record = self._object_to_dict(obj, flags)
+			objects.append(record)
+			
+			if limit is not None and len(objects) >= limit:
+				break
+		
+		result = {"total": len(objects), "objects": objects}
+		
+		try:
+			with open(output_path, 'w', encoding='utf-8') as f:
+				if pretty:
+					json.dump(result, f, indent=2, ensure_ascii=False)
+				else:
+					json.dump(result, f, ensure_ascii=False)
+			print(f"Wrote {len(objects)} object(s) to {output_path}")
+		except OSError as e:
+			print(f"Error writing {output_path}: {e}")
+
+
 # Register commands
 debugger.register("rb-heap-scan", RubyHeapScanHandler, usage=RubyHeapScanHandler.USAGE)
+debugger.register("rb-heap-dump", RubyHeapDumpHandler, usage=RubyHeapDumpHandler.USAGE)

data/data/toolbox/print.py

@@ -15,6 +15,7 @@ import rstruct
 import rfloat
 import rbignum
 import rbasic
+import robject
 import format
 
 

data/data/toolbox/rarray.py

@@ -56,6 +56,10 @@ class RArrayBase:
 			except Exception as e:
 				print(f"Error accessing element {i}: {e}")
 
+	def as_json(self):
+		"""Return a JSON-serializable dict of this array's data."""
+		return {"length": self.length()}
+
 class RArrayEmbedded(RArrayBase):
 	"""Embedded array (small arrays stored directly in struct)."""
 	

data/data/toolbox/rbasic.py

@@ -24,7 +24,7 @@ def is_type(value, ruby_type_constant):
 		True if the value is of the specified type, False otherwise
 	"""
 	type_flag = type_of(value)
-	expected_type = constants.get(ruby_type_constant)
+	expected_type = constants.type(ruby_type_constant)
 	return type_flag == expected_type
 
 # Map of type constants to their names for display
@@ -67,7 +67,7 @@ def type_name(value):
 	
 	# Try to find matching type name
 	for const_name, display_name in TYPE_NAMES.items():
-		if constants.get(const_name) == type_flag:
+		if constants.type(const_name) == type_flag:
 			return display_name
 	
 	return f'Unknown(0x{type_flag:x})'
@@ -94,6 +94,10 @@ class RBasic:
 		# Use print_type_tag for consistency with other types
 		terminal.print_type_tag(type_str, addr)
 	
+	def as_json(self):
+		"""Return a JSON-serializable dict of this object's data."""
+		return {}
+
 	def print_recursive(self, printer, depth):
 		"""Print this basic object (no recursion)."""
 		printer.print(self)

data/data/toolbox/rbignum.py

@@ -37,6 +37,10 @@ class RBignumObject:
 		details = f"{storage} length={len(self)}"
 		terminal.print_type_tag('T_BIGNUM', addr, details)
 	
+	def as_json(self):
+		"""Return a JSON-serializable dict of this bignum's data."""
+		return {"embedded": self.is_embedded(), "digits": len(self)}
+
 	def print_recursive(self, printer, depth):
 		"""Print this bignum (no recursion needed)."""
 		printer.print(self)

data/data/toolbox/rfloat.py

@@ -37,6 +37,13 @@ class RFloatImmediate:
 		terminal.print(' ', end='')
 		terminal.print(format.number, str(self.float_value()), format.reset, end='')
 	
+	def as_json(self):
+		"""Return a JSON-serializable dict of this float's data."""
+		try:
+			return {"value": self.float_value()}
+		except Exception:
+			return {"value": None}
+
 	def print_recursive(self, printer, depth):
 		"""Print this float (no recursion needed)."""
 		printer.print(self)
@@ -60,6 +67,13 @@ class RFloatObject:
 		terminal.print(' ', end='')
 		terminal.print(format.number, str(self.float_value()), format.reset, end='')
 	
+	def as_json(self):
+		"""Return a JSON-serializable dict of this float's data."""
+		try:
+			return {"value": self.float_value()}
+		except Exception:
+			return {"value": None}
+
 	def print_recursive(self, printer, depth):
 		"""Print this float (no recursion needed)."""
 		printer.print(self)

data/data/toolbox/rhash.py

@@ -70,6 +70,10 @@ class RHashSTTable(RHashBase):
 			printer.print_value_label(printer.max_depth - depth)
 			printer.print_value(value, depth - 1)
 
+	def as_json(self):
+		"""Return a JSON-serializable dict of this hash's data."""
+		return {"size": self.size()}
+
 class RHashARTable(RHashBase):
 	"""Hash using AR table structure (newer, smaller hashes)."""
 	

data/data/toolbox/robject.py

@@ -0,0 +1,219 @@
+import debugger
+import constants
+import format
+import rclass
+
+
+class RObjectBase:
+	"""Base class for Ruby T_OBJECT instances (regular class instances like User.new)."""
+	
+	def __init__(self, value):
+		"""value is a VALUE pointing to a T_OBJECT."""
+		self.value = value
+		self.basic = value.cast(constants.type_struct('struct RBasic').pointer())
+		self.flags = int(self.basic.dereference()['flags'])
+		self._class_name = None
+	
+	@property
+	def class_name(self):
+		if self._class_name is None:
+			try:
+				klass = self.basic['klass']
+				self._class_name = rclass.get_class_name(klass)
+			except Exception:
+				self._class_name = f"#<Class:0x{int(self.value):x}>"
+		return self._class_name
+	
+	def numiv(self):
+		"""Get the number of instance variables. Subclasses must implement."""
+		raise NotImplementedError
+	
+	def ivptr(self):
+		"""Get pointer to instance variable values. Subclasses must implement."""
+		raise NotImplementedError
+	
+	def __str__(self):
+		addr = int(self.value)
+		n = self.numiv()
+		if n > 0:
+			return f"<{self.class_name}@0x{addr:x} ivars={n}>"
+		return f"<{self.class_name}@0x{addr:x}>"
+	
+	def print_to(self, terminal):
+		addr = int(self.value)
+		n = self.numiv()
+		details = f"ivars={n}" if n > 0 else None
+		terminal.print_type_tag(self.class_name, addr, details)
+	
+	def as_json(self):
+		"""Return a JSON-serializable dict of this object's data."""
+		data = {"class": self.class_name}
+		try:
+			data["ivars"] = self.numiv()
+		except Exception:
+			data["ivars"] = None
+		return data
+
+	def print_recursive(self, printer, depth):
+		printer.print(self)
+		
+		n = self.numiv()
+		if depth <= 0 or n <= 0:
+			return
+		
+		ptr = self.ivptr()
+		if ptr is None:
+			return
+		
+		for i in range(n):
+			try:
+				printer.print_item_label(printer.max_depth - depth, i)
+				printer.print_value(ptr[i], depth - 1)
+			except Exception:
+				break
+
+
+class RObjectEmbedded(RObjectBase):
+	"""T_OBJECT with instance variables stored inline (small objects)."""
+	
+	def __init__(self, value, robject):
+		super().__init__(value)
+		self.robject = robject
+		self._numiv = None
+	
+	def numiv(self):
+		if self._numiv is not None:
+			return self._numiv
+		
+		try:
+			# Try shape-based numiv (Ruby 3.4+)
+			self._numiv = self._numiv_from_shape()
+			if self._numiv is not None:
+				return self._numiv
+		except Exception:
+			pass
+		
+		# Fallback: count non-zero slots in the embedded array
+		self._numiv = self._count_embedded_slots()
+		return self._numiv
+	
+	def _numiv_from_shape(self):
+		"""Try to get ivar count from the object's shape (Ruby 3.4+)."""
+		try:
+			shape_id_mask = 0xFFFF  # shape_id is in bits 16..31 of flags typically
+			# In Ruby 3.4+, shape_id_t is stored in flags
+			# SHAPE_FLAG_SHIFT is typically 16
+			shape_id = (self.flags >> 16) & 0xFFFF
+			if shape_id == 0:
+				return 0
+			
+			# Try to read from shape table
+			shape_list = debugger.parse_and_eval('rb_shape_tree.shape_list')
+			shape = shape_list[shape_id]
+			next_iv = int(shape['next_iv'])
+			return next_iv
+		except Exception:
+			return None
+	
+	def _count_embedded_slots(self):
+		"""Count non-Qundef/non-zero slots in the embedded array."""
+		try:
+			ary = self.robject.dereference()['as']['ary']
+			count = 0
+			# ROBJECT_EMBED_LEN_MAX is typically 3 (Ruby 3.2) or varies by slot size
+			for i in range(12):
+				try:
+					val = int(ary[i])
+					if val == 0 or val == 0x34:  # Qundef
+						break
+					count += 1
+				except Exception:
+					break
+			return count
+		except Exception:
+			return 0
+	
+	def ivptr(self):
+		try:
+			return self.robject.dereference()['as']['ary']
+		except Exception:
+			return None
+
+
+class RObjectHeap(RObjectBase):
+	"""T_OBJECT with instance variables stored on the heap (many ivars)."""
+	
+	def __init__(self, value, robject):
+		super().__init__(value)
+		self.robject = robject
+		self._numiv = None
+	
+	def numiv(self):
+		if self._numiv is not None:
+			return self._numiv
+		
+		try:
+			self._numiv = int(self.robject.dereference()['as']['heap']['numiv'])
+		except Exception:
+			self._numiv = 0
+		return self._numiv
+	
+	def ivptr(self):
+		try:
+			return self.robject.dereference()['as']['heap']['ivptr']
+		except Exception:
+			return None
+
+
+class RObjectGeneric(RObjectBase):
+	"""Fallback T_OBJECT when struct RObject is unavailable or has unknown layout."""
+	
+	def numiv(self):
+		return 0
+	
+	def ivptr(self):
+		return None
+
+
+def RObject(value):
+	"""Factory function that detects the RObject variant and returns the appropriate instance.
+	
+	Caller should ensure value is a RUBY_T_OBJECT before calling.
+	"""
+	try:
+		robject = value.cast(constants.type_struct('struct RObject').pointer())
+	except Exception:
+		return RObjectGeneric(value)
+	
+	# Detect embedded vs heap storage
+	try:
+		FL_USER1 = constants.flag('RUBY_FL_USER1')
+		basic = value.cast(constants.type_struct('struct RBasic').pointer())
+		flags = int(basic.dereference()['flags'])
+		
+		if flags & FL_USER1:
+			# ROBJECT_EMBED flag set — ivars are inline
+			return RObjectEmbedded(value, robject)
+		else:
+			# Heap-allocated ivars
+			return RObjectHeap(value, robject)
+	except Exception:
+		pass
+	
+	# Feature detection: check what fields exist
+	try:
+		as_union = robject.dereference()['as']
+		if as_union is not None:
+			heap = as_union['heap']
+			if heap is not None:
+				numiv_field = heap['numiv']
+				if numiv_field is not None:
+					return RObjectHeap(value, robject)
+			
+			ary = as_union['ary']
+			if ary is not None:
+				return RObjectEmbedded(value, robject)
+	except Exception:
+		pass
+	
+	return RObjectGeneric(value)

data/data/toolbox/rstring.py

@@ -77,6 +77,15 @@ class RStringBase:
 		# Use repr() to properly escape quotes, newlines, etc.
 		terminal.print(format.string, repr(content), format.reset, end='')
 	
+	def as_json(self):
+		"""Return a JSON-serializable dict of this string's data."""
+		data = {"length": self.length(), "embedded": self._is_embedded()}
+		try:
+			data["value"] = self.to_str()
+		except Exception:
+			data["value"] = None
+		return data
+
 	def print_recursive(self, printer, depth):
 		"""Print this string (no recursion needed for strings)."""
 		printer.print(self)

data/data/toolbox/rvalue.py

@@ -11,6 +11,7 @@ import rarray
 import rhash
 import rstruct
 import rbignum
+import robject
 
 class RImmediate:
 	"""Wrapper for Ruby immediate values (fixnum, nil, true, false)."""
@@ -50,6 +51,18 @@ class RImmediate:
 			# Unknown immediate
 			terminal.print_type_tag('Immediate', self.val_int)
 	
+	def as_json(self):
+		"""Return a JSON-serializable dict of this immediate value's data."""
+		if self.val_int == 0:
+			return {"value": False}
+		elif self.val_int == 0x04 or self.val_int == 0x08:
+			return {"value": None}
+		elif self.val_int == 0x14:
+			return {"value": True}
+		elif (self.val_int & 0x01) != 0:
+			return {"value": self.val_int >> 1}
+		return {}
+
 	def print_recursive(self, printer, depth):
 		"""Print this immediate value (no recursion needed)."""
 		printer.print(self)
@@ -174,6 +187,8 @@ def interpret(value):
 			return rfloat.RFloat(value)
 		elif type_flag == constants.type("RUBY_T_BIGNUM"):
 			return rbignum.RBignum(value)
+		elif type_flag == constants.type("RUBY_T_OBJECT"):
+			return robject.RObject(value)
 		else:
 			# Unknown type - return generic RBasic
 			return rbasic.RBasic(value)

data/lib/toolbox/version.rb

@@ -5,6 +5,6 @@
 
 # @namespace
 module Toolbox
-	VERSION = "0.3.0"
+	VERSION = "0.4.0"
 end
 

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2025, by Samuel Williams.  
+Copyright, 2025-2026, by Samuel Williams.  
 
 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/readme.md

@@ -31,6 +31,11 @@ Please see the [project documentation](https://socketry.github.io/toolbox/) for
 
 Please see the [project releases](https://socketry.github.io/toolbox/releases/index) for all releases.
 
+### v0.4.0
+
+  - Better support for printing `T_OBJECT` values, including class name.
+  - Introduce `rb-heap-dump` command to dump the Ruby heap to a JSON file, with optional type filtering and limit.
+
 ### v0.2.0
 
   - Introduce support for `lldb` using debugger shims.
@@ -55,6 +60,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.

data/releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## v0.4.0
+
+  - Better support for printing `T_OBJECT` values, including class name.
+  - Introduce `rb-heap-dump` command to dump the Ruby heap to a JSON file, with optional type filtering and limit.
+
 ## v0.2.0
 
   - Introduce support for `lldb` using debugger shims.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toolbox
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -70,6 +70,7 @@ files:
 - data/toolbox/rexception.py
 - data/toolbox/rfloat.py
 - data/toolbox/rhash.py
+- data/toolbox/robject.py
 - data/toolbox/rstring.py
 - data/toolbox/rstruct.py
 - data/toolbox/rsymbol.py
@@ -95,14 +96,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Ruby debugging toolbox for GDB and LLDB
 test_files: []