toolbox 0.1.4 → 0.3.0

data/data/toolbox/init.py

@@ -0,0 +1,89 @@
+"""
+Ruby Toolbox - Unified entry point for GDB and LLDB
+
+This module auto-detects which debugger is running and loads
+the appropriate Ruby debugging extensions.
+"""
+
+import os
+import sys
+
+# Get the directory containing this file (data/toolbox)
+toolbox_dir = os.path.dirname(os.path.abspath(__file__))
+
+# Add to Python path for imports
+if toolbox_dir not in sys.path:
+	sys.path.insert(0, toolbox_dir)
+
+# Load debugger abstraction (auto-detects GDB or LLDB)
+import debugger
+
+# Load Ruby debugging extensions
+loaded_extensions = []
+failed_extensions = []
+
+# Try to load each extension individually
+extensions_to_load = [
+	('print', 'rb-print'),
+	('context', 'rb-context, rb-context-storage'),
+	('fiber', 'rb-fiber-scan-heap, rb-fiber-switch'),
+	('stack', 'rb-stack-trace'),
+	('heap', 'rb-heap-scan'),
+]
+
+for module_name, commands in extensions_to_load:
+	try:
+		if module_name == 'print':
+			import print as print_module
+		elif module_name == 'context':
+			import context
+		elif module_name == 'fiber':
+			import fiber
+		elif module_name == 'stack':
+			import stack
+		elif module_name == 'heap':
+			import heap
+		loaded_extensions.append((module_name, commands))
+	except Exception as e:
+		# Catch all exceptions during module load
+		failed_extensions.append((module_name, str(e)))
+		import traceback
+		print(f"Failed to load {module_name}: {e}", file=sys.stderr)
+		traceback.print_exc(file=sys.stderr)
+
+# Silently load - no status messages printed by default
+# Users can run 'help' to see available commands
+
+# For LLDB, register commands that were successfully loaded
+if debugger.DEBUGGER_NAME == 'lldb':
+	import lldb
+	
+	# Get all registered commands
+	for cmd_name, cmd_obj in debugger.Command._commands.items():
+		# Create a wrapper function in this module's namespace
+		func_name = f"_cmd_{cmd_name.replace('-', '_')}"
+		
+		# Create closure that captures cmd_obj
+		def make_wrapper(command_obj):
+			def wrapper(debugger_obj, command, result, internal_dict):
+				try:
+					# Check if stdout is a TTY
+					from_tty = sys.stdout.isatty()
+					command_obj.invoke(command, from_tty=from_tty)
+				except Exception as e:
+					print(f"Error: {e}")
+					import traceback
+					traceback.print_exc()
+			return wrapper
+		
+		# Add to this module's globals
+		globals()[func_name] = make_wrapper(cmd_obj)
+		
+		# Register with LLDB
+		# The module is imported as 'init' by LLDB
+		result = lldb.SBCommandReturnObject()
+		cmd_str = f"command script add -f init.{func_name} {cmd_name}"
+		lldb.debugger.GetCommandInterpreter().HandleCommand(cmd_str, result)
+		
+		# Silently ignore registration failures
+

data/data/toolbox/print.py

