toolbox 0.1.3 → 0.2.0

data/context/object-inspection.md

@@ -0,0 +1,208 @@
+# Object Inspection
+
+This guide explains how to use `rb-object-print` to inspect Ruby objects, hashes, arrays, and structs in GDB.
+
+## Why Object Inspection Matters
+
+When debugging Ruby programs or analyzing core dumps, you often need to inspect complex data structures that are difficult to read in their raw memory representation. Standard GDB commands show pointer addresses and raw memory, but not the logical structure of Ruby objects.
+
+Use `rb-object-print` when you need:
+
+- **Understand exception objects**: See the full exception hierarchy, message, and backtrace data
+- **Inspect fiber storage**: View thread-local data and fiber-specific variables
+- **Debug data corruption**: Check the contents of hashes and arrays for unexpected values
+- **Analyze VM state**: Examine objects on the VM stack without manual pointer arithmetic
+
+## Basic Usage
+
+The `rb-object-print` command recursively prints Ruby objects in a human-readable format.
+
+### Syntax
+
+~~~
+rb-object-print <expression> [--depth N] [--debug]
+~~~
+
+Where:
+- `<expression>`: Any GDB expression that evaluates to a Ruby VALUE
+- `--depth N`: Maximum recursion depth (default: 1)
+- `--debug`: Enable diagnostic output for troubleshooting
+
+### Simple Values
+
+Print immediate values and special constants:
+
+~~~
+(gdb) rb-object-print 0        # <T_FALSE>
+(gdb) rb-object-print 8        # <T_NIL>
+(gdb) rb-object-print 20       # <T_TRUE>
+(gdb) rb-object-print 85       # <T_FIXNUM> 42
+~~~
+
+These work without any Ruby process running, making them useful for learning and testing.
+
+### Expressions
+
+Use any valid GDB expression:
+
+~~~
+(gdb) rb-object-print $ec->errinfo                    # Exception object
+(gdb) rb-object-print $ec->cfp->sp[-1]                # Top of VM stack
+(gdb) rb-object-print $ec->storage                    # Fiber storage hash
+(gdb) rb-object-print (VALUE)0x00007f8a12345678      # Object at specific address
+~~~
+
+## Inspecting Hashes
+
+Ruby hashes have two internal representations (ST table and AR table). The command automatically detects and displays both:
+
+### Small Hashes (AR Table)
+
+For hashes with fewer than 8 entries, Ruby uses an array-based implementation:
+
+~~~
+(gdb) rb-object-print $some_hash
+<T_HASH@...>
+[   0] K: <T_SYMBOL> :name
+       V: <T_STRING@...> "Alice"
+[   1] K: <T_SYMBOL> :age
+       V: <T_FIXNUM> 30
+[   2] K: <T_SYMBOL> :active
+       V: <T_TRUE>
+~~~
+
+### Large Hashes (ST Table)
+
+For larger hashes, Ruby uses a hash table (output format is similar):
+
+~~~
+(gdb) rb-object-print $large_hash
+<T_HASH@...>
+[   0] K: <T_SYMBOL> :user_id
+       V: <T_FIXNUM> 12345
+[   1] K: <T_SYMBOL> :session_data
+       V: <T_STRING@...> "..."
+  ...
+~~~
+
+### Controlling Depth
+
+Prevent overwhelming output from deeply nested structures:
+
+~~~
+(gdb) rb-object-print $nested_hash --depth 1   # Only top level
+<T_HASH@...>
+[   0] K: <T_SYMBOL> :data
+       V: <T_HASH@...>  # Nested hash not expanded
+
+(gdb) rb-object-print $nested_hash --depth 2   # Expand one level
+<T_HASH@...>
+[   0] K: <T_SYMBOL> :data
+       V: <T_HASH@...>
+       [   0] K: <T_SYMBOL> :nested_key
+              V: <T_STRING@...> "value"
+~~~
+
+At depth 1, nested structures show their type and address but aren't expanded. Increase depth to expand them.
+
+## Inspecting Arrays
+
+Arrays also have two representations based on size:
+
+### Arrays
+
+Arrays display their elements with type information:
+
+~~~
+(gdb) rb-object-print $array
+<T_ARRAY@...>
+[   0] <T_FIXNUM> 1
+[   1] <T_FIXNUM> 2
+[   2] <T_FIXNUM> 3
+~~~
+
+For arrays with nested objects:
+
+~~~
+(gdb) rb-object-print $array --depth 2
+<T_ARRAY@...>
+[   0] <T_STRING@...> "first item"
+[   1] <T_HASH@...>
+[   0] K: <T_SYMBOL> :key
+       V: <T_FIXNUM> 123
+  ...
+~~~
+
+## Inspecting Structs
+
+Ruby Struct objects work similarly to arrays:
+
+~~~
+(gdb) rb-object-print $struct_instance
+<T_STRUCT@...>
+[   0] <T_STRING@...> "John"
+[   1] <T_FIXNUM> 25
+[   2] <T_STRING@...> "Engineer"
+[   3] <T_TRUE>
+~~~
+
+## Practical Examples
+
+### Debugging Exception in Fiber
+
+When a fiber has an exception, inspect it:
+
+~~~
+(gdb) rb-fiber-scan-heap
+(gdb) rb-fiber-scan-switch 5  # Switch to fiber #5
+(gdb) rb-object-print $errinfo --depth 3
+~~~
+
+This reveals the full exception structure including any nested causes. After switching to a fiber, `$errinfo` and `$ec` convenience variables are automatically set.
+
+### Inspecting Method Arguments
+
+Break at a method and examine arguments on the stack:
+
+~~~
+(gdb) break some_method
+(gdb) run
+(gdb) rb-object-print $ec->cfp->sp[-1]  # Last argument
+(gdb) rb-object-print $ec->cfp->sp[-2]  # Second-to-last argument
+~~~
+
+### Examining Fiber Storage
+
+Thread-local variables are stored in fiber storage:
+
+~~~
+(gdb) rb-fiber-scan-heap
+(gdb) rb-fiber-scan-switch 0
+(gdb) rb-object-print $ec->storage --depth 2
+~~~
+
+This shows all thread-local variables and their values.
+
+## Debugging with --debug Flag
+
+When `rb-object-print` doesn't show what you expect, use `--debug`:
+
+~~~
+(gdb) rb-object-print $suspicious_value --debug
+DEBUG: Evaluated '$suspicious_value' to 0x7f8a1c567890
+DEBUG: Loaded constant RUBY_T_MASK = 31
+DEBUG: Object at 0x7f8a1c567890 with flags=0x20040005, type=0x5
+...
+~~~
+
+This shows:
+- How the expression was evaluated
+- What constants were loaded
+- Object type detection logic
+- Any errors encountered
+
+Use this to troubleshoot:
+- Unexpected output format
+- Missing nested structures
+- Type detection issues
+- Access errors

