toolbox 0.1.4 → 0.2.0

data/data/toolbox/rstring.py

@@ -0,0 +1,234 @@
+import debugger
+import rbasic
+import constants
+import format
+
+# Type code for arrays (same in GDB and LLDB)
+_TYPE_CODE_ARRAY = 1
+
+def _char_ptr_type():
+	"""Return char* type for GDB."""
+	return constants.type_struct('char').pointer()
+
+class RStringBase:
+	"""Base class for RString variants with common functionality."""
+	
+	def __init__(self, value):
+		"""value is a VALUE pointing to a T_STRING object."""
+		self.value = value
+		self.rstring = value.cast(constants.type_struct('struct RString').pointer())
+		self.basic = value.cast(constants.type_struct('struct RBasic').pointer())
+		self.flags = int(self.basic.dereference()['flags'])
+	
+	def _is_embedded(self):
+		"""Check if string is embedded. Must be implemented by subclasses."""
+		raise NotImplementedError
+	
+	def length(self):
+		"""Get string length. Must be implemented by subclasses."""
+		raise NotImplementedError
+	
+	def data_ptr(self):
+		"""Get pointer to string data. Must be implemented by subclasses."""
+		raise NotImplementedError
+	
+	def read_bytes(self, max_fallback_scan=256):
+		"""Return (bytes, length). If declared length is 0, will fallback to scanning for NUL up to max_fallback_scan."""
+		pointer = self.data_ptr()
+		length = self.length()
+		
+		# Convert pointer to integer address
+		pointer_addr = int(pointer)
+		
+		if length and length > 0:
+			# Known length - read exact amount
+			try:
+				data = debugger.read_memory(pointer_addr, length)
+				return (data, length)
+			except debugger.MemoryError:
+				return (b"", 0)
+		else:
+			# Unknown length - scan for NUL terminator
+			try:
+				return debugger.read_cstring(pointer_addr, max_fallback_scan)
+			except debugger.MemoryError:
+				return (b"", 0)
+	
+	def to_str(self, encoding='utf-8'):
+		"""Convert to Python string."""
+		data, length = self.read_bytes()
+		return data.decode(encoding, errors='replace')
+	
+	def __str__(self):
+		"""Return the string with type tag and metadata."""
+		addr = int(self.value)
+		storage = "embedded" if self._is_embedded() else "heap"
+		content = self.to_str()
+		return f"<T_STRING@0x{addr:x} {storage} length={self.length()}> {repr(content)}"
+	
+	def print_to(self, terminal):
+		"""Print this string with formatting."""
+		addr = int(self.value)
+		storage = "embedded" if self._is_embedded() else "heap"
+		content = self.to_str()
+		tag = terminal.print(
+			format.metadata, '<',
+			format.type, 'T_STRING',
+			format.metadata, f'@0x{addr:x} {storage} length={self.length()}>',
+			format.reset
+		)
+		# Use repr() to properly escape quotes, newlines, etc.
+		string_val = terminal.print(format.string, repr(content), format.reset)
+		return f"{tag} {string_val}"
+	
+	def print_recursive(self, printer, depth):
+		"""Print this string (no recursion needed for strings)."""
+		printer.print(self)
+
+class RString34(RStringBase):
+	"""Ruby 3.4+ strings: top-level len, as.embed.ary, FL_USER1 set = heap."""
+	
+	def _is_embedded(self):
+		FL_USER1 = constants.flag('RUBY_FL_USER1')
+		# FL_USER1 set => heap (not embedded)
+		return (self.flags & FL_USER1) == 0
+	
+	def length(self):
+		return int(self.rstring.dereference()['len'])
+	
+	def data_ptr(self):
+		if not self._is_embedded():
+			return self.rstring.dereference()['as']['heap']['ptr']
+		# Embedded: use as.embed.ary
+		ary = self.rstring.dereference()['as']['embed']['ary']
+		try:
+			if ary.type.code == _TYPE_CODE_ARRAY:
+				return ary.address.cast(_char_ptr_type())
+			return ary
+		except Exception:
+			return ary.address.cast(_char_ptr_type())
+
+class RString33(RStringBase):
+	"""Ruby 3.3 strings: top-level len, as.embed.len exists, FL_USER1 set = embedded."""
+	
+	def _is_embedded(self):
+		FL_USER1 = constants.flag('RUBY_FL_USER1')
+		# FL_USER1 set => embedded
+		return (self.flags & FL_USER1) != 0
+	
+	def length(self):
+		return int(self.rstring.dereference()['len'])
+	
+	def data_ptr(self):
+		if not self._is_embedded():
+			# FL_USER1 not set: in Ruby 3.3, the data may be in as.heap.ptr field
+			# For small strings, this is inline data (union overlaps with as.embed)
+			# We need the ADDRESS of this field to read the bytes, not the value
+			heap_ptr_field = self.rstring.dereference()['as']['heap']['ptr']
+			return heap_ptr_field.address.cast(_char_ptr_type())
+		# Embedded: use as.embed.ary
+		ary = self.rstring.dereference()['as']['embed']['ary']
+		try:
+			if ary.type.code == _TYPE_CODE_ARRAY:
+				return ary.address.cast(_char_ptr_type())
+			return ary
+		except Exception:
+			return ary.address.cast(_char_ptr_type())
+
+class RString32RVARGC(RStringBase):
+	"""Ruby 3.2 with RVARGC: as.embed.len for embedded, as.embed.ary for data."""
+	
+	def _is_embedded(self):
+		FL_USER1 = constants.flag('RUBY_FL_USER1')
+		# FL_USER1 set => heap (not embedded)
+		return (self.flags & FL_USER1) == 0
+	
+	def length(self):
+		if self._is_embedded():
+			return int(self.rstring.dereference()['as']['embed']['len'])
+		else:
+			return int(self.rstring.dereference()['as']['heap']['len'])
+	
+	def data_ptr(self):
+		if not self._is_embedded():
+			return self.rstring.dereference()['as']['heap']['ptr']
+		# Embedded: use as.embed.ary
+		ary = self.rstring.dereference()['as']['embed']['ary']
+		try:
+			if ary.type.code == _TYPE_CODE_ARRAY:
+				return ary.address.cast(_char_ptr_type())
+			return ary
+		except Exception:
+			return ary.address.cast(_char_ptr_type())
+
+class RString32Legacy(RStringBase):
+	"""Legacy Ruby 3.2: embedded length in FL_USER2..6, data in as.ary."""
+	
+	def _is_embedded(self):
+		FL_USER1 = constants.flag('RUBY_FL_USER1')
+		# FL_USER1 set => heap (not embedded)
+		return (self.flags & FL_USER1) == 0
+	
+	def length(self):
+		if self._is_embedded():
+			FL2 = constants.flag('RUBY_FL_USER2')
+			FL3 = constants.flag('RUBY_FL_USER3')
+			FL4 = constants.flag('RUBY_FL_USER4')
+			FL5 = constants.flag('RUBY_FL_USER5')
+			FL6 = constants.flag('RUBY_FL_USER6')
+			USHIFT = constants.flag('RUBY_FL_USHIFT')
+			mask = FL2 | FL3 | FL4 | FL5 | FL6
+			return (self.flags & mask) >> (USHIFT + 2)
+		else:
+			return int(self.rstring.dereference()['as']['heap']['len'])
+	
+	def data_ptr(self):
+		if not self._is_embedded():
+			return self.rstring.dereference()['as']['heap']['ptr']
+		# Embedded: use as.ary (not as.embed.ary)
+		ary = self.rstring.dereference()['as']['ary']
+		try:
+			if ary.type.code == _TYPE_CODE_ARRAY:
+				return ary.address.cast(_char_ptr_type())
+			return ary
+		except Exception:
+			return ary.address.cast(_char_ptr_type())
+
+def RString(value):
+	"""Factory function that detects the RString variant and returns the appropriate instance.
+	
+	Caller should ensure value is a RUBY_T_STRING before calling this function.
+	
+	Detects at runtime whether the process uses:
+	- Ruby 3.4+: top-level len field, as.embed.ary (no embed.len), FL_USER1 set = heap
+	- Ruby 3.3: top-level len field, as.embed.len exists, FL_USER1 set = embedded
+	- Ruby 3.2 with RVARGC: as.embed.len for embedded, as.embed.ary for data
+	- Legacy 3.2: embedded length in FL_USER2..6, data in as.ary
+	"""
+	rstring = value.cast(constants.type_struct('struct RString').pointer())
+	
+	# Try top-level len field (Ruby 3.3+/3.4+)
+	len_field = rstring.dereference()['len']
+	if len_field is not None:
+		# Now check if embed structure has len field (3.3) or just ary (3.4+)
+		as_union = rstring.dereference()['as']
+		if as_union is not None:
+			embed_struct = as_union['embed']
+			if embed_struct is not None:
+				embed_len = embed_struct['len']
+				if embed_len is not None:
+					return RString33(value)
+				else:
+					return RString34(value)
+	
+	# Try RVARGC embedded len field (3.2 RVARGC)
+	as_union = rstring.dereference()['as']
+	if as_union is not None:
+		embed_struct = as_union['embed']
+		if embed_struct is not None:
+			embed_len = embed_struct['len']
+			if embed_len is not None:
+				return RString32RVARGC(value)
+	
+	# Fallback to legacy 3.2
+	return RString32Legacy(value)