@@ -0,0 +1,79 @@
+"""Print command for Ruby values."""
+
+import debugger
+import sys
+
+# Import utilities
+import command
+import constants
+import rvalue
+import rstring
+import rarray
+import rhash
+import rsymbol
+import rstruct
+import rfloat
+import rbignum
+import rbasic
+import format
+
+
+class RubyObjectPrinter:
+	"""Print Ruby objects with recursive descent into nested structures."""
+	
+	USAGE = command.Usage(
+		summary="Print Ruby objects with recursive inspection",
+		parameters=[('value', 'VALUE or expression to print')],
+		options={
+			'depth': (int, 1, 'Maximum recursion depth for nested objects')
+		},
+		flags=[
+			('debug', 'Show internal structure and debug information')
+		],
+		examples=[
+			("rb-print $errinfo", "Print exception object"),
+			("rb-print $ec->storage --depth 3", "Print fiber storage with depth 3"),
+			("rb-print $ec->cfp->sp[-1] --debug", "Print top of stack with debug info")
+		]
+	)
+	
+	def invoke(self, arguments, terminal):
+		"""Execute the print command.
+		
+		Args:
+			arguments: Parsed Arguments object
+			terminal: Terminal formatter (already configured for TTY/non-TTY)
+		"""
+		# Get options
+		max_depth = arguments.get_option('depth', 1)
+		debug_mode = arguments.has_flag('debug')
+		
+		# Validate depth
+		if max_depth < 1:
+			print("Error: --depth must be >= 1")
+			return
+		
+		# Create printer
+		printer = format.Printer(terminal, max_depth, debug_mode)
+		
+		# Process each expression
+		for expression in arguments.expressions:
+			try:
+				# Evaluate the expression
+				ruby_value = debugger.parse_and_eval(expression)
+				
+				# Interpret the value and let it print itself recursively
+				ruby_object = rvalue.interpret(ruby_value)
+				ruby_object.print_recursive(printer, max_depth)
+			except debugger.Error as e:
+				print(f"Error evaluating expression '{expression}': {e}")
+			except Exception as e:
+				print(f"Error processing '{expression}': {type(e).__name__}: {e}")
+				if debug_mode:
+					import traceback
+					traceback.print_exc(file=sys.stderr)
+
+
+# Register command using new interface
+debugger.register("rb-print", RubyObjectPrinter, usage=RubyObjectPrinter.USAGE)
+

data/data/toolbox/rarray.py

@@ -0,0 +1,116 @@
+import debugger
+import rbasic
+import constants
+import format
+
+class RArrayBase:
+	"""Base class for RArray variants."""
+	
+	def __init__(self, value):
+		"""value is a VALUE pointing to a T_ARRAY object."""
+		self.value = value
+		self.rarray = value.cast(constants.type_struct('struct RArray').pointer())
+		self.basic = value.cast(constants.type_struct('struct RBasic').pointer())
+		self.flags = int(self.basic.dereference()['flags'])
+	
+	def length(self):
+		"""Get array length. Must be implemented by subclasses."""
+		raise NotImplementedError
+	
+	def items_ptr(self):
+		"""Get pointer to array items. Must be implemented by subclasses."""
+		raise NotImplementedError
+	
+	def get_item(self, index):
+		"""Get item at index."""
+		if index < 0 or index >= self.length():
+			raise IndexError(f"Index {index} out of range")
+		items = self.items_ptr()
+		return items[index]
+	
+	def __len__(self):
+		"""Support len() function."""
+		return self.length()
+	
+	def __getitem__(self, index):
+		"""Support indexing."""
+		return self.get_item(index)
+	
+	def print_recursive(self, printer, depth):
+		"""Print this array recursively."""
+		# Print the array header
+		printer.print(self)
+		
+		# If depth is 0, don't recurse into elements
+		if depth <= 0:
+			if len(self) > 0:
+				printer.print_with_indent(printer.max_depth - depth, "  ...")
+			return
+		
+		# Print each element
+		for i in range(len(self)):
+			printer.print_item_label(printer.max_depth - depth, i)
+			try:
+				element = self[i]
+				printer.print_value(element, depth - 1)
+			except Exception as e:
+				print(f"Error accessing element {i}: {e}")
+
+class RArrayEmbedded(RArrayBase):
+	"""Embedded array (small arrays stored directly in struct)."""
+	
+	def length(self):
+		# Extract length from flags using Ruby's encoding
+		# Length is stored in RUBY_FL_USER3|RUBY_FL_USER4 bits, shifted by RUBY_FL_USHIFT+3
+		mask = constants.flag("RUBY_FL_USER3") | constants.flag("RUBY_FL_USER4")
+		shift = constants.flag("RUBY_FL_USHIFT") + 3
+		return (self.flags & mask) >> shift
+	
+	def items_ptr(self):
+		return self.rarray.dereference()['as']['ary']
+	
+	def __str__(self):
+		"""Return string representation of array."""
+		addr = int(self.value)
+		return f"<T_ARRAY@0x{addr:x} embedded length={len(self)}>"
+	
+	def print_to(self, terminal):
+		"""Print this array with formatting."""
+		addr = int(self.value)
+		details = f"embedded length={len(self)}"
+		terminal.print_type_tag('T_ARRAY', addr, details)
+
+class RArrayHeap(RArrayBase):
+	"""Heap array (larger arrays with separate memory allocation)."""
+	
+	def length(self):
+		return int(self.rarray.dereference()['as']['heap']['len'])
+	
+	def items_ptr(self):
+		return self.rarray.dereference()['as']['heap']['ptr']
+	
+	def __str__(self):
+		"""Return string representation of array."""
+		addr = int(self.value)
+		return f"<T_ARRAY@0x{addr:x} heap length={len(self)}>"
+	
+	def print_to(self, terminal):
+		"""Print this array with formatting."""
+		addr = int(self.value)
+		details = f"heap length={len(self)}"
+		terminal.print_type_tag('T_ARRAY', addr, details)
+
+def RArray(value):
+	"""Factory function that returns the appropriate RArray variant.
+	
+	Caller should ensure value is a RUBY_T_ARRAY before calling this function.
+	"""
+	# Get flags to determine embedded vs heap
+	basic = value.cast(constants.type_struct('struct RBasic').pointer())
+	flags = int(basic.dereference()['flags'])
+	
+	# Check if array is embedded or heap-allocated using flags
+	if (flags & constants.get("RARRAY_EMBED_FLAG")) != 0:
+		return RArrayEmbedded(value)
+	else:
+		return RArrayHeap(value)

