toolbox 0.1.3 → 0.2.0

data/data/toolbox/readme.md

@@ -0,0 +1,214 @@
+# Ruby Toolbox Extensions
+
+This directory contains Ruby debugging extensions that work with both GDB and LLDB through automatic debugger detection.
+
+## Structure
+
+```
+data/toolbox/
+├── init.py                  # Single entry point for both debuggers
+├── debugger.py              # Auto-detects GDB or LLDB
+├── debugger/                # Abstraction layer implementations
+│   ├── gdb.py              # GDB backend
+│   ├── lldb.py             # LLDB backend
+│   └── *.md                # Documentation
+│
+# Ruby debugging extensions (currently GDB-specific, migrating to abstraction)
+├── object.py               # Object inspection (rb-object-print)
+├── fiber.py                # Fiber debugging (rb-fiber-scan-heap, rb-fiber-switch)
+├── heap.py                 # Heap scanning (rb-heap-scan)
+├── stack.py                # Stack inspection
+│
+# Support modules
+├── value.py                # Ruby VALUE interpretation
+├── constants.py            # Ruby constant lookups
+├── command.py              # Command argument parsing
+├── format.py               # Output formatting
+│
+# Ruby type wrappers
+├── rbasic.py               # RBasic
+├── rstring.py              # RString
+├── rarray.py               # RArray
+├── rhash.py                # RHash
+├── rstruct.py              # RStruct
+├── rsymbol.py              # RSymbol
+├── rfloat.py               # RFloat
+├── rbignum.py              # RBignum
+├── rclass.py               # RClass
+└── rexception.py           # RException
+```
+
+## How It Works
+
+### 1. Single Entry Point
+
+Both GDB and LLDB load the same `init.py` file:
+
+**GDB** (~/.gdbinit):
+```gdb
+source /path/to/data/toolbox/init.py
+```
+
+**LLDB** (~/.lldbinit):
+```lldb
+command script import /path/to/data/toolbox/init.py
+```
+
+### 2. Auto-Detection
+
+`init.py` imports `debugger.py`, which automatically detects which debugger is running:
+
+```python
+import debugger  # Auto-detects!
+
+if debugger.DEBUGGER_NAME == 'gdb':
+    print("Running in GDB")
+elif debugger.DEBUGGER_NAME == 'lldb':
+    print("Running in LLDB")
+```
+
+### 3. Unified Abstraction
+
+The `debugger` module provides a common API:
+
+```python
+import debugger
+
+# These work in both GDB and LLDB:
+value = debugger.parse_and_eval("$var")
+type = debugger.lookup_type("struct RBasic")
+value_cast = value.cast(type.pointer())
+```
+
+### 4. Extension Loading
+
+`init.py` loads all Ruby debugging extensions, which register commands with the debugger.
+
+## Installation
+
+### GDB
+```bash
+gem install toolbox
+bake toolbox:gdb:install
+```
+
+This adds to `~/.gdbinit`:
+```gdb
+# Ruby Toolbox GDB Extensions
+source /path/to/gem/data/toolbox/init.py
+```
+
+### LLDB
+```bash
+gem install toolbox
+bake toolbox:lldb:install
+```
+
+This adds to `~/.lldbinit`:
+```lldb
+# Ruby Toolbox LLDB Extensions
+command script import /path/to/gem/data/toolbox/init.py
+```
+
+## Available Commands
+
+### Object Inspection
+- `rb-object-print <expression> [--depth N]` - Print Ruby objects with recursion
+
+### Fiber Debugging
+- `rb-fiber-scan-heap [--limit N]` - Scan heap for fiber objects
+- `rb-fiber-scan-switch <index>` - Switch to a fiber from scan cache
+- `rb-fiber-switch <fiber_value>` - Switch to a specific fiber
+- `rb-fiber-scan-stack-trace-all` - Print stack traces for all cached fibers
+
+### Heap Scanning
+- `rb-heap-scan [--type TYPE] [--limit N]` - Scan Ruby heap for objects
+
+### Stack Inspection
+- `rb-stack-print` - Print Ruby stack (coming soon)
+
+## Migration Status
+
+### ✅ Fully Abstracted
+- Command argument parsing
+- Output formatting
+- Constant lookups
+
+### 🚧 Partially Abstracted
+- Object inspection (uses `gdb` directly, needs migration to `debugger`)
+- Fiber debugging (uses `gdb` directly, needs migration to `debugger`)
+- Heap scanning (uses `gdb` directly, needs migration to `debugger`)
+
+### 📋 Migration Plan
+1. Update extension modules to import `debugger` instead of `gdb`
+2. Replace `gdb.parse_and_eval()` with `debugger.parse_and_eval()`
+3. Replace `gdb.lookup_type()` with `debugger.lookup_type()`
+4. Test with both GDB and LLDB
+5. Add LLDB-specific handling where needed
+
+## Testing
+
+Test with GDB:
+```bash
+gdb -q ruby
+(gdb) help rb-object-print
+(gdb) help rb-fiber-scan-heap
+```
+
+Test with LLDB (once migrated):
+```bash
+lldb ruby
+(lldb) help rb-object-print
+(lldb) help rb-fiber-scan-heap
+```
+
+## Documentation
+
+- [debugger/README.md](debugger/README.md) - Abstraction layer documentation
+- [debugger/ARCHITECTURE.md](debugger/ARCHITECTURE.md) - Architecture details
+- [debugger/API_COMPARISON.md](debugger/API_COMPARISON.md) - GDB vs LLDB API reference
+- [debugger/MIGRATION.md](debugger/MIGRATION.md) - Migration guide for code
+
+## Python Module Notes
+
+### Why `init.py` not `__init__.py`?
+
+- `__init__.py` makes a directory a Python *package*
+- `init.py` is a regular Python file loaded explicitly by debuggers
+- GDB uses `source init.py`, LLDB uses `command script import init.py`
+- Neither requires package structure, so we use a simple `init.py`
+
+### Import Path Setup
+
+`init.py` adds its directory to `sys.path` so extensions can import each other:
+
+```python
+import os, sys
+toolbox_dir = os.path.dirname(os.path.abspath(__file__))
+if toolbox_dir not in sys.path:
+    sys.path.insert(0, toolbox_dir)
+```
+
+This allows:
+```python
+import debugger      # data/toolbox/debugger.py
+import object        # data/toolbox/object.py
+import fiber         # data/toolbox/fiber.py
+from debugger import gdb   # data/toolbox/debugger/gdb.py
+```
+
+## Contributing
+
+When adding new extensions:
+
+1. Use the `debugger` abstraction for portability
+2. Test with both GDB and LLDB
+3. Add documentation and examples
+4. Update this README
+
+## See Also
+
+- [GDB Python API](https://sourceware.org/gdb/current/onlinedocs/gdb/Python-API.html)
+- [LLDB Python API](https://lldb.llvm.org/use/python-reference.html)
+- [Ruby VM Internals](https://docs.ruby-lang.org/en/master/extension_rdoc.html)
+

data/data/toolbox/rexception.py

@@ -0,0 +1,150 @@
+import debugger
+import constants
+import format
+import value
+import rstring
+import rclass
+
+class RException:
+	"""Wrapper for Ruby exception objects."""
+	
+	def __init__(self, exception_value):
+		"""Initialize with a Ruby exception VALUE.
+		
+		Args:
+			exception_value: A GDB value representing a Ruby exception object
+		"""
+		self.value = exception_value
+		self._basic = None
+		self._klass = None
+		self._class_name = None
+		self._message = None
+		
+		# Validate it's an object
+		if value.is_immediate(exception_value):
+			raise ValueError("Exception VALUE cannot be an immediate value")
+	
+	@property
+	def klass(self):
+		"""Get the exception's class (klass pointer)."""
+		if self._klass is None:
+			if self._basic is None:
+				self._basic = self.value.cast(constants.type_struct('struct RBasic').pointer())
+			self._klass = self._basic['klass']
+		return self._klass
+	
+	@property
+	def class_name(self):
+		"""Get the exception class name as a string."""
+		if self._class_name is None:
+			self._class_name = self._get_class_name()
+		return self._class_name
+	
+	@property
+	def message(self):
+		"""Get the exception message as a string (None if unavailable)."""
+		if self._message is None:
+			self._message = self._get_message()
+		return self._message
+	
+	def _get_class_name(self):
+		"""Extract class name from klass pointer.
+		
+		Uses the rclass module to get the class name.
+		"""
+		try:
+			return rclass.get_class_name(self.klass)
+		except Exception:
+			# Fallback if we can't read the class
+			return f"Exception(klass=0x{int(self.klass):x})"
+	
+	def _get_message(self):
+		"""Extract message from exception object.
+		
+		Walks instance variables to find 'mesg' ivar.
+		Returns None if message is unavailable (common in core dumps).
+		"""
+		try:
+			# Exception objects store message in 'mesg' instance variable
+			# For now, return None as full ivar walking is complex
+			# TODO: Implement full instance variable walking for core dumps
+			return None
+		except Exception:
+			return None
+	
+	def __str__(self):
+		"""Return formatted string 'ClassName: message' or just 'ClassName'."""
+		class_name = self.class_name
+		msg = self.message
+		
+		if msg:
+			return f"{class_name}: {msg}"
+		else:
+			return class_name
+	
+	def print_to(self, terminal):
+		"""Print this exception with formatting to the given terminal."""
+		class_name = self.class_name
+		msg = self.message
+		
+		# Print class name with type formatting
+		class_output = terminal.print(
+			format.type, class_name,
+			format.reset
+		)
+		
+		if msg:
+			# Print message with string formatting
+			msg_output = terminal.print(
+				format.string, f': {msg}',
+				format.reset
+			)
+			return f"{class_output}{msg_output}"
+		else:
+			return class_output
+	
+	def print_recursive(self, printer, depth):
+		"""Print this exception (no recursion needed for exceptions)."""
+		printer.print(self)
+
+def is_exception(val):
+	"""Check if a VALUE is an exception object.
+	
+	Args:
+		val: A GDB value representing a Ruby VALUE
+	
+	Returns:
+		True if the value appears to be an exception object, False otherwise
+	"""
+	if not value.is_object(val):
+		return False
+	
+	try:
+		# Check if it's a T_OBJECT or T_DATA (exceptions can be either)
+		basic = val.cast(constants.type_struct("struct RBasic").pointer())
+		flags = int(basic['flags'])
+		type_flag = flags & constants.type("RUBY_T_MASK")
+		
+		# Exceptions are typically T_OBJECT, but could also be T_DATA
+		t_object = constants.type("RUBY_T_OBJECT")
+		t_data = constants.type("RUBY_T_DATA")
+		
+		return type_flag == t_object or type_flag == t_data
+	except Exception:
+		return False
+
+def RExceptionFactory(val):
+	"""Factory function to create RException or return None.
+	
+	Args:
+		val: A GDB value representing a Ruby VALUE
+	
+	Returns:
+		RException instance if val is an exception, None otherwise
+	"""
+	if is_exception(val):
+		try:
+			return RException(val)
+		except Exception:
+			return None
+	return None

data/data/toolbox/rfloat.py

@@ -0,0 +1,98 @@
+import debugger
+import constants
+import rbasic
+import struct
+import format
+
+class RFloatImmediate:
+	"""Flonum - immediate float encoding (Ruby 3.4+)"""
+	def __init__(self, value):
+		self.value = int(value)
+	
+	def float_value(self):
+		# Flonum decoding from Ruby's rb_float_flonum_value
+		# Special case for 0.0
+		if self.value == 0x8000000000000002:
+			return 0.0
+		
+		v = self.value
+		b63 = (v >> 63) & 1
+		# e: xx1... -> 011...
+		#    xx0... -> 100...
+		#      ^b63
+		adjusted = (2 - b63) | (v & ~0x03)
+		# RUBY_BIT_ROTR(x, 3) rotates right by 3 bits
+		# Which is: (x >> 3) | (x << (64 - 3))
+		rotated = ((adjusted >> 3) | (adjusted << 61)) & 0xFFFFFFFFFFFFFFFF
+		
+		# Pack as unsigned long long, then unpack as double
+		return struct.unpack('d', struct.pack('Q', rotated))[0]
+	
+	def __str__(self):
+		return f"<T_FLOAT> {self.float_value()}"
+	
+	def print_to(self, terminal):
+		"""Return formatted float representation."""
+		tag = terminal.print(
+			format.metadata, '<',
+			format.type, 'T_FLOAT',
+			format.metadata, '>',
+			format.reset
+		)
+		num_val = terminal.print(format.number, str(self.float_value()), format.reset)
+		return f"{tag} {num_val}"
+	
+	def print_recursive(self, printer, depth):
+		"""Print this float (no recursion needed)."""
+		printer.print(self)
+
+class RFloatObject:
+	"""Heap-allocated float object"""
+	def __init__(self, value):
+		self.value = value.cast(constants.type_struct('struct RFloat'))
+	
+	def float_value(self):
+		return float(self.value['float_value'])
+	
+	def __str__(self):
+		addr = int(self.value.address)
+		return f"<T_FLOAT@0x{addr:x}> {self.float_value()}"
+	
+	def print_to(self, terminal):
+		"""Return formatted float representation."""
+		addr = int(self.value.address)
+		tag = terminal.print(
+			format.metadata, '<',
+			format.type, 'T_FLOAT',
+			format.metadata, f'@0x{addr:x}>',
+			format.reset
+		)
+		num_val = terminal.print(format.number, str(self.float_value()), format.reset)
+		return f"{tag} {num_val}"
+	
+	def print_recursive(self, printer, depth):
+		"""Print this float (no recursion needed)."""
+		printer.print(self)
+
+def is_flonum(value):
+	"""Check if value is an immediate flonum"""
+	import sys
+	val_int = int(value)
+	# FLONUM_MASK = 0x03, FLONUM_FLAG = 0x02 (on USE_FLONUM platforms)
+	# Get from ruby_special_consts enum
+	FLONUM_MASK = constants.get_enum('ruby_special_consts', 'RUBY_FLONUM_MASK', 0x03)
+	FLONUM_FLAG = constants.get_enum('ruby_special_consts', 'RUBY_FLONUM_FLAG', 0x02)
+	result = (val_int & FLONUM_MASK) == FLONUM_FLAG
+	return result
+
+def RFloat(value):
+	"""Factory function for float values - handles both flonums and heap objects"""
+	# Check for immediate flonum first
+	if is_flonum(value):
+		return RFloatImmediate(value)
+	
+	# Check for heap-allocated T_FLOAT
+	if rbasic.is_type(value, 'RUBY_T_FLOAT'):
+		return RFloatObject(value)
+	
+	return None

data/data/toolbox/rhash.py

@@ -0,0 +1,159 @@
+import debugger
+import rbasic
+import constants
+import format
+
+class RHashBase:
+	"""Base class for RHash variants."""
+	
+	def __init__(self, value):
+		"""value is a VALUE pointing to a T_HASH object."""
+		self.value = value
+		self.rhash = value.cast(constants.type_struct('struct RHash').pointer())
+		self.basic = value.cast(constants.type_struct('struct RBasic').pointer())
+		self.flags = int(self.basic.dereference()['flags'])
+	
+	def size(self):
+		"""Get hash size. Must be implemented by subclasses."""
+		raise NotImplementedError
+	
+	def pairs(self):
+		"""Iterate over (key, value) pairs. Must be implemented by subclasses."""
+		raise NotImplementedError
+
+class RHashSTTable(RHashBase):
+	"""Hash using ST table structure (older or larger hashes)."""
+	
+	def __init__(self, value):
+		super().__init__(value)
+		# Calculate st_table pointer
+		rhash_size = debugger.parse_and_eval("sizeof(struct RHash)")
+		st_table_addr = int(value) + int(rhash_size)
+		st_table_type = constants.type_struct("st_table")
+		self.st_table = debugger.create_value_from_address(st_table_addr, st_table_type).address
+	
+	def size(self):
+		return int(self.st_table.dereference()['num_entries'])
+	
+	def pairs(self):
+		"""Yield (key, value) pairs."""
+		num_entries = self.size()
+		for i in range(num_entries):
+			key = self.st_table.dereference()['entries'][i]['key']
+			value = self.st_table.dereference()['entries'][i]['record']
+			yield (key, value)
+	
+	def __str__(self):
+		"""Return string representation of hash."""
+		addr = int(self.value)
+		return f"<T_HASH@0x{addr:x} ST-Table entries={self.size()}>"
+	
+	def print_to(self, terminal):
+		"""Print this hash with formatting."""
+		addr = int(self.value)
+		return terminal.print(
+			format.metadata, '<', 
+			format.type, 'T_HASH',
+			format.metadata, f'@0x{addr:x} ST-Table entries={self.size()}>',
+			format.reset
+		)
+	
+	def print_recursive(self, printer, depth):
+		"""Print this hash recursively."""
+		printer.print(self)
+		
+		if depth <= 0:
+			if self.size() > 0:
+				printer.print_with_indent(printer.max_depth - depth, "  ...")
+			return
+		
+		# Print each key-value pair
+		for i, (key, value) in enumerate(self.pairs()):
+			printer.print_key_label(printer.max_depth - depth, i)
+			printer.print_value(key, depth - 1)
+			printer.print_value_label(printer.max_depth - depth)
+			printer.print_value(value, depth - 1)
+
+class RHashARTable(RHashBase):
+	"""Hash using AR table structure (newer, smaller hashes)."""
+	
+	def __init__(self, value):
+		super().__init__(value)
+		# Feature detection: check if as.ar field exists (Ruby 3.2)
+		# vs embedded after RHash (Ruby 3.3+)
+		as_union = self.rhash.dereference()['as']
+		if as_union is not None:
+			# Ruby 3.2 layout: ar_table is accessed via as.ar pointer
+			self.ar_table = as_union['ar']
+		else:
+			# Ruby 3.3+: ar_table is embedded directly after RHash structure
+			rhash_size = debugger.parse_and_eval("sizeof(struct RHash)")
+			ar_table_addr = int(self.rhash) + int(rhash_size)
+			ar_table_type = constants.type_struct("struct ar_table_struct")
+			self.ar_table = debugger.create_value_from_address(ar_table_addr, ar_table_type).address
+		
+		# Get array table size and bound from flags
+		self.ar_size = ((self.flags & constants.get("RHASH_AR_TABLE_SIZE_MASK")) >> constants.get("RHASH_AR_TABLE_SIZE_SHIFT"))
+		self.ar_bound = ((self.flags & constants.get("RHASH_AR_TABLE_BOUND_MASK")) >> constants.get("RHASH_AR_TABLE_BOUND_SHIFT"))
+	
+	def size(self):
+		return self.ar_size
+	
+	def bound(self):
+		"""Get the bound (capacity) of the AR table."""
+		return self.ar_bound
+	
+	def pairs(self):
+		"""Yield (key, value) pairs, skipping undefined/deleted entries."""
+		RUBY_Qundef = constants.get("RUBY_Qundef")
+		for i in range(int(self.ar_bound)):
+			key = self.ar_table.dereference()['pairs'][i]['key']
+			# Skip undefined/deleted entries
+			if int(key) != RUBY_Qundef:
+				value = self.ar_table.dereference()['pairs'][i]['val']
+				yield (key, value)
+	
+	def __str__(self):
+		"""Return string representation of hash."""
+		addr = int(self.value)
+		return f"<T_HASH@0x{addr:x} AR-Table size={self.size()} bound={self.bound()}>"
+	
+	def print_to(self, terminal):
+		"""Print this hash with formatting."""
+		addr = int(self.value)
+		return terminal.print(
+			format.metadata, '<',
+			format.type, 'T_HASH',
+			format.metadata, f'@0x{addr:x} AR-Table size={self.size()} bound={self.bound()}>',
+			format.reset
+		)
+	
+	def print_recursive(self, printer, depth):
+		"""Print this hash recursively."""
+		printer.print(self)
+		
+		if depth <= 0:
+			if self.size() > 0:
+				printer.print_with_indent(printer.max_depth - depth, "  ...")
+			return
+		
+		# Print each key-value pair
+		for i, (key, value) in enumerate(self.pairs()):
+			printer.print_key_label(printer.max_depth - depth, i)
+			printer.print_value(key, depth - 1)
+			printer.print_value_label(printer.max_depth - depth)
+			printer.print_value(value, depth - 1)
+
+def RHash(value):
+	"""Factory function that returns the appropriate RHash variant.
+	
+	Caller should ensure value is a RUBY_T_HASH before calling this function.
+	"""
+	# Get flags to determine ST table vs AR table
+	basic = value.cast(constants.type_struct('struct RBasic').pointer())
+	flags = int(basic.dereference()['flags'])
+	
+	if (flags & constants.get("RHASH_ST_TABLE_FLAG")) != 0:
+		return RHashSTTable(value)
+	else:
+		return RHashARTable(value)