data/data/toolbox/rstruct.py

@@ -0,0 +1,157 @@
+import debugger
+import rbasic
+import constants
+import format
+
+
+class RStructBase:
+	"""Base class for Ruby struct variants."""
+	
+	def __init__(self, value):
+		"""value is a VALUE pointing to a T_STRUCT object."""
+		self.value = value
+		self.rstruct = value.cast(constants.type_struct('struct RStruct').pointer())
+	
+	def length(self):
+		"""Get the number of fields in the struct."""
+		raise NotImplementedError("Subclass must implement length()")
+	
+	def items_ptr(self):
+		"""Get pointer to the struct's data array."""
+		raise NotImplementedError("Subclass must implement items_ptr()")
+	
+	def __len__(self):
+		"""Support len(struct) syntax."""
+		return self.length()
+	
+	def __getitem__(self, index):
+		"""Support struct[i] syntax to access fields."""
+		length = self.length()
+		if index < 0 or index >= length:
+			raise IndexError(f"struct index out of range: {index} (length: {length})")
+		
+		ptr = self.items_ptr()
+		return ptr[index]
+
+
+class RStructEmbedded(RStructBase):
+	"""Ruby struct with embedded storage (small structs)."""
+	
+	def length(self):
+		"""Get length from flags for embedded struct."""
+		flags = int(self.rstruct.dereference()['basic']['flags'])
+		
+		# Extract length from FL_USER1 and FL_USER2 flags
+		RUBY_FL_USER1 = constants.flag("RUBY_FL_USER1")
+		RUBY_FL_USER2 = constants.flag("RUBY_FL_USER2")
+		RUBY_FL_USHIFT = constants.flag("RUBY_FL_USHIFT")
+		
+		mask = RUBY_FL_USER1 | RUBY_FL_USER2
+		shift = RUBY_FL_USHIFT + 1
+		return (flags & mask) >> shift
+	
+	def items_ptr(self):
+		"""Get pointer to embedded data array."""
+		return self.rstruct.dereference()['as']['ary']
+	
+	def __str__(self):
+		"""Return string representation of struct."""
+		addr = int(self.value)
+		return f"<T_STRUCT@0x{addr:x} embedded length={len(self)}>"
+	
+	def print_to(self, terminal):
+		"""Return formatted struct representation."""
+		addr = int(self.value)
+		return terminal.print(
+			format.metadata, '<',
+			format.type, 'T_STRUCT',
+			format.metadata, f'@0x{addr:x} embedded length={len(self)}>',
+			format.reset
+		)
+	
+	def print_recursive(self, printer, depth):
+		"""Print this struct recursively."""
+		printer.print(self)
+		
+		if depth <= 0:
+			if len(self) > 0:
+				printer.print_with_indent(printer.max_depth - depth, "  ...")
+			return
+		
+		# Print each field
+		for i in range(len(self)):
+			printer.print_item_label(printer.max_depth - depth, i)
+			printer.print_value(self[i], depth - 1)
+
+
+class RStructHeap(RStructBase):
+	"""Ruby struct with heap-allocated storage (large structs)."""
+	
+	def length(self):
+		"""Get length from heap structure."""
+		return int(self.rstruct.dereference()['as']['heap']['len'])
+	
+	def items_ptr(self):
+		"""Get pointer to heap-allocated data array."""
+		return self.rstruct.dereference()['as']['heap']['ptr']
+	
+	def __str__(self):
+		"""Return string representation of struct."""
+		addr = int(self.value)
+		return f"<T_STRUCT@0x{addr:x} heap length={len(self)}>"
+	
+	def print_to(self, terminal):
+		"""Return formatted struct representation."""
+		addr = int(self.value)
+		return terminal.print(
+			format.metadata, '<',
+			format.type, 'T_STRUCT',
+			format.metadata, f'@0x{addr:x} heap length={len(self)}>',
+			format.reset
+		)
+	
+	def print_recursive(self, printer, depth):
+		"""Print this struct recursively."""
+		printer.print(self)
+		
+		if depth <= 0:
+			if len(self) > 0:
+				printer.print_with_indent(printer.max_depth - depth, "  ...")
+			return
+		
+		# Print each field
+		for i in range(len(self)):
+			printer.print_item_label(printer.max_depth - depth, i)
+			printer.print_value(self[i], depth - 1)
+
+
+def RStruct(value):
+	"""
+	Factory function to create the appropriate RStruct variant.
+	
+	Caller should ensure value is a RUBY_T_STRUCT before calling this function.
+	
+	Returns:
+		RStructEmbedded or RStructHeap instance
+	"""
+	# Cast to RStruct pointer to read flags
+	rstruct_type = constants.type_struct("struct RStruct").pointer()
+	rstruct = value.cast(rstruct_type)
+	flags = int(rstruct.dereference()['basic']['flags'])
+	
+	# Feature detection: check for RSTRUCT_EMBED_LEN_MASK flag
+	# If struct uses embedded storage, the length is encoded in flags
+	RSTRUCT_EMBED_LEN_MASK = constants.get("RSTRUCT_EMBED_LEN_MASK")
+	if RSTRUCT_EMBED_LEN_MASK is None:
+		# Fallback: try to detect by checking if as.heap exists
+		try:
+			_ = rstruct.dereference()['as']['heap']
+			return RStructHeap(value)
+		except Exception:
+			return RStructEmbedded(value)
+	
+	# Check if embedded flag is set
+	if flags & RSTRUCT_EMBED_LEN_MASK:
+		return RStructEmbedded(value)
+	else:
+		return RStructHeap(value)