data/data/toolbox/rbasic.py

@@ -0,0 +1,99 @@
+import debugger
+import constants
+import format
+
+def type_of(value):
+	"""Get the Ruby type of a VALUE.
+	
+	Returns the RUBY_T_* constant value (e.g., RUBY_T_STRING, RUBY_T_ARRAY),
+	or None if the type cannot be determined.
+	"""
+	basic = value.cast(constants.type_struct('struct RBasic').pointer())
+	flags = int(basic.dereference()['flags'])
+	RUBY_T_MASK = constants.type('RUBY_T_MASK')
+	return flags & RUBY_T_MASK
+
+def is_type(value, ruby_type_constant):
+	"""Check if a VALUE is of a specific Ruby type.
+	
+	Arguments:
+		value: The GDB value to check
+		ruby_type_constant: String name of the constant (e.g., 'RUBY_T_STRING')
+	
+	Returns:
+		True if the value is of the specified type, False otherwise
+	"""
+	type_flag = type_of(value)
+	expected_type = constants.get(ruby_type_constant)
+	return type_flag == expected_type
+
+# Map of type constants to their names for display
+TYPE_NAMES = {
+	'RUBY_T_NONE': 'T_NONE',
+	'RUBY_T_OBJECT': 'T_OBJECT',
+	'RUBY_T_CLASS': 'T_CLASS',
+	'RUBY_T_MODULE': 'T_MODULE',
+	'RUBY_T_FLOAT': 'T_FLOAT',
+	'RUBY_T_STRING': 'T_STRING',
+	'RUBY_T_REGEXP': 'T_REGEXP',
+	'RUBY_T_ARRAY': 'T_ARRAY',
+	'RUBY_T_HASH': 'T_HASH',
+	'RUBY_T_STRUCT': 'T_STRUCT',
+	'RUBY_T_BIGNUM': 'T_BIGNUM',
+	'RUBY_T_FILE': 'T_FILE',
+	'RUBY_T_DATA': 'T_DATA',
+	'RUBY_T_MATCH': 'T_MATCH',
+	'RUBY_T_COMPLEX': 'T_COMPLEX',
+	'RUBY_T_RATIONAL': 'T_RATIONAL',
+	'RUBY_T_NIL': 'T_NIL',
+	'RUBY_T_TRUE': 'T_TRUE',
+	'RUBY_T_FALSE': 'T_FALSE',
+	'RUBY_T_SYMBOL': 'T_SYMBOL',
+	'RUBY_T_FIXNUM': 'T_FIXNUM',
+	'RUBY_T_UNDEF': 'T_UNDEF',
+	'RUBY_T_IMEMO': 'T_IMEMO',
+	'RUBY_T_NODE': 'T_NODE',
+	'RUBY_T_ICLASS': 'T_ICLASS',
+	'RUBY_T_ZOMBIE': 'T_ZOMBIE',
+}
+
+def type_name(value):
+	"""Get the human-readable type name for a VALUE.
+	
+	Returns:
+		String like 'T_STRING', 'T_ARRAY', 'T_HASH', etc., or 'Unknown(0x...)'
+	"""
+	type_flag = type_of(value)
+	
+	# Try to find matching type name
+	for const_name, display_name in TYPE_NAMES.items():
+		if constants.get(const_name) == type_flag:
+			return display_name
+	
+	return f'Unknown(0x{type_flag:x})'
+
+class RBasic:
+	"""Generic Ruby object wrapper for unhandled types.
+	
+	This provides a fallback for types that don't have specialized handlers.
+	"""
+	def __init__(self, value):
+		self.value = value
+		self.basic = value.cast(constants.type_struct('struct RBasic').pointer())
+		self.flags = int(self.basic.dereference()['flags'])
+		self.type_flag = self.flags & constants.type('RUBY_T_MASK')
+	
+	def __str__(self):
+		type_str = type_name(self.value)
+		return f"<{type_str}@0x{int(self.value):x}>"
+	
+	def print_to(self, terminal):
+		"""Print formatted basic object representation."""
+		type_str = type_name(self.value)
+		addr = int(self.value)
+		# Use print_type_tag for consistency with other types
+		terminal.print_type_tag(type_str, addr)
+	
+	def print_recursive(self, printer, depth):
+		"""Print this basic object (no recursion)."""
+		printer.print(self)