data/context/stack-inspection.md

@@ -0,0 +1,188 @@
+# Stack Inspection
+
+This guide explains how to inspect both Ruby VM stacks and native C stacks when debugging Ruby programs.
+
+## Understanding Ruby's Dual Stack System
+
+Ruby programs operate with two distinct stacks that serve different purposes. Understanding both is crucial for effective debugging, especially when tracking down segfaults, stack overflows, or unexpected behavior in C extensions.
+
+Use stack inspection when you need:
+
+- **Trace execution flow**: Understand the sequence of method calls that led to the current state
+- **Debug C extensions**: See both Ruby and native frames when extensions are involved
+- **Find stack overflows**: Identify deep recursion in either Ruby or C code
+- **Understand fiber switches**: See where fibers yield and resume
+
+## The Two Stack Types
+
+### VM Stack (Ruby Level)
+
+The VM stack holds:
+- Ruby method call frames (control frames)
+- Local variables and temporaries
+- Method arguments
+- Block parameters
+- Return values
+
+This is what you see with Ruby's `caller` method at runtime.
+
+### C Stack (Native Level)
+
+The C/machine stack holds:
+- Native function call frames
+- C local variables
+- Saved registers
+- Return addresses
+
+This is what GDB's `bt` command shows by default.
+
+## Inspecting VM Stacks
+
+### Current Frame Information
+
+See the current Ruby control frame:
+
+~~~
+(gdb) set $ec = ruby_current_execution_context_ptr
+(gdb) set $cfp = $ec->cfp
+(gdb) p $cfp->pc       # Program counter
+(gdb) p $cfp->sp       # Stack pointer
+(gdb) p $cfp->iseq     # Instruction sequence
+(gdb) p $cfp->ep       # Environment pointer
+~~~
+
+### Combined Stack Trace
+
+The simplest way to see both Ruby and C frames:
+
+~~~
+(gdb) rb-fiber-scan-heap
+(gdb) rb-fiber-scan-switch 5
+(gdb) rb-stack-trace
+Combined Ruby/C backtrace for Fiber #5:
+  [C] fiber_setcontext
+  [R] /app/lib/connection.rb:123:in `read'
+  [C] rb_io_wait_readable
+  [R] /app/lib/connection.rb:89:in `receive'
+  ...
+~~~
+
+This shows both levels of the call stack in order.
+
+### Detailed Frame Information
+
+For advanced debugging, you can inspect the raw VM frames:
+
+~~~
+(gdb) set $ec = ruby_current_execution_context_ptr
+(gdb) set $cfp = $ec->cfp
+
+# Current frame details:
+(gdb) p $cfp->pc       # Program counter
+(gdb) p $cfp->sp       # Stack pointer  
+(gdb) p $cfp->iseq     # Instruction sequence
+(gdb) p $cfp->ep       # Environment pointer
+~~~
+
+## Inspecting C Stacks
+
+### C Backtrace with GDB
+
+After switching to a fiber, use standard GDB commands to inspect the C stack:
+
+~~~
+(gdb) rb-fiber-scan-switch 5
+(gdb) bt                    # Show C backtrace
+(gdb) frame 2               # Switch to specific frame
+(gdb) info args             # Show function arguments
+(gdb) info locals           # Show local variables
+~~~
+
+The fiber unwinder automatically integrates with GDB's backtrace functionality, so `bt` shows the correct C stack for the selected fiber.
+
+## Practical Examples
+
+### Finding Where Execution Stopped
+
+Identify the exact location in both Ruby and C:
+
+~~~
+(gdb) rb-fiber-scan-heap
+(gdb) rb-fiber-scan-switch 5         # Switch to fiber context
+(gdb) rb-stack-trace                 # Combined backtrace
+  [R] /app/lib/connection.rb:123:in `read'
+  [C] rb_fiber_yield
+  [C] rb_io_wait_readable
+  [R] /app/lib/connection.rb:89:in `receive'
+~~~
+
+This shows the fiber is suspended in `read`, waiting for I/O.
+
+### Debugging Deep Recursion
+
+Detect excessive call depth:
+
+~~~
+(gdb) rb-fiber-scan-heap
+(gdb) rb-fiber-scan-switch 5
+(gdb) rb-stack-trace | grep "/app/lib/parser.rb:45" | wc -l
+134                            # Same line appearing 134 times!
+~~~
+
+Identifies a recursion issue in the parser.
+
+### Examining Stack Values
+
+See what values are on the current frame's stack:
+
+~~~
+(gdb) rb-fiber-scan-switch 5
+(gdb) set $sp = $ec->cfp->sp
+
+# Print values on stack
+(gdb) rb-object-print *(VALUE*)($sp - 1)  # Top of stack
+(gdb) rb-object-print *(VALUE*)($sp - 2)  # Second value
+(gdb) rb-object-print *(VALUE*)($sp - 3)  # Third value
+~~~
+
+### Tracking Fiber Switches
+
+See the call stack across fiber boundaries:
+
+~~~
+(gdb) rb-fiber-scan-switch 5
+(gdb) bt
+#0  fiber_setcontext
+#1  rb_fiber_yield            # Fiber yielded here
+#2  rb_io_wait_readable       # Waiting for I/O
+#3  some_io_operation
+
+(gdb) frame 3
+(gdb) info locals              # C variables at I/O call
+~~~
+
+## Combining VM and C Stacks
+
+For the complete picture, use the combined stack trace:
+
+~~~
+(gdb) rb-fiber-scan-switch 5
+(gdb) rb-stack-trace
+Combined Ruby/C backtrace:
+  [R] /app/lib/connection.rb:123:in `read'
+  [C] rb_io_wait_readable
+  [C] rb_io_read
+  [R] /app/lib/connection.rb:89:in `receive'
+  [C] rb_fiber_yield
+  [R] /app/lib/server.rb:56:in `handle_client'
+  ...
+~~~
+
+Or separately:
+
+~~~
+(gdb) rb-stack-trace --values          # Ruby perspective with stack values
+(gdb) bt                               # C perspective only
+~~~
+
+The combined view reveals the full execution path through both Ruby and C code.

data/data/toolbox/command.py

@@ -0,0 +1,254 @@
+class Arguments:
+	"""Structured result from parsing GDB command arguments.
+	
+	Attributes:
+		expressions: List of expressions to evaluate (e.g., ["$var", "$ec->cfp->sp[-1]"])
+		flags: Set of boolean flags (e.g., {'debug'})
+		options: Dict of options with values (e.g., {'depth': 3})
+	"""
+	def __init__(self, expressions, flags, options):
+		self.expressions = expressions
+		self.flags = flags
+		self.options = options
+	
+	def has_flag(self, flag_name):
+		"""Check if a boolean flag is present"""
+		return flag_name in self.flags
+	
+	def get_option(self, option_name, default=None):
+		"""Get an option value with optional default"""
+		return self.options.get(option_name, default)
+
+class ArgumentParser:
+	"""Parse GDB command arguments handling nested brackets, quotes, and flags.
+	
+	This parser correctly handles:
+	- Nested brackets: $ec->cfp->sp[-1]
+	- Nested parentheses: ((struct foo*)bar)->baz
+	- Quotes: "string value"
+	- Flags: --debug, --depth 3
+	- Complex expressions: foo + 10, bar->ptr[idx * 2]
+	"""
+	
+	def __init__(self, argument_string):
+		self.argument_string = argument_string.strip()
+		self.position = 0
+		self.length = len(self.argument_string)
+	
+	def parse(self):
+		"""Parse the argument string and return (expressions, flags, options)
+		
+		Returns:
+			tuple: (expressions: list[str], flags: set, options: dict)
+			- expressions: List of expressions to evaluate
+			- flags: Set of boolean flags (e.g., {'debug'})
+			- options: Dict of options with values (e.g., {'depth': 3})
+		"""
+		flags = set()
+		options = {}
+		expressions = []
+		
+		while self.position < self.length:
+			self.skip_whitespace()
+			if self.position >= self.length:
+				break
+			
+			if self.peek() == '-' and self.peek(1) == '-':
+				# Parse a flag or option
+				flag_name, flag_value = self.parse_flag()
+				if flag_value is None:
+					flags.add(flag_name)
+				else:
+					options[flag_name] = flag_value
+			else:
+				# Parse an expression
+				expression = self.parse_expression()
+				if expression:
+					expressions.append(expression)
+		
+		return expressions, flags, options
+	
+	def peek(self, offset=0):
+		"""Peek at character at current position + offset"""
+		position = self.position + offset
+		if position < self.length:
+			return self.argument_string[position]
+		return None
+	
+	def consume(self, count=1):
+		"""Consume and return count characters"""
+		result = self.argument_string[self.position:self.position + count]
+		self.position += count
+		return result
+	
+	def skip_whitespace(self):
+		"""Skip whitespace characters"""
+		while self.position < self.length and self.argument_string[self.position].isspace():
+			self.position += 1
+	
+	def parse_flag(self):
+		"""Parse a flag starting with --
+		
+		Returns:
+			tuple: (flag_name: str, value: str|None)
+			- For boolean flags: ('debug', None)
+			- For valued flags: ('depth', '3')
+		"""
+		# Consume '--'
+		self.consume(2)
+		
+		# Read flag name
+		flag_name = ''
+		while self.position < self.length and self.argument_string[self.position].isalnum():
+			flag_name += self.consume()
+		
+		# Check if flag has a value
+		self.skip_whitespace()
+		
+		# If next character is not another flag and not end of string, it might be a value
+		if self.position < self.length and not (self.peek() == '-' and self.peek(1) == '-'):
+			# Try to parse a value - it could start with $, digit, or letter
+			if self.peek() and not self.peek().isspace():
+				value = ''
+				while self.position < self.length and not self.argument_string[self.position].isspace():
+					if self.peek() == '-' and self.peek(1) == '-':
+						break
+					value += self.consume()
+				
+				# Try to convert to int if it's a number
+				try:
+					return flag_name, int(value)
+				except ValueError:
+					return flag_name, value
+		
+		return flag_name, None
+	
+	def parse_expression(self):
+		"""Parse a single expression, stopping at whitespace (unless nested) or flags.
+		
+		An expression can be:
+		- A quoted string: "foo" or 'bar'
+		- A parenthesized expression: (x + y)
+		- A variable with accessors: $ec->cfp->sp[-1]
+		- Any combination that doesn't contain unquoted/unnested whitespace
+		"""
+		expression = ''
+		
+		while self.position < self.length:
+			self.skip_whitespace()
+			if self.position >= self.length:
+				break
+			
+			character = self.peek()
+			
+			# Stop at flags
+			if character == '-' and self.peek(1) == '-':
+				break
+			
+			# Handle quoted strings - these are complete expressions
+			if character in ('"', "'"):
+				quoted = self.parse_quoted_string(character)
+				expression += quoted
+				# After a quoted string, we're done with this expression
+				break
+			
+			# Handle parentheses - collect the whole balanced expression
+			if character == '(':
+				expression += self.parse_balanced('(', ')')
+				continue
+			
+			# Handle brackets
+			if character == '[':
+				expression += self.parse_balanced('[', ']')
+				continue
+			
+			# Handle braces
+			if character == '{':
+				expression += self.parse_balanced('{', '}')
+				continue
+			
+			# Stop at whitespace (this separates expressions)
+			if character.isspace():
+				break
+			
+			# Regular character - part of a variable name, operator, etc.
+			expression += self.consume()
+		
+		return expression.strip()
+	
+	def parse_quoted_string(self, quote_character):
+		"""Parse a quoted string, handling escapes"""
+		result = self.consume()  # Opening quote
+		
+		while self.position < self.length:
+			character = self.peek()
+			
+			if character == '\\':
+				# Escape sequence
+				result += self.consume()
+				if self.position < self.length:
+					result += self.consume()
+			elif character == quote_character:
+				# Closing quote
+				result += self.consume()
+				break
+			else:
+				result += self.consume()
+		
+		return result
+	
+	def parse_balanced(self, open_character, close_character):
+		"""Parse a balanced pair of delimiters (e.g., parentheses, brackets)"""
+		result = self.consume()  # Opening delimiter
+		depth = 1
+		
+		while self.position < self.length and depth > 0:
+			character = self.peek()
+			
+			# Handle quotes inside balanced delimiters
+			if character in ('"', "'"):
+				result += self.parse_quoted_string(character)
+				continue
+			
+			if character == open_character:
+				depth += 1
+			elif character == close_character:
+				depth -= 1
+			
+			result += self.consume()
+		
+		return result
+
+def parse_arguments(input):
+	"""Convenience function to parse argument string.
+	
+	Arguments:
+		input: The raw argument string from GDB command
+	
+	Returns:
+		Arguments: Structured object with expressions, flags, and options
+	
+	Examples:
+		>>> arguments = parse_arguments("$var --debug")
+		>>> arguments.expressions
+		['$var']
+		>>> arguments.has_flag('debug')
+		True
+		
+		>>> arguments = parse_arguments('"foo" "bar" --depth 3')
+		>>> arguments.expressions
+		['"foo"', '"bar"']
+		>>> arguments.get_option('depth')
+		3
+		
+		>>> arguments = parse_arguments("$ec->cfp->sp[-1] --debug --depth 2")
+		>>> arguments.expressions
+		['$ec->cfp->sp[-1]']
+		>>> arguments.has_flag('debug')
+		True
+		>>> arguments.get_option('depth')
+		2
+	"""
+	parser = ArgumentParser(input)
+	expressions, flags, options = parser.parse()
+	return Arguments(expressions, flags, options)