data/data/toolbox/rsymbol.py

@@ -0,0 +1,302 @@
+import debugger
+import rbasic
+import constants
+import format
+
+
+class RubySymbol:
+	"""Ruby symbol from ID (integer identifier)."""
+	
+	def __init__(self, symbol_id):
+		"""Initialize from a symbol ID.
+		
+		Args:
+			symbol_id: Integer symbol ID
+		"""
+		self.symbol_id = int(symbol_id)
+		self._name = None
+	
+	def to_str(self):
+		"""Get symbol name from global symbol table, or None if not found."""
+		import sys
+		if self._name is not None:
+			return self._name
+		
+		try:
+			# rb_id_to_serial
+			# tLAST_OP_ID is in enum ruby_method_ids
+			tLAST_OP_ID = constants.get_enum('ruby_method_ids', 'tLAST_OP_ID', 163)
+			ID_ENTRY_UNIT = 512
+			ID_ENTRY_SIZE = 2
+			
+			id_val = self.symbol_id
+			
+			# The symbol_id is already the ID value (shifted from VALUE by RUBY_SPECIAL_SHIFT)
+			# We just need to convert it to a serial number for the global symbol table lookup
+			if id_val > tLAST_OP_ID:
+				# For dynamic symbols, the serial is stored in the upper bits
+				try:
+					RUBY_ID_SCOPE_SHIFT = int(constants.get_enum('ruby_id_types', 'RUBY_ID_SCOPE_SHIFT', 4))
+				except Exception:
+					RUBY_ID_SCOPE_SHIFT = 4  # Default value
+				serial = id_val >> RUBY_ID_SCOPE_SHIFT
+			else:
+				# For static symbols (operators, etc.), the ID is the serial
+				serial = id_val
+			
+			# Access ruby_global_symbols
+			global_symbols = debugger.parse_and_eval("ruby_global_symbols")
+			
+			# Ruby 3.5+ changed from last_id to next_id
+			last_id_field = global_symbols['last_id']
+			if last_id_field is not None:
+				last_id = int(last_id_field)
+			else:
+				# Ruby 3.5+ uses next_id instead
+				next_id_field = global_symbols['next_id']
+				if next_id_field is not None:
+					last_id = int(next_id_field) - 1
+				else:
+					return None
+			
+			if not serial or serial > last_id:
+				return None
+			
+			idx = serial // ID_ENTRY_UNIT
+			
+			# Get ids array
+			ids = global_symbols['ids'].cast(constants.type_struct("struct RArray").pointer())
+			
+			# Import rarray to access the array
+			import rarray
+			arr = rarray.RArray(global_symbols['ids'])
+			if arr is None:
+				return None
+			
+			# Get the symbols entry
+			entry_val = arr[idx]
+			
+			# Get the symbol from the entry
+			entry_arr = rarray.RArray(entry_val)
+			if entry_arr is None:
+				return None
+			
+			ids_idx = (serial % ID_ENTRY_UNIT) * ID_ENTRY_SIZE
+			sym_val = entry_arr[ids_idx]
+			
+			# Get the string from the symbol
+			import rstring
+			str_obj = rstring.RString(sym_val)
+			if str_obj is None:
+				return None
+			
+			self._name = str_obj.to_str()
+			return self._name
+			
+		except Exception as e:
+			import traceback
+			traceback.print_exc(file=sys.stderr)
+			return None
+	
+	def __str__(self):
+		"""Return symbol representation."""
+		name = self.to_str()
+		if name:
+			return f":{name}"
+		else:
+			return f":id_0x{self.symbol_id:x}"
+
+
+class RSymbolImmediate:
+	"""Ruby immediate symbol (encoded in VALUE)."""
+	
+	def __init__(self, value):
+		self.value = value
+		self._ruby_symbol = None
+	
+	def id(self):
+		"""Get the symbol ID."""
+		return get_id(self.value)
+	
+	def ruby_symbol(self):
+		"""Get RubySymbol instance for this symbol."""
+		if self._ruby_symbol is None:
+			self._ruby_symbol = RubySymbol(self.id())
+		return self._ruby_symbol
+	
+	def to_str(self):
+		"""Get symbol name from global symbol table, or None if not found."""
+		return self.ruby_symbol().to_str()
+	
+	def __str__(self):
+		"""Return symbol representation."""
+		name = self.to_str()
+		if name:
+			return f"<T_SYMBOL> :{name}"
+		else:
+			return f"<T_SYMBOL> :id_0x{self.id():x}"
+	
+	def print_to(self, terminal):
+		"""Return formatted symbol representation."""
+		name = self.to_str()
+		if name:
+			tag = terminal.print(
+				format.metadata, '<',
+				format.type, 'T_SYMBOL',
+				format.metadata, '>',
+				format.reset
+			)
+			symbol_val = terminal.print(format.symbol, f':{name}', format.reset)
+			return f"{tag} {symbol_val}"
+		else:
+			tag = terminal.print(
+				format.metadata, '<',
+				format.type, 'T_SYMBOL',
+				format.metadata, '>',
+				format.reset
+			)
+			symbol_val = terminal.print(format.symbol, f':id_0x{self.id():x}', format.reset)
+			return f"{tag} {symbol_val}"
+	
+	def print_recursive(self, printer, depth):
+		"""Print this symbol (no recursion needed)."""
+		printer.print(self)
+
+
+class RSymbolObject:
+	"""Ruby T_SYMBOL heap object."""
+	
+	def __init__(self, value):
+		self.value = value
+		self.rsymbol = value.cast(constants.type_struct("struct RSymbol").pointer())
+		self._ruby_symbol = None
+	
+	def id(self):
+		"""Get the symbol ID."""
+		return int(self.rsymbol.dereference()['id'])
+	
+	def ruby_symbol(self):
+		"""Get RubySymbol instance for this symbol."""
+		if self._ruby_symbol is None:
+			self._ruby_symbol = RubySymbol(self.id())
+		return self._ruby_symbol
+	
+	def fstr(self):
+		"""Get the frozen string containing the symbol name."""
+		return self.rsymbol.dereference()['fstr']
+	
+	def to_str(self):
+		"""Get symbol name as a string."""
+		try:
+			import rstring
+			fstr_val = self.fstr()
+			str_obj = rstring.RString(fstr_val)
+			if str_obj:
+				return str_obj.to_str()
+			return None
+		except Exception:
+			return None
+	
+	def __str__(self):
+		"""Return symbol representation."""
+		name = self.to_str()
+		addr = int(self.value)
+		if name:
+			return f"<T_SYMBOL@0x{addr:x}> :{name}"
+		else:
+			fstr_val = self.fstr()
+			return f"<T_SYMBOL@0x{addr:x}> :<Symbol:0x{int(fstr_val):x}>"
+	
+	def print_to(self, terminal):
+		"""Return formatted symbol representation."""
+		name = self.to_str()
+		addr = int(self.value)
+		if name:
+			tag = terminal.print(
+				format.metadata, '<',
+				format.type, 'T_SYMBOL',
+				format.metadata, f'@0x{addr:x}>',
+				format.reset
+			)
+			symbol_val = terminal.print(format.symbol, f':{name}', format.reset)
+			return f"{tag} {symbol_val}"
+		else:
+			fstr_val = self.fstr()
+			tag = terminal.print(
+				format.metadata, '<',
+				format.type, 'T_SYMBOL',
+				format.metadata, f'@0x{addr:x}>',
+				format.reset
+			)
+			symbol_val = terminal.print(format.symbol, f':<Symbol:0x{int(fstr_val):x}>', format.reset)
+			return f"{tag} {symbol_val}"
+	
+	def print_recursive(self, printer, depth):
+		"""Print this symbol (no recursion needed)."""
+		printer.print(self)
+
+
+
+def is_symbol(value):
+	"""
+	Check if a VALUE is a symbol using the logic from Ruby's .gdbinit.
+	
+	From .gdbinit:
+	  if (($arg0) & ~(~(VALUE)0<<RUBY_SPECIAL_SHIFT)) == RUBY_SYMBOL_FLAG
+	
+	This checks if the low bits (after masking RUBY_SPECIAL_SHIFT) match RUBY_SYMBOL_FLAG.
+	"""
+	import sys
+	try:
+		val_int = int(value)
+		
+		# Get Ruby constants from ruby_special_consts enum
+		RUBY_SPECIAL_SHIFT = constants.get_enum('ruby_special_consts', 'RUBY_SPECIAL_SHIFT', 8)
+		RUBY_SYMBOL_FLAG = constants.get_enum('ruby_special_consts', 'RUBY_SYMBOL_FLAG', 0x0c)
+		
+		# Create mask for low bits: ~(~0 << RUBY_SPECIAL_SHIFT)
+		# This gives us RUBY_SPECIAL_SHIFT low bits set to 1
+		mask = ~(~0 << RUBY_SPECIAL_SHIFT)
+		
+		# Check if masked value equals RUBY_SYMBOL_FLAG
+		result = (val_int & mask) == RUBY_SYMBOL_FLAG
+		return result
+	except Exception as e:
+		# Fallback to simple check
+		return (int(value) & 0xFF) == 0x0C
+
+
+def get_id(value):
+	"""
+	Extract symbol ID from a VALUE using the logic from Ruby's .gdbinit.
+	
+	From .gdbinit:
+	  set $id = (($arg0) >> RUBY_SPECIAL_SHIFT)
+	"""
+	import sys
+	try:
+		RUBY_SPECIAL_SHIFT = constants.get_enum('ruby_special_consts', 'RUBY_SPECIAL_SHIFT', 8)
+		val_int = int(value)
+		result = val_int >> RUBY_SPECIAL_SHIFT
+		return result
+	except Exception as e:
+		# Fallback to shift by 8
+		return int(value) >> 8
+
+
+def RSymbol(value):
+	"""
+	Factory function to create the appropriate RSymbol variant.
+	
+	Returns:
+		RSymbolImmediate, RSymbolObject, or None
+	"""
+	# Check if it's an immediate symbol
+	if is_symbol(value):
+		return RSymbolImmediate(value)
+	
+	# Check if it's a T_SYMBOL object
+	if rbasic.is_type(value, 'RUBY_T_SYMBOL'):
+		return RSymbolObject(value)
+	
+	return None