data/data/toolbox/rbignum.py

@@ -0,0 +1,48 @@
+import debugger
+import constants
+import rbasic
+import format
+
+class RBignumObject:
+	def __init__(self, value):
+		self.value = value
+		self.rbignum = value.cast(constants.type_struct('struct RBignum').pointer())
+		self.basic = value.cast(constants.type_struct('struct RBasic').pointer())
+		self.flags = int(self.basic.dereference()['flags'])
+	
+	def is_embedded(self):
+		# Check if FL_USER1 flag is set (RBIGNUM_EMBED_FLAG)
+		FL_USER1 = 1 << (constants.flag('RUBY_FL_USHIFT') + 1)
+		return bool(self.flags & FL_USER1)
+	
+	def __len__(self):
+		if self.is_embedded():
+			# Embedded length is stored in flags
+			# Extract length from FL_USER2 onwards
+			return (self.flags >> (constants.flag('RUBY_FL_USHIFT') + 2)) & 0x1F
+		else:
+			return int(self.rbignum.dereference()['as']['heap']['len'])
+	
+	def __str__(self):
+		addr = int(self.value)
+		if self.is_embedded():
+			return f"<T_BIGNUM@0x{addr:x} embedded length={len(self)}>"
+		else:
+			return f"<T_BIGNUM@0x{addr:x} heap length={len(self)}>"
+	
+	def print_to(self, terminal):
+		"""Print formatted bignum representation."""
+		addr = int(self.value)
+		storage = "embedded" if self.is_embedded() else "heap"
+		details = f"{storage} length={len(self)}"
+		terminal.print_type_tag('T_BIGNUM', addr, details)
+	
+	def print_recursive(self, printer, depth):
+		"""Print this bignum (no recursion needed)."""
+		printer.print(self)
+
+def RBignum(value):
+	if rbasic.is_type(value, 'RUBY_T_BIGNUM'):
+		return RBignumObject(value)
+	
+	return None

data/data/toolbox/rclass.py

@@ -0,0 +1,136 @@
+import debugger
+import constants
+import rvalue
+import rstring
+
+class RClass:
+	"""Wrapper for Ruby class objects (klass pointers)."""
+	
+	def __init__(self, klass_value):
+		"""Initialize with a klass VALUE.
+		
+		Args:
+			klass_value: A GDB value representing a Ruby class (klass pointer)
+		"""
+		self.klass = klass_value
+		self._name = None
+	
+	def name(self):
+		"""Get the class name as a string.
+		
+		Returns:
+			Class name string, or formatted anonymous class representation
+		"""
+		if self._name is None:
+			self._name = self._get_class_name()
+		return self._name
+	
+	def _get_class_name(self):
+		"""Extract class name from klass pointer.
+		
+		Tries multiple strategies across Ruby versions:
+		1. Check against well-known global class pointers (rb_eStandardError, etc.)
+		2. Try rb_classext_struct.classpath (Ruby 3.4+)
+		3. Fall back to anonymous class format
+		
+		Returns:
+			Class name string
+		"""
+		try:
+			# Strategy 1: Check well-known exception classes
+			# This works in core dumps since we're just comparing pointers
+			well_known = [
+				('rb_eException', 'Exception'),
+				('rb_eStandardError', 'StandardError'),
+				('rb_eSystemExit', 'SystemExit'),
+				('rb_eInterrupt', 'Interrupt'),
+				('rb_eSignal', 'SignalException'),
+				('rb_eFatal', 'fatal'),
+				('rb_eScriptError', 'ScriptError'),
+				('rb_eLoadError', 'LoadError'),
+				('rb_eNotImpError', 'NotImplementedError'),
+				('rb_eSyntaxError', 'SyntaxError'),
+				('rb_eSecurityError', 'SecurityError'),
+				('rb_eNoMemError', 'NoMemoryError'),
+				('rb_eTypeError', 'TypeError'),
+				('rb_eArgError', 'ArgumentError'),
+				('rb_eIndexError', 'IndexError'),
+				('rb_eKeyError', 'KeyError'),
+				('rb_eRangeError', 'RangeError'),
+				('rb_eNameError', 'NameError'),
+				('rb_eNoMethodError', 'NoMethodError'),
+				('rb_eRuntimeError', 'RuntimeError'),
+				('rb_eFrozenError', 'FrozenError'),
+				('rb_eIOError', 'IOError'),
+				('rb_eEOFError', 'EOFError'),
+				('rb_eLocalJumpError', 'LocalJumpError'),
+				('rb_eSysStackError', 'SystemStackError'),
+				('rb_eRegexpError', 'RegexpError'),
+				('rb_eThreadError', 'ThreadError'),
+				('rb_eZeroDivError', 'ZeroDivisionError'),
+				('rb_eFloatDomainError', 'FloatDomainError'),
+				('rb_eStopIteration', 'StopIteration'),
+				('rb_eMathDomainError', 'Math::DomainError'),
+				('rb_eEncCompatError', 'Encoding::CompatibilityError'),
+			]
+			
+			klass_addr = int(self.klass)
+			for var_name, class_name in well_known:
+				try:
+					known_klass = debugger.parse_and_eval(var_name)
+					if int(known_klass) == klass_addr:
+						return class_name
+				except:
+					# Variable might not exist in this Ruby version
+					continue
+			
+			# Strategy 2: Try modern rb_classext_struct.classpath (Ruby 3.4+)
+			try:
+				rclass = self.klass.cast(constants.type_struct('struct RClass').pointer())
+				# Try to access classext.classpath
+				try:
+					# Try embedded classext (RCLASS_EXT_EMBEDDED)
+					rclass_size = debugger.parse_and_eval("sizeof(struct RClass)")
+					classext_addr = int(self.klass) + int(rclass_size)
+					classext_type = constants.type_struct('rb_classext_t')
+					classext_ptr = debugger.create_value_from_address(classext_addr, classext_type).address
+					classpath_val = classext_ptr['classpath']
+				except:
+					# Try pointer-based classext
+					try:
+						classext_ptr = rclass['ptr']
+						classpath_val = classext_ptr['classpath']
+					except:
+						classpath_val = None
+				
+				if classpath_val and int(classpath_val) != 0 and not rvalue.is_nil(classpath_val):
+					# Decode the classpath string
+					class_name_obj = rvalue.interpret(classpath_val)
+					if hasattr(class_name_obj, 'to_str'):
+						class_name = class_name_obj.to_str()
+						if class_name and not class_name.startswith('<'):
+							return class_name
+			except:
+				pass
+			
+			# Strategy 3: Fall back to anonymous class format
+			return f"#<Class:0x{int(self.klass):x}>"
+		except Exception as e:
+			# Ultimate fallback
+			return f"#<Class:0x{int(self.klass):x}>"
+	
+	def __str__(self):
+		"""Return the class name."""
+		return self.name()
+
+def get_class_name(klass_value):
+	"""Get the name of a class from its klass pointer.
+	
+	Args:
+		klass_value: A GDB value representing a Ruby class (klass pointer)
+	
+	Returns:
+		Class name string
+	"""
+	rc = RClass(klass_value)
+	return rc